Chapter 2. Developing JAX-RS Web Services

You can use the javax.ws.rs.core.Application class to create a subclass that declares those providers and web resources. This class is provided by the RESTEasy libraries included with JBoss EAP.

To configure a resource or provider using javax.ws.rs.core.Application, simply create a class that extends it and add an @ApplicationPath annotation.

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

@ApplicationPath("/root-path")
public class MyApplication extends Application
{
}

Alternatively, if you do not want to create a class that extends javax.ws.rs.core.Application, you can add the following to your web.xml file.

<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <servlet>
      <servlet-name>javax.ws.rs.core.Application</servlet-name>
  </servlet>
  <servlet-mapping>
      <servlet-name>javax.ws.rs.core.Application</servlet-name>
      <url-pattern>/root-path/*</url-pattern>
  </servlet-mapping>
  ...
</web-app>

When subclassing javax.ws.rs.core.Application you can choose to provide a custom implementation for any of the existing methods. The getClasses and getSingletons methods return a collection of classes or singletons that must be included in the published JAX-RS application.

JAX-RS 2.0 introduced a new client API to send HTTP requests to remote RESTful web services. It is a fluent request-building API with 3 main classes:

The Client interface is a builder of WebTarget instances. The WebTarget represents a distinct URL or URL template to build subresource WebTargets or invoke requests on.

There are two ways to create a client: the standard way, or using the ResteasyClientBuilder class. The advantage of using the ResteasyClientBuilder class is that it provides a few more helper methods to configure your client.

Using the Standard Way to Create a Client

The following example shows one of the standard ways to create a client:

Client client = ClientBuilder.newClient();

Alternatively, you can use another standard way to create a client as shown in the example below:

Client client = ClientBuilder.newBuilder().build();
WebTarget target = client.target("http://foo.com/resource");
Response response = target.request().get();
String value = response.readEntity(String.class);
response.close();  // You should close connections!

Using the ResteasyClientBuilder Class to Create a Client

ResteasyClient client = new ResteasyClientBuilder().build();
ResteasyWebTarget target = client.target("http://foo.com/resource");

RESTEasy automatically loads a set of default providers that includes all classes listed in the META-INF/services/javax.ws.rs.ext.Providers file. Additionally, you can manually register other providers, filters, and interceptors through the configuration object provided by the method call Client.configuration(). Configuration also lets you set configuration properties that might be needed.

Each WebTarget has a configuration instance that inherits the components and properties registered with the parent instance. This lets you set specific configuration options for each target resource, for example, the username and password.

Using RESTEasy Client Classes

You must add the following dependency for RESTEasy client to your Maven pom.xml file:

<dependency>
	<groupId>org.jboss.resteasy</groupId>
	<artifactId>resteasy-client</artifactId>
	<version>VERSION_IN_EAP</version>
 </dependency>

See the jaxrs-client and resteasy-jaxrs-client quickstarts that ship with JBoss EAP for working examples that use the RESTEasy client classes.

Client-side Filters

The client side has two types of filters:

// execute request filters
for (ClientRequestFilter filter : requestFilters) {
	filter.filter(requestContext);
	if (isAborted(requestContext)) {
    return requestContext.getAbortedResponseObject();
  }
}

// send request over the wire
response = sendRequest(request);

// execute response filters
for (ClientResponseFilter filter : responseFilters) {
	filter.filter(requestContext, responseContext);
}

Register Client-side Filters to the Client Request

The following example shows how to register the client-side filters to the client request:

client = ClientBuilder.newClient();
WebTarget base = client.target(generateURL("/") + "get");
base.register(ClientExceptionsCustomClientResponseFilter.class).request("text/plain").get();

Client-side Cache

RESTEasy has the ability to set up a client-side cache. This cache looks for cache-control headers sent back with a server response. If the cache-control headers specify that the client is allowed to cache the response, RESTEasy caches it within the local memory.

ResteasyWebTarget target = client.target(generateBaseUrl());
target.register(BrowserCacheFeature.class);

Chunked Encoding Support

RESTEasy provides the client API the ability to specify that requests should be sent in a chunked transfer mode. There are two ways of specifying the chunked transfer mode, as shown below.

Network communication between the client and server is handled by default in RESTEasy. It uses the HttpClient from the Apache HttpComponents project. The interface between the RESTEasy client framework and the network is defined by the ClientHttpEngine interface.

RESTEasy ships with four implementations of this interface. The default implementation is ApacheHttpClient43Engine. This implementation uses Apache 4.3.

ApacheHttpClient4Engine is an implementation that uses the versions earlier than Apache 4.3. This class provides backward compatibility. RESTEasy automatically selects one of these two ClientHttpEngine implementations based on the detection of the Apache version. InMemoryClientEngine is an implementation that dispatches requests to a server in the same JVM, and URLConnectionEngine is an implementation that uses java.net.HttpURLConnection.

A client executor can be passed to a specific ClientRequest:

ResteasyClient client = new
ResteasyClientBuilder().httpEngine(engine).build();

RESTEasy and HttpClient make the default decisions to use the client framework without referencing HttpClient. However, for some applications it might be necessary to drill down into the HttpClient details. ApacheHttpClient43Engine and ApacheHttpClient4Engine can be supplied with an instance of org.apache.http.client.HttpClient and org.apache.http.protocol.HttpContext, which can carry additional configuration details into the HttpClient layer. For example, authentication can be configured as follows:

// Configure HttpClient to authenticate preemptively
// by prepopulating the authentication data cache.

// 1. Create AuthCache instance
AuthCache authCache = new BasicAuthCache();

// 2. Generate BASIC scheme object and add it to the local auth cache
AuthScheme basicAuth = new BasicScheme();
authCache.put(new HttpHost("sippycups.bluemonkeydiamond.com"), basicAuth);

// 3. Add AuthCache to the execution context
BasicHttpContext localContext = new BasicHttpContext();
localContext.setAttribute(ClientContext.AUTH_CACHE, authCache);

// 4. Create client executor and proxy
HttpClient httpClient = HttpClientBuilder.create().build();
ApacheHttpClient4Engine engine = new ApacheHttpClient4Engine(httpClient, localContext);
ResteasyClient client = new ResteasyClientBuilder().httpEngine(engine).build();

HttpContextProvider is an interface provided by RESTEasy, using which you can supply a custom HttpContext to the ApacheHttpClient43Engine and ApacheHttpClient4Engine implementations.

RESTEasy releases the connection without notification. The only counter example is the case in which the response is an instance of InputStream, which must be closed explicitly.

On the other hand, if the result of an invocation is an instance of Response, the Response.close() method must be used to release the connection.

WebTarget target = client.target("http://localhost:8081/customer/123");
Response response = target.request().get();
System.out.println(response.getStatus());
response.close();

You may execute this in a try-finally block. Releasing a connection makes it available for another use. It does not normally close the socket.

ApacheHttpClient4Engine.finalize() closes any open sockets, if it created the HttpClient that it has been using. It is not safe to rely on JDK to call finalize(). If an HttpClient is passed to the ApacheHttpClient4Executor, the user must close the connections, as shown below:

HttpClient httpClient = new HttpClientBuilder.create().build();
ApacheHttpClient4Engine executor = new ApacheHttpClient4Engine(httpClient);
...
httpClient.getConnectionManager().shutdown();

Finally, if the javax.ws.rs.client.Client class has created the engine automatically, call Client.close(). This call cleans up any socket connections.

ApacheHttpClient43Engine engine = new ApacheHttpClient43Engine();
engine.setFollowRedirects(true);
Client client = new ResteasyClientBuilder().httpEngine(engine).build();

Asynchronous request processing allows you to process a single HTTP request using non-blocking input and output and, if required, in separate threads.

Consider an AJAX chat client in which you want to push and pull from both the client and the server. This scenario has the client blocking for a long time on the server’s socket, waiting for a new message. In case of synchronous HTTP processing, where the server is blocking on incoming and outgoing input and output, you have one separate thread consumed per client connection. This model of request processing consumes a lot of memory and valuable thread resources.

Asynchronous processing separates the connection accepting and the request processing operations. It allocates two different threads: one to accept the client connection; the other to handle heavy, time-consuming operations. In this model, the container works as follows:

The result is sent back to the client by the worker thread. Hence, the client’s connection remains open, thereby improving the server’s throughput and scalability.

Client asyncClient = new ResteasyClientBuilder().useAsyncHttpEngine()
                     .build();
Future<Response> future = asyncClient
                          .target("http://locahost:8080/test").request()
                          .async().get();
Response res = future.get();
Assert.assertEquals(HttpResponseCodes.SC_OK, res.getStatus());
String entity = res.readEntity(String.class);

import javax.ws.rs.container.Suspended;
import javax.ws.rs.container.AsyncResponse;

@Path("/")
public class SimpleResource {
   @GET
   @Path("basic")
   @Produces("text/plain")
   public void getBasic(@Suspended final AsyncResponse response) throws Exception {
      Thread t = new Thread() {
         @Override
         public void run() {
            try {
               Response jaxrs = Response.ok("basic").type(MediaType.TEXT_PLAIN).build();
               response.resume(jaxrs);
            }
            catch (Exception e) {
               e.printStackTrace();
            }
         }
      };
      t.start();
   }
}

import java.util.concurrent.Future;
import javax.ws.rs.client.Client;
...

@Test
public void AsyncGetTest() throws Exception {
    Client client = ClientBuilder.newClient();
    Future<String> future = client.target(generateURL("/test")).request().async().get(String.class);
    String entity = future.get();
    Assert.assertEquals("get", entity);
}

import javax.ws.rs.client.InvocationCallback;
...

@Test
public void AsyncCallbackGetTest() throws Exception {
    Client client = ClientBuilder.newClient();
	final CountDownLatch latch = new CountDownLatch(1);
        Future<Response> future = client.target(generateURL("/test")).request().async().get(new InvocationCallback<Response>() {
         	@Override
                public void completed(Response response) {
                    String entity = response.readEntity(String.class);
                    Assert.assertEquals("get", entity);
                    latch.countDown();
                }

                @Override
                public void failed(Throwable error) {
                }
            });
            Response res = future.get();
            Assert.assertEquals(HttpResponseCodes.SC_OK, res.getStatus());
            Assert.assertTrue("Asynchronous invocation didn't use custom implemented Invocation callback", latch.await(5, imeUnit.SECONDS));
}

With the addition of parameter names in the bytecode, you are no longer required to specify the parameter names in the following annotations: @PathParam, @QueryParam, @FormParam, @CookieParam, @HeaderParam and @MatrixParam. To do so, you must switch to the new annotations with the same name, in a different package, which have an optional value parameter. You can achieve this by following the steps below:

Consider the following usage for an example:

import org.jboss.resteasy.annotations.jaxrs.*;

@Path("/library")
public class Library {

   @GET
   @Path("/book/{isbn}")
   public String getBook(@PathParam String isbn) {
      // search my database and get a string representation and return it
   }
}

If your annotated variable does not have the same name as the path parameter, you can specify the name as shown below:

import org.jboss.resteasy.annotations.jaxrs.*;

@Path("/library")
public class Library {

   @GET
   @Path("/book/{isbn}")
   public String getBook(@PathParam("isbn") String id) {
      // search my database and get a string representation and return it
   }
}

Some clients, such as browsers, cannot use the Accept and Accept-Language headers to negotiate the representation media type or language. RESTEasy can map file name suffixes to media types and languages to deal with this issue.

To map media types to file extensions using the web.xml file, you need to add a resteasy.media.type.mappings context param and the list of mappings as the param-value. The list is comma separated and uses colons (:) to delimit the file extension and media type.

<context-param>
    <param-name>resteasy.media.type.mappings</param-name>
    <param-value>html : text/html, json : application/json, xml : application/xml</param-value>
</context-param>

In this example, the following URL variants for http://localhost:8080/my-application/test would be mapped:

Some clients, such as browsers, cannot use the Accept and Accept-Language headers to negotiate the representation media type or language. RESTEasy can map file name suffixes to media types and languages to deal with this issue. Follow these steps to map languages to file extensions, in the web.xml file.

To map media types to file extensions using the web.xml file, you need to add a resteasy.language.mappings context param and the list of mappings as the param-value. The list is comma separated and uses colons (:) to delimit the file extension and language type.

<context-param>
    <param-name>resteasy.language.mappings</param-name>
    <param-value> en : en-US, es : es, fr : fr</param-name>
</context-param>

In this example, the following URL variants for http://localhost:8080/my-application/test would be mapped:

RESTEasy can automatically marshal and unmarshal a few different message bodies.

The JAX-RS specification allows you to plug in your own request/response body readers and writers. To do this, you annotate a class with @Provider and specify the @Produces types for a writer and @Consumes types for a reader. You must also implement a MessageBodyReader/Writer interface.

The RESTEasy ServletContextLoader automatically scans the WEB-INF/lib and classes directories for classes annotated with @Provider, or you can manually configure them in the web.xml file.

javax.ws.rs.ext.Providers is a simple injectable interface that allows you to look up MessageBodyReaders, Writers, ContextResolvers, and ExceptionMappers. It is very useful for implementing multipart providers and content types that embed other random content types.

public interface Providers {
  <T> MessageBodyReader<T> getMessageBodyReader(Class<T> type, Type genericType, Annotation annotations[], MediaType mediaType);
  <T> MessageBodyWriter<T> getMessageBodyWriter(Class<T> type, Type genericType, Annotation annotations[], MediaType mediaType);
  <T extends="" throwable=""> ExceptionMapper<T> getExceptionMapper(Class<T> type);
  <T> ContextResolver<T> getContextResolver(Class<T> contextType, MediaType mediaType);
}

A Providers instance is injectable into MessageBodyReader or Writers:

@Provider
@Consumes("multipart/fixed")
public class MultipartProvider implements MessageBodyReader {

  private @Context Providers providers;
  ...
}

XML document parsers are subject to a form of attack known as the XXE (XML eXternal Entity) attack, in which expanding an external entity causes an unsafe file to be loaded. For example, the following document could cause the /etc/passwd file to be loaded.

<!--?xml version="1.0"?-->
<!DOCTYPE foo
[<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
<search>
 <user>bill</user>
 <file>&xxe;<file>
</search>

By default, the RESTEasy built-in unmarshaller for org.w3c.dom.Document documents does not expand external entities. It replaces them with an empty string. You can configure it to replace external entities with values defined in the DTD. This is done by setting the resteasy.document.expand.entity.references context parameter to true in the web.xml file.

<context-param>
 <param-name>resteasy.document.expand.entity.references</param-name>
 <param-value>true</param-value>
</context-param>

Another way of dealing with the problem is by prohibiting DTDs, which RESTEasy does by default. This behavior can be changed by setting the resteasy.document.secure.disableDTDs context parameter to false.

<context-param>
 <param-name>resteasy.document.secure.disableDTDs</param-name>
 <param-value>false</param-value>
</context-param>

Documents are also subject to Denial of Service Attacks when buffers are overrun by large entities or too many attributes. For example, if a DTD defined the following entities, the expansion of &foo6; would result in 1,000,000 foos.

<!--ENTITY foo 'foo'-->
<!--ENTITY foo1 '&foo;&foo;&foo;&foo;&foo;&foo;&foo;&foo;&foo;&foo;'-->
<!--ENTITY foo2 '&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;&foo1;'-->
<!--ENTITY foo3 '&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;&foo2;'-->
<!--ENTITY foo4 '&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;&foo3;'-->
<!--ENTITY foo5 '&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;&foo4;'-->
<!--ENTITY foo6 '&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;&foo5;'-->

By default, RESTEasy limits the number of expansions and the number of attributes per entity. The exact behavior depends on the underlying parser. The limit can be turned off by setting the resteasy.document.secure.processing.feature context parameter to false.

<context-param>
 <param-name>resteasy.document.secure.processing.feature</param-name>
 <param-value>false</param-value>
</context-param>

You can use MapProvider to accept and return a map with JAX-RS resources.

@Path("manipulateMap")
@POST
@Consumes("application/x-www-form-urlencoded")
@Produces("application/x-www-form-urlencoded")
public MultivaluedMap<String, String> manipulateMap(MultivaluedMap<String, String> map) {
  //do something
  return map;
}

You can also send and receive maps to JAX-RS resources using the client.

MultivaluedMap<String, String> map = new MultivaluedHashMap<String, String>();

//add values to the map...

Response response = client.target(generateURL("/manipulateMap"))
                          .request(MediaType.APPLICATION_FORM_URLENCODED_TYPE)
                          .post(Entity.entity(map, MediaType.APPLICATION_FORM_URLENCODED_TYPE));

String data = response.readEntity(String.class);

//handle data...

JAX-RS @*Param annotations, including @QueryParam, @MatrixParam, @HeaderParam, @PathParam, and @FormParam, are represented as strings in a raw HTTP request. These types of injected parameters can be converted to objects if these objects have a valueOf(String) static method or a constructor that takes one String parameter.

If you have a class where the valueOf() method or the string constructor does not exist or is inappropriate for an HTTP request, JAX-RS provides the javax.ws.rs.ext.ParamConverterProvider and javax.ws.rs.ext.ParamConverter to help convert the message parameter value to the corresponding custom Java type. ParamConverterProvider must be either programmatically registered in a JAX-RS runtime or must be annotated with @Provider annotation to be automatically discovered by the JAX-RS runtime during a provider scanning phase.

For example: The steps below demonstrate how to create a custom POJO object. The conversion from message parameter value such as @QueryParam, @PathParam, @MatrixParam, @HeaderParam into POJO object is done by implementation of ParamConverter and ParamConverterProvider interfaces.

Extending the Functionality of the ParamConverter

In the JAX-RS semantics, a ParamConverter converts a single string that represents an individual object. RESTEasy extends the semantics to allow a ParamConverter to parse the string representation of multiple objects and generate a List<T>, Set<T>, SortedSet<T>, array, or any other multi-valued data structure.

For an example, consider the resource:

@Path("queryParam")
public static class TestResource {
   @GET
   @Path("")
   public Response conversion(@QueryParam("q") List<String> list) {
      return Response.ok(stringify(list)).build();
   }
}

private static <T> String stringify(List<T> list) {
   StringBuffer sb = new StringBuffer();
   for (T s : list) {
      sb.append(s).append(',');
   }
   return sb.toString();
}

Calling TestResource as follows, using the standard notation:

@Test
public void testQueryParamStandard() throws Exception {
   ResteasyClient client = new ResteasyClientBuilder().build();
   Invocation.Builder request = client.target("http://localhost:8081/queryParam?q=20161217&q=20161218&q=20161219").request();
   Response response = request.get();
   System.out.println("response: " + response.readEntity(String.class));
}

results in response: 20161217,20161218,20161219,.

If you want to use a comma-separated notation instead, you can add:

public static class MultiValuedParamConverterProvider implements ParamConverterProvider
   @SuppressWarnings("unchecked")
   @Override
   public <T> ParamConverter<T> getConverter(Class<T> rawType, Type genericType, Annotation[] annotations) {
      if (List.class.isAssignableFrom(rawType)) {
         return (ParamConverter<T>) new MultiValuedParamConverter();
      }
      return null;
   }
}

public static class MultiValuedParamConverter implements ParamConverter<List<?>> {
   @Override
   public List<?> fromString(String param) {
      if (param == null || param.trim().isEmpty()) {
         return null;
      }
      return parse(param.split(","));
   }

   @Override
   public String toString(List<?> list) {
      if (list == null || list.isEmpty()) {
         return null;
      }
      return stringify(list);
   }

   private static List<String> parse(String[] params) {
      List<String> list = new ArrayList<String>();
      for (String param : params) {
         list.add(param);
      }
      return list;
   }
}

Now you can call TestResource as follows:

@Test
public void testQueryParamCustom() throws Exception {
   ResteasyClient client = new ResteasyClientBuilder().build();
   Invocation.Builder request = client.target("http://localhost:8081/queryParam?q=20161217,20161218,20161219").request();
   Response response = request.get();
   System.out.println("response: " + response.readEntity(String.class));
}

and get response: 20161217,20161218,20161219,.

In this case, the MultiValuedParamConverter.fromString() function creates and returns an ArrayList, so that the TestResource.conversion() function can be rewritten:

@Path("queryParam")
public static class TestResource {

   @GET
   @Path("")
   public Response conversion(@QueryParam("q") ArrayList<String> list) {
      return Response.ok(stringify(list)).build();
   }
}

Alternatively, MultiValuedParamConverter can be rewritten to return a LinkList and the parameter list in TestResource.conversion() can be either a List or a LinkedList.

Finally, note that this extension works for arrays as well. For example,

public static class Foo {
    private String foo;
    public Foo(String foo) {
        this.foo = foo;
    }
    public String getFoo() {
        return foo;
    }
}

public static class FooArrayParamConverter implements ParamConverter < Foo[] > {
    @Override
    public Foo[] fromString(String value) {
        String[] ss = value.split(",");
        Foo[] fs = new Foo[ss.length];
        int i = 0;
        for (String s: ss) {
            fs[i++] = new Foo(s);
        }
        return fs;
    }

    @Override
    public String toString(Foo[] values) {
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < values.length; i++) {
            sb.append(values[i].getFoo()).append(",");
        }
        if (sb.length() > 0) {
            sb.deleteCharAt(sb.length() - 1);
        }
        return sb.toString();
    }
}

@Provider
public static class FooArrayParamConverterProvider implements ParamConverterProvider {
    @SuppressWarnings("unchecked")
    @Override
    public < T > ParamConverter < T > getConverter(Class < T > rawType, Type genericType, Annotation[] annotations) {
        if (rawType.equals(Foo[].class));
        return (ParamConverter < T > ) new FooArrayParamConverter();
    }
}

@Path("")
public static class ParamConverterResource {

    @GET
    @Path("test")
    public Response test(@QueryParam("foos") Foo[] foos) {
        return Response.ok(new FooArrayParamConverter().toString(foos)).build();
    }
}

Deserializing Java objects from untrusted sources is not safe. Therefore, org.jboss.resteasy.plugins.providers.SerializableProvider is disabled by default. It is not recommended to use this provider.

RESTEasy’s JAXB providers have a pluggable way to decorate Marshaller and Unmarshaller instances. You can create an annotation that can trigger either a Marshaller or Unmarshaller instance, which can be used to decorate methods.

Create a JAXB Decorator with RESTEasy

You have now created a JAXB decorator, which can be applied within a JAX-RS web service.

The multipart MIME format is used to pass lists of content bodies embedded in one message. One example of a multipart MIME format is the multipart/form-data MIME type. This is often found in web application HTML form documents and is generally used to upload files. The form-data format in this MIME type is the same as other multipart formats, except that each inlined piece of content has a name associated with it.

RESTEasy allows for the multipart/form-data and multipart/* MIME types. RESTEasy also provides a custom API for reading and writing multipart types as well as marshalling arbitrary List (for any multipart type) and Map (multipart/form-data only) objects.

package org.jboss.resteasy.plugins.providers.multipart;

public interface MultipartInput {

   List<InputPart> getParts();
   String getPreamble();

   // You must call close to delete any temporary files created
   // Otherwise they will be deleted on garbage collection or on JVM exit
   void close();
}

public interface InputPart {

   MultivaluedMap<String, String> getHeaders();
   String getBodyAsString();
   <T> T getBody(Class<T> type, Type genericType) throws IOException;
   <T> T getBody(org.jboss.resteasy.util.GenericType<T> type) throws IOException;
   MediaType getMediaType();
   boolean isContentTypeFromMessage();
}

@Path("/multipart")
public class MyService {

    @PUT
    @Consumes("multipart/mixed")
    public void put(MultipartInput input) {
        List<Customer> customers = new ArrayList...;
        for (InputPart part : input.getParts()) {
            Customer cust = part.getBody(Customer.class, null);
            customers.add(cust);
        }
        input.close();
    }
}

@Path("/multipart")
public class MyService {

    @PUT
    @Consumes("multipart/mixed")
    public void put(MultipartInput input) {
        for (InputPart part : input.getParts()) {
            List<Customer> cust = part.getBody(new GenericType<List<Customer>>() {});
        }
        input.close();
    }
}

@Path("/multipart")
public class MyService {

    @PUT
    @Consumes("multipart/mixed")
    public void put(List<Customer> customers) {
        ...
    }
}

public interface MultipartFormDataInput extends MultipartInput {

    @Deprecated
    Map<String, InputPart> getFormData();
    Map<String, List<InputPart>> getFormDataMap();
    <T> T getFormDataPart(String key, Class<T> rawType, Type genericType) throws IOException;
    <T> T getFormDataPart(String key, GenericType<T> type) throws IOException;
}

@Path("/multipart")
public class MyService {

    @PUT
    @Consumes("multipart/form-data")
    public void put(Map<String, Customer> customers) {
        ...
    }
}

public interface MultipartRelatedInput extends MultipartInput {

    String getType();
    String getStart();
    String getStartInfo();
    InputPart getRootPart();
    Map<String, InputPart> getRelatedMap();
}

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartOutput {

    public OutputPart addPart(Object entity, MediaType mediaType)
    public OutputPart addPart(Object entity, GenericType type, MediaType mediaType)
    public OutputPart addPart(Object entity, Class type, Type genericType, MediaType mediaType)
    public List<OutputPart> getParts()
    public String getBoundary()
    public void setBoundary(String boundary)
}

public class OutputPart {

    public MultivaluedMap<String, Object> getHeaders()
    public Object getEntity()
    public Class getType()
    public Type getGenericType()
    public MediaType getMediaType()
}

@Path("/multipart")
public class MyService {

    @GET
    @Produces("multipart/mixed")
    public MultipartOutput get() {

        MultipartOutput output = new MultipartOutput();
        output.addPart(new Customer("bill"), MediaType.APPLICATION_XML_TYPE);
        output.addPart(new Customer("monica"), MediaType.APPLICATION_XML_TYPE);
        return output;
    }
}

@Path("/multipart")
public class MyService {

    @GET
    @Produces("multipart/mixed")
    @PartType("application/xml")
    public List<Customer> get(){
        ...
    }
}

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartFormDataOutput extends MultipartOutput {

    public OutputPart addFormData(String key, Object entity, MediaType mediaType)
    public OutputPart addFormData(String key, Object entity, GenericType type, MediaType mediaType)
    public OutputPart addFormData(String key, Object entity, Class type, Type genericType, MediaType mediaType)
    public Map<String, OutputPart> getFormData()
}

@Path("/form")
public class MyService {

    @GET
    @Produces("multipart/form-data")
    public MultipartFormDataOutput get() {

        MultipartFormDataOutput output = new MultipartFormDataOutput();
        output.addPart("bill", new Customer("bill"), MediaType.APPLICATION_XML_TYPE);
        output.addPart("monica", new Customer("monica"), MediaType.APPLICATION_XML_TYPE);
        return output;
    }
}

@Path("/multipart")
public class MyService {

    @GET
    @Produces("multipart/form-data")
    @PartType("application/xml")
    public Map<String, Customer> get() {
        ...
    }
}

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartRelatedOutput extends MultipartOutput {

    public OutputPart getRootPart()
    public OutputPart addPart(Object entity, MediaType mediaType,
        String contentId, String contentTransferEncoding)
    public String getStartInfo()
    public void setStartInfo(String startInfo)
}

@Path("/related")
public class MyService {

    @GET
    @Produces("multipart/related")
    public MultipartRelatedOutput get() {

        MultipartRelatedOutput output = new MultipartRelatedOutput();
        output.setStartInfo("text/html");

        Map<String, String> mediaTypeParameters = new LinkedHashMap<String, String>();
        mediaTypeParameters.put("charset", "UTF-8");
        mediaTypeParameters.put("type", "text/html");
        output.addPart(
            "<html><body>\n"
            + "This is me: <img src='cid:http://example.org/me.png' />\n"
            + "<br />This is you: <img src='cid:http://example.org/you.png' />\n"
            + "</body></html>",
            new MediaType("text", "html", mediaTypeParameters),
            "<mymessage.xml@example.org>", "8bit");
        output.addPart("// binary octets for me png",
            new MediaType("image", "png"), "<http://example.org/me.png>",
            "binary");
        output.addPart("// binary octets for you png", new MediaType(
            "image", "png"),
            "<http://example.org/you.png>", "binary");
        client.putRelated(output);
        return output;
    }
}

public class CustomerProblemForm {

    @FormParam("customer")
    @PartType("application/xml")
    private Customer customer;

    @FormParam("problem")
    @PartType("text/plain")
    private String problem;

    public Customer getCustomer() { return customer; }
    public void setCustomer(Customer cust) { this.customer = cust; }
    public String getProblem() { return problem; }
    public void setProblem(String problem) { this.problem = problem; }
}

@Path("portal")
public interface CustomerPortal {

    @Path("issues/{id}")
    @Consumes("multipart/form-data")
    @PUT
    public void putProblem(@MultipartForm CustomerProblemForm,
                           @PathParam("id") int id);
}

// Somewhere using it:
{
    CustomerPortal portal = ProxyFactory.create(CustomerPortal.class, "http://example.com");
    CustomerProblemForm form = new CustomerProblemForm();
    form.setCustomer(...);
    form.setProblem(...);

    portal.putProblem(form, 333);
}

@Path("portal")
public class CustomerPortalServer {

    @Path("issues/{id})
    @Consumes("multipart/form-data")
    @PUT
    public void putIssue(@MultipartForm CustomerProblemForm,
                         @PathParam("id") int id) {
       ... write to database...
    }
}

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public static class Xop {

    private Customer bill;
    private Customer monica;

    @XmlMimeType(MediaType.APPLICATION_OCTET_STREAM)
    private byte[] myBinary;

    @XmlMimeType(MediaType.APPLICATION_OCTET_STREAM)
    private DataHandler myDataHandler;

    // methods, other fields ...
}

// our client interface:
@Path("mime")
public static interface MultipartClient {
    @Path("xop")
    @PUT
    @Consumes(MultipartConstants.MULTIPART_RELATED)
    public void putXop(@XopWithMultipartRelated Xop bean);
}

// Somewhere using it:
{
    MultipartClient client = ProxyFactory.create(MultipartClient.class,
        "http://www.example.org");
    Xop xop = new Xop(new Customer("bill"), new Customer("monica"),
        "Hello Xop World!".getBytes("UTF-8"),
        new DataHandler(new ByteArrayDataSource("Hello Xop World!".getBytes("UTF-8"),
        MediaType.APPLICATION_OCTET_STREAM)));
    client.putXop(xop);
}

@Path("/mime")
public class XopService {
    @PUT
    @Path("xop")
    @Consumes(MultipartConstants.MULTIPART_RELATED)
    public void putXopWithMultipartRelated(@XopWithMultipartRelated Xop xop) {
        // do very important things here
    }
}

import org.jboss.resteasy.plugins.providers.multipart.InputPart;

@Provider
@ServerInterceptor
public class ContentTypeSetterPreProcessorInterceptor implements PreProcessInterceptor {

    public ServerResponse preProcess(HttpRequest request, ResourceMethod method)
            throws Failure, WebApplicationException {
        request.setAttribute(InputPart.DEFAULT_CONTENT_TYPE_PROPERTY, "*/*; charset=UTF-8");
        return null;
    }
}

