The @Path annotation is not limited to simple path expressions. Regular expressions can be inserted into a @Path's value. For example:

@Path("/resources)
public class MyResource {

   @GET
   @Path("{var:.*}/stuff")
   public String get() {...}
}

The following GETs will route to the getResource() method:

GET /resources/stuff
GET /resources/foo/stuff
GET /resources/on/and/on/stuff

The format of the expression is:

"{" variable-name [ ":" regular-expression ] "}"

The regular-expression part is optional. When the expression is not provided, it defaults to a wildcard matching of one particular segment. In regular-expression terms, the expression defaults to

"([]*)"

For example:

@Path("/resources/{var}/stuff")

will match these:

GET /resources/foo/stuff
GET /resources/bar/stuff

but will not match:

GET /resources/a/bunch/of/stuff

There are a few more complicated uses of @PathParams not discussed in the previous section.

It is allowed to specify one or more path params embedded in one URI segment. Here are some examples:

1. @Path("/aaa{param}bbb")
2. @Path("/{name}-{zip}")
3. @Path("/foo{name}-{zip}bar")

So, a URI of "/aaa111bbb" would match #1. "/bill-02115" would match #2. "foobill-02115bar" would match #3.

It was discussed before how to use regular expression patterns within @Path values.

@GET
@Path("/aaa{param:b+}/{many:.*}/stuff")
public String getIt(@PathParam("param") String bs, @PathParam("many") String many) {...}

For the following requests, lets see what the values of the "param" and "many" @PathParams would be:

The specification has a very simple abstraction for examining a fragment of the URI path being invoked on jakarta.ws.rs.core.PathSegment:

public interface PathSegment {

    /**
     * Get the path segment.
     * <p>
     * @return the path segment
     */
    String getPath();
    
    /**
     * Get a map of the matrix parameters associated with the path segment
     * @return the map of matrix parameters
     */
    MultivaluedMap<String, String> getMatrixParameters();

}

RESTEasy can inject a PathSegment instead of a value with the @PathParam.

@GET
@Path("/book/{id}")
public String getBook(@PathParam("id") PathSegment id) {...}

This is very useful if you have a bunch of @PathParams that use matrix parameters. The idea of matrix parameters is that they are an arbitrary set of name-value pairs embedded in a uri path segment. The PathSegment object gives you access to these parameters. See also MatrixParam.

A matrix parameter example is:

GET http://host.com/library/book;name=EJB 3.0;author=Bill Burke

The idea of matrix parameters is that it represents resources that are addressable by their attributes as well as their raw id.

Some clients, like browsers, cannot use the Accept and Accept-Language headers to negotiation the representation's media type or language. RESTEasy allows the mapping of file name suffixes like (.xml, .txt, .en, .fr) to media types and languages. These file name suffixes take the place and override any Accept header sent by the client. They are configured using the resteasy.media.type.mappings and resteasy.language.mappings parameters. If configured within the application's web.xml, it would look like:

<web-app>
    <display-name>Archetype Created Web Application</display-name>
    <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>

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

   ...
</web-app>

See Section 3.4, “Configuration” for more information about application configuration.

Mappings are a comma delimited list of suffix/mediatype or suffix/language mappings. Each mapping is delimited by a ':'. If GET /foo/bar.xml.en is invoked , this would be equivalent to invoking the following request:

GET /foo/bar
Accept: application/xml
Accept-Language: en-US

The mapped file suffixes are stripped from the target URL path before the request is dispatched to a corresponding Jakarta RESTful Web Services resource.

RESTEasy can do content negotiation based in a parameter in the query string. To enable this, the parameter resteasy.media.type.param.mapping should be configured in the web.xml file. It would look like the following:

<web-app>
    <display-name>Archetype Created Web Application</display-name>
    <context-param>
        <param-name>resteasy.media.type.param.mapping</param-name>
        <param-value>someName</param-value>
    </context-param>

    ...
</web-app>

See Section 3.4, “Configuration” for more information about application configuration.

The param-value is the name of the query string parameter that RESTEasy will use in the place of the Accept header.

Invoking http://service.foo.com/resouce?someName=application/xml, will give the application/xml media type the highest priority in the content negotiation.

In cases where the request contains both the parameter and the Accept header, the parameter will be more relevant.

It is possible to leave the param-value empty, that will cause the processor to look for a parameter named 'accept'.

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

Note. When a java.io.File is created, as in

@Path("/test")
public class TempFileDeletionResource
{
   @POST
   @Path("post")
   public Response post(File file) throws Exception
   {
      return Response.ok(file.getPath()).build();
   }
}
      

a temporary file is created in the file system. On the server side, that temporary file will be deleted at the end of the invocation. On the client side, however, it is the responsibility of the user to delete the temporary file.

The Jakarta RESTful Web Services specification allows the user to plug in their own request/response body reader and writers. To do this, the user annotates a class with @Provider and specify the @Produces types for a writer and @Consumes types for a reader. The user must also implement a MessageBodyReader/Writer interface respectively. Here is an example:

         @Provider
         @Produces("text/plain")
         @Consumes("text/plain")
         public class DefaultTextPlain implements MessageBodyReader, MessageBodyWriter {

            public boolean isReadable(Class type, Type genericType, Annotation[] annotations, MediaType mediaType) {
               // StringTextStar should pick up strings
               return !String.class.equals(type) && TypeConverter.isConvertable(type);
            }

            public Object readFrom(Class type, Type genericType, Annotation[] annotations, MediaType mediaType, MultivaluedMap httpHeaders, InputStream entityStream) throws IOException, WebApplicationException {
               InputStream delegate = NoContent.noContentCheck(httpHeaders, entityStream);
               String value = ProviderHelper.readString(delegate, mediaType);
               return TypeConverter.getType(type, value);
            }

            public boolean isWriteable(Class type, Type genericType, Annotation[] annotations, MediaType mediaType) {
               // StringTextStar should pick up strings
               return !String.class.equals(type) && !type.isArray();
            }

            public long getSize(Object o, Class type, Type genericType, Annotation[] annotations, MediaType mediaType) {
               String charset = mediaType.getParameters().get("charset");
               if (charset != null)
                  try {
                     return o.toString().getBytes(charset).length;
                  } catch (UnsupportedEncodingException e) {
                     // Use default encoding.
                  }
               return o.toString().getBytes(StandardCharsets.UTF_8).length;
            }

            public void writeTo(Object o, Class type, Type genericType, Annotation[] annotations, MediaType mediaType, MultivaluedMap httpHeaders, OutputStream entityStream) throws IOException, WebApplicationException {
               String charset = mediaType.getParameters().get("charset");
               if (charset == null) entityStream.write(o.toString().getBytes(StandardCharsets.UTF_8));
               else entityStream.write(o.toString().getBytes(charset));
            }
         }
      

Note that in order to support Async IO, the user must implement the AsyncMessageBodyWriter interface, which requires the implementation of this extra method:

         @Provider
         @Produces("text/plain")
         @Consumes("text/plain")
         public class DefaultTextPlain implements MessageBodyReader, AsyncMessageBodyWriter {
            // ...
            public CompletionStage<Void> asyncWriteTo(Object o, Class type, Type genericType, Annotation[] annotations, MediaType mediaType, MultivaluedMap httpHeaders, AsyncOutputStream entityStream) {
               String charset = mediaType.getParameters().get("charset");
               if (charset == null)
                  return entityStream.asyncWrite(o.toString().getBytes(StandardCharsets.UTF_8));
               else
                  return entityStream.asyncWrite(o.toString().getBytes(charset));
            }
         }
      

The RESTEasy ServletContextLoader will automatically scan the application's WEB-INF/lib and classes directories for classes annotated with @Provider or the user can manually configure them in web.xml. See Installation/Configuration.

jakarta.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 instance, for implementing multipart providers. Content types that embed other random content types.

public interface Providers
{

   /**
    * Get a message body reader that matches a set of criteria. The set of
    * readers is first filtered by comparing the supplied value of
    * {@code mediaType} with the value of each reader's
    * {@link jakarta.ws.rs.Consumes}, ensuring the supplied value of
    * {@code type} is assignable to the generic type of the reader, and
    * eliminating those that do not match.
    * The list of matching readers is then ordered with those with the best
    * matching values of {@link jakarta.ws.rs.Consumes} (x/y > x/* > */*)
    * sorted first. Finally, the
    * {@link MessageBodyReader#isReadable}
    * method is called on each reader in order using the supplied criteria and
    * the first reader that returns {@code true} is selected and returned.
    *
    * @param type        the class of object that is to be written.
    * @param mediaType   the media type of the data that will be read.
    * @param genericType the type of object to be produced. E.g. if the
    *                    message body is to be converted into a method parameter, this will be
    *                    the formal type of the method parameter as returned by
    *                    <code>Class.getGenericParameterTypes</code>.
    * @param annotations an array of the annotations on the declaration of the
    *                    artifact that will be initialized with the produced instance. E.g. if the
    *                    message body is to be converted into a method parameter, this will be
    *                    the annotations on that parameter returned by
    *                    <code>Class.getParameterAnnotations</code>.
    * @return a MessageBodyReader that matches the supplied criteria or null
    *         if none is found.
    */
   <T> MessageBodyReader<T> getMessageBodyReader(Class<T> type,
                                                 Type genericType, Annotation annotations[], MediaType mediaType);

   /**
    * Get a message body writer that matches a set of criteria. The set of
    * writers is first filtered by comparing the supplied value of
    * {@code mediaType} with the value of each writer's
    * {@link jakarta.ws.rs.Produces}, ensuring the supplied value of
    * {@code type} is assignable to the generic type of the reader, and
    * eliminating those that do not match.
    * The list of matching writers is then ordered with those with the best
    * matching values of {@link jakarta.ws.rs.Produces} (x/y > x&#47;* > *&#47;*)
    * sorted first. Finally, the
    * {@link MessageBodyWriter#isWriteable}
    * method is called on each writer in order using the supplied criteria and
    * the first writer that returns {@code true} is selected and returned.
    *
    * @param mediaType   the media type of the data that will be written.
    * @param type        the class of object that is to be written.
    * @param genericType the type of object to be written. E.g. if the
    *                    message body is to be produced from a field, this will be
    *                    the declared type of the field as returned by
    *                    <code>Field.getGenericType</code>.
    * @param annotations an array of the annotations on the declaration of the
    *                    artifact that will be written. E.g. if the
    *                    message body is to be produced from a field, this will be
    *                    the annotations on that field returned by
    *                    <code>Field.getDeclaredAnnotations</code>.
    * @return a MessageBodyReader that matches the supplied criteria or null
    *         if none is found.
    */
   <T> MessageBodyWriter<T> getMessageBodyWriter(Class<T> type,
                                                 Type genericType, Annotation annotations[], MediaType mediaType);

   /**
    * Get an exception mapping provider for a particular class of exception.
    * Returns the provider whose generic type is the nearest superclass of
    * {@code type}.
    *
    * @param type the class of exception
    * @return an {@link ExceptionMapper} for the supplied type or null if none
    *         is found.
    */
   <T extends Throwable> ExceptionMapper<T> getExceptionMapper(Class<T> type);

   /**
    * Get a context resolver for a particular type of context and media type.
    * The set of resolvers is first filtered by comparing the supplied value of
    * {@code mediaType} with the value of each resolver's
    * {@link jakarta.ws.rs.Produces}, ensuring the generic type of the context
    * resolver is assignable to the supplied value of {@code contextType}, and
    * eliminating those that do not match. If only one resolver matches the
    * criteria then it is returned. If more than one resolver matches then the
    * list of matching resolvers is ordered with those with the best
    * matching values of {@link jakarta.ws.rs.Produces} (x/y > x&#47;* > *&#47;*)
    * sorted first. A proxy is returned that delegates calls to
    * {@link ContextResolver#getContext(java.lang.Class)} to each matching context
    * resolver in order and returns the first non-null value it obtains or null
    * if all matching context resolvers return null.
    *
    * @param contextType the class of context desired
    * @param mediaType   the media type of data for which a context is required.
    * @return a matching context resolver instance or null if no matching
    *         context providers are found.
    */
   <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 (https://owasp.org/www-community/vulnerabilities/XML_External_Entity_(XXE)_Processing), in which expanding an external entity causes an unsafe file to be loaded. For example, the document

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

could cause the passwd file to be loaded.

By default, RESTEasy's built-in unmarshaller for org.w3c.dom.Document documents will not expand external entities, replacing them by the empty string instead. It can be configured to replace external entities by values defined in the DTD by setting the parameter

to "true". If configured in the web.xml file, it would be:

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

See Section 3.4, “Configuration” for more information about application configuration.

Another way of dealing with the problem is by prohibiting DTDs, which RESTEasy does by default. This behavior can be changed by setting the parameter

to "false".

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

<!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;'>

then the expansion of &foo6; would result in 1,000,000 foos. By default, RESTEasy will limit the number of expansions and the number of attributes per entity. The exact behavior depends on the underlying parser. The limits can be turned off by setting the parameter

to "false".

The Jakarta RESTful Web Services specification says

When writing responses, implementations SHOULD respect application-supplied character
set metadata and SHOULD use UTF-8 if a character set is not specified by the application
or if the application specifies a character set that is unsupported.

On the other hand, the HTTP specification says

When no explicit charset parameter is provided by the sender, media subtypes of the
"text" type are defined to have a default charset value of "ISO-8859-1" when received
via HTTP. Data in character sets other than "ISO-8859-1" or its subsets MUST be labeled
with an appropriate charset value.

It follows that, in the absence of a character set specified by a resource or resource method, RESTEasy SHOULD use UTF-8 as the character set for text media types, and, if it does, it MUST add an explicit charset parameter to the Content-Type response header. RESTEasy started adding the explicit charset parameter in releases 3.1.2.Final and 3.0.22.Final, and that new behavior could cause some compatibility problems. To specify the previous behavior, in which UTF-8 was used for text media types, but the explicit charset was not appended, the parameter "resteasy.add.charset" may be set to "false". It defaults to "true".

Note. By "text" media types, we mean

The latter set includes "application/xml-external-parsed-entity" and "application/xml-dtd".

Resteasy's Jakarta XML Binding providers have a pluggable way to decorate Marshaller and Unmarshaller instances. The way it works is that you can write an annotation that can trigger the decoration of a Marshaller or Unmarshaller. Your decorators can do things like set Marshaller or Unmarshaller properties, set up validation, and the like. Here's an example. Say we want to have an annotation that will trigger pretty-printing, nice formatting, of an XML document. If we were using raw Jakarta XML Binding, we would set a property on the Marshaller of Marshaller.JAXB_FORMATTED_OUTPUT. Let's write a Marshaller decorator.

First define an annotation:

import org.jboss.resteasy.annotations.Decorator;

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Decorator(processor = PrettyProcessor.class, target = Marshaller.class)
public @interface Pretty {}

For this to work, we must annotate the @Pretty annotation with a meta-annotation called @Decorator. The target() attribute must be the Jakarta XML Binding Marshaller class. The processor() attribute is a class we will write next.

import org.jboss.resteasy.core.interception.DecoratorProcessor;
import org.jboss.resteasy.annotations.DecorateTypes;

import jakarta.xml.bind.Marshaller;
import jakarta.xml.bind.PropertyException;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.Produces;
import java.lang.annotation.Annotation;

/**
 * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
 * @version $Revision: 1 $
 */
@DecorateTypes({"text/*+xml", "application/*+xml"})
public class PrettyProcessor implements DecoratorProcessor<Marshaller, Pretty>
{
    public Marshaller decorate(Marshaller target, Pretty annotation,
                  Class type, Annotation[] annotations, MediaType mediaType)
    {
       target.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
    }
}

The processor implementation must implement the DecoratorProcessor interface and should also be annotated with @DecorateTypes. This annotation specifies what media types the processor can be used with. Now that we've defined our annotation and our Processor, we can use it on our Jakarta RESTful Web Services resource methods or Jakarta XML Binding types as follows:

@GET
@Pretty
@Produces("application/xml")
public SomeJAXBObject get() {...}

Check the RESTEasy source code for the implementation of @XmlHeader for more detailed information

Do not use this feature unless you are knowledgeable about using it.

Based on the class being marshalling/unmarshalling, RESTEasy will, by default create and cache JAXBContext instances per class type. If you do not want RESTEasy to create JAXBContexts, plug in your own by implementing an instance of jakarta.ws.rs.ext.ContextResolver

public interface ContextResolver<T>
{
    T getContext(Class<?> type);
}

@Provider
@Produces("application/xml")
public class MyJAXBContextResolver implements ContextResolver<JAXBContext>
{
    JAXBContext getContext(Class<?> type)
    {
        if (type.equals(WhateverClassIsOverridedFor.class)) return JAXBContext.newInstance()...;
    }
}

A @Produces annotation must be provided to specify the media type the context is meant for. An implementation of ContextResolver<JAXBContext> must be provided and that class must have the @Provider annotation. This helps the runtime match to the correct context resolver.

There are multiple ways to make this ContextResolver available.

RESTEasy is required to provide Jakarta XML Binding provider support for XML. It has a few extra annotations that can help code the application.

@XmlRootElement
public static class Thing
{
    private String name;

    public String getName()
    {
        return name;
    }

    public void setName(String name)
    {
        this.name = name;
    }
}

@Path("/test")
public static class TestService
{
    @GET
    @Path("/header")
    @Produces("application/xml")
    @XmlHeader("<?xml-stylesheet type='text/xsl' href='${baseuri}foo.xsl' ?>")
    public Thing get()
    {
        Thing thing = new Thing();
        thing.setName("bill");
        return thing;
    }
}

@XmlRootElement
public static class Thing
{
    private String name;

    public String getName()
    {
        return name;
    }

    public void setName(String name)
    {
        this.name = name;
    }
}

@Path("/test")
public static class TestService
{
    @GET
    @Path("/stylesheet")
    @Produces("application/xml")
    @Stylesheet(type="text/css", href="${basepath}foo.xsl")
    @Junk
    public Thing getStyle()
    {
        Thing thing = new Thing();
        thing.setName("bill");
        return thing;
    }
}

RESTEasy supports the marshalling of Jakarta XML Binding annotated POJOs to and from JSON. This provider wraps the Jackson2 library to accomplish this.

To use this integration with Jackson import the resteasy-jackson2-provider Maven module.

For example, consider this Jakarta XML Binding class:

@XmlRootElement(name = "book")
public class Book
{
    private String author;
    private String ISBN;
    private String title;

    public Book()
    {
    }

    public Book(String author, String ISBN, String title)
    {
        this.author = author;
        this.ISBN = ISBN;
        this.title = title;
    }

    @XmlElement
    public String getAuthor()
    {
        return author;
    }

    public void setAuthor(String author)
    {
    this.author = author;
    }

    @XmlElement
    public String getISBN()
    {
        return ISBN;
    }

    public void setISBN(String ISBN)
    {
        this.ISBN = ISBN;
    }

    @XmlAttribute
    public String getTitle()
    {
        return title;
    }

    public void setTitle(String title)
    {
        this.title = title;
    }
}

And we can write a method to use the above entity:

@Path("/test_json")
@GET
@Produces(MediaType.APPLICATION_JSON)
public Book test_json() {
    Book book = new Book();
    book.setTitle("EJB 3.0");
    book.setAuthor("Bill Burke");
    book.setISBN("596529260");
    return book;
}

When making a requesting of the above method, the default Jackson2 marshaller would return JSON output that looked like this:

$ http localhost:8080/dummy/test_json
HTTP/1.1 200
...
Content-Type: application/json

{
"ISBN": "596529260",
"author": "Bill Burke",
"title": "EJB 3.0"
}

RESTEasy supports the FastinfoSet mime type with Jakarta XML Binding annotated classes. Fast infoset documents are faster to serialize and parse, and smaller in size, than logically equivalent XML documents. Thus, fast infoset documents may be used whenever the size and processing time of XML documents is an issue. It is configured the same way the provider is.

To use this integration with Fastinfoset import the resteasy-fastinfoset-provider Maven module.

RESTEasy will automatically marshal arrays, java.util.Set's, and java.util.List's of Jakarta XML Binding objects to and from XML, JSON, Fastinfoset.

@XmlRootElement(name = "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("/")
public class MyResource
{
    @PUT
    @Path("array")
    @Consumes("application/xml")
    public void putCustomers(Customer[] customers)
    {
        Assert.assertEquals("bill", customers[0].getName());
        Assert.assertEquals("monica", customers[1].getName());
    }

    @GET
    @Path("set")
    @Produces("application/xml")
    public Set<Customer> getCustomerSet()
    {
        HashSet<Customer> set = new HashSet<Customer>();
        set.add(new Customer("bill"));
        set.add(new Customer("monica"));

        return set;
    }

    @PUT
    @Path("list")
    @Consumes("application/xml")
    public void putCustomers(List<Customer> customers)
    {
        Assert.assertEquals("bill", customers.get(0).getName());
        Assert.assertEquals("monica", customers.get(1).getName());
    }
}

The above resource can publish and receive Jakarta XML Binding objects. It is assumed they are wrapped in a collection element

<collection>
    <customer><name>bill</name></customer>
    <customer><name>monica</name></customer>
<collection>

The namespace URI, namespace tag, and collection element name can be changed by using the @org.jboss.resteasy.annotations.providers.jaxb.Wrapped annotation on a parameter or method

@Target({ElementType.PARAMETER, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Wrapped
{
    String element() default "collection";

    String namespace() default "http://jboss.org/resteasy";

    String prefix() default "resteasy";
}

To output this XML

<foo:list xmlns:foo="http://foo.org">
    <customer><name>bill</name></customer>
    <customer><name>monica</name></customer>
</foo:list>

The @Wrapped annotation would be used as follows:

@GET
@Path("list")
@Produces("application/xml")
@Wrapped(element="list", namespace="http://foo.org", prefix="foo")
public List<Customer> getCustomerSet()
{
    List<Customer> list = new ArrayList<Customer>();
    list.add(new Customer("bill"));
    list.add(new Customer("monica"));

    return list;
}

      Response response = request.get();
      List<Customer> list = response.readEntity(List.class);

      Response response = request.get();
      GenericType<List<Customer>> genericType = new GenericType<List<Customer>>() {};
      List<Customer> list = response.readEntity(genericType);

      Response response = request.get();
      GenericType<Set<Customer>> genericType = new GenericType<Set<Customer>>() {};
      Set<Customer> set = response.readEntity(genericType);

      Response response = request.get();
      Customer[] array = response.readEntity(Customer[].class);

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public static class Foo
{
    @XmlAttribute
    private String test;

    public Foo()
    {
    }

    public Foo(String test)
    {
        this.test = test;
    }

    public String getTest()
    {
        return test;
    }

    public void setTest(String test)
    {
        this.test = test;
    }
}

[{"foo":{"@test":"bill"}},{"foo":{"@test":"monica}"}}]

RESTEasy automatically marshals maps of Jakarta XML Binding objects to and from XML, JSON, Fastinfoset (or any other new Jakarta XML Binding mapper). The parameter or method return type must be a generic with a String as the key and the Jakarta XML Binding object's type.

@XmlRootElement(namespace = "http://foo.com")
public static class Foo
{
    @XmlAttribute
    private String name;

    public Foo()
    {
    }

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

    public String getName()
    {
        return name;
    }
}

@Path("/map")
public static class MyResource
{
    @POST
    @Produces("application/xml")
    @Consumes("application/xml")
    public Map<String, Foo> post(Map<String, Foo> map)
    {
        Assert.assertEquals(2, map.size());
        Assert.assertNotNull(map.get("bill"));
        Assert.assertNotNull(map.get("monica"));
        Assert.assertEquals(map.get("bill").getName(), "bill");
        Assert.assertEquals(map.get("monica").getName(), "monica");
        return map;
    }
}

The above resource can publish and receive XML objects within a map. By default, they are wrapped in a "map" element in the default namespace. Also, each "map" element has zero or more "entry" elements with a "key" attribute.

<map>
    <entry key="bill" xmlns="http://foo.com">
        <foo name="bill"/>
    </entry>
    <entry key="monica" xmlns="http://foo.com">
        <foo name="monica"/>
    </entry>
</map>

The namespace URI, namespace prefix and map, entry, and key element and attribute names can be changed by using the @org.jboss.resteasy.annotations.providers.jaxb.WrappedMap annotation on a parameter or method

@Target({ElementType.PARAMETER, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface WrappedMap
{
    /**
     * map element name
     */
    String map() default "map";

    /**
     * entry element name *
     */
    String entry() default "entry";

    /**
     * entry's key attribute name
     */
    String key() default "key";

    String namespace() default "";

    String prefix() default "";
}

To output this XML

<hashmap>
    <hashentry hashkey="bill" xmlns:foo="http://foo.com">
        <foo:foo name="bill"/>
    </hashentry>
</map>

Use the @WrappedMap annotation as follows:

@Path("/map")
public static class MyResource
{
    @GET
    @Produces("application/xml")
    @WrappedMap(map="hashmap", entry="hashentry", key="hashkey")
    public Map<String, Foo> get()
    {
        ...
        return map;
    }
}

      Response response = request.get();
      Map<String, Customer> map = response.readEntity(Map.class);

      Response response = request.get();
      GenericType<Map<String, Customer> genericType = new GenericType<Map<String, Customer>>() {};
      Map<String, Customer> map = response.readEntity(genericType);

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public static class Foo
{
    @XmlAttribute
    private String test;

    public Foo()
    {
    }

    public Foo(String test)
    {
        this.test = test;
    }

    public String getTest()
    {
        return test;
    }

    public void setTest(String test)
    {
        this.test = test;
    }
}

{ "entry1" : {"foo":{"@test":"bill"}}, "entry2" : {"foo":{"@test":"monica}"}}}

Some objects models use abstract classes and interfaces heavily. Unfortunately, Jakarta XML Binding doesn't work with interfaces that are root elements and RESTEasy can't unmarshal parameters that are interfaces or raw abstract classes because it doesn't have enough information to create a JAXBContext. For example:

public interface IFoo {}

@XmlRootElement
public class RealFoo implements IFoo {}

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

    @PUT
    @Consumes("application/xml")
    public void put(IFoo foo) {...}
}

In this example, RESTEasy will report error, "Cannot find a MessageBodyReader for...". This is because RESTEasy does not know that implementations of IFoo are Jakarta XML Binding classes and doesn't know how to create a JAXBContext for it. As a workaround, RESTEasy allows the use of Jakarta XML Binding annotation @XmlSeeAlso on the interface to correct the problem. (NOTE, this will not work with manual, hand-coded Jakarta XML Binding).

@XmlSeeAlso(RealFoo.class)
public interface IFoo {}

The extra @XmlSeeAlso on IFoo allows RESTEasy to create a JAXBContext that knows how to unmarshal RealFoo instances.

As a consumer of XML datasets, Jakarta XML Binding is subject to a form of attack known as the XXE (Xml eXternal Entity) Attack (https://owasp.org/www-community/vulnerabilities/XML_External_Entity_(XXE)_Processing), in which expanding an external entity causes an unsafe file to be loaded. Preventing the expansion of external entities is discussed in Section 21.4, “Configuring Document Marshalling”. The same parameter,

applies to Jakarta XML Binding unmarshallers.

Section 21.4, “Configuring Document Marshalling” also discusses the prohibition of DTDs and the imposition of limits on entity expansion and the number of attributes per element. The parameters

and

discussed there, and their default values, also apply to the representation of Jakarta XML Binding objects.

RESTEasy has defined a simple object model in Java to represent Atom and uses Jakarta XML Binding to marshal and unmarshal it. The main classes are in the org.jboss.resteasy.plugins.providers.atom package and are Feed, Entry, Content, and Link. If you look at the source, you will see that these are annotated with Jakarta XML Binding annotations. The distribution contains the javadocs for this project and are a must to learn the model. Here is a simple example of sending an atom feed using the RESTEasy API.

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("Bill Burke"));
        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;
    }
}

RESTEasy's atom provider is Jakarta XML Binding based, there are no limits to sending atom objects using XML. All the other Jakarta XML Binding providers that RESTEasy has like JSON and fastinfoset can automatically be re-use. Just add "atom+" in front of the main subtype. i.e. @Produces("application/atom+json") or @Consumes("application/atom+fastinfoset")

The org.jboss.resteasy.plugins.providers.atom.Content class is used to unmarshal and marshal Jakarta XML Binding annotated objects that are the body of the content. Here's an example of sending an Entry with a Customer object attached as the body of the entry's content.

@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;
    }
}

The Content.setJAXBObject() method is used to tell the content object, an object is being sent back and it is to be marshalled appropriately. If using a different base format than XML, i.e. "application/atom+json", this attached object will be marshalled into that same format.

If the input is an atom document, Jakarta XML Binding objects can be extracted from Content using the Content.getJAXBObject(Class clazz) method. Here is an example of an input atom document and extracting a Customer object from the content.

@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);
    }
}

If deploying RESTEasy outside WildFly, add the RESTEasy Jackson provider to the pom.xml:

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

In Jackson 2.13+ com.fasterxml.jackson.module.jakarta.xmlbind.JakartaXmlBindAnnotationModule must be registered in order to use XML binding annotations for Jackson to marshall/unmarshall them in JSON. To do this, com.fasterxml.jackson.databind.ObjectMapper must be provided via an implementation of jakarta.ws.rs.ext.ContextResolver.

An example jakarta.ws.rs.ext.ContextResolver:

@Provider
public class ObjectMapperProvider implements ContextResolver<ObjectMapper> {
    static final JsonMapper MAPPER = JsonMapper.builder()
            .addModule(new JakartaXmlBindAnnotationModule())
            .build();

    @Override
    public ObjectMapper getContext(final Class<?> type) {
        return MAPPER;
    }
}
            

RESTEasy added support for "application/*+json". Jackson supports "application/json" and "text/json" as valid media types. This allows the creation of json-based media types and still lets Jackson perform the marshalling. For example:

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

    @GET
    @Produces("application/vnd.customer+json")
    public Customer[] getCustomers() {}
}

RESTEasy supports JSONP. It can be enabled by adding provider org.jboss.resteasy.plugins.providers.jackson.Jackson2JsonpInterceptor to the deployment. Jackson and JSONP can be used together. If the media type of the response is json and a callback query parameter is given, the response will be a javascript snippet with a method call of the method defined by the callback parameter. For example:

GET /resources/stuff?callback=processStuffResponse

will produce this response:

processStuffResponse(<nomal JSON body>)

This supports the default behavior of jQuery. To enable Jackson2JsonpInterceptor in WildFly, annotations must be imported from the org.jboss.resteasy.resteasy-jackson2-provider module. To do that a jboss-deployment-structure.xml file must be added to the application's WAR:

<jboss-deployment-structure>
  <deployment>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider" annotations="true"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

The name of the callback parameter can be changed by setting the callbackQueryParameter property.

Jackson2JsonpInterceptor can wrap the response into a try-catch block:

try{processStuffResponse(<normal JSON body>)}catch(e){}

This feature can be enabled by setting the resteasy.jsonp.silent property to true

Note. Because JSONP can be used in Cross Site Scripting Inclusion (XSSI) attacks, Jackson2JsonpInterceptor is disabled by default. Two steps are necessary to enable it:

If using the Jackson 2 provider, RESTEasy has provided a pretty-printing annotation similar with the one in Jakarta XML Binding provider:

org.jboss.resteasy.annotations.providers.jackson.Formatted

Here is an example:

@GET
@Produces("application/json")
@Path("/formatted/{id}")
@Formatted
public Product getFormattedProduct()
{
    return new Product(333, "robot");
}

As the example shown above, the @Formatted annotation will enable the underlying Jackson option "SerializationFeature.INDENT_OUTPUT".

Jackson2 provides annotation, JsonFilter. @JsonFilter is used to apply filtering during serialization/de-serialization for example which properties are to be used or not. Here is an example which defines mapping from "nameFilter" to filter instances and filter bean properties when serialized to json format:

@JsonFilter(value="nameFilter")
public class Jackson2Product {
    protected String name;
    protected int id;
    public Jackson2Product() {
    }
    public Jackson2Product(final int id, final String name) {
        this.id = id;
        this.name = name;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public int getId() {
        return id;
    }
    public void setId(int id) {
        this.id = id;
    }
}

@JsonFilter annotates a resource class to filter out some property not to be serialized in the json response. To map the filter id and instance we need to create another jackson class to add the id and filter instance map:

public class ObjectFilterModifier extends ObjectWriterModifier {
	public ObjectFilterModifier() {
	}
	@Override
	public ObjectWriter modify(EndpointConfigBase<?> endpoint,
			MultivaluedMap<String, Object> httpHeaders, Object valueToWrite,
			ObjectWriter w, JsonGenerator jg) throws IOException {

		FilterProvider filterProvider = new SimpleFilterProvider().addFilter(
				"nameFilter",
				SimpleBeanPropertyFilter.filterOutAllExcept("name"));
		return w.with(filterProvider);

	}
}

Here the method modify() takes care of filtering all properties except "name" property before a write. To make this work, the mapping information must be accessible to RESTEasy. This can be made available through a WriterInterceptor that uses Jackson's ObjectWriterInjector:

@Provider
public class JsonFilterWriteInterceptor implements WriterInterceptor{

	private ObjectFilterModifier modifier = new ObjectFilterModifier();
	@Override
	public void aroundWriteTo(WriterInterceptorContext context)
			throws IOException, WebApplicationException {
		//set a threadlocal modifier
	    ObjectWriterInjector.set(modifier);
		context.proceed();
	}

}

Alternatively, Jackson's documentation suggest doing the same in a servlet filter; that however potentially leads to issues in RESTEasy. The ObjectFilterModifier is stored using a ThreadLocal object and there's no guarantee the same thread serving the servlet filter will be running the resource endpoint execution. For the servlet filter scenario, RESTEasy offers its own injector that relies on the current thread context classloader for carrying the specified modifier:

public class ObjectWriterModifierFilter implements Filter {
	private static ObjectFilterModifier modifier = new ObjectFilterModifier();

	@Override
	public void init(FilterConfig filterConfig) throws ServletException {
	}

	@Override
	public void doFilter(ServletRequest request, ServletResponse response,
			FilterChain chain) throws IOException, ServletException {
		ResteasyObjectWriterInjector.set(Thread.currentThread().getContextClassLoader(), modifier);
		chain.doFilter(request, response);
	}

	@Override
	public void destroy() {
	}

}

Due to numerous CVEs for a specific kind of Polymorphic Deserialization (see details in FasterXML Jackson documentation), starting from Jackson 2.10 users have a means to allow only specified classes to be deserialized. RESTEasy enables this feature by default. It allows controlling the content of the whitelist of allowed classes/packages.

The specification adds support for declaring asynchronous resource methods by returning a CompletionStage instead of using the @Suspended annotation.

The specification 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.

There is also a new rx method which is used in a similar manner to async.

SSE is part of HTML standard, currently supported by many browsers. It is a server push technology, which provides a way to establish a one-way channel to continuously send data to clients. SSE events are pushed to the client via a long-running HTTP connection. In case of lost connection, clients can retrieve missed events by setting a "Last-Event-ID" HTTP header in a new request.

SSE stream has text/event-stream media type and contains multiple SSE events. SSE event is a data structure encoded with UTF-8 and contains fields and comment. The field can be event, data, id, retry and other kinds of field will be ignored.

From Jakarta RESTful Web Services 2.1, Server-sent Events APIs are introduced to support sending, receiving and broadcasting SSE events.

   @GET
   @Path("domains/{id}")
   @Produces(MediaType.SERVER_SENT_EVENTS)
   public void startDomain(@PathParam("id") final String id, @Context SseEventSink sink @Context Sse sse)
   {
      ExecutorService service = (ExecutorService) servletContext
            .getAttribute(ExecutorServletContextListener.TEST_EXECUTOR);
      service.execute(new Thread()
      {
         public void run()
         {
            try
            {
               sink.send(sse.newEventBuilder().name("domain-progress")
                     .data(String.class, "starting domain " + id + " ...").build());
               Thread.sleep(200);
               sink.send(sse.newEvent("domain-progress", "50%"));
               Thread.sleep(200);
               sink.send(sse.newEvent("domain-progress", "60%"));
               Thread.sleep(200);
               sink.send(sse.newEvent("domain-progress", "70%"));
               Thread.sleep(200);
               sink.send(sse.newEvent("domain-progress", "99%"));
               Thread.sleep(200);
               sink.send(sse.newEvent("domain-progress", "Done.")).thenAccept((Object obj) -> {
                  sink.close();
               });
            }
            catch (final InterruptedException e)
            {
               logger.error(e.getMessage(), e);
            }
         }
      });
   }              
                
                

   @GET
   @Path("/subscribe")
   @Produces(MediaType.SERVER_SENT_EVENTS)
   public void subscribe(@Context SseEventSink sink) throws IOException
   {
      if (sink == null)
      {
         throw new IllegalStateException("No client connected.");
      }
      if (sseBroadcaster == null)
      {
         sseBroadcaster = sse.newBroadcaster();
      }
      sseBroadcaster.register(sink);
   }

   @POST
   @Path("/broadcast")
   public void broadcast(String message) throws IOException
   {
      if (sseBroadcaster == null)
      {
         sseBroadcaster = sse.newBroadcaster();
      }
      sseBroadcaster.broadcast(sse.newEvent(message));

   }          
                
                

    public void printEvent() throws Exception
    {
      WebTarget target = client.target("http://localhost:8080/service/server-sent-events"));
      SseEventSource msgEventSource = SseEventSource.target(target).build();
      try (SseEventSource eventSource = msgEventSource)
      {
         eventSource.register(event -> {
            System.out.println(event.readData(String.class));
         }, ex -> {
            ex.printStackTrace();
         });
         eventSource.open();
      } 
    }   
                
                

RESTEasy supports both JSON-B and JSON-P. In accordance with the specification, entity providers for JSON-B take precedence over those for JSON-P for all types except JsonValue and its sub-types.

The support for JSON-B is provided by the JsonBindingProvider from resteasy-json-binding-provider module. To satisfy Jakarta RESTful Web Services 2.1 requirements, JsonBindingProvider takes precedence over the other providers for dealing with JSON payloads, in particular the Jackson one. The JSON outputs (for the same input) from Jackson and JSON-B reference implementation can be slightly different. As a consequence, in order to allow retaining backward compatibility, RESTEasy offers a resteasy.preferJacksonOverJsonB context property that can be set to true to disable JsonBindingProvider for the current deloyment.

WildFly 14 supports specifying the default value for the resteasy.preferJacksonOverJsonB context property by setting a system property with the same name. Moreover, if no value is set for the context and system properties, it scans Jakarta RESTful Web Services deployments for Jackson annotations and sets the property to true if any of those annotations is found.

RESTEasy supports applying partial modifications to target resources with JSON Patch/JSON Merge Patch. Instead of sending a json request which represents the whole modified resource with an HTTP PUT method, the json request only contains the modified part with an HTTP PATCH method to do the same job.

JSON Patch request has an array of json objects and each JSON object gives the operation to execute against the target resource. Here is an example to modify the target Student resource which has these fields and values: {"firstName":"Alice","id":1,"school":"MiddleWood School"}:

            PATCH /StudentPatchTest/students/1 HTTP/1.1
            Content-Type: application/json-patch+json
            Content-Length: 184
            Host: localhost:8090
            Connection: Keep-Alive

            [{"op":"copy","from":"/firstName","path":"/lastName"},
             {"op":"replace","path":"/firstName","value":"John"},
             {"op":"remove","path":"/school"},
             {"op":"add","path":"/gender","value":"male"}]
                 
                

This JSON Patch request will copy the firstName to lastName field , then change the firstName value to "John". The next operation will remove the school value and add male gender to this "id=1" student resource. After this JSON Path is applied. The target resource will be modified to: {"firstName":"John","gender":"male","id":1,"lastName":"Taylor"}. The operation keyword here can be "add", "remove", "replace", "move", "copy", or "test". The "path" value must be a JSON Pointer value that points to the part to apply this JSON Patch.

Unlike using the operation keyword to patch the target resource, JSON Merge Patch request directly sends the expected json change. RestEasy merges this change into the target resource which is identified by the request URI. Like the JSON Merge Patch request below, it removes the "school" value and changes the "firstName" to "Green".

             PATCH /StudentPatchTest/students/1 HTTP/1.1
             Content-Type: application/merge-patch+json
             Content-Length: 34
             Host: localhost:8090
             Connection: Keep-Alive
             {"firstName":"Green","school":null}
             
            

Enabling JSON Patch or JSON Merge Patch only requires correctly annotating the resource method with these mediaTypes. @Consumes(MediaType.APPLICATION_JSON_PATCH_JSON) enables JSON Patch. @Consumes("application/merge-patch+json") enables JSON Merge Patch:

            @GET
            @Path("/{id}")
            @Consumes(MediaType.APPLICATION_JSON)
            @Produces(MediaType.APPLICATION_JSON)
            public Student getStudent(@PathParam("id") long id)
            {
            Student student = studentsMap.get(id);
            if (student == null)
            {
            throw new NotFoundException();
            }
            return student;
            }
            @PATCH
            @Path("/{id}")
            @Consumes(MediaType.APPLICATION_JSON_PATCH_JSON)
            @Produces(MediaType.APPLICATION_JSON)
            public Student patchStudent(@PathParam("id") long id, Student student)
            {
            if (studentsMap.get(id) == null)
            {
            throw new NotFoundException();
            }
            studentsMap.put(id, student);
            return student;
            }
            @PATCH
            @Path("/{id}")
            @Consumes("application/merge-patch+json")
            @Produces(MediaType.APPLICATION_JSON)
            public Student mergePatchStudent(@PathParam("id") long id, Student student)
            {
            if (studentsMap.get(id) == null)
            {
            throw new NotFoundException();
            }
            studentsMap.put(id, student);
            return student;
            }
            
            

The client side needs to create these json objects and send them with a http PATCH method.

            //send JSON Patch request
            WebTarget patchTarget = client.target("http://localhost:8090/StudentPatchTest/students/1"));
            JsonArray patchRequest = Json.createArrayBuilder()
            .add(Json.createObjectBuilder().add("op", "copy").add("from", "/firstName").add("path", "/lastName").build())
            .build();
            patchTarget.request().build(HttpMethod.PATCH, Entity.entity(patchRequest, MediaType.APPLICATION_JSON_PATCH_JSON)).invoke();
            //send JSON Merge Patch request
            WebTarget patchTarget = client.target("http://localhost:8090/StudentPatchTest/students/1");
            JsonObject object = Json.createObjectBuilder().add("lastName", "Green").addNull("school").build();
            Response result = patchTarget.request().build(HttpMethod.PATCH, Entity.entity(object, "application/merge-patch+json")).invoke();
                        
            

Parameters and properties annotated with @CookieParam, @HeaderParam, @MatrixParam, @PathParam, or @QueryParam are represented as strings in a raw HTTP request. The specification says that any of these injected parameters can be converted to an object if the object's class has a valueOf(String) static method or a constructor that takes one Stringparameter. In the following, for example,

public static class Customer {
   private String name;

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

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

   @GET
   @Path("")
   public Response test(@QueryParam("cust") Customer cust) {
      return Response.ok(cust.getName()).build();
   }
}

@Test
public void testQuery() throws Exception {
   Invocation.Builder request = ClientBuilder.newClient().target("http://localhost:8081/test?cust=Bill").request();
   Response response = request.get();
   ...
}
   

the query "?cust=Bill" will be transformed automatically to an instance of Customer with name == "Bill".

What if you have a class where valueOf()or this string constructor don't exist or is inappropriate for an HTTP request? Jakarta RESTful Web Services has the jakarta.ws.rs.ext.ParamConverterProvider to help in this situation.

A ParamConverterProvider is a provider defined as follows:

public interface ParamConverterProvider {

   public <T> ParamConverter<T> getConverter(Class<T> rawType, Type genericType, Annotation annotations[]);
}
   

where a ParamConverter is defined:

public interface ParamConverter<T> {
   ...
   public T fromString(String value);
   public String toString(T value);
}
   

For example, consider DateParamConverterProvider and DateParamConverter:

@Provider
public class DateParamConverterProvider implements ParamConverterProvider {

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

public class DateParamConverter implements ParamConverter<Date> {

   public static final String DATE_PATTERN = "yyyyMMdd";

   @Override
   public Date fromString(String param) {
      try {
         return new SimpleDateFormat(DATE_PATTERN).parse(param.trim());
      } catch (ParseException e) {
         throw new BadRequestException(e);
      }
   }

   @Override
   public String toString(Date date) {
      return new SimpleDateFormat(DATE_PATTERN).format(date);
   }
}
   

Sending a Date in the form of a query, e.g., "?date=20161217" will cause the string "20161217" to be converted to a Date on the server.

In addition to the Jakarta RESTful Web Services jakarta.ws.rs.ext.ParamConverterProvider, RESTEasy also has its own org.jboss.resteasy.StringParameterUnmarshaller, defined

public interface StringParameterUnmarshaller<T>
{
   void setAnnotations(Annotation[] annotations);

   T fromString(String str);
}
   

It is similar to jakarta.ws.rs.ext.ParamConverter except that

@Target({ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface StringParameterUnmarshallerBinder
{
   Class<? extends StringParameterUnmarshaller> value();
}
   

For example,

   @Retention(RetentionPolicy.RUNTIME)
   @StringParameterUnmarshallerBinder(TestDateFormatter.class)
   public @interface TestDateFormat {
      String value();
   }

   public static class TestDateFormatter implements StringParameterUnmarshaller<Date> {
      private SimpleDateFormat formatter;

      public void setAnnotations(Annotation[] annotations) {
         TestDateFormat format = FindAnnotation.findAnnotation(annotations, TestDateFormat.class);
         formatter = new SimpleDateFormat(format.value());
      }

      public Date fromString(String str) {
         try {
            return formatter.parse(str);
         } catch (ParseException e) {
            throw new RuntimeException(e);
         }
      }
   }
   
   @Path("/")
   public static class TestResource {

      @GET
      @Produces("text/plain")
      @Path("/datetest/{date}")
      public String get(@PathParam("date") @TestDateFormat("MM-dd-yyyy") Date date) {
         Calendar c = Calendar.getInstance();
         c.setTime(date);
         return date.toString();
      }
   }
   

Note that the annotation @StringParameterUnmarshallerBinder on the annotation @TestDateFormat binds the formatter TestDateFormatter to a parameter annotated with @TestDateFormat. In this example, TestDateFormatter is used to format the Date parameter. Note also that the parameter "MM-dd-yyyy" to @TestDateFormat is accessible from TestDateFormatter.setAnnotations().

For parameters and properties annotated with @CookieParam, @HeaderParam, @MatrixParam, @PathParam, or @QueryParam, the Jakarta RESTful Web Services specification [https://jcp.org/aboutJava/communityprocess/final/jsr339/index.html] allows conversion as defined in the Javadoc of the corresponding annotation. In general, the following types are supported:

Items 1, 3, and 4 have been discussed above, and item 2 is obvious. Note that item 5 allows for collections of parameters. How these collections are expressed in HTTP messages depends, by default, on the particular kind of parameter. In most cases, the notation for collections is based on convention rather than a specification.

http://bluemonkeydiamond.com?q=1&q=2&q=3
   

public MultivaluedMap<String, String> getQueryParameters();
   

http://bluemonkeydiamond.com/sippycup;m=1;m=2;m=3
   

public MultivaluedMap<String, String> getRequestHeaders();
   

x-header: a, b, c
   

public Map<String, Cookie> getCookies();
   

@Path("")
public static class TestResource {

   @GET
   @Path("{segment}/{other}/{segment}/array")
   public Response getTwoSegmentsArray(@PathParam("segment") PathSegment[] segments) {
      System.out.println("array segments: " + segments.length);
      return Response.ok().build();
   }
   
   @GET
   @Path("{segment}/{other}/{segment}/list")
   public Response getTwoSegmentsList(@PathParam("segment") List<PathSegment> segments) {
      System.out.println("list segments: " + segments.size());
      return Response.ok().build();
   }
}

...

   @Test
   public void testTwoSegmentsArray() throws Exception {
      Invocation.Builder request = client.target("http://localhost:8081/a/b/c/array").request();
      Response response = request.get();
      Assert.assertEquals(200, response.getStatus());
      response.close();
   }
   
   @Test
   public void testTwoSegmentsList() throws Exception {
      Invocation.Builder request = client.target("http://localhost:8081/a/b/c/list").request();
      Response response = request.get();
      Assert.assertEquals(200, response.getStatus());
      response.close();
   }
   

array segments: 2
list segments: 2
   

@Path("")
public static class TestResource {

   @GET
   @Path("{segments:.*}/array")
   public Response getWildcardArray(@PathParam("segments") PathSegment[] segments) {
      System.out.println("array segments: " + segments.length);
      return Response.ok().build();
   }
   
   @GET
   @Path("{segments:.*}/list")
   public Response getWildcardList(@PathParam("segments") List<PathSegment> segments) {
      System.out.println("list segments: " + segments.size());
      return Response.ok().build();
   }
   
...

   @Test
   public void testWildcardArray() throws Exception {
      Invocation.Builder request = client.target("http://localhost:8081/a/b/c/array").request();
      Response response = request.get();
      response.close();
   }
   
   @Test
   public void testWildcardList() throws Exception {
      Invocation.Builder request = client.target("http://localhost:8081/a/b/c/list").request();
      Response response = request.get();
      response.close();
   }
   

array segments: 3
list segments: 3
   

In the Jakarta RESTful Web Services semantics, a ParamConverter is supposed to convert 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, indeed, any multivalued data structure whatever. First, 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 {
   Client client = ClientBuilder.newClient();
   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,
   

Suppose, instead, that we want to use a comma separated notation. We 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 we can call

@Test
public void testQueryParamCustom() throws Exception {
   Client client = ClientBuilder.newClient();
   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,
   

Note that in this case, MultiValuedParamConverter.fromString() creates and returns an ArrayList, so TestResource.conversion() could be rewritten

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

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

On the other hand, MultiValuedParamConverter could be rewritten to return a LinkList and the parameter list in TestResource.conversion() could 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();
      }
   }
   

RESTEasy includes two built-in ParamConverters in the resteasy-core module, one for Collections:

   org.jboss.resteasy.plugins.providers.MultiValuedCollectionParamConverter,

and one for arrays:

   org.jboss.resteasy.plugins.providers.MultiValuedArrayParamConverter,

which implement the concepts in the previous section.

In particular, MultiValued*ParamConverter.fromString() can transform a string representation coming over the network into a Collection or array, and MultiValued*ParamConverter.toString() can be used by a client side proxy to transform Collections or arrays into a string representation.

String representations are determined by org.jboss.resteasy.annotations.Separator, a parameter annotation in the resteasy-core module:

@Target({ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface Separator
{
   public String value() default "";
}

The value of Separator.value() is used to separate individual elements of a Collection or array. For example, a proxy implementing

@Path("path/separator/multi/{p}")
@GET
public String pathMultiSeparator(@PathParam("p") @Separator("-") List<String> ss); 

will turn

List<String> list = new ArrayList<String>();
list.add("abc");
list.add("xyz");
proxy.pathMultiSeparator(list);

and "path/separator/multi/{p}" into ".../path/separator/multi/abc-xyz". On the server side, the RESTEasy runtime will turn "abc-xyz" back into a list consisting of elements "abc" and "xyz" for

@Path("path/separator/multi/{p}")
@GET
public String pathMultiSeparator(@PathParam("p") @Separator("-") List<String> ss) {
   StringBuffer sb = new StringBuffer();
   for (String s : ss) {
      sb.append(s);
      sb.append("|");
   }
   return sb.toString();
}

which will return "abc|xyz|".

In fact, the value of the Separator annotations may be a more general regular expression, which is passed to String.split(). For example, "[-,;]" tells the server side to break up a string using either "-", ",", or ";". On the client side, a string will be created using the first element, "-" in this case.

If a parameter is annotated with @Separator with no value, then the default value is

The MultiValued*ParamConverters depend on existing facilities for handling the individual elements. On the server side, once it has parsed the incoming string into substrings, MultiValued*ParamConverter turns each substring into an Java object according to Section 3.2 "Fields and Bean Properties" of the Jakarta RESTful Web Services specification. On the client side, MultiValued*ParamConverter turns a Java object into a string as follows:

These ParamConverters are meant to be fairly general, but there are a number of restrictions:

There are also some logical restrictions:

These built-in ParamConverters have the lowest priority, so any user supplied ParamConverters will be tried first.

ExceptionMappers are custom, application provided, components that can catch thrown application exceptions and write specific HTTP responses. They are classes annotated with @Provider and implement this interface

         package jakarta.ws.rs.ext;

         import jakarta.ws.rs.core.Response;

         /**
         * Contract for a provider that maps Java exceptions to
         * {@link jakarta.ws.rs.core.Response}. An implementation of this interface must
         * be annotated with {@link Provider}.
         *
         * @see Provider
         * @see jakarta.ws.rs.core.Response
         */
         public interface ExceptionMapper<E>
         {
            /**
            * Map an exception to a {@link jakarta.ws.rs.core.Response}.
            *
            * @param exception the exception to map to a response
            * @return a response mapped from the supplied exception
            */
            Response toResponse(E exception);
         }
      

When an application exception is thrown it will be caught by the Jakarta RESTful Web Services runtime. Jakarta RESTful Web Services will then scan registered ExceptionMappers to see which one support marshalling the exception type thrown. Here is an example of ExceptionMapper

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

ExceptionMappers are registered the same way as MessageBodyReader/Writers. By scanning for @Provider annotated classes, or programmatically through the ResteasyProviderFactory class.

As of RESTEasy 6.1 if a default ExceptionMapper is registered. It handles all uncaught exceptions and returns a response with the exception's message and a status of 500. If the exception is a WebApplicationException the response from the exception is returned. This can be turned off by setting the dev.resteasy.exception.mapper to false.

The default ExceptionMapper will also log the exception at a error level. The logger name is org.jboss.resteasy.core.providerfactory.DefaultExceptionMapper which can be used to disable these log messages.

RESTEasy has a set of built-in exceptions that are thrown when it encounters errors during dispatching or marshalling. They all revolve around specific HTTP error codes. They can be found in RESTEasy's javadoc under the package org.jboss.resteasy.spi. Here's a list of them:

Suppose a client at local.com calls the following resource method:

   @GET
   @Path("remote")
   public String remote() throws Exception {
      Client client = ClientBuilder.newClient();
      return client.target("http://third.party.com/exception").request().get(String.class);
   }
   

If the call to http://third.party.com returns a status code 3xx, 4xx, or 5xx, then the Client is obliged by the Jakarta RESTful Web Services specification to throw a WebApplicationException. Moreover, if the WebApplicationException contains a Response, which it normally would in RESTEasy, the server runtime is obliged by the Jakarta RESTful Web Services specification to return that Response. As a result, information from the server at third.party.com, e.g., headers and body, will get sent back to local.com. The problem is that that information could be, at best, meaningless to the client and, at worst, a security breach.

RESTEasy has a solution that works around the problem and still conforms to the Jakarta RESTful Web Services specification. In particular, for each WebApplicationException it defines a new subclass:

WebApplicationException
+-ResteasyWebApplicationException
+-ClientErrorException
| +-ResteasyClientErrorException
| +-BadRequestException
| | +-ResteasyBadRequestException
| +-ForbiddenException
| | +-ResteasyForbiddenException
| +-NotAcceptableException
| | +-ResteasyNotAcceptableException
| +-NotAllowedException
| | +-ResteasyNotAllowedException
| +-NotAuthorizedException
| | +-ResteasyNotAuthorizedException
| +-NotFoundException
| | +-ResteasyNotFoundException
| +-NotSupportedException
| | +-ResteasyNotSupportedException
+-RedirectionException
| +-ResteasyRedirectionException
+-ServerErrorException
| +-ResteasyServerErrorException
| +-InternalServerErrorException
| | +-ResteasyInternalServerErrorException
| +-ServiceUnavailableException
| | +-ResteasyServiceUnavailableException

The new Exceptions play the same role as the original ones, but RESTEasy treats them slightly differently. When a Client detects that it is running in the context of a resource method, it will throw one of the new Exceptions. However, instead of storing the original Response, it stores a "sanitized" version of the Response, in which only the status and the Allow and Content-Type headers are preserved. The original WebApplicationException, and therefore the original Response, can be accessed in one of two ways:

// Create a NotAcceptableException.
NotAcceptableException nae = new NotAcceptableException(Response.status(406).entity("ooops").build());

// Wrap the NotAcceptableException in a ResteasyNotAcceptableException.
ResteasyNotAcceptableException rnae = (ResteasyNotAcceptableException) WebApplicationExceptionWrapper.wrap(nae);

// Extract the original NotAcceptableException using instance method.
NotAcceptableException nae2 = rnae.unwrap();
Assert.assertEquals(nae, nae2);

// Extract the original NotAcceptableException using class method.
NotAcceptableException nae3 = (NotAcceptableException) WebApplicationExceptionWrapper.unwrap(nae); // second way
Assert.assertEquals(nae, nae3);
   

Note that this change is intended to introduce a safe default behavior in the case that the Exception generated by the remote call is allowed to make its way up to the server runtime. It is considered a good practice, though, to catch the Exception and treat it in some appropriate manner:

   @GET
   @Path("remote/{i}")
   public String remote(@PathParam("i") String i) throws Exception {
      Client client = ClientBuilder.newClient();
      try {
         return client.target("http://remote.com/exception/" + i).request().get(String.class);
      } catch (WebApplicationException wae) {
         ...
      }
   }

Note. While RESTEasy will default to the new, safer behavior, the original behavior can be restored by setting the configuration parameter "resteasy.original.webapplicationexception.behavior" to "true".

RESTEasy built-in exceptions can be overridden by writing an ExceptionMapper for the exception. You can write an ExceptionMapper for any thrown exception including WebApplicationException

RESTEasy supports (though not by default - see below) GZIP decompression. If properly configured, the client framework or a Jakarta RESTful Web Services service, upon receiving a message body with a Content-Encoding of "gzip", will automatically decompress it. The client framework can (though not by default - see below) automatically set the Accept-Encoding header to be "gzip, deflate" so you do not have to set this header yourself.

RESTEasy also supports (though not by default - see below) automatic compression. If the client framework is sending a request or the server is sending a response with the Content-Encoding header set to "gzip", RESTEasy will (if properly configured) do the compression. So that you do not have to set the Content-Encoding header directly, you can use the @org.jboss.resteasy.annotation.GZIP annotation.

@Path("/")
public interface MyProxy {

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

In the above example, we tag the outgoing message body, order, to be gzip compressed. The same annotation can be used to tag server responses

@Path("/")
public class MyService {

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

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

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

The designation of a compressible entity by the use of the @GZIP annotation is a built-in, specific instance of a more general facility supported by RESTEasy. There are three components to this facility.

The annotation @GZIP is built into RESTEasy, but ClientContentEncodingAnnotationFeature and ServerContentEncodingAnnotationFeature will also recognize application defined annotations. For example,

   @Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER})
   @Retention(RetentionPolicy.RUNTIME)
   @ContentEncoding("compress")
   public @interface Compress
   {
   }
   
   @Path("")
   public static class TestResource {
      
      @GET
      @Path("a")
      @Compress
      public String a() {
         return "a";
      }
   }
   

If TestResource.a() is invoked as follows

   @Test
   public void testCompress() throws Exception
   {
      Client client = ClientBuilder.newClient();
      Invocation.Builder request = client.target("http://localhost:8081/a").request();
      request.acceptEncoding("gzip,compress");
      Response response = request.get();
      System.out.println("content-encoding: "+ response.getHeaderString("Content-Encoding"));
      client.close();
   }
   

the output will be

content-encoding: compress
   

RESTEasy provides an extension to Jakarta RESTful Web Services that allows you to automatically set Cache-Control headers on a successful GET request. It can only be used on @GET annotated methods. A successful @GET request is any request that returns 200 OK response.

package org.jboss.resteasy.annotations.cache;

public @interface Cache
{
   int maxAge() default -1;
   int sMaxAge() default -1;
   boolean noStore() default false;
   boolean noTransform() default false;
   boolean mustRevalidate() default false;
   boolean proxyRevalidate() default false;
   boolean isPrivate() default false;
}

public @interface NoCache
{
   String[] fields() default {};
}

   

While @Cache builds a complex Cache-Control header, @NoCache is a simplified notation to indicate no caching is wanted; i.e. Cache-Control: nocache.

These annotations can be put on the resource class or interface and specifies a default cache value for each @GET resource method, or they can be put individually on each @GET resource method.

RESTEasy has the ability to set up a client-side, browser-like, cache. It can be used with the Client Proxy Framework, or with ordinary requests. 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 local memory. The cache obeys max-age requirements and will also automatically do HTTP 1.1 cache revalidation if either or both the Last-Modified and/or ETag headers are sent back with the original response. See the HTTP 1.1 specification for details on how Cache-Control or cache revalidation works.

It is very simple to enable caching. Here's an example of using the client cache with the Client Proxy Framework

@Path("/orders")
public interface OrderServiceClient {

   @Path("{id}")
   @GET
   @Produces("application/xml")
   public Order getOrder(@PathParam("id") String id);
}

To create a proxy for this interface and enable caching for that proxy requires only a few simple steps in which the BrowserCacheFeature is registered:

ResteasyWebTarget target = (ResteasyWebTarget) ClientBuilder.newClient().target("http://localhost:8081");
BrowserCacheFeature cacheFeature = new BrowserCacheFeature();
OrderServiceClient orderService = target.register(cacheFeature).proxy(OrderServiceClient.class);

BrowserCacheFeature will create a Resteasy LightweightBrowserCache by default. It is also possible to configure the cache, or install a completely different cache implementation:

ResteasyWebTarget target = (ResteasyWebTarget) ClientBuilder.newClient().target("http://localhost:8081");
LightweightBrowserCache cache = new LightweightBrowserCache();
cache.setMaxBytes(20);
BrowserCacheFeature cacheFeature = new BrowserCacheFeature();
cacheFeature.setCache(cache);
OrderServiceClient orderService = target.register(cacheFeature).proxy(OrderServiceClient.class); 

If using the standard Jakarta RESTful Web Services client framework to make invocations rather than the proxy framework, it is just as easy:

ResteasyWebTarget target = (ResteasyWebTarget) ClientBuilder.newClient().target("http://localhost:8081/orders/{id}");
BrowserCacheFeature cacheFeature = new BrowserCacheFeature();
target.register(cacheFeature);
String rtn = target.resolveTemplate("id", "1").request().get(String.class);

The LightweightBrowserCache, by default, has a maximum 2 megabytes of caching space. This can be changed programmatically by calling its setMaxBytes() method. If the cache gets full, the cache completely wipes itself of all cached data. This may seem a bit draconian, but the cache was written to avoid unnecessary synchronizations in a concurrent environment where the cache is shared between multiple threads. If a more complex caching solution is desired or a third party cache is to be plugged in please contact our resteasy-developers list and discuss it with the community.

RESTEasy has a server-side cache that can sit in front of Jakarta RESTful Web Services services. It automatically caches marshalled responses from HTTP GET Jakarta RESTful Web Services invocations if, and only if the Jakarta RESTful Web Services resource method sets a Cache-Control header. When a GET comes in, the RESTEasy Server Cache checks to see if the URI is stored in the cache. If found, it returns the already marshalled response without invoking the Jakarta RESTful Web Services method. Each cache entry has a max age to whatever is specified in the Cache-Control header of the initial request. The cache also will automatically generate an ETag using an MD5 hash on the response body. This allows the client to do HTTP 1.1 cache revalidation with the IF-NONE-MATCH header. The cache is also smart enough to perform revalidation if there is no initial cache hit, but the Jakarta RESTful Web Services method still returns a body that has the same ETag.

The cache is also automatically invalidated for a particular URI that has PUT, POST, or DELETE invoked on it. A reference to the cache can be obtained by injecting an org.jboss.resteasy.plugins.cache.ServerCache via the @Context annotation

    @Context
    ServerCache cache;

    @GET
    public String get(@Context ServerCache cache) {...}

To set up the server-side cache an instance of org.jboss.resteasy.plugins.cache.server.ServerCacheFeature must be registered via the Application's getSingletons() or getClasses() methods. The underlying cache is Infinispan. By default, RESTEasy will create an Infinispan cache for you. Alternatively, you can create and pass in an instance of your cache to the ServerCacheFeature constructor. Infinispan can also be configured by specifying various parameters. If using Maven, add RESTEasy's cache-core artifact to the project:

<dependency>
   <groupId>org.jboss.resteasy.cache</groupId>
   <artifactId>cache-core</artifactId>
   <version>${version.org.jboss.resteasy.cache}</version>
</dependency>

Next set up the Infinispan configuration in the application's web.xml, it would look like

<web-app>
    <context-param>
        <param-name>server.request.cache.infinispan.config.file</param-name>
        <param-value>infinispan.xml</param-value>
    </context-param>

    <context-param>
        <param-name>server.request.cache.infinispan.cache.name</param-name>
        <param-value>MyCache</param-value>
    </context-param>

</web-app>

server.request.cache.infinispan.config.file can either be a classpath or a file path. server.request.cache.infinispan.cache.name is the name of the cache to reference that is declared in the config file.

See Section 3.4, “Configuration” for more information about application configuration.

Jakarta RESTful Web Services provides an API for evaluating HTTP preconditions based on "If-Match", "If-None-Match", "If-Modified-Since" and "If-Unmodified-Since" headers.

            Response.ResponseBuilder rb = request.evaluatePreconditions(lastModified, etag);
        

By default RESTEasy will return status code 304 (Not modified) or 412 (Precondition failed) if any of conditions fails, however it is not compliant with RFC 7232 which states that headers "If-Match", "If-None-Match" MUST have higher precedence. RFC 7232 compatible mode can be enabled by setting the parameter resteasy.rfc7232preconditions to true. See Section 3.4, “Configuration” for more information about application configuration.

On the server-side there are two different types of filters. ContainerRequestFilters run before a Jakarta RESTful Web Services resource method is invoked. ContainerResponseFilters run after a Jakarta RESTful Web Services resource method is invoked. As an added caveat, ContainerRequestFilters come in two flavors: pre-match and post-matching. Pre-matching ContainerRequestFilters are designated with the @PreMatching annotation and will execute before the Jakarta RESTful Web Services 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 (i.e. strip .xml and add an Accept header). ContainerRequestFilters can abort the request by calling ContainerRequestContext.abortWith(Response). A filter might want to abort if it implements a custom authentication protocol.

After the resource class method is executed, Jakarta RESTful Web Services will run all ContainerResponseFilters. These filters allow the outgoing response to be modified before it is marshalling and sent to the client. Here is some pseudocode to give some understanding of how it works.

        // execute pre match filters
        for (ContainerRequestFilter filter : preMatchFilters) {
            filter.filter(requestContext);
            if (isAborted(requestContext)) {
               sendAbortionToClient(requestContext);
               return;
            }
        }
        // match the HTTP request to a resource class and method
        JaxrsMethod method = matchMethod(requestContext);

        // Execute post match filters
        for (ContainerRequestFilter filter : postMatchFilters) {
           filter.filter(requestContext);
           if (isAborted(requestContext)) {
              sendAbortionToClient(requestContext);
              return;
           }
        }

        // execute resource class method
        method.execute(request);

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

The client side also has two types of filters: ClientRequestFilter and ClientResponseFilter. ClientRequestFilters run before an HTTP request is sent over the wire to the server. ClientResponseFilters run after a response is received from the server, but before the response body is unmarshalled. ClientRequestFilters are allowed to abort the execution of the request and provide a canned response without going over the wire to the server. ClientResponseFilters can modify the Response object before it is handed back to application code. Here's pseudocode to illustrate this.

            // 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);
            }
        

While filters modify request or response headers, interceptors deal with message bodies. Interceptors are executed in the same call stack as their corresponding reader or writer. ReaderInterceptors wrap around the execution of MessageBodyReaders. WriterInterceptors wrap around the execution of MessageBodyWriters. They can be used to implement a specific content-encoding. They can be used to generate digital signatures or to post or pre-process a Java object model before or after it is marshalled.

Note that in order to support Async IO, AsyncWriterInterceptor can be implemented, which is a subtype of WriterInterceptor.

Sometimes it is desired to have a filter or interceptor only run for a specific resource method. This can be done in two different ways: register an implementation of DynamicFeature or use the @NameBinding annotation. The DynamicFeature interface is executed at deployment time for each resource method. Use the Configurable interface to register the filters and interceptors wanted for the specific resource method. @NameBinding works a lot like CDI interceptors. Annotate a custom annotation with @NameBinding and then apply that custom annotation to the filter and resource method. The custom annotation must use @Retention(RetentionPolicy.RUNTIME) in order for the attribute to be picked up by the RESTEasy runtime when it is deployed.

            @NameBinding
            @Retention(RetentionPolicy.RUNTIME)
            public @interface DoIt {}

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

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

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

Ordering is accomplished by using the @BindingPriority annotation on the filter or interceptor classes.

The Jakarta RESTful Web Services specification includes asynchronous HTTP support via two classes. The @Suspended annotation, and AsyncResponse interface.

Injecting an AsyncResponse as a parameter to a Jakarta RESTful Web Services methods tells RESTEasy that the HTTP request/response should be detached from the currently executing thread and that the current thread should not try to automatically process the response.

The AsyncResponse is the callback object. The act of calling one of the resume() methods will cause a response to be sent back to the client and will also terminate the HTTP request. Here is an example of asynchronous processing:

import jakarta.ws.rs.Suspend;
import jakarta.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)
            {
               response.resume(e);
            }
         }
      };
      t.start();
   }
}
      

AsyncResponse also has other methods to cancel the execution. See javadoc for more details.

NOTE: In RESTEasy version 4.0.0.Final proprietary annotation org.jboss.resteasy.annotations.Suspend was removed and replaced by jakarta.ws.rs.container.Suspended and class org.jboss.resteasy.spi.AsynchronousResponse was removed and replaced by jakarta.ws.rs.container.AsyncResponse.

jakarta.ws.rs.container.Suspended replaces javax.ws.rs.container.Suspended. Note that @Suspended does not have a value field, which represented a timeout limit. Instead, AsyncResponse.setTimeout() may be called.

The Jakarta RESTful Web Services 2.1 specification adds support for declaring asynchronous resource methods by returning a CompletionStage instead of using the @Suspended annotation.

Whenever a resource method returns a CompletionStage, it will be subscribed to, the request will be suspended, and only resumed when the CompletionStage is resolved either to a value (which is then treated as the return value for the method), or as an error case, in which case the exception will be processed as if it were thrown by the resource method.

Here is an example of asynchronous processing using CompletionStage:

import jakarta.ws.rs.Suspend;
import jakarta.ws.rs.container.AsyncResponse;

@Path("/")
public class SimpleResource
{

   @GET
   @Path("basic")
   @Produces("text/plain")
   public CompletionStage<Response> getBasic() throws Exception
   {
      final CompletableFuture<Response> response = new CompletableFuture<>();
      Thread t = new Thread()
      {
         @Override
         public void run()
         {
            try
            {
               Response jaxrs = Response.ok("basic").type(MediaType.TEXT_PLAIN).build();
               response.complete(jaxrs);
            }
            catch (Exception e)
            {
               response.completeExceptionally(e);
            }
         }
      };
      t.start();
      return response;
   }
}
     

It is possible to write filters that also make the request asynchronous. Whether filters make the request asynchronous before execution of a method makes absolutely no difference to a method: it does not need to be declared asynchronous in order to function as specified. Synchronous methods and asynchronous methods will work as specified by the spec.

Some backends support asynchronous IO operations (Servlet, Undertow, Vert.x, Quarkus, Netty), which are exposed using the AsyncOutputStream subtype of OutputStream. It includes async variants for writing and flushing the stream.

Some backends have what is called an "Event Loop Thread", which is a thread responsible for doing all IO operations. Those backends require the Event Loop Thread to never be blocked, because it does IO for every other thread. Those backends typically require Jakarta RESTful Web Services endpoints to be invoked on worker threads, to make sure they never block the Event Loop Thread.

Sometimes, with Async programming, it is possible for asynchronous Jakarta RESTful Web Services requests to be resumed from the Event Loop Thread. As a result, Jakarta RESTful Web Services will attempt to serialise the response and send it to the client. But Jakarta RESTful Web Services is written using "Blocking IO" mechanics, such as OutputStream (used by MessageBodyWriter and WriterInterceptor), which means that sending the response will block the current thread until the response is received. This would work on a worker thread, but if it happens on the Event Loop Thread it will block it and prevent it from sending the response, resulting in a deadlock.

As a result, we've decided to support and expose Async IO interfaces in the form of AsyncOutputStream, AsyncMessageBodyWriter and AsyncWriterInterceptor, to allow users to write Async IO applications in RESTEasy.

Most built-in MessageBodyWriter and WriterInterceptor support Async IO, with the notable exceptions of:

Async IO will be preferred if the following conditions are met:

If those conditions are not met, and you attempt to use Blocking IO on an Event Loop Thread (as determined by the backend), then an exception will be thrown.

While HTTP is a synchronous protocol it does have a faint idea of asynchronous invocations. The HTTP 1.1 response code 202, "Accepted" means that the server has received and accepted the response for processing, but the processing has not yet been completed. The RESTEasy Asynchronous Job Service builds around this idea.

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

For example, if making the above post with the asynch query parameter set to true, RESTEasy will return a 202, "Accepted" response code and run the invocation in the background. It also sends back a Location header with a URL pointing to where the response of the background method is located.

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

The URI will have the form of:

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

You can perform the GET, POST, and DELETE operations on this job URL. GET returns whatever the Jakarta RESTful Web Services resource method invoked returnes as a response if the job was completed. If the job has not completed, this GET will return a response code of 202, Accepted. Invoking GET does not remove the job, so it can be called multiple times. When RESTEasy's job queue gets full, it will evict the least recently used job from memory. Manual clean up can be performed by calling DELETE on the URI. POST does a read of the JOB response and will remove the JOB it has completed.

Both GET and POST allow the specification of a maximum wait time in milliseconds, a "wait" query parameter. Here's an example:

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

If a "wait" parameter is not specified, the GET or POST will not wait if the job is not complete.

NOTE!! While GET, DELETE, and PUT methods can be invoked asynchronously, this breaks the HTTP 1.1 contract of these methods. While these invocations may not change the state of the resource if invoked more than once, they do change the state of the server as new Job entries with each invocation. To be a purist, stick with only invoking POST methods asynchronously.

Security NOTE! RESTEasy's role-based security (annotations) does not work with the Asynchronous Job Service. XML declarative security must be used within the web.xml file, because it is impossible to implement role-based security in a portable way.

NOTE. A java.security.SecureRandom object is used to generate unique job ids. For security purposes, the SecureRandom is periodically reseeded. By default, it is reseeded after 100 uses. This value may be configured with the servlet init parameter "resteasy.secure.random.max.use".

RESTEasy also supports the notion of fire and forget. This will also return a 202, Accepted response, but no Job will be created. This is as simple as using the oneway query parameter instead of asynch. For example:

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

Security NOTE! RESTEasy role-based security (annotations) does not work with the Asynchronous Job Service. XML declaritive security must be use within the web.xml file, because it is impossible to implement role-based security in a portable way.

The Asynchronous Job Service must be enabled, as it is not turned on by default. If the relevant configuration properties are configured in web.xml, it would look like the following:

<web-app>
    <!-- enable the Asynchronous Job Service -->
    <context-param>
        <param-name>resteasy.async.job.service.enabled</param-name>
        <param-value>true</param-value>
    </context-param>

    <!-- The next context parameters are all optional.  
         Their default values are shown as example param-values -->

    <!-- How many jobs results can be held in memory at once? -->
    <context-param>
        <param-name>resteasy.async.job.service.max.job.results</param-name>
        <param-value>100</param-value>
    </context-param>

    <!-- Maximum wait time on a job when a client is querying for it -->
    <context-param>
        <param-name>resteasy.async.job.service.max.wait</param-name>
        <param-value>300000</param-value>
    </context-param>

    <!-- Thread pool size of background threads that run the job -->
    <context-param>
        <param-name>resteasy.async.job.service.thread.pool.size</param-name>
        <param-value>100</param-value>
    </context-param>

    <!-- Set the base path for the Job uris -->
    <context-param>
        <param-name>resteasy.async.job.service.base.path</param-name>
        <param-value>/asynch/jobs</param-value>
    </context-param>

    ...
</web-app>

See Section 3.4, “Configuration” for more information about application configuration.

The org.jboss.resteasy.spi.ContextInjector interface must be implemented on any custom asynch injector object. The implementation class must be tagged with the @Provider annotation.

/**
 * @param <WrappedType> A class that wraps a data type or data object
 *                            (e.g. Single<Foo>)
 * @param <UnwrappedType> The data type or data object declared in the
 *                              WrappedType (e.g. Foo)
*/
public interface ContextInjector<WrappedType, UnwrappedType> {
/**
 * This interface allows users to create custom injectable asynchronous types.
 *
 * Asynch injection is only attempted at points where asynchronous injection is
 * permitted, such as on resource creation and resource method invocation. It
 * is not enabled at points where the API does not allow for suspending the
 * request
 *
 * @param rawType
 * @param genericType
 * @param annotations The annotation list is useful to parametrize the injection.
 * @return
 */
 public WrappedType resolve(
            Class<? extends WrappedType> rawType,
            Type genericType,
            Annotation[] annotations);
  }
        

package my.test;

public class Foo {
   private String value = "PRE-SET-VALUE";

   public void setValue(String s) {
      this.value = s;
   }

   public String getValue() {
      return this.value;
   }
}
        

package my.test.asyc.resources;

import io.reactivex.Single;
import jakarta.ws.rs.ext.Provider;
import org.jboss.resteasy.spi.ContextInjector;
import my.test.Foo;

@Provider
public class FooAsychInjectorProvider implements
            ContextInjector<Single<Foo>,Foo> {

   public Single<Foo> resolve(Class<? extends Single<Foo>> rawType,
            Type genericType,
            Annotation[] annotations)
   {
      Foo value = new Foo();
      return Single.just(value.setValue("made it"));
   }
}
        

A convenience interface to provide annotation parameter designators

@Retention(RUNTIME)
@Target({ FIELD, METHOD, PARAMETER })
public @interface AsyncInjectionPrimitiveInjectorSpecifier
{
   public enum Type {
      VALUE, NULL, NO_RESULT;
   }

   Type value() default Type.VALUE;
}
    

@Provider
public class AsyncInjectionFloatInjector implements
            ContextInjector<CompletionStage<Float>, Float>
{

   @Override
   public CompletionStage<Float> resolve(
      Class<? extends CompletionStage<Float>> rawType,
            Type genericType,
            Annotation[] annotations)
    {
       for (Annotation annotation : annotations)
       {
           if(annotation.annotationType() ==
              AsyncInjectionPrimitiveInjectorSpecifier.class) {
             AsyncInjectionPrimitiveInjectorSpecifier.Type value =
               ((AsyncInjectionPrimitiveInjectorSpecifier)annotation).value();
             switch(value) {
               case NO_RESULT:
                  return null;
               case NULL:
                  return CompletableFuture.completedFuture(null);
               case VALUE:
                  return CompletableFuture.completedFuture(4.2f);
            }
            break;
          }
       }
       return CompletableFuture.completedFuture(4.2f);
    }
}
        

In Java 1.8 and Jakarta RESTful Web Services, the support for reactive programming is fairly limited. Java 1.8 introduces the interface java.util.concurrent.CompletionStage, and Jakarta RESTful Web Services mandates support for the jakarta.ws.rs.client.CompletionStageRxInvoker, which allows a client to obtain a response in the form of a CompletionStage.

One implementation of CompletionStage is the java.util.concurrent.CompleteableFuture. For example:

@Test
public void testCompletionStage() throws Exception {
   CompletionStage<String> stage = getCompletionStage();
   log.info("result: " + stage.toCompletableFuture().get());
}

private CompletionStage<String> getCompletionStage() {
   CompletableFuture<String> future = new CompletableFuture<String>();
   future.complete("foo");
   return future;
}

Here, a CompleteableFuture is created with the value "foo", and its value is extracted by the method CompletableFuture.get(). That's fine, but consider the altered version:

@Test
public void testCompletionStageAsync() throws Exception {
   log.info("start");
   CompletionStage<String> stage = getCompletionStageAsync();
   String result = stage.toCompletableFuture().get();
   log.info("do some work");
   log.info("result: " + result);
}

private CompletionStage<String> getCompletionStageAsync() {
   CompletableFuture<String> future = new CompletableFuture<String>();
   Executors.newCachedThreadPool().submit(() -> {sleep(2000); future.complete("foo");});
   return future;
}

private void sleep(long l) {
   try {
      Thread.sleep(l);
   } catch (InterruptedException e) {
      e.printStackTrace();
   }
}

with output something like:

3:10:51 PM INFO: start
3:10:53 PM INFO: do some work
3:10:53 PM INFO: result: foo

It also works, but it illustrates the fact that CompletableFuture.get() is a blocking call. The CompletionStage is constructed and returned immediately, but the value isn't returned for two seconds. A version that is more in the spirit of the reactive style is:

@Test
public void testCompletionStageAsyncAccept() throws Exception {
   log.info("start");
   CompletionStage<String> stage = getCompletionStageAsync();
   stage.thenAccept((String s) -> log.info("s: " + s));
   log.info("do some work");
   ...
}

In this case, the lambda (String s) -> log.info("s: " + s) is registered with the CompletionStage as a "subscriber", and, when the CompletionStage eventually has a value, that value is passed to the lambda. Note that the output is something like

3:23:05 INFO: start
3:23:05 INFO: do some work
3:23:07 INFO: s: foo

Executing CompletionStages asynchronously is so common that there are several supporting convenience methods. For example:

@Test
public void testCompletionStageSupplyAsync() throws Exception {
   CompletionStage<String> stage = getCompletionStageSupplyAsync();;
   stage.thenAccept((String s) -> log.info("s: " + s));
}

private CompletionStage<String> getCompletionStageSupplyAsync() {
   return CompletableFuture.supplyAsync(() -> "foo");
}

The static method ComputableFuture.supplyAsync() creates a ComputableFuture, the value of which is supplied asynchronously by the lambda () -> "foo", running, by default, in the default pool of java.util.concurrent.ForkJoinPool.

One final example illustrates a more complex computational structure:

@Test
public void testCompletionStageComplex() throws Exception {
   ExecutorService executor = Executors.newCachedThreadPool();
   CompletionStage<String> stage1 = getCompletionStageSupplyAsync1("foo", executor);
   CompletionStage<String> stage2 = getCompletionStageSupplyAsync1("bar", executor);
   CompletionStage<String> stage3 = stage1.thenCombineAsync(stage2, (String s, String t) -> s + t, executor);
   stage3.thenAccept((String s) -> log.info("s: " + s));
}

private CompletionStage<String> getCompletionStageSupplyAsync1(String s, ExecutorService executor) {
   return CompletableFuture.supplyAsync(() -> s, executor);
}

stage1 returns "foo", stage2 returns "bar", and stage3, which runs when both stage1 and stage2 have completed, returns the concatenation of "foo" and "bar". Note that, in this example, an explict ExecutorService is provided for asynchronous processing.

On the client side, the Jakarta RESTful Web Services specification mandates an implementation of the interface jakarta.ws.rs.client.CompletionStageRxInvoker:

public interface CompletionStageRxInvoker extends RxInvoker<CompletionStage> {

    @Override
    public CompletionStage<Response> get();

    @Override
    public <T> CompletionStage<T> get(Class<T> responseType);

    @Override
    public <T> CompletionStage<T> get(GenericType<T> responseType);
    ...

That is, there are invocation methods for the standard HTTP verbs, just as in the standard jakarta.ws.rs.client.SyncInvoker. A CompletionStageRxInvoker is obtained by calling rx() on a jakarta.ws.rs.client.Invocation.Builder, which extends SyncInvoker. For example,

Invocation.Builder builder = client.target(generateURL("/get/string")).request();
CompletionStageRxInvoker invoker = builder.rx(CompletionStageRxInvoker.class);
CompletionStage<Response> stage = invoker.get();
Response response = stage.toCompletableFuture().get();
log.info("result: " + response.readEntity(String.class));

or

CompletionStageRxInvoker invoker = client.target(generateURL("/get/string")).request().rx(CompletionStageRxInvoker.class);
CompletionStage<String> stage = invoker.get(String.class);
String s = stage.toCompletableFuture().get();
log.info("result: " + s);

On the server side, the Jakarta RESTful Web Services specification requires support for resource methods with return type CompletionStage<T>. For example,

@GET
@Path("get/async")
public CompletionStage<String> longRunningOpAsync() {
   CompletableFuture<String> cs = new CompletableFuture<>();
   executor.submit(
      new Runnable() {
         public void run() {
            executeLongRunningOp();
            cs.complete("Hello async world!");
         }
      });
   return cs;
}

The way to think about longRunningOpAsync() is that it is asynchronously creating and returning a String. After cs.complete() is called, the server will return the String "Hello async world!" to the client.

An important thing to understand is that the decision to produce a result asynchronously on the server and the decision to retrieve the result asynchronously on the client are independent. Suppose that there is also a resource method

@GET
@Path("get/sync")
public String longRunningOpSync() {
   return "Hello async world!";
}

Then all three of the following invocations are valid:

public void testGetStringAsyncAsync() throws Exception {
   CompletionStageRxInvoker invoker = client.target(generateURL("/get/async")).request().rx();
   CompletionStage<String> stage = invoker.get(String.class);
   log.info("s: " + stage.toCompletableFuture().get());
}

public void testGetStringSyncAsync() throws Exception {
   Builder request = client.target(generateURL("/get/async")).request();
   String s = request.get(String.class);
   log.info("s: " + s);
}

and

public void testGetStringAsyncSync() throws Exception {
   CompletionStageRxInvoker invoker = client.target(generateURL("/get/sync")).request().rx();
   CompletionStage<String> stage = invoker.get(String.class);
   log.info("s: " + stage.toCompletableFuture().get());
}

@GET
@Path("test")
@Produces("text/plain")
public CompletionStage<String> text(@Context HttpRequest request) {
   System.out.println("request (inline): " + request);
   System.out.println("application (inline): " + ResteasyContext.getContextData(Application.class));
   CompletableFuture<String> cs = new CompletableFuture<>();
   ExecutorService executor = Executors.newSingleThreadExecutor();
   executor.submit(
         new Runnable() {
            public void run() {
               try {
                  System.out.println("request (async): " + request); 
                  System.out.println("application (async): " + ResteasyContext.getContextData(Application.class));
                  cs.complete("hello");
               } catch (Exception e) {
                  e.printStackTrace();
               }
            }
         });
   return cs;
}

application (inline): org.jboss.resteasy.experiment.Test1798CompletionStage$TestApp@23c57474
request (inline): org.jboss.resteasy.plugins.server.servlet.Servlet3AsyncHttpRequest@2ce23138
application (async): null
org.jboss.resteasy.spi.LoggableFailure: RESTEASY003880: Unable to find contextual data of type: org.jboss.resteasy.spi.HttpRequest

@GET
@Path("test")
@Produces("text/plain")
public CompletionStage<String> text(@Context HttpRequest request) {
   System.out.println("request (inline): " + request);
   System.out.println("application (inline): " + ResteasyContext.getContextData(Application.class));
   CompletableFuture<String> cs = new CompletableFuture<>();
   ExecutorService executor = Executors.newSingleThreadExecutor();
   final String httpMethodFinal = request.getHttpMethod();
   final Map<String, Object> mapFinal = ResteasyContext.getContextData(Application.class).getProperties();
   executor.submit(
         new Runnable() {
            public void run() {
               System.out.println("httpMethod (async): " + httpMethodFinal); 
               System.out.println("map (async): " + mapFinal); 
               cs.complete("hello");
            }
         });
   return cs;
}

@GET
@Path("test")
@Produces("text/plain")
public CompletionStage<String> text(@Context HttpRequest request) {
   System.out.println("request (inline): " + request);
   System.out.println("application (inline): " + ResteasyContext.getContextData(Application.class));
   CompletableFuture<String> cs = new CompletableFuture<>();
   ThreadContext threadContext = ThreadContext.builder()
                                                   .propagated(ThreadContext.ALL_REMAINING)
                                                   .unchanged()
                                                   .cleared()
                                                   .build();
   ExecutorService executor = Executors.newSingleThreadExecutor();
   executor.submit(
         threadContext.contextualRunnable(new Runnable() {
            public void run() {
               try {
                  System.out.println("request (async): " + request); 
                  System.out.println("application (async): " + ResteasyContext.getContextData(Application.class));
                  cs.complete("hello");
               } catch (Exception e) {
                  e.printStackTrace();
               }
            }
         }));
   return cs;
}

@GET
@Path("test")
@Produces(MediaType.TEXT_PLAIN)
public CompletionStage<String> text(@Context UriInfo uriInfo) {
  CompletableFuture<String> cs = new CompletableFuture<>();
  ExecutorService executor = ContextualExecutors.threadPool();
  executor.submit(() -> {
     try {
        cs.complete("hello from: " + uriInfo.getAbsolutePath());
     } catch (Exception e) {
        e.printStackTrace();
     }
  });
  return cs;
}

The picture becomes more complex and interesting when sequences are added. A CompletionStage holds no more than one potential value, but other reactive objects can hold multiple, even unlimited, values. Currently, most Java implementations of reactive programming are based on the project Reactive Streams (http://www.reactive-streams.org/), which defines a set of four interfaces and a specification, in the form of a set of rules, describing how they interact:

public interface Publisher<T> {
    public void subscribe(Subscriber<? super T> s);
}

public interface Subscriber<T> {
    public void onSubscribe(Subscription s);
    public void onNext(T t);
    public void onError(Throwable t);
    public void onComplete();
}

public interface Subscription {
    public void request(long n);
    public void cancel();
}

public interface Processor<T, R> extends Subscriber<T>, Publisher<R> {
}

A Producer pushes objects to a Subscriber, a Subscription mediates the relationship between the two, and a Processor which is derived from both, helps to construct pipelines through which objects pass.

One important aspect of the specification is flow control, the ability of a Suscriber to control the load it receives from a Producer by calling Suscription.request(). The general term in this context for flow control is backpressure.

There are a number of implementations of Reactive Streams, including

RESTEasy currently supports RxJava (deprecated), RxJava2 and Reactor.

Jakarta RESTful Web Services doesn't currently require support for any Reactive Streams implementations, but it does allow for extensibility to support various reactive libraries. RESTEasy's optional module resteasy-rxjava2 adds support for RxJava 2.

More in details, resteasy-rxjava2 contributes support for reactive types io.reactivex.Single, io.reactivex.Flowable, and io.reactivex.Observable. Of these, Single is similar to CompletionStage in that it holds at most one potential value. Flowable implements io.reactivex.Publisher, and Observable is very similar to Flowable except that it doesn't support backpressure. If importing resteasy-rxjava2, you can start returning these reactive types from your resource methods on the server side and receiving them on the client side.

public class Thing {

   private String name;

   public Thing() {
   }

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

@POST
@Path("post/thing/list")
@Produces(MediaType.APPLICATION_JSON)
@Stream
public Flowable<List<Thing>> postThingList(String s) {
   return buildFlowableThingList(s, 2, 3);
}

static Flowable<List<Thing>> buildFlowableThingList(String s, int listSize, int elementSize) {
   return Flowable.create(
      new FlowableOnSubscribe<List<Thing>>() {

         @Override
         public void subscribe(FlowableEmitter<List<Thing>> emitter) throws Exception {
            for (int i = 0; i < listSize; i++) {
               List<Thing> list = new ArrayList<Thing>();
               for (int j = 0; j < elementSize; j++) {
                  list.add(new Thing(s));
               }
               emitter.onNext(list);
            }
            emitter.onComplete();
         }
      },
      BackpressureStrategy.BUFFER);
}

Flowable<List<Thing>> Flowable.create(FlowableOnSubscribe<List<Thing>> source, BackpressureStrategy mode);

/**
 * Base interface for emitting signals in a push-fashion in various generator-like source
 * operators (create, generate).
 *
 * @param <T> the value type emitted
 */
public interface Emitter<T> {

    /**
     * Signal a normal value.
     * @param value the value to signal, not null
     */
    void onNext(@NonNull T value);

    /**
     * Signal a Throwable exception.
     * @param error the Throwable to signal, not null
     */
    void onError(@NonNull Throwable error);

    /**
     * Signal a completion.
     */
    void onComplete();
}

/**
 * A functional interface that has a {@code subscribe()} method that receives
 * an instance of a {@link FlowableEmitter} instance that allows pushing
 * events in a backpressure-safe and cancellation-safe manner.
 *
 * @param <T> the value type pushed
 */
public interface FlowableOnSubscribe<T> {

    /**
     * Called for each Subscriber that subscribes.
     * @param e the safe emitter instance, never null
     * @throws Exception on error
     */
    void subscribe(@NonNull FlowableEmitter<T> e) throws Exception;
}

/**
 * Access a reactive invoker based on a {@link RxInvoker} subclass provider. Note
 * that corresponding {@link RxInvokerProvider} must be registered in the client runtime.
 * 
 * This method is an extension point for Jakarta RESTful Web Services implementations to support other types
 * representing asynchronous computations.
 *
 * @param clazz {@link RxInvoker} subclass.
 * @return reactive invoker instance.
 * @throws IllegalStateException when provider for given class is not registered.
 * @see jakarta.ws.rs.client.Client#register(Class)
 * @since 2.1
 */
public <T extends RxInvoker> T rx(Class<T> clazz);

@SuppressWarnings("unchecked")
@Test
public void testPostThingList() throws Exception {
   CountDownLatch latch = new CountdownLatch(1);
   FlowableRxInvoker invoker = client.target(generateURL("/post/thing/list")).request().rx(FlowableRxInvoker.class);
   Flowable<List<Thing>> flowable = (Flowable<List<Thing>>) invoker.post(Entity.entity("a", MediaType.TEXT_PLAIN_TYPE), new GenericType<List<Thing>>() {});
   flowable.subscribe(
         (List<?> l) -> thingListList.add(l),
         (Throwable t) -> latch.countDown(),
         () -> latch.countDown());
   latch.await();
   Assert.assertEquals(aThingListList, thingListList);
}

[[Thing[a], Thing[a], Thing[a]], [Thing[a], Thing[a], Thing[a]]]

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Stream
{
   public enum MODE {RAW, GENERAL};
   public String INCLUDE_STREAMING_PARAMETER = "streaming";
   public MODE value() default MODE.GENERAL;
   public boolean includeStreaming() default false;
}

@POST
@Path("post/thing/list")
@Produces(MediaType.APPLICATION_JSON)
@Stream(Stream.MODE.GENERAL)
public Flowable<List<Thing>> postThingList(String s) {
   return buildFlowableThingList(s, 2, 3);
}
...
@SuppressWarnings("unchecked")
@Test
public void testPostThingList() throws Exception {
   CountDownLatch latch = new CountdownLatch(1);
   FlowableRxInvoker invoker = client.target(generateURL("/post/thing/list")).request().rx(FlowableRxInvoker.class);
   Flowable<List<Thing>> flowable = (Flowable<List<Thing>>) invoker.post(Entity.entity("a", MediaType.TEXT_PLAIN_TYPE), new GenericType<List<Thing>>() {});
   flowable.subscribe(
         (List<?> l) -> thingListList.add(l),
         (Throwable t) -> latch.countDown(),
         () -> latch.countDown());
   latch.await();
   Assert.assertEquals(aThingListList, thingListList);
}

data: [{"name":"a"},{"name":"a"},{"name":"a"}]
data: [{"name":"a"},{"name":"a"},{"name":"a"}]

@POST
@Path("post/thing/list")
@Produces(MediaType.APPLICATION_JSON)
public Flowable<List<Thing>> postThingList(String s) {
   return buildFlowableThingList(s, 2, 3);
}
...
@Test
public void testPostThingList() throws Exception {
   Builder request = client.target(generateURL("/post/thing/list")).request();
   List<List<Thing>> list = request.post(Entity.entity("a", MediaType.TEXT_PLAIN_TYPE), new GenericType<List<List<Thing>>>() {});
   Assert.assertEquals(aThingListList, list);
}  

[[{"name":"a"},{"name":"a"},{"name":"a"}],[{"name":"a"},{"name":"a"},{"name":"a"}]]

@GET
@Path("get/bytes")
@Produces(MediaType.APPLICATION_OCTET_STREAM)
@Stream(Stream.MODE.RAW)
public Flowable<byte[]> getBytes() {
   return Flowable.create(
      new FlowableOnSubscribe<byte[]>() {

         @Override
         public void subscribe(FlowableEmitter<byte[]> emitter) throws Exception {
            for (int i = 0; i < 3; i++) {
               byte[] b = new byte[10];
               for (int j = 0; j < 10; j++) {
                  b[j] = (byte) (i + j);
               }
               emitter.onNext(b);
            }
            emitter.onComplete();
         }
      },
      BackpressureStrategy.BUFFER);
}
...
@Test
public void testGetBytes() throws Exception {
   Builder request = client.target(generateURL("/get/bytes")).request();
   InputStream is = request.get(InputStream.class);
   int n = is.read();
   while (n > -1) {
      System.out.print(n);
      n = is.read();
   }
}

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface SseElementType
{
   public String value();
}

@GET
@Path("eventStream/thing")
@Produces("text/event-stream")
@SseElementType("application/json")
public void eventStreamThing(@Context SseEventSink eventSink, @Context Sse sse) {
   new ScheduledThreadPoolExecutor(5).execute(() -> {
      try (SseEventSink sink = eventSink) {
         OutboundSseEvent.Builder  builder = sse.newEventBuilder();
         eventSink.send(builder.data(new Thing("e1")).build());
         eventSink.send(builder.data(new Thing("e2")).build());
         eventSink.send(builder.data(new Thing("e3")).build());
      }
   });
}
...
@SuppressWarnings("unchecked")
@Test
public void testFlowableToSse() throws Exception {
   CountDownLatch latch = new CountDownLatch(1);
   final AtomicInteger errors = new AtomicInteger(0);
   FlowableRxInvoker invoker = client.target(generateURL("/eventStream/thing")).request().rx(FlowableRxInvoker.class);
   Flowable<Thing> flowable = (Flowable<Thing>) invoker.get(Thing.class);
   flowable.subscribe(
      (Thing t) -> thingList.add(t),
      (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(eThingList, thingList);
}  

data: {"name":"e1"}
data: {"name":"e2"}
data: {"name":"e3"}

    text/event-stream;element-type="application/json"

@GET
@Path("flowable/thing")
@Produces("text/event-stream")
@SseElementType("application/json")
public Flowable<Thing> flowableSSE() {
   return Flowable.create(
      new FlowableOnSubscribe<Thing>() {

         @Override
         public void subscribe(FlowableEmitter<Thing> emitter) throws Exception {
            emitter.onNext(new Thing("e1"));
            emitter.onNext(new Thing("e2"));
            emitter.onNext(new Thing("e3"));
            emitter.onComplete();
         }
      },
      BackpressureStrategy.BUFFER);
}
...
@Test
public void testSseToFlowable() throws Exception {
   final CountDownLatch latch = new CountDownLatch(3);
   final AtomicInteger errors = new AtomicInteger(0);
   WebTarget target = client.target(generateURL("/flowable/thing"));
   SseEventSource msgEventSource = SseEventSource.target(target).build();
   try (SseEventSource eventSource = msgEventSource)
   {
      eventSource.register(
         event -> {thingList.add(event.readData(Thing.class, MediaType.APPLICATION_JSON_TYPE)); latch.countDown();},
         ex -> errors.incrementAndGet());
      eventSource.open();

      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(eThingList, thingList);
   }
}

Proxies, discussed in RESTEasy Proxy Framework, are a RESTEasy extension that supports a natural programming style in which generic Jakarta RESTful Web Services invoker calls are replaced by application specific interface calls. The proxy framework is extended to include both CompletionStage and the RxJava2 types Single, Observable, and Flowable.

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 = (ResteasyClient)ClientBuilder.newClient();
      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 = (ResteasyClient)ClientBuilder.newClient();
      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);
   }
}

RESTEasy implements a framework that supports extensions for additional reactive classes. To understand the framework, it is necessary to understand the existing support for CompletionStage and other reactive classes.

Server side. When a resource method returns a CompletionStage, RESTEasy subscribes to it using the class org.jboss.resteasy.core.AsyncResponseConsumer.CompletionStageResponseConsumer. When the CompletionStage completes, it calls CompletionStageResponseConsumer.accept(), which sends the result back to the client.

Support for CompletionStage is built in to RESTEasy, but it's not hard to extend that support to a class like Single by providing a mechanism for transforming a Single into a CompletionStage. In module resteasy-rxjava2, that mechanism is supplied by org.jboss.resteasy.rxjava2.SingleProvider, which implements interface org.jboss.resteasy.spi.AsyncResponseProvider<Single<?>>:

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

Given SingleProvider, 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. Subscribing is done by calling org.reactivestreams.Publisher.subscribe(), so a mechanism is needed for turning, say, a Flowable into a Publisher. That is, an implementation of org.jboss.resteasy.spi.AsyncStreamProvider<Flowable> is called for, where AsyncStreamProvider is defined:

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

In module resteasy-rxjava2, org.jboss.resteasy.FlowableProvider provides that mechanism for Flowable. [Actually, that's not too hard since, in rxjava2, a Flowable is a Provider.]

So, on the server side, adding support for other reactive types can be done by declaring a @Provider for the interface AsyncStreamProvider (for streams) or AsyncResponseProvider (for single values), which both have a single method to convert the new reactive type into (respectively) a Publisher (for streams) or a CompletionStage (for single values).

Client side. The Jakarta RESTful Web Services specification imposes two requirements for support of reactive classes on the client side:

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

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

SingleProvider's ability to turn a CompletionStage into a Single is used in the implementation of org.jboss.resteasy.rxjava2.SingleRxInvokerImpl.

The same concept might be useful in implementing other RxInvokers. Note, though, that ObservableRxInvokerImpl and FlowableRxInvokerImpl in module resteasy-rxjava2 are each derived directly from the SSE implementation.

One of the central ideas in MicroProfile Rest Client is a version of distributed object communication, a concept implemented in, among other places, CORBA, Java RMI, the JBoss Remoting project, and RESTEasy. Consider the resource

@Path("resource")
public class TestResource {

   @Path("test")
   @GET
   String test() {
      return "test";
   }
}

The Jakarta RESTful Web Services native way of accessing TestResource looks like

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

The call to TestResource.test() is not particularly onerous, but calling test() directly allows a more natural syntax. That is exactly what Microprofile Rest Client supports:

@Path("resource")
public interface TestResourceIntf {

   @Path("test")
   @GET
   public String test();
}
   
TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl("http://localhost:8081/")
                              .build(TestResourceIntf.class);
String s = service.test();

The first four lines of executable code are spent creating a proxy, service, that implements TestResourceIntf, but once that is done, calls on TestResource can be made very naturally in terms of TestResourceIntf, as illustrated by the call service.test().

Beyond the natural syntax, another advantage of proxies is the way the proxy construction process quietly gathers useful information from the implemented interface and makes it available for remote invocations. Consider a more elaborate version of TestResourceIntf:

@Path("resource")
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);
}

Calling service.test("p", "q", "e") 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

The HTTP verb is derived from the @POST annotation, the request URI is derived from the two instances of the @Path annotation (one on the class, one on the method) plus the first and second parameters of test(), the Accept header is derived from the @Produces annotation, and the Content-Type header is derived from the @Consumes annotation,

Using the Jakarta RESTful Web Services API, service.test("p", "q", "e") would look like the more verbose

Client client = ClientBuilder.newClient();
String response = client.target("http://localhost:8081/resource/test/p")
                     .queryParam("query", "q")
                     .request()
                     .accept("text/html")
                     .post(Entity.entity("e", "text/plain"), String.class);

One other basic facility offered by MicroProfile Rest Client is the ability to configure the client environment by registering providers:

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

Naturally, the registered providers should be relevant to the client environment, rather than, say, a ContainerResponseFilter.

ResteasyClient client = (ResteasyClient) ResteasyClientBuilder.newClient();
TestResourceIntf service = client.target("http://localhost:8081/")
                              .register(MyClientResponseFilter.class)
                              .register(MyMessageBodyReader.class)
                              .proxy(TestResourceIntf.class);

Beyond the central concept of the client proxy, some basic concepts in MicroProfile Client originate in Jakarta RESTful Web Services. Some of these have already been introduced in the previous section, since the interface implemented by a client proxy represents the facilities provided by a Jakarta RESTful Web Services server. For example, the HTTP verb annotations and the @Consumes and @Produces annotations originate on the Jakarta RESTful Web Services server side. Injectable parameters annotated with @PathParameter, @QueryParameter, etc., also come from Jakarta RESTful Web Services.

Nearly all of the provider concepts supported by MicroProfile Client also originate in Jakarta RESTful Web Services. These are:

Like Jakarta RESTful Web Services, MicroProfile Client also has the concept of mandated providers. These are

Some concepts in MicroProfile Rest Client do not appear in either Jakarta RESTful Web Services or RESTEasy.

@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);
}

public interface RestClientBuilderListener {

    void onNewBuilder(RestClientBuilder builder);
}

public interface RestClientListener {

    void onNewClient(Class<?> serviceInterface, RestClientBuilder builder);
}

META-INF/services/org.eclipse.microprofile.rest.client.spi.RestClientBuilderListener

META-INF/services/org.eclipse.microprofile.rest.client.spi.RestClientListener

@POST
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
String contentLang(@HeaderParam(HttpHeaders.CONTENT_LANGUAGE) String contentLanguage, String subject);

@POST
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
@ClientHeaderParam(name=HttpHeaders.CONTENT_LANGUAGE, value="en")
String contentLang(String subject);

@POST
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
@ClientHeaderParam(name=HttpHeaders.CONTENT_LANGUAGE, value="{getLanguage}")
String contentLang(String subject);

default String getLanguage() {
   return ...;
}

public interface ClientHeadersFactory {

/**
 * Updates the HTTP headers to send to the remote service. Note that providers
 * on the outbound processing chain could further update the headers.
 *
 * @param incomingHeaders - the map of headers from the inbound Jakarta RESTful Web Services request. This will
 * be an empty map if the associated client interface is not part of a Jakarta RESTful Web Services request.
 * @param clientOutgoingHeaders - the read-only map of header parameters specified on the
 * client interface.
 * @return a map of HTTP headers to merge with the clientOutgoingHeaders to be sent to
 * the remote service.
 */
MultivaluedMap<String, String> update(MultivaluedMap<String, String> incomingHeaders,
                                      MultivaluedMap<String, String> clientOutgoingHeaders);
}

org.eclipse.microprofile.rest.client.propagateHeaders

   public interface Book {
      public String getTitle();
      public void setTitle(String title);
   }

   public class BookImpl implements Book {
      
      private String title;

      @Override
      public String getTitle() {
         return title;
      }
      
      @Override
      public void setTitle(String title) {
         this.title = title;
      }
   }
   
   public class Author {
      
      @Inject private Book book; 
      
      public Book getBook() {
         return book;
      }
   }

   @Qualifier
   @Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
   @Retention(RetentionPolicy.RUNTIME)
   public @interface Text {}
   
   @Qualifier
   @Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
   @Retention(RetentionPolicy.RUNTIME)
   public @interface Graphic {}
   
   @Text
   public class TextBookImpl extends BookImpl { }
   
   @Graphic
   public class GraphicNovelImpl extends BookImpl { }
   
   public class Genius {
      
      @Inject @Graphic Book book;
   }

   @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);
   }

   @Path("database")
   @RegisterRestClient(baseUri="https://localhost:8080/webapp")
   public interface TestDataBase {
      
      @Path("")
      @POST
      public String getByName(String name);
   }

<fqn of TestDataBase>/mp-rest/uri=<URL>

<fqn of TestDataBase>/mp-rest/url=<URL>

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

com.bluemonkeydiamond.TestDatabase/mp-rest/providers

@Path("database")
@RegisterRestClient(configKey="bmd")
public interface TestDataBase { ... }

bmd/mp-rest/url=https://localhost:8080/webapp

@Path("resource")
public interface TestResourceIntf extends Closeable {

   @Path("test")
   @GET
   public String test();
}
   
TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl("http://localhost:8081/")
                              .build(TestResourceIntf.class);
try (TestResourceIntf tr = service) {
   String s = service.test();
}

public interface TestResourceIntf extends Closeable {

   @Path("test")
   @GET
   public String test();
   
   @Path("testasync")
   @GET
   public CompletionStage<String> testAsync();
}

public interface AsyncInvocationInterceptorFactory {

    /**
     * Implementations of this method should return an implementation of the
     * AsyncInvocationInterceptor interface.  The MP Rest Client
     * implementation runtime will invoke this method, and then invoke the
     * prepareContext and applyContext methods of the
     * returned interceptor when performing an asynchronous method invocation.
     * Null return values will be ignored.
     *
     * @return Non-null instance of AsyncInvocationInterceptor
     */
    AsyncInvocationInterceptor newInterceptor();
}

public interface AsyncInvocationInterceptor {

    /**
     * This method will be invoked by the MP Rest Client runtime on the "main"
     * thread (i.e. the thread calling the async Rest Client interface method)
     * prior to returning control to the calling method.
     */
    void prepareContext();

    /**
     * This method will be invoked by the MP Rest Client runtime on the "async"
     * thread (i.e. the thread used to actually invoke the remote service and
     * wait for the response) prior to sending the request.
     */
    void applyContext();

    /**
     * This method will be invoked by the MP Rest Client runtime on the "async"
     * thread (i.e. the thread used to actually invoke the remote service and
     * wait for the response) after all providers on the inbound response flow
     * have been invoked.
     *
     * @since 1.2
     */
     void removeContext();
}

RestClientBuilder hostnameVerifier(HostnameVerifier hostnameVerifier);
RestClientBuilder keyStore(KeyStore keyStore, String keystorePassword);
RestClientBuilder sslContext(SSLContext sslContext);
RestClientBuilder trustStore(KeyStore trustStore);

KeyStore trustStore = ... ;
HostnameVerifier verifier ... ;
TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl("http://localhost:8081/")
                              .trustStore(trustStore)
                              .hostnameVerifier(verifier)
                              .build(TestResourceIntf.class);