-
Notifications
You must be signed in to change notification settings - Fork 200
Enunciate Runtime Utilities
Enunciate 2 provides a small, light, and completely optional runtime library that
can be used to provide some extra features to your Web service API. The library is
named enunciate-rt-util.jar
and is included in the distribution bundle. It's Maven
coordinates are com.webcohesion.enunciate
:enunciate-rt-util
.
Enunciate's runtime utilities provides some extra features to the JAX-RS application.
Enunciate provides a class, com.webcohesion.enunciate.rt.EnunciateApplication
, that
extends the JAX-RS Application
and discovers the JAX-RS providers and root resources
available in your application. You may find it convenient to use this instance of Application
instead of having to maintain your own Application
class.
The EnunciateApplication
depends on the presence of files named jaxrs-resource-classes.list
and jaxrs-provider-classes.list
that are each generated at build-time by Enunciate's
JAXRS Module and expected at the root of the classpath at runtime. Maven users
will find it there already; Ant users will probably need to export those files to the
right place (the artifact ids of those files are "jaxrs-provider-classes.list" and
"jaxrs-resource-classes.list").
Here's a sample web.xml
file that uses Resteasy to leverage the EnunciateApplication
:
<web-app>
<filter>
<filter-name>resteasy</filter-name>
<filter-class>
org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
</filter-class>
<init-param>
<param-name>jakarta.ws.rs.Application</param-name>
<param-value>com.webcohesion.enunciate.rt.EnunciateApplication</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>resteasy</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
...
</web-app>
By default, JAXB uses ugly namespace prefixes. You can register the
com.webcohesion.enunciate.rt.EnunciateJaxbContextResolver
with your JAX-RS
application to use the namespace prefixes you've configured in Enunciate, or that
you've configued with @XmlNs
annotations.
The EnunciateJaxbContextResolver
depends on the presence of a file named jaxb-context-classes.list
that is generated at build-time by Enunciate's JAXB Module and expected
at the root of the classpath at runtime. Maven users will find it there already;
Ant users will probably need to export the file to the right place (artifact id: "jaxb-context-classes.list".
The EnunciateJaxbContextResolver
also requires jaxb-runtime
to be on your classpath.
The com.webcohesion.enunciate.rt.EnunciateApplication
will register the EnunciateJaxbContextResolver
automatically. If you don't use the EnunciateApplication
, you'll need to register the
EnunciateJaxbContextResolver
in your own application.
The IDLs (WSDL, WADL, etc.) generated by Enunciate have some pretty nice features (e.g. full documentation), but since the IDL files are generated statically, Enunciate has to guess what URLs to use for the application. These URLs can be provided in the Enunciate configuration file, but static URLs are often inconvenient in a development environment.
To support dynamic resolution of the application base URL, Enunciate provides a servlet
filter, com.webcohesion.enunciate.rt.IDLFilter
that can be applied to all requests
for IDLs and dynamically resolve the IDL and provide it with the correct base address.
The following web.xml
snippet configures the Enunciate IDL filter:
<web-app>
...
<filter>
<filter-name>idl-filter</filter-name>
<filter-class>com.webcohesion.enunciate.rt.IDLFilter</filter-class>
</filter>
...
<filter-mapping>
<filter-name>idl-filter</filter-name>
<url-pattern>*.wsdl</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>idl-filter</filter-name>
<url-pattern>*.wadl</url-pattern>
</filter-mapping>
...
<mime-mapping>
<extension>wsdl</extension>
<mime-type>text/xml</mime-type>
</mime-mapping>
<mime-mapping>
<extension>xsd</extension>
<mime-type>text/xml</mime-type>
</mime-mapping>
</web-app>