@POST
@Path("query")
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces(MediaType.TEXT_PLAIN)
public Response setMediaType(MultipartInput input) throws IOException {

    List<InputPart> parts = input.getParts();
    InputPart part = parts.get(0);
    part.setMediaType(MediaType.valueOf("application/foo+xml"));
    String s = part.getBody(String.class, null);
    ...
}

import org.jboss.resteasy.plugins.providers.multipart.InputPart;

@Provider
@ServerInterceptor
public class ContentTypeSetterPreProcessorInterceptor implements PreProcessInterceptor {

    public ServerResponse preProcess(HttpRequest request, ResourceMethod method)
            throws Failure, WebApplicationException {
        request.setAttribute(InputPart.DEFAULT_CHARSET_PROPERTY, "UTF-8");
        return null;
    }
}

<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-client</artifactId>
  <version>${version.org.jboss.resteasy}</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-multipart-provider</artifactId>
  <version>${version.org.jboss.resteasy}</version>
  <scope>provided</scope>
</dependency>

ResteasyClient client = new ResteasyClientBuilder().build();
ResteasyWebTarget target = client.target("http://foo.com/resource");

MultipartFormDataOutput formOutputData = new MultipartFormDataOutput();
formOutputData.addFormData("part1", "this is part 1", MediaType.TEXT_PLAIN);
formOutputData.addFormData("part2", "this is part 2", MediaType.TEXT_PLAIN);

