Module Jersey

Jersey Module

The Jersey module generates and compiles the support files and classes necessary to support a REST application according to the JAX-RS specification using Jersey.

Application Nuances

Refer to the JAX-RS and Jersey documentation to learn how to build a REST application using these technologies. However, it is important to note a few idiosyncrasies of the Enunciate-supported Jersey application.

REST subcontext

Because the Jersey application is presumably deployed along with other Enunciate-supported applications (JAX-WS for SOAP, API documentation, etc.), it will, by default, be mounted at a specific subcontext as defined in the Enunciate configuration (attribute "defaultRestSubcontext" of the "enunciate/services/rest" element). This means that a JAX-RS resource applied at path "mypath" will actually be mounted at "rest/mypath", assuming that "rest" is the subcontext (which it is by default).

While is it recommended that the subcontext be preserved, you can disable it in the configuration for this module. Note, however, that this increases the chance of the paths of your REST resources conflicting with the paths of your documentation, SOAP endpoints, etc. Enunciate provides an additional check to see if a REST resource is too greedy because it has a path parameter in the first path segment. This can also be disabled in configuration, but doing so will effectively disable the Enunciate-generated documentation and other web service endpoints.

Content Negotiation

Enuncite provides a special content negotiation (conneg) to Jersey such that that each resource is mounted from the REST subcontext (see above) but ALSO from a subcontext that conforms to the id of each content type that the resource supports. So, if the content type id of the "application/xml" content type is "xml" then the resource at path "mypath" will be mounted at both "/rest/mypath" and "/xml/mypath". You can disable this path-based content negotiation feature by setting usePathBasedConneg="false".

The content types for each JAX-RS resource are declared by the @Produces annotation. The content type ids are customized with the "enunciate/services/rest/content-types" element in the Enunciate configuration. Enunciate supplies providers for the "application/xml" and "application/json" content types by default.

Configuration

The Jersey module is configured with the jersey element under the modules element of the enunciate configuration file. The following attributes are supported on the jersey element:

attribute	description
useSubcontext	The "useSubcontext" attribute is used to enable/disable mounting the JAX-RS resources at the rest subcontext. Default: "true".
usePathBasedConneg	The "usePathBasedConneg" attribute is used to enable/disable path-based conneg (see above). Default: "true".
useWildcardServletMapping	The "useWildcardServletMapping" attribute is used to tell Enunciate to use a wildcard to map to the jersey servlet. By default, Enunciate attempts to map each endpoint to a specific servlet mapping. Default: "false".
disableWildcardServletError	The "disableWildcardServletError" attribute is used to enable/disable the Enunciate "wildcard" resource check. Default: "false".
resourceProviderFactory	The "resourceProviderFactory" attribute is used to specify the fully-qualified classname of an instance of com.sun.jersey.core.spi.component.ioc.IoCComponentProviderFactory that jersey will use. The default is the spring-based factory or the jersey default instance if spring isn't enabled.
defaultNamespace	The "defaultNamespace" attribute is used to specify the default XML namespace. This namespace will have no prefix during XML serialization.
loadOnStartup	The "loadOnStartup" attribute is used to specify the order in which the servlet is loaded on startup by the web application. By default, no order is specified.

Elements

The jersey element supports the following child elements:

init-param

The Jersey module also supports an arbitrary number of "init-param" child elements that can be used to specify the init parameters (e.g. container request filters, etc.) of the Jersey servlet. The "init-param" element supports a "name" attribute and a "value" attribute.