Open main menu

Jax-rs 2.0

Revision as of 17:48, 16 February 2019 by Adam (talk | contribs) (→‎Response objektum előállítása)

Revision as of 17:48, 16 February 2019 by Adam (talk | contribs) (→‎Response objektum előállítása)

https://dennis-xlc.gitbooks.io/restful-java-with-jax-rs-2-0-en/cn/part1/chapter8/building_and_invoking_requests.html

Contents

JAX-RS szerver

Inicializálás

A JAX-RS szerver futtatásához el kell indítsuk a Jersy servlet-et a WEB alkalmazásunkban, ami kiválóan megfér más servlet-ek mellett, pl JSF. A Jersey servletnek meg fogjuk mondani, hogy milyen PATH tartozik hozzá, így minden más erőforrás kérés továbbra is a JSF servlet-hez fog beesni.

Maven dependenciák

		<dependency>
			<groupId>org.glassfish.jersey.containers</groupId>
			<artifactId>jersey-container-servlet</artifactId>
			<version>2.28</version>
		</dependency>
		<dependency>
			<groupId>org.glassfish.jersey.inject</groupId>
			<artifactId>jersey-hk2</artifactId>
			<version>2.28</version>
		</dependency>
		<dependency>
			<groupId>org.glassfish.jersey.core</groupId>
			<artifactId>jersey-common</artifactId>
			<version>2.28</version>
		</dependency>


web.xml

Ha JSF-et akarunk párhuzamosan JAX-RS-el használni, akkor nincs más dolgunk, mint hogy mint két serlvet implementációt felvegyünk a web.xml-be. Elsőként a JSF implementációt, ami az esetünkben PrimeFaces lesz, aztán meg felvesszük a JAX-RS serlvetet, ami az esetünkben Glassfish-Jeresy lesz.

A Glassfish-Jeresy-t többféle képen lehet paraméterezni. Vagy itt, a web.xml-ben adjuk meg a szükséges paramétereket (provide-erek, mapperek, stb..) vagy implementáljuk a javax.ws.rs.core.Application osztályt, megadjuk a helyét a javax.ws.rs.Application paraméterrel, majd a konfigurációt többi részét az osztályon belül definiáljuk.

Elsőre nézzük az a web.xml-es konfigurációt. <init-param> szekciókkal kell megadni a Jersey paramétereit:

  • jersey.config.server.provider.packages: meg kell adni azt a java csomagot, ahol a webservice implementációk és az exception mapper-ek vannak. Mi itt azt a csomagot adjuk meg, ahol a service implementációk vannak.
  • jersey.config.server.provider.classnames: fel lehet sorolni konkrét class megadásokkal további implementációkat. Mi itt az Exception mapper-eket adjuk meg.


A servlet-mapping szekcióban elsőre megadjuk hogy a Jeresey servlet a /rest/ útvonalon fog hallgatózni. Aztán adjuk meg a JSF servletet, ami minden másra illeszkedni fog. 

...
	<!-- JSF servlet -->
	<servlet>
		<servlet-name>Faces Servlet</servlet-name>
		<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
		<load-on-startup>1</load-on-startup>
	</servlet>

        <!-- Jersey servlet -->
	<servlet>
		<servlet-name>Jersey Service</servlet-name>

		<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
		<init-param>
			<param-name>jersey.config.server.provider.packages</param-name>
			<param-value>hu.adam.loginHelper.jaxrs.service</param-value>
		</init-param>

		<init-param>
			<param-name>jersey.config.server.provider.classnames</param-name>
			<param-value>
                           hu.adam.loginHelper.jaxrs.mapper.AppExceptionMapper;
                           hu.adam.loginHelper.jaxrs.mapper.ErrorMessage;
                           hu.adam.loginHelper.jaxrs.mapper.WebServiceExceptionMapper
                         </param-value>
		</init-param>

		<load-on-startup>1</load-on-startup>
	</servlet>

        <!-- Jersey mapping -->
	<servlet-mapping>
		<servlet-name>Jersey Service</servlet-name>
		<url-pattern>/rest/*</url-pattern>
	</servlet-mapping>

        <!-- JSF servlet -->
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>/faces/*</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>*.jsf</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>*.faces</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Faces Servlet</servlet-name>
		<url-pattern>*.xhtml</url-pattern>
	</servlet-mapping>


Másik alternatíva lenne ha JAX-RS konfigurációt a javax.ws.rs.core.Application osztály implementációjában definiálnánk. Ekkor a web.xml-ben csak az implementációs osztályt kell megadni: ha a web.xml-ben az 

	<!-- Jersey servlet -->
	<servlet>
		<servlet-name>Jersey Service</servlet-name>
		<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
		<init-param>
			<param-name>javax.ws.rs.Application</param-name>
			<param-value>hu.adam.MyApplication</param-value>
		</init-param>


Majd a tovább konfigurációkat az implementációs osztályban definiáljuk: 

import java.util.HashSet;
import java.util.Set;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/rest/")
public class MyApplication extends Application {
	
	 public Set<Class<?>> getClasses() {
	        Set<Class<?>> s = new HashSet<Class<?>>();
                //Webservices
	        s.add(LoginService.class);
	        
                //Mappers
	        s.add(AppExceptionMapper.class);	        
	        s.add(GenericExceptionMapper.class);	        
	        return s;
	    }	
}

Service osztály definiálása

A service osztályokat nagyon egyszerű definiálni, az alábbi osztály loginByEmail metódusa a POST:<app root>/rest/login/loginbyemail URL-en lesz elérhető. A HTTP body-ban a LoginByEmalLoginHelperRequest osztály JSON reprezentációját fogja várni, amit automatikusan mappelni fog a JAX-RS egy LoginByEmalLoginHelperRequest objektum példányba. A metódus a TokenResponse típusú objektummal tér vissza, mait a JAX-RS automatikusan JSON -ra fog mappelni anélkül, hogy vagy a request vagy a response objektumba bármilyen annotációt el kéne helyezni. Bonyolult, vagy nem egyértelmű struktúrák esetén szükség lehet rá, hogy annotációkkal támogassuk a JSON<->JAVA mapper-t, lásd lentebb. 

import javax.ws.rs.POST;
import javax.ws.rs.Path;


@Path("/login/")
@Consumes({ "application/json" })
@Produces({ "application/json" })
public class LoginService {

	@POST
	@Path("/loginbyemail")
	public TokenResponse loginByEmail(LoginByEmalLoginHelperRequest loginByEmalRequest) throws WebServiceException {
		
		return new TokenResponse();
	}

        @GET
	@Path("/book/{isbn}")
	public Book getBook(@PathParam("isbn") String id, @QueryParam("title") String title) {

		Book oneBook = new Book();
		oneBook.setIsbn("ISBN11111");
		oneBook.setTitle("Mastering Jax-RS");

		return oneBook;

	}

}

A második metódus (getBook) a GET:<app root>/rest/book/ URL-en érhető el. Vár egy PATH paramétert a /book/ után, valamint egy title nevű QUERY paramétert, tehát a teljes request valami ilyesmi lesz: GET:<app root>/rest/book/12345?title=adam


Response objektum előállítása

A @GET/POST/PUT annotációkkal ellátott metódusoknál a visszatérési objektum típus meghatározására két lehetőségünk van.

  • Ha rest metódusnak egy POJO a visszatérési értéke (vagy egy abból képzett típus) akkor sikeres futás estében, a metódus visszatérése után a JAX-RS ebből automatikusan REST választ fog generálni, a POJO-t JSON/XML-re fogja konvertálni, és be is állítja a HTTP státuszt, nekünk ezzel ebben az esetben semmi dolgunk. Viszont több okból is meg van kötve a kezünk: Ha a metódus sikeresen elfut, akkor a JAX-RS ezt mindig sikeres futásnak fogja tekinteni, és a HTTP státuszt mindig 200-ra fogja állítani, nem tudunk beavatkozni a válasz elkészítésébe. 
	
	   @GET
	   @Path("/contract")
	   public Contract getContract() {
	       Contract contract = new Contract();	      
	       return contract;
	   }
  • Ha a service metódusnak nem egy POJO a visszatérési értéke, hanem a javax.ws.rs.core.Response, akkor teljes kontrolunk van a válasz összeállításában, viszont mindent mind sikeres, mind sikertelen ágon nekünk kell kézzel a válaszba belerakni a megfelelő response JAVA objektumot és beállítani a HTTP státuszt.

https://dennis-xlc.gitbooks.io/restful-java-with-jax-rs-2-0-en/cn/part1/chapter7/complex_responses.html Alább láthatunk egy példát a teljesen manuális response összeállítására. Ha a header-t és azon belül a sütiket is állítani akarjuk, akkor muszáj ezt a megközelítést használni. 

	
	   @GET
	   @Path("/contract2")
	   public Response getContract() {

	       Contract contract = new Contract();
		
	       ResponseBuilder builder = Response.ok(contract);
	       builder.language("en").header("Some-Header", "some value").cookie(new NewCookie("adamCooke", "value"));

	       return builder.build();
	   }

A státuszt kétféle képen határozhatjuk meg A Resonse osztálynak többféle metódusa van, ami beállítja a státuszt: ok=200, created=204 ..., vagy mi állítjuk be kézzel: .status(int)

Hibakezelés

Áttekintés

Ez egy sarkalatos pontja a REST interfész implementációnak, ugyanis a kliensnek minden esetben vissza kell adni egy szabványos REST választ, ahol hiba esetén lehetőleg megmondjuk, hogy mi történt, tehát minden hibát le kell valahogy kezelni. Úgy fogjuk megoldani, hogy hiba esetén egyedi response objektumot dobjuk, hogy hiba esetén egy saját Exception-t dobunk, amit egy Exception provider-el feldolgozunk, és egyedi hiba objektumot készítünk belőle a válaszba.

Ahhoz hogy a hibaágakat is kezelni tudjuk, létre kell hozzunk egyedi Exception osztályokat, és hozzájuk tartozó response mapper-eket (Provider), amik az Exception eldobása estén megkapják a vezérlést, és az Exception alapján össze tudják állítani a választ. Ehhez három osztályt kell létrehozzunk:

  1. ErrorResponse osztály, egy egységesített struktúra, amit minden nem 200-as válaszban vár a kliens. (pl hibakódok, szöveges leírás)
  2. Saját Exception implementáció (WebServiceException), amibe minden olyan infónak szerepelnie kell, ami alapján az ErrorResponse osztály elkészíthető.
  3. Exception provider osztály, ami megkapja a vezérlést ha WebServiceException dobódott, és a benne található információk alapján példányosítja a ErrorResponse osztályt, majd beleteszi a REST válaszba, amit a JAX-RS JSON formátumra fog hozni.



Jax-RS provider típusok

A JAX-RS-ben 3 típusa létezik a provider-ekenek, melyekkel három különféle feladatot láthatunk el:

  • Entity provider

https://docs.huihoo.com/jersey/2.13/message-body-workers.html
The Entity provider API contains 2 interfaces. One for handling inbound entity representation-to-Java de-serialization - MessageBodyReader<T> and the other one for handling the outbound entity Java-to-representation serialization - MessageBodyWriter<T>. A MessageBodyReader<T>, as the name suggests, is an extension that supports reading the message body representation from an input stream and converting the data into an instance of a specific Java type. A MessageBodyWriter<T> is then responsible for converting a message payload from an instance of a specific Java type into a specific representation format that is sent over the wire to the other party as part of an HTTP message exchange. Both of these providers can be used to provide message payload serialization and de-serialization support on the server as well as the client side.

  • Context provider

https://www.logicbig.com/tutorials/java-ee-tutorial/jax-rs/context-resolver.html
Context providers supply a context object to resource classes or to other providers.A context provider class must implement the ContextResolver<T>interface.

  • Exception provider

These providers map a checked or runtime exception to an instance of Response. They implement ExceptionMapper<T>. Számunkra ez a lényeges. Itt fogjuk az exception-t




Megvalósítás

Elsőként definiáljuk azt az osztályt ami alapján a NEM 200-as státusz esetén a válasz objektumot létre akarjuk hozni. Létrehoztunk egy Facory metódust is a JSON<->JAVA konverzióra, amit @JsonCreator annotációval láttunk el (a metódusnak az 'of' nevet adtuk). A @JsonProperty-val megadtuk az egyez mezők JSON nevét és Jáva típusát. 

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;

public class ErrorMessageResponse implements Serializable {

	private String correlationId;
	
	private String message;

        @JsonCreator
        public static ErrorMessageResponse of
                    (@JsonProperty("correlationId") String correlationId, 
                     @JsonProperty("messages") String message) {
        return new ErrorMessageResponse(correlationId, message);
        }
       
        //Getters and setters and constructor...
}

A HTTP válaszba JSON alakban ez így fog kinézni: 

{"correlationId":"XXX", "message":"111"}


Hozzunk létre egy egyedi Exception implementációt, amit minden kezelt hiba estén mi fogunk dobni a webservice metódusok belsejében. Ezt az exception-t fogja elkapni a mapper osztályunk, és alakítja majd át ErrorMessageResponse objektumra. Az exception-t származtassuk le az IllegalArgumentException-böl, és a konstruktorban töltsük ki az ős konstruktorát is. 

public class WebServiceException extends IllegalArgumentException {
        //HTTP status 
	private int status;

	private String correlationId;
	
	private String responseMessage;


	public WebServiceException(String correlationId, String responseMessage, String message, Throwable cause) {
		super(message, cause);
            ...
        }

        //getters...
}


És végezetül nézzük meg az Exception provider osztályt aminek implementálni kell a ExceptionMapper<T> interfészt és a toResponse metódust, amivel az Exception alapján előállítjuk a válasz objektomt. 

import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.ext.ExceptionMapper;
import javax.ws.rs.ext.Provider;
import hu.adam.loginHelper.exception.WebServiceException;

@Provider
public class WebServiceExceptionMapper implements ExceptionMapper<WebServiceException> {
	@Override
	public Response toResponse(WebServiceException exception) {
 		
                ErrorMessageResponse emr = new ErrorMessageResponse(exception.getCorrelationId(), exception.getResonseMessage());

		return Response.status(exception.getStatus())
				.entity(emr)
				.type(MediaType.APPLICATION_JSON).
				build();
	}
}


Használata: 



Cookie kezelés


https://www.logicbig.com/tutorials/java-ee-tutorial/jax-rs/cookie-param.html




JAX-RS kliens







Retrieved from "http://wiki.berki.org/index.php?title=Jax-rs_2.0&oldid=2795"



	

		
			Last edited on 26 April 2019, at 16:25