GenericEntity<MultipartFormDataOutput> data = new GenericEntity<MultipartFormDataOutput>(formOutputData) { };

Response response = target.request().put(Entity.entity(data, MediaType.MULTIPART_FORM_DATA_TYPE));

response.close();

The RESTEasy Atom API and Provider is a simple object model that RESTEasy defines to represent Atom. The main classes for the API are in the org.jboss.resteasy.plugins.providers.atom package. RESTEasy uses JAXB to marshal and unmarshal the API. The provider is JAXB based, and is not limited to sending Atom objects using XML. All JAXB providers that RESTEasy has can be reused by the Atom API and provider, including JSON.

import org.jboss.resteasy.plugins.providers.atom.Content;
import org.jboss.resteasy.plugins.providers.atom.Entry;
import org.jboss.resteasy.plugins.providers.atom.Feed;
import org.jboss.resteasy.plugins.providers.atom.Link;
import org.jboss.resteasy.plugins.providers.atom.Person;

@Path("atom")
public class MyAtomService {

   @GET
   @Path("feed")
   @Produces("application/atom+xml")
   public Feed getFeed() throws URISyntaxException {
      Feed feed = new Feed();
      feed.setId(new URI("http://example.com/42"));
      feed.setTitle("My Feed");
      feed.setUpdated(new Date());
      Link link = new Link();
      link.setHref(new URI("http://localhost"));
      link.setRel("edit");
      feed.getLinks().add(link);
      feed.getAuthors().add(new Person("John Brown"));
      Entry entry = new Entry();
      entry.setTitle("Hello World");
      Content content = new Content();
      content.setType(MediaType.TEXT_HTML_TYPE);
      content.setText("Nothing much");
      entry.setContent(content);
      feed.getEntries().add(entry);
      return feed;
   }
}

@XmlRootElement(namespace = "http://jboss.org/Customer")
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
   @XmlElement
   private String name;

   public Customer() {
   }

   public Customer(String name) {
      this.name = name;
   }

   public String getName() {
      return name;
   }
}

@Path("atom")
public static class AtomServer {
   @GET
   @Path("entry")
   @Produces("application/atom+xml")
   public Entry getEntry() {
      Entry entry = new Entry();
      entry.setTitle("Hello World");
      Content content = new Content();
      content.setJAXBObject(new Customer("bill"));
      entry.setContent(content);
      return entry;
   }
}

@Path("atom")
public static class AtomServer {
   @PUT
   @Path("entry")
   @Produces("application/atom+xml")
   public void putCustomer(Entry entry) {
      Content content = entry.getContent();
      Customer cust = content.getJAXBObject(Customer.class);
   }
}

RESTEasy comes with built in support for YAML using the SnakeYAML library.

In releases prior to JBoss EAP 7.1, the YAML provider setting was enabled by default and you only needed to configure the Maven dependencies for YAML to use it in your application. Starting with JBoss EAP 7.1, the YAML provider is disabled by default and must be explicitly enabled in the application.

Enable the YAML Provider

To enable the YAML provider in your application, follow these steps:

YAML Provider Maven Dependencies

To use the YAML provider in your application, you must add the snakeyaml JAR dependencies to the project POM file of your application.

<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-yaml-provider</artifactId>
    <version>${version.org.jboss.resteasy}</version>
    <scope>provided</scope>
</dependency>

<dependency>
    <groupId>org.yaml</groupId>
    <artifactId>snakeyaml</artifactId>
    <version>${version.org.yaml.snakeyaml}</version>
</dependency>

YAML Provider Code Example

The YAML provider recognizes three mime types:

The following is an example of how to use YAML in a resource method.

import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

@Path("/yaml")
public class YamlResource {

  @GET
  @Produces("text/x-yaml")
  public MyObject getMyObject() {
    return createMyObject();
  }
...
}

A CDI bean that does not explicitly define a scope is @Dependent scoped by default. This pseudo-scope means that the bean adapts to the lifecycle of the bean that it is injected into. Normal scopes, including request, session, and application, are more suitable for JAX-RS components as they designate the component’s lifecycle boundaries explicitly. Therefore, the resteasy-cdi module alters the default scoping in the following way:

The resteasy-cdi module is bundled with JBoss EAP. Therefore, there is no need to download the module separately or add any additional configuration. See the kitchensink quickstart that ships with JBoss EAP for a working example of using CDI beans with a JAX-RS resource.

On the server side, you have two different types of filters: ContainerRequestFilters and ContainerResponseFilters. ContainerRequestFilters run before your JAX-RS resource method is invoked. ContainerResponseFilters run after your JAX-RS resource method is invoked.

In addition, there are two types of ContainerRequestFilters: pre-matching and post-matching. Pre-matching ContainerRequestFilters are designated with the @PreMatching annotation and execute before the JAX-RS resource method is matched with the incoming HTTP request. Post-matching ContainerRequestFilters are designated with the @PostMatching annotation and execute after the JAX-RS resource method is matched with the incoming HTTP request.

Pre-matching filters often are used to modify request attributes to change how it matches to a specific resource method, for example to strip .xml and add an Accept header. ContainerRequestFilters can abort the request by calling ContainerRequestContext.abortWith(Response). For example, a filter might want to abort if it implements a custom authentication protocol.

After the resource class method is executed, JAX-RS runs all ContainerResponseFilters. These filters allow you to modify the outgoing response before it is marshalled and sent to the client.

public class RoleBasedSecurityFilter implements ContainerRequestFilter {
  protected String[] rolesAllowed;
  protected boolean denyAll;
  protected boolean permitAll;

  public RoleBasedSecurityFilter(String[] rolesAllowed, boolean denyAll, boolean permitAll) {
    this.rolesAllowed = rolesAllowed;
    this.denyAll = denyAll;
    this.permitAll = permitAll;
  }

  @Override
  public void filter(ContainerRequestContext requestContext) throws IOException  {
    if (denyAll) {
       requestContext.abortWith(Response.status(403).entity("Access forbidden: role not allowed").build());
       return;
    }
    if (permitAll) return;
    if (rolesAllowed != null) {
       SecurityContext context = ResteasyProviderFactory.getContextData(SecurityContext.class);
       if (context != null) {
          for (String role : rolesAllowed) {
             if (context.isUserInRole(role)) return;
          }
          requestContext.abortWith(Response.status(403).entity("Access forbidden: role not allowed").build());
          return;
       }
    }
    return;
  }
}

public class CacheControlFilter implements ContainerResponseFilter {
   private int maxAge;

   public CacheControlFilter(int maxAge) {
      this.maxAge = maxAge;
   }

   public void filter(ContainerRequestContext req, ContainerResponseContext res)
           throws IOException {
      if (req.getMethod().equals("GET")) {
         CacheControl cc = new CacheControl();
         cc.setMaxAge(this.maxAge);
         res.getHeaders().add("Cache-Control", cc);
      }
   }
}

More information on client-side filters can be found in the JAX-RS Client API section of this guide.

RESTEasy supports GZIP compression and decompression. To support GZIP decompression, the client framework or a JAX-RS service automatically decompresses a message body with a Content-Encoding of gzip, and it can automatically set the Accept-Encoding header to gzip, deflate so that you do not have to set this header manually. To support GZIP compression, RESTEasy compresses the outgoing message if the client framework is sending a request or if the server is sending a response with the Content-Encoding header set to gzip. You can use the @org.jboss.resteasy.annotation.GZIP annotation to set the Content-Encoding header.

The following example tags the outgoing message body order to be gzip compressed.

@Path("/")
public interface MyProxy {

   @Consumes("application/xml")
   @PUT
   public void put(@GZIP Order order);
}

@Path("/")
public class MyService {

   @GET
   @Produces("application/xml")
   @GZIP
   public String getData() {...}
}

Client client = new ResteasyClientBuilder() // Activate gzip compression on client:
    .register(AcceptEncodingGZIPFilter.class)
    .register(GZIPDecodingInterceptor.class)
    .register(GZIPEncodingInterceptor.class)
    .build();

Client client = new ResteasyClientBuilder() // Activate gzip compression on client:
    .register(AcceptEncodingGZIPFilter.class)
    .register(new GZIPDecodingInterceptor(256))
    .register(GZIPEncodingInterceptor.class)
    .build();

Sometimes you want a filter or interceptor to only run for a specific resource method. You can do this in two different ways:

Implement the DynamicFeature Interface

The DynamicFeature interface includes a callback method, configure(ResourceInfo resourceInfo, FeatureContext context), which is invoked for each and every deployed JAX-RS method. The ResourceInfo parameter contains information about the current JAX-RS method being deployed. FeatureContext is an extension of the Configurable interface. You can use the register() method of this parameter to bind the filters and interceptors that you want to assign to this method.

@Provider
public class AnimalTypeFeature implements DynamicFeature {
    @Override
    public void configure(ResourceInfo info, FeatureContext context) {
        if (info.getResourceMethod().getAnnotation(GET.class) != null)
            AnimalFilter filter = new AnimalFilter();
            context.register(filter);
        }
    }
}

In the example above, the provider that you register using AnimalTypeFeature must implement one of the interfaces. This example registers the provider AnimalFilter that must implement one of the following interfaces: ContainerRequestFilter, ContainerResponseFilter, ReaderInterceptor, WriterInterceptor, or Feature. In this case AnimalFilter will be applied to all resource methods annotated with GET annotation. See DynamicFeature Documentation for details.

Use the @NameBinding Annotation

@NameBinding works a lot like CDI interceptors. You annotate a custom annotation with @NameBinding and then apply that custom annotation to your filter and resource method.

@NameBinding
public @interface DoIt {}

@DoIt
public class MyFilter implements ContainerRequestFilter {...}

@Path("/root")
public class MyResource {

   @GET
   @DoIt
   public String get() {...}
}

See NameBinding Documentation for details.

Ordering is accomplished by using the @Priority annotation on your filter or interceptor class.

Exceptions associated with filters or interceptors can occur on either the client side or the server side. On the client side, there are two types of exceptions you will have to handle: javax.ws.rs.client.ProcessingException and javax.ws.rs.client.ResponseProcessingException. A javax.ws.rs.client.ProcessingException will be thrown on the client side if there was an error before a request is sent to the server. A javax.ws.rs.client.ResponseProcessingException will be thrown on the client side if there was an error in processing the response received by the client from the server.

On the server side, exceptions thrown by filters or interceptors are handled in the same way as other exceptions thrown from JAX-RS methods, which tries to find an ExceptionMapper for the exception being thrown. More details on how exceptions are handled in JAX-RS methods can be found in the Exception Handling section.

Exception mappers are custom components provided by applications that catch thrown exceptions and write specific HTTP responses.

When you create an exception mapper, you create a class that is annotated with the @Provider annotation and implements the ExceptionMapper interface.

An example exception mapper is provided below:

@Provider
public class EJBExceptionMapper implements ExceptionMapper<javax.ejb.EJBException> {
  public Response toResponse(EJBException exception) {
    return Response.status(500).build();
  }
}

To register an exception mapper, list it in the web.xml file, under the resteasy.providers context-param, or register it programmatically through the ResteasyProviderFactory class.

Follow these steps to configure the web.xml file to enable role-based security.

Role-based security has been enabled within the application, with a set of defined roles.

<web-app>

  <context-param>
    <param-name>resteasy.role.based.security</param-name>
    <param-value>true</param-value>
  </context-param>

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Resteasy</web-resource-name>
      <url-pattern>/security</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>admin</role-name>
      <role-name>user</role-name>
    </auth-constraint>
  </security-constraint>

  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>jaxrs</realm-name>
  </login-config>

  <security-role>
    <role-name>admin</role-name>
  </security-role>
  <security-role>
    <role-name>user</role-name>
  </security-role>

</web-app>

To secure JAX-RS web services using an annotation, complete the following steps.

Below is an example that uses the @RolesAllowed annotation to specify that the admin role can access the web service.

@RolesAllowed("admin")
@Path("/test")
public class TestService {
  ...
}

JAX-RS includes a programmatic API for gathering security information about a secured request. The javax.ws.rs.core.SecurityContext interface has a method for determining the identity of the user making the secured HTTP invocation. It also has a method that allows you to check whether or not the current user belongs to a certain role:

public interface SecurityContext {

   public Principal getUserPrincipal();
   public boolean isUserInRole(String role);
   public boolean isSecure();
   public String getAuthenticationScheme();
}

You can access a SecurityContext instance by injecting it into a field, setter method, or resource method parameter using the @Context annotation.

@Path("test")
public class SecurityContextResource {
    @Context
    SecurityContext securityContext;

    @GET
    @Produces("text/plain")
    public String get() {
        if (!securityContext.isUserInRole("admin")) {
            throw new WebApplicationException(Response.serverError().status(HttpResponseCodes.SC_UNAUTHORIZED)
                    .entity("User " + securityContext.getUserPrincipal().getName() + " is not authorized").build());
        }
        return "Good user " + securityContext.getUserPrincipal().getName();
    }
}

Enable the asynchronous job service in the web.xml file:

<context-param>
    <param-name>resteasy.async.job.service.enabled</param-name>
    <param-value>true</param-value>
</context-param>

This section covers examples of the query parameters for asynchronous jobs with RESTEasy.

The asynch query parameter is used to run invocations in the background. A 202 Accepted response is returned, as well as a location header with a URL pointing to where the response of the background method is located.

POST http://example.com/myservice?asynch=true

The example above returns a 202 Accepted response. It also returns a location header with a URL pointing to where the response of the background method is located. An example of the location header is shown below:

HTTP/1.1 202 Accepted
Location: http://example.com/asynch/jobs/3332334

The URI will take the form of:

/asynch/jobs/{job-id}?wait={milliseconds}|nowait=true

GET, POST and DELETE operations can be performed on this URL.

The GET and POST operations allow for the maximum wait time to be defined, using the wait and nowait query parameters. If the wait parameter is not specified, the operation will default to nowait=true, and will not wait at all if the job is not complete. The wait parameter is defined in milliseconds.

POST http://example.com/asynch/jobs/122?wait=3000

RESTEasy supports fire and forget jobs, using the oneway query parameter.

POST http://example.com/myservice?oneway=true

The example above returns a 202 Accepted response, but no job is created.

RESTEasy can generate a JavaScript API that uses AJAX calls to invoke JAX-RS operations. Each JAX-RS resource class will generate a JavaScript object of the same name as the declaring class or interface. The JavaScript object contains each JAX-RS method as properties.

@Path("foo")
public class Foo {

  @Path("{id}")
  @GET
  public String get(@QueryParam("order") String order, @HeaderParam("X-Foo") String header,
    @MatrixParam("colour") String colour, @CookieParam("Foo-Cookie") String cookie) {
  }

  @POST
  public void post(String text) {
  }
}

The following JavaScript code uses the JAX-RS API that was generated in the previous example.

var text = Foo.get({order: 'desc', 'X-Foo': 'hello', colour: 'blue', 'Foo-Cookie': 123987235444});
Foo.post({$entity: text});

Each JavaScript API method takes an optional object as single parameter where each property is a cookie, header, path, query or form parameter as identified by its name, or the API parameter properties. For details about the API parameter properties see RESTEasy Javascript API Parameters appendix.

// Change the base URL used by the API:
REST.apiURL = "http://api.service.com";

// log everything in a div element
REST.log = function(text) {
  jQuery("#log-div").append(text);
};

var r = new REST.Request();
r.setURI("http://api.service.com/orders/23/json");
r.setMethod("PUT");
r.setContentType("application/json");
r.setEntity({id: "23"});
r.addMatrixParameter("JSESSIONID", "12309812378123");
r.execute(function(status, request, entity) {
  log("Response is " + status);
});

The MicroProfile REST client enables a version of distributed object communication, which is also implemented in CORBA, Java Remote Method Invocation (RMI), the JBoss Remoting Project, and RESTEasy. For example, consider the resource:

@Path("resource")
public class TestResource {
   @Path("test")
   @GET
   String test() {
      return "test";
   }
 }

The JAX-RS native way of accessing the TestResource class is:

Client client = ClientBuilder.newClient();
String response = client.target("http://localhost:8081/test").request().get(String.class);

However, Microprofile REST client supports a more intuitive syntax by directly calling the test() method:

@Path("resource")
public interface TestResourceIntf {
    @Path("test")
    @GET
    public String test();
}

TestResourceIntf service = MicroprofileClientBuilderResolver.instance()
                              .newBuilder()
                              .baseUrl(http://localhost:8081/))
                              .build(TestResourceIntf.class);
String s = service.test();

In the example above, making calls on the TestResource class becomes much easier with the TestResourceIntf class, as illustrated by the call service.test().

The following example is a more elaborate version of the TestResourceIntf class:

@Path("resource")
public interface TestResourceIntf2 {
   @Path("test/{path}")mes("text/plain")
   @Produces("text/html")
   @POST
   public String test(@PathParam("path") String path, @QueryParam("query") String query, String entity);
}

Calling the service.test("p", "q", "e") method results in an HTTP message that looks like:

POST /resource/test/p/?query=q HTTP/1.1
Accept: text/html
Content-Type: text/plain
Content-Length: 1

e

With the MicroProfile REST client, you can also configure the client environment by registering providers. For example:

TestResourceIntf service = MicroprofileClientBuilderResolver.instance()
                              .newBuilder()
                              .baseUrl(http://localhost:8081/))
                              .register(MyClientResponseFilter.class)
                              .register(MyMessageBodyReader.class)
                              .build(TestResourceIntf.class);

Declaring the MyClientResponseFilter class and the MyMessageBodyReader class with annotations eliminates the need to call the RestClientBuilder.register() method.

You can also register providers declaratively with annotations introduced in MicroProfile REST client. You can register providers by adding the org.eclipse.microprofile.rest.client.annotation.RegisterProvider annotation to the target interface as shown below:

@Path("resource")
@RegisterProvider(MyClientResponseFilter.class)
@RegisterProvider(MyMessageBodyReader.class)
public interface TestResourceIntf2 {
   @Path("test/{path}")
   @Consumes("text/plain")
   @Produces("text/html")
   @POST
   public String test(@PathParam("path") String path, @QueryParam("query") String query, String entity);
}

Declaring the MyClientResponseFilter class and the MyMessageBodyReader class with annotations eliminates the need to call the RestClientBuilder.register() method.

The org.eclipse.microprofile.rest.client.ext.ResponseExceptionMapper class is the client-side inverse of the javax.ws.rs.ext.ExceptionMapper class defined in JAX-RS. That is, where the ExceptionMapper.toResponse() method turns an Exception class thrown during the server-side processing into a Response class, the ResponseExceptionMapper.toThrowable() method turns a Response class received on the client-side with an HTTP error status into an Exception class.

You can register the ResponseExceptionMapper class either programmatically or declaratively. In the absence of a registered ResponseExceptionMapper class, a default ResponseExceptionMapper class maps any response with status >= 400 to a WebApplicationException class.

In MicroProfile REST client, you must annotate any interface that is managed as a CDI bean with the @RegisterRestClient class. For example:

@Path("resource")
@RegisterProvider(MyClientResponseFilter.class)
public static class TestResourceImpl {
      @Inject TestDataBase db;

      @Path("test/{path}")
      @Consumes("text/plain")
      @Produces("text/html")
      @POST
      public String test(@PathParam("path") String path, @QueryParam("query")
      String query, String entity) {
         return db.getByName(query);
      }
   }
   @Path("database")
   @RegisterRestClient
   public interface TestDataBase {

      @Path("")
      @POST
      public String getByName(String name);
   }

Here, the MicroProfile REST client implementation creates a client for a TestDataBase class service, allowing easy access by the TestResourceImpl class. However, it does not indicate where the TestDataBase class implementation lives. We can supply that information externally with the following system variable:

<fully qualified name of TestDataBase>/mp-rest/url=<URL>

For example, the following indicates that you can access an implementation of the com.bluemonkeydiamond.TestDatabase class at https://localhost:8080/webapp:

com.bluemonkeydiamond.TestDatabase/mp-rest/url=https://localhost:8080/webapp

JAX-RS 2.1 is extensible to support various reactive libraries. RESTEasy’s optional module resteasy-rxjava2 supports the following reactive types:

If you import resteasy-rxjava2, you can return these reactive types from your resource methods on the server side and receive them on the client side.

The resteasy-rxjava2 module supports the following three classes to access Singles, Observables, and Flowables respectively on the client side:

RESTEasy implements a framework that supports extensions for additional reactive classes. On the server side, when a resource method returns a CompletionStage type, RESTEasy subscribes to it using the org.jboss.resteasy.core.AsyncResponseConsumer.CompletionStageResponseConsumer class. When the CompletionStage completes, it calls CompletionStageResponseConsumer.accept(), which sends the result back to the client.

Support for CompletionStage is built in to RESTEasy. We can extend that support to a class like Single by providing a mechanism for transforming a Single into a CompletionStage. In the resteasy-rxjava2 module, org.jboss.resteasy.rxjava2.SingleProvider, which implements the org.jboss.resteasy.spi.AsyncResponseProvider<Single<?>> interface provides this mechanism:

public interface AsyncResponseProvider<T> {
   public CompletionStage toCompletionStage(T asyncResponse);
}

Given the SingleProvider class, RESTEasy can take a Single, transform it into a CompletionStage and then use CompletionStageResponseConsumer to handle the eventual value of the Single. Similarly, when a resource method returns a streaming reactive class like Flowable, RESTEasy subscribes to it, receives a stream of data elements, and sends them to the client. AsyncResponseConsumer has several supporting classes, each of which implements a different mode of streaming.

For example, AsyncResponseConsumer.AsyncGeneralStreamingSseResponseConsumer handles general streaming and SSE streaming. Subscription is done by calling org.reactivestreams.Publisher.subscribe(), so it needs a mechanism to turn a Flowable into a Publisher, for example. That is, an implementation of org.jboss.resteasy.spi.AsyncStreamProvider<Flowable> is called for, which defines AsyncStreamProvider as shown in the following example:

public interface AsyncStreamProvider<T> {
   public Publisher toAsyncStream(T asyncResponse);
}

In the resteasy-rxjava2 module, org.jboss.resteasy.FlowableProvider provides that mechanism for Flowable.

That means, on the server side, you can add support for other reactive types by declaring a @Provider annotation for the AsyncStreamProvider interface for streams or the AsyncResponseProvider interface for single values. Both these interfaces have a single method to convert the new reactive type into a Publisher or a CompletionStage for streams or for single values respectively.

On the client side, the JAX-RS 2.1 imposes two requirements for support of the reactive classes:

public interface RxInvokerProvider<T extends RxInvoker> {
    public boolean isProviderFor(Class<T> clazz);
    public T getRxInvoker(SyncInvoker syncInvoker, ExecutorService executorService);
}

Once an RxInvokerProvider is registered, you can request an RxInvoker by calling the javax.ws.rs.client.Invocation.Builder method:

public <T extends RxInvoker> T rx(Class<T> clazz);

You can use the RxInvoker for making an invocation that returns the appropriate reactive class. For example:

FlowableRxInvoker invoker = client.target(generateURL("/get/string")).request().rx(FlowableRxInvoker.class);
Flowable<String> flowable = (Flowable<String>) invoker.get();

RESTEasy provides partial support for implementing RxInvokers. For example, SingleProvider, mentioned above, also implements org.jboss.resteasy.spi.AsyncClientResponseProvider<Single<?>>, where AsyncClientResponseProvider is defined as the following:

public interface AsyncClientResponseProvider<T> {
   public T fromCompletionStage(CompletionStage<?> completionStage);
}

RESTEasy defines a new type of invoker named RxInvoker, and a default implementation of this type named CompletionStageRxInvoker. CompletionStageRxInvoker implements Java 8’s interface CompletionStage. This interface declares a large number of methods dedicated to managing asynchronous computations.

If you must suspend execution of your filter until a certain resource is available, you can convert it into an asynchronous filter. Turning a request asynchronous does not require any change to your resource method declaration or the additional filter declaration.

To turn a filter’s execution asynchronous, you must cast:

These context objects can turn the current filter’s execution into asynchronous by calling the suspend() method. Once asynchronous, the filter chain is suspended, and resumes only after one of the following methods is called on the context object:

Proxies are a RESTEasy extension that supports an intuitive programming style, which replaces generic JAX-RS invoker calls with application-specific interface calls. The proxy framework is extended to include both CompletionStage and the RxJava2 types Single, Observable, and Flowable. The two following examples illustrate how RESTEasy proxies work:

Example 1:

@Path("")
public interface RxCompletionStageResource {

   @GET
   @Path("get/string")
   @Produces(MediaType.TEXT_PLAIN)
   public CompletionStage<String> getString();
}

@Path("")
public class RxCompletionStageResourceImpl {

   @GET
   @Path("get/string")
   @Produces(MediaType.TEXT_PLAIN)
   public CompletionStage<String> getString() { .... }
}

public class RxCompletionStageProxyTest {

   private static ResteasyClient client;
   private static RxCompletionStageResource proxy;

   static {
      client = new ResteasyClientBuilder().build();
      proxy = client.target(generateURL("/")).proxy(RxCompletionStageResource.class);
   }

   @Test
   public void testGet() throws Exception {
      CompletionStage<String> completionStage = proxy.getString();
      Assert.assertEquals("x", completionStage.toCompletableFuture().get());
   }
}

Example 2:

public interface Rx2FlowableResource {

   @GET
   @Path("get/string")
   @Produces(MediaType.TEXT_PLAIN)
   @Stream
   public Flowable<String> getFlowable();
}

@Path("")
public class Rx2FlowableResourceImpl {

   @GET
   @Path("get/string")
   @Produces(MediaType.TEXT_PLAIN)
   @Stream
   public Flowable<String> getFlowable() { ... }
}

public class Rx2FlowableProxyTest {

   private static ResteasyClient client;
   private static Rx2FlowableResource proxy;

   static {
      client = new ResteasyClientBuilder().build();
      proxy = client.target(generateURL("/")).proxy(Rx2FlowableResource.class);
   }

   @Test
   public void testGet() throws Exception {
      Flowable<String> flowable = proxy.getFlowable();
      flowable.subscribe(
         (String o) -> stringList.add(o),
         (Throwable t) -> errors.incrementAndGet(),
         () -> latch.countDown());
      boolean waitResult = latch.await(30, TimeUnit.SECONDS);
      Assert.assertTrue("Waiting for event to be delivered has timed out.", waitResult);
      Assert.assertEquals(0, errors.get());
      Assert.assertEquals(xStringList, stringList);
   }
}