JAX-RS 2.0 behavior changes
The JAX-RS 2.0 implementation contains some behavior changes. These changes might cause applications to behave differently or fail on JAX-RS 2.0 if the applications are upgraded from JAX-RS 1.1.
The following list describes the differences between JAX-RS 1.1 and JAX-RS 2.0:
- JAX-RS 1.1 requires CDI 1.0. Version 9.0 of the product supports CDI 1.2 only. In Version 9.0, if a customer application uses JAX-RS and CDI, the application must use JAX-RS 2.0.
- In JAX-RS 1.1 and Jersey, if an EJB or CDI class creates a new instance that is returned
by the JAX-RS application.getSingletons() method, the engine uses the returned instance and does not
try to access the instance from the EJB or CDI container. In JAX-RS 2.0, for the same scenario, the
engine tries to access the instance from the EJB or CDI container. If the instance can be accessed,
the retrieved instance is used. But if the instance cannot be accessed, the returned instance from
the getSingletons() method is used. For
example:
@Override public Set<Object> getSingletons() { Set<Object> objs = new HashSet<Object>(); objs.add(new CDIInjectResource()); objs.add(new EJBInjectResource()); return objs; }
- JAX-RS 2.0 includes many API changes when it handles the MultiPart file. For example, in
JAX-RS 1.1, the
@FormParam
can be used to handle the MultiPart file, but in JAX-RS 2.0, only@IMultipartBody
or@IAttachment
can be used to handle the MultiPart file. For more information, see Configuring a resource to receive multipart/form-data parts from an HTML form submission in JAX-RS 2.0. - The Jackson packages that are displayed as a third-party API in JAX-RS 1.1 are no longer
displayed in JAX-RS 2.0. If you want to use any
org.codehaus.jackson
APIs in your application, you need to compress the Jackson packages in your application. To handle Jackson annotations in Java objects with JAX-RS 2.0, you need to overridegetSingletons()
in your application class to return Jackson's JSON provider.@Override public Set<Object> getSingletons() { Set<Object> singletons = new HashSet<Object>(); singletons.add(new JacksonJaxbJsonProvider()); return singletons; }
- If you specify
javax.ws.rs.core.Application
for the servlet name in the web.xml file, thegetClasses
method in the Application object, which is injected by@Context
, does not return the resource classes.<servlet> <servlet-name>javax.ws.rs.core.Application</servlet-name> </servlet> <servlet-mapping> <servlet-name>javax.ws.rs.core.Application</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping>
- The JAX-RS 2.0 specification states that a provider is a class that implements one or more
JAX-RS interfaces and that can be annotated with
@Provider
for automatic discovery. In the scenario, a class has@Local
annotation that refers to a provider interface, but it does not implement any POJO provider interface, and then it is an invalid provider. For example:@Stateless @Local(OneLocalInterfaceMyOtherStuffMessageBodyWriter.class) public class OneLocalInterfaceMyOtherStuffProvide
- If you use the MessageBodyReader and MessageBodyWriter
@Consumes
and@Produces
annotations, some supported media types might be restricted. Use theisReadable
method orisWriteable
method to check the media type. For example:@Provider @Consumes("<custom/type>") @Produces("<custom/type>") @Singleton public class MyMessageBodyReaderAndWriter implements MessageBodyReader,MessageBodyWriter { public boolean isReadable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) { if (mediaType.toString().equals("<custom/type>")) return true; return false; } public boolean isWriteable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) { if (mediaType.toString().equals("<custom/type>")) return true; return false; } ... }
- You can use asynchronous processing in JAX-RS 2.0 to process threads.
- None of the Wink APIs that are displayed as third-party APIs in JAX-RS 1.1 are supported in
JAX-RS 2.0. Here is a partial list:
org.apache.wink.common.model.atom.AtomEntry
. For more information about integrating JAX-RS 2.0 with Atom, see Integrating JAX-RS 2.0 with Atom.org.apache.wink.client.handlers.BasicAuthSecurityHandler
. If you want to use basic authentication in JAX-RS 2.0, see the following code snippets:- Use
ClientRequestFilter
through the JAX-RS 2.0 standard Client API as shown in the code example:import java.io.IOException; import java.io.UnsupportedEncodingException; import javax.ws.rs.client.ClientRequestContext; import javax.ws.rs.client.ClientRequestFilter; import javax.ws.rs.core.MultivaluedMap; import javax.xml.bind.DatatypeConverter; public class BasicAuthFilter implements ClientRequestFilter { private final String usr; private final String pwd; public BasicAuthFilter(String usr, String pwd) { this.usr = user; this.pwd = pwd; } public void filter(ClientRequestContext requestContext) throws IOException { MultivaluedMap<String, Object> headers = requestContext.getHeaders(); String token = this.usr + ":" + this.pwd; final String basicAuthentication ="Basic " + DatatypeConverter.printBase64Binary(token.getBytes("UTF-8")); headers.add("Authorization", basicAuthentication); } }
- Register to the
ClientBuilder:
ClientBuilder cb = ClientBuilder.newBuilder(); cb.register(new BasicAuthFilter("user","password"));
- Use
org.apache.wink.client.handlers.LtpaAuthSecurityHandler
.org.apache.wink.server.internal.providers.exception.EJBAccessExceptionMapper
. This API is no longer supported because it is the Wink-specified ExceptionMapper. You can define your own ExceptionMapper to map the EJBAccessException.com.ibm.websphere.jaxrs.server.IBMRestFilter
. This API is no longer supported because it is based on Wink Filter.
Note: Detect if there are wink jar packages in your application. If there are any wink packages in your application, you must do the following steps:- Make sure that there is Application subclass defined.
- At least one of
getClasses
andgetSingletons
must not return null.
- For more information about the supported client properties that can be used in the JAX-RS 2.0 client, see Configuring JAX-RS 2.0 client.
- If you want to use the Secure Sockets Layer (SSL) function in JAX-RS 2.0, do the
following steps:
- Configure the SSL properties in the WebSphere® Application Server traditional administrative console.
- Enable security for your JAX-RS application and configure your application to use an SSL channel
for transport when it calls the REST resources.
At application development or deployment time, edit the web.xml file to add a security constraint that requires use of SSL for your resources. See the securing JAX-RS applications within the web container information for more details on enabling SSL for your application.
The following element within the security-constraint element specifies to enforce SSL for your application:<user-data-constraint id="UserDataConstraint_1"> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint>
- To enable client SSL when you develop your client application, add a client property
in your client application code.
Set the client property key to
com.ibm.ws.jaxrs.client.ssl.config
and its value to true. See the following code snippet as reference:ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.ssl.config", "NodeDefaultSSLSettings");
Tip: The property value equals to the server SSL alias that you set. For more information, go toApplication servers->server n, where n is the number that you assigned to the application server.->Web container transport chains->WCInboundDefaultSecure->SSL inbound channel (SSL_2)
to check it under the SSL configuration field. - Deploy your client application to WebSphere Application Server traditional by using the administrative console.
- Start the client application in the WebSphere Application Server traditional
administrative console.
To start your application, go to
Applications->Application types->WebSphere enterprise applications->Start
.
Note: For more information about asynchronous processing in Client and Server APIs, see Chapter
8 of JSR 339: JAX-RS 2.0: The Java™ API for RESTful Web Services (the "Specification").