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.

JAX-RS Features

Enunciate's runtime utilities provides some extra features to the JAX-RS application.

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

Pretty XML Namespace Prefixes

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.

IDL Filtering

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>