org.codehaus.enunciate.modules.jersey
Class JerseyDeploymentModule

java.lang.Object
  extended by org.codehaus.enunciate.modules.BasicDeploymentModule
      extended by org.codehaus.enunciate.modules.FreemarkerDeploymentModule
          extended by org.codehaus.enunciate.modules.jersey.JerseyDeploymentModule
All Implemented Interfaces:
EnunciateClasspathListener, EnunciateModelAware, DeploymentModule, SpecProviderModule

public class JerseyDeploymentModule
extends FreemarkerDeploymentModule
implements EnunciateClasspathListener, SpecProviderModule

Jersey Module

The Jersey module generates and compiles the support files and classes necessary to support a REST application according to JSR-311, using Jersey.

Jersey Application

We direct you do the documentation for JAX-RS and Jersey 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.

Steps

generate

The generate step of the Jersey module generates the configuration files for a servlet-based Jersey application.

Configuration

The Jersey module supports the following attributes:

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.

Artifacts

The Jersey deployment module exports no artifacts.

Author:
Ryan Heaton

Field Summary
 
Fields inherited from class org.codehaus.enunciate.modules.BasicDeploymentModule
enunciate
 
Constructor Summary
JerseyDeploymentModule()
           
 
Method Summary
 void addServletInitParam(java.lang.String name, java.lang.String value)
          Add a servlet init param.
protected  void doBuild()
          Default implementation is a no-op.
 void doFreemarkerGenerate()
          Generate using Freemarker.
 java.lang.String getApplicationClass()
          The fully-qualified classname of an instance of the implementation of javax.ws.rs.core.Application that jersey will use.
 org.apache.commons.digester.RuleSet getConfigurationRules()
          Default implementation returns null.
 java.lang.String getDefaultNamespace()
          The default namespace.
 java.net.URL getJaxbTypesTemplateURL()
          The jaxb types template URL.
 java.lang.String getLoadOnStartup()
          The order in which the servlet is loaded on startup by the web application.
 java.lang.String getName()
          The name of the deployment module.
 java.net.URL getProvidersListTemplateURL()
          The providers template URL.
 java.lang.String getResourceProviderFactory()
          The fully-qualified classname of an instance of com.sun.jersey.core.spi.component.ioc.IoCComponentProviderFactory that jersey will use.
protected  java.lang.String getRestSubcontext()
           
 java.net.URL getRootResourceListTemplateURL()
          The root resources template URL.
 java.util.Map<java.lang.String,java.lang.String> getServletInitParams()
          Get the servlet init params.
 Validator getValidator()
          Get the validator for this module, or null if none.
 void init(Enunciate enunciate)
          Sets the enunciate mechanism.
 void initModel(EnunciateFreemarkerModel model)
          Initialize the model.
 boolean isDisabled()
          Whether this deployment module has been disabled, e.g.
 boolean isDisableWildcardServletError()
          Whether to disable the greedy servlet pattern error.
 boolean isJaxrsProvider()
          Whether this module is a JAX-RS provider module.
 boolean isJaxwsProvider()
          Whether this module is a JAX-WS provider module.
protected  boolean isUpToDate()
          Whether the generated sources are up-to-date.
 boolean isUsePathBasedConneg()
          Whether to use path-based conneg.
 boolean isUseSubcontext()
          Whether to use the REST subcontext.
 boolean isUseWildcardServletMapping()
          Whether to use the wildcard servlet mapping.
 void onClassesFound(java.util.Set<java.lang.String> classes)
          Logic for handling a set of classes that were found on the Enunciate classpath.
 void setApplicationClass(java.lang.String applicationClass)
          The fully-qualified classname of an instance of the implementation of javax.ws.rs.core.Application that jersey will use.'
 void setDefaultNamespace(java.lang.String defaultNamespace)
          The default namespace.
 void setDisableWildcardServletError(boolean disableWildcardServletError)
          Whether to disable the wildcard servlet pattern error.
 void setLoadOnStartup(java.lang.String loadOnStartup)
          The order in which the servlet is loaded on startup by the web application.
 void setResourceProviderFactory(java.lang.String resourceProviderFactory)
          The fully-qualified classname of an instance of com.sun.jersey.core.spi.component.ioc.IoCComponentProviderFactory that jersey will use.
 void setUsePathBasedConneg(boolean usePathBasedConneg)
          Whether to use path-based conneg.
 void setUseSubcontext(boolean useSubcontext)
          Whether to use the REST subcontext.
 void setUseWildcardServletMapping(boolean useWildcardServletMapping)
          Whether to use the wildcard servlet mapping.
 
Methods inherited from class org.codehaus.enunciate.modules.FreemarkerDeploymentModule
close, doGenerate, getConfiguration, getModel, getModelInternal, getObjectWrapper, getTemplateExceptionHandler, getTemplateLoader, processTemplate, processTemplate, processTemplate, processTemplate
 
Methods inherited from class org.codehaus.enunciate.modules.BasicDeploymentModule
debug, doCompile, doPackage, getAliases, getBuildDir, getCompileDir, getEnunciate, getGenerateDir, getOrder, getPackageDir, info, setBuildDir, setCompileDir, setDisabled, setGenerateDir, setPackageDir, step, warn
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JerseyDeploymentModule

public JerseyDeploymentModule()
Method Detail

getName

public java.lang.String getName()
Description copied from interface: DeploymentModule
The name of the deployment module. Identifies its section in the enunciate configuration.

Specified by:
getName in interface DeploymentModule
Overrides:
getName in class BasicDeploymentModule
Returns:
"jersey"

getRootResourceListTemplateURL

public java.net.URL getRootResourceListTemplateURL()
The root resources template URL.

Returns:
The root resources template URL.

getProvidersListTemplateURL

public java.net.URL getProvidersListTemplateURL()
The providers template URL.

Returns:
The providers template URL.

getJaxbTypesTemplateURL

public java.net.URL getJaxbTypesTemplateURL()
The jaxb types template URL.

Returns:
The jaxb types template URL.

getValidator

public Validator getValidator()
Description copied from interface: DeploymentModule
Get the validator for this module, or null if none.

Specified by:
getValidator in interface DeploymentModule
Overrides:
getValidator in class BasicDeploymentModule
Returns:
A new JerseyValidator.

init

public void init(Enunciate enunciate)
          throws EnunciateException
Description copied from class: BasicDeploymentModule
Sets the enunciate mechanism.

Specified by:
init in interface DeploymentModule
Overrides:
init in class BasicDeploymentModule
Parameters:
enunciate - The enunciate mechanism.
Throws:
EnunciateException

initModel

public void initModel(EnunciateFreemarkerModel model)
Description copied from interface: EnunciateModelAware
Initialize the model.

Specified by:
initModel in interface EnunciateModelAware
Overrides:
initModel in class FreemarkerDeploymentModule
Parameters:
model - The model to initialize.

onClassesFound

public void onClassesFound(java.util.Set<java.lang.String> classes)
Description copied from interface: EnunciateClasspathListener
Logic for handling a set of classes that were found on the Enunciate classpath.

Specified by:
onClassesFound in interface EnunciateClasspathListener
Parameters:
classes - The classes that were found.

doFreemarkerGenerate

public void doFreemarkerGenerate()
                          throws EnunciateException,
                                 java.io.IOException,
                                 freemarker.template.TemplateException
Description copied from class: FreemarkerDeploymentModule
Generate using Freemarker. Same as FreemarkerDeploymentModule.doGenerate() but can throw a TemplateException.

Specified by:
doFreemarkerGenerate in class FreemarkerDeploymentModule
Throws:
EnunciateException
java.io.IOException
freemarker.template.TemplateException

doBuild

protected void doBuild()
                throws EnunciateException,
                       java.io.IOException
Description copied from class: BasicDeploymentModule
Default implementation is a no-op.

Overrides:
doBuild in class BasicDeploymentModule
Throws:
EnunciateException
java.io.IOException

getRestSubcontext

protected java.lang.String getRestSubcontext()

getConfigurationRules

public org.apache.commons.digester.RuleSet getConfigurationRules()
Description copied from class: BasicDeploymentModule
Default implementation returns null.

Specified by:
getConfigurationRules in interface DeploymentModule
Overrides:
getConfigurationRules in class BasicDeploymentModule
Returns:
null.

isUpToDate

protected boolean isUpToDate()
Whether the generated sources are up-to-date.

Returns:
Whether the generated sources are up-to-date.

isJaxwsProvider

public boolean isJaxwsProvider()
Description copied from interface: SpecProviderModule
Whether this module is a JAX-WS provider module.

Specified by:
isJaxwsProvider in interface SpecProviderModule
Returns:
Whether this module is a JAX-WS provider module.

isJaxrsProvider

public boolean isJaxrsProvider()
Description copied from interface: SpecProviderModule
Whether this module is a JAX-RS provider module.

Specified by:
isJaxrsProvider in interface SpecProviderModule
Returns:
Whether this module is a JAX-RS provider module.

isUseSubcontext

public boolean isUseSubcontext()
Whether to use the REST subcontext.

Returns:
Whether to use the REST subcontext.

setUseSubcontext

public void setUseSubcontext(boolean useSubcontext)
Whether to use the REST subcontext.

Parameters:
useSubcontext - Whether to use the REST subcontext.

isUsePathBasedConneg

public boolean isUsePathBasedConneg()
Whether to use path-based conneg.

Returns:
Whether to use path-based conneg.

setUsePathBasedConneg

public void setUsePathBasedConneg(boolean usePathBasedConneg)
Whether to use path-based conneg.

Parameters:
usePathBasedConneg - Whether to use path-based conneg.

getResourceProviderFactory

public java.lang.String getResourceProviderFactory()
The fully-qualified classname of an instance of com.sun.jersey.core.spi.component.ioc.IoCComponentProviderFactory that jersey will use.

Returns:
The fully-qualified classname of an instance of com.sun.jersey.core.spi.component.ioc.IoCComponentProviderFactory that jersey will use.

setResourceProviderFactory

public void setResourceProviderFactory(java.lang.String resourceProviderFactory)
The fully-qualified classname of an instance of com.sun.jersey.core.spi.component.ioc.IoCComponentProviderFactory that jersey will use.

Parameters:
resourceProviderFactory - The fully-qualified classname of an instance of com.sun.jersey.core.spi.component.ioc.IoCComponentProviderFactory that jersey will use.

getApplicationClass

public java.lang.String getApplicationClass()
The fully-qualified classname of an instance of the implementation of javax.ws.rs.core.Application that jersey will use.

Returns:
The fully-qualified classname of an instance of the implementation of javax.ws.rs.core.Application that jersey will use.

setApplicationClass

public void setApplicationClass(java.lang.String applicationClass)
The fully-qualified classname of an instance of the implementation of javax.ws.rs.core.Application that jersey will use.'

Parameters:
applicationClass - The fully-qualified classname of an instance of the implementation of javax.ws.rs.core.Application that jersey will use.

getLoadOnStartup

public java.lang.String getLoadOnStartup()
The order in which the servlet is loaded on startup by the web application.

Returns:
The order in which the servlet is loaded on startup by the web application.

setLoadOnStartup

public void setLoadOnStartup(java.lang.String loadOnStartup)
The order in which the servlet is loaded on startup by the web application.

Parameters:
loadOnStartup - The order in which the servlet is loaded on startup by the web application.

isDisableWildcardServletError

public boolean isDisableWildcardServletError()
Whether to disable the greedy servlet pattern error.

Returns:
Whether to disable the greedy servlet pattern error.

setDisableWildcardServletError

public void setDisableWildcardServletError(boolean disableWildcardServletError)
Whether to disable the wildcard servlet pattern error.

Parameters:
disableWildcardServletError - Whether to disable the wildcard servlet pattern error.

isUseWildcardServletMapping

public boolean isUseWildcardServletMapping()
Whether to use the wildcard servlet mapping.

Returns:
Whether to use the wildcard servlet mapping.

setUseWildcardServletMapping

public void setUseWildcardServletMapping(boolean useWildcardServletMapping)
Whether to use the wildcard servlet mapping.

Parameters:
useWildcardServletMapping - Whether to use the wildcard servlet mapping.

getDefaultNamespace

public java.lang.String getDefaultNamespace()
The default namespace. This namespace will have no prefix associated with it during XML serialization.

Returns:
The default namespace.

setDefaultNamespace

public void setDefaultNamespace(java.lang.String defaultNamespace)
The default namespace.

Parameters:
defaultNamespace - The default namespace.

getServletInitParams

public java.util.Map<java.lang.String,java.lang.String> getServletInitParams()
Get the servlet init params.

Returns:
The servlet init params.

addServletInitParam

public void addServletInitParam(java.lang.String name,
                                java.lang.String value)
Add a servlet init param.

Parameters:
name - The name of the init param.
value - The value of the init param.

isDisabled

public boolean isDisabled()
Description copied from interface: DeploymentModule
Whether this deployment module has been disabled, e.g. in the config file. Since the discovery mechanism is used to discover the modules on the classpath, it may be necessary to be able to disable a module.

Specified by:
isDisabled in interface DeploymentModule
Overrides:
isDisabled in class BasicDeploymentModule
Returns:
Whether this deployment module has been disabled.