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

   <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>

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