JAX-RS Extension Mappings

The JAX-RS specification provides an ease-of-use feature that allows you to map resource file extensions to specific media types and languages.  Sometimes a client is not able to set the ACCEPT and ACCEPT-LANGUAGE headers, for example, a browser.  The JAX-RS Extension Mappings allow you to define a resource method that consumes ACCEPT headers.  For example, lets say our environment has a mapping of the "html" extension to the media type "text/html".

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

   @GET
   @ProduceMime("text/html")
   public String getHtml() {...}


   @GET
   @ProduceMime("application/xml")
   public String getXml() {...}

Normally, the getHtml() resource method is triggered by

GET /resource
ACCEPT: text/html

Since browsers can't set accept headers we could have an extension mapping for "html" and do the following instead

GET /resource.html

The "text/html" media type would be appended to the incoming request's ACCEPT header.  The ".html" suffix would be stripped from the incoming URI and matched to the getHtml() method.  You can also use extension mappings with languages.  Let's map "fr" to "fr", french.

GET /resource.html.fr

The "text/html" media type would be appended to the incoming request's ACCEPT header.  The "fr" language would be appended to the incoming request's ACCEPT-LANGUAGE header  The ".html.fr" suffix would be stripped from the incoming URI and matched to getHtml().  You can obtain a list of acceptable languages by injecting an instance of javax.ws.rs.core.HttpHeaders and invoking its getAcceptableLanguages() method.

@Path("/resource")

public class MyResource {

   @GET

   @ProduceMime("text/html")

   public String getHtml(@Context HttpHeaders headers)

   {

      for(String language : headers.getAcceptableLanguages()) System.out.println("Language: " + language);

   }

}}}

Configuring Extension Mappings

The standard way of configuring extension mappings is through the ApplicationConfig class.  Many times though you want all your configuration information in one text configuration file.  RESTEasy allows you to define these mappings as context-params within your WAR's web.xml file.

resteasy.media.type.mappings

This context-param allows you to define media type extension mappings.  The format is very similar to JSON.  Extension is the, media type is the value.  They are separated by a ':'.  Each name-value pair is delimited by a ','.

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

resteasy.language.mappings

This context-param allows you to define language extension mappings.  The format is very similar to JSON.  Extension is the, media type is the value.  They are separated by a ':'.  Each name-value pair is delimited by a ','.

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