org.codehaus.enunciate.modules.jersey
Class JerseyDeploymentModule

java.lang.Object
  org.codehaus.enunciate.modules.BasicDeploymentModule
      org.codehaus.enunciate.modules.FreemarkerDeploymentModule
          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
• steps
• configuration
• artifacts

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 content type negotiation (conneg) to Jersey that conforms to the content type negotiation of the Enunciate REST module. This means 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".

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 "useSubcontext" attribute is used to enable/disable mounting the JAX-RS resources at the rest subcontext. Default: "true".
• The "usePathBasedConneg" attribute is used to enable/disable path-based conneg (see above). Default: "true".
• The "disableWildcardServletError" attribute is used to enable/disable the Enunciate "wildcard" resource check. Default: "false".
• 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.
• The "defaultNamespace" attribute is used to specify the default XML namespace. This namespace will have no prefix during XML serialization.

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

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.

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.

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.