Spring App Module

The spring app deployment module produces the web app for hosting the API endpoints and documentation.

The order of the spring app deployment module is 200, putting it after any of the other modules, including the documentation deployment module. The spring app deployment module maintains soft dependencies on the other Enunciate modules. If those modules are active, the spring app deployment modules will assemble their artifacts into a spring-supported web application.

• steps
• application configuration
• security configuration
• artifacts

Steps

generate

The "generate" step generates the deployment descriptors, and the Spring configuration file. Refer to configuration to learn how to customize the deployment descriptors and the spring config file.

compile

The "compile" step compiles all API source files, including the source files that were generated from other modules (e.g. JAX-WS module, XFire module, GWT module, AMF module, etc.).

build

The "build" step assembles all the generated artifacts, compiled classes, and deployment descriptors into an (expanded) war directory.

All classes compiled in the compile step are copied to the WEB-INF/classes directory.

A set of libraries are copied to the WEB-INF/lib directory. This set of libraries can be specified in the configuration file. Unless specified otherwise in the configuration file, the libraries copied will be filtered from the classpath specified to Enunciate at compile-time. The filtered libraries are those libraries that are determined to be specific to running the Enunciate compile-time engine. All other libraries on the classpath are assumed to be dependencies for the API and are therefore copied to WEB-INF/lib. (If a directory is found on the classpath, its contents are copied to WEB-INF/classes.)

The web.xml file is copied to the WEB-INF directory. A tranformation can be applied to the web.xml file before the copy, if specified in the config, allowing you to apply your own servlet filters, etc. Take care to preserve the existing elements when applying a transformation to the web.xml file, as losing data will result in missing or malfunctioning endpoints.

The spring-servlet.xml file is generated and copied to the WEB-INF directory. You can specify other spring config files that will be copied (and imported by the spring-servlet.xml file) in the configuration. This option allows you to specify spring AOP interceptors and XFire in/out handlers to wrap your endpoints, if desired. Additional spring configuration for security is also copied.

The documentation (if found) is copied to the configured location.

The other modules application are copied to the configured location. This includes GWT apps and Flex apps.

package

The "package" step packages the expanded war and exports it.

Configuration

• structure
• attributes
• elements
  
  • The "war" element
  • The "springImport" element
  • The "globalServiceInterceptor" element
  • The "handlerInterceptor" element
  • The "handlerMapping" element
  • The "copyResources" element
• Spring Application Security
  
  • Security Annotations
  • User Details Service
  • The "security" configuration element
  • Login and Logout API Methods

The configuration for the Spring App deployment module is specified by the "spring-app" child element under the "modules" element of the enunciate configuration file.

Structure

The following example shows the structure of the configuration elements for this module. Note that this shows only the structure. Some configuration elements don't make sense when used together. For more information about the security configuration, see Spring Application Security.

<enunciate>   <modules>     <spring-app compileDebugInfo="[true | false]"         contextLoaderListenerClass="..."         dispatcherServletClass="..."         defaultDependencyCheck="[none | objects | simple | all]"         defaultAutowire="[no | byName | byType | constructor | autodetect]">       <war name="..." webXMLTransform="..." webXMLTransformURL="..."         preBase="..." postBase="..."         includeClasspathLibs="[true|false]" excludeDefaultLibs="[true|false]"         docsDir="..." gwtAppDir="..." flexAppDir="...">         <includeLibs pattern="..." file="..."/>         <includeLibs pattern="..." file="..."/>         ...         <excludeLibs pattern="..." file="..."/>         <excludeLibs pattern="..." file="..."/>         ...           <manifest>             <attribute name="..." value="..."/>             <attribute section="..." name="..." value="..."/>             ...           </manifest>       </war>       <springImport file="..." uri="..."/>       <springImport file="..." uri="..."/>       ...       <globalServiceInterceptor interceptorClass="..." beanName="..."/>       <globalServiceInterceptor interceptorClass="..." beanName="..."/>       ...       <handlerInterceptor interceptorClass="..." beanName="..."/>       <handlerInterceptor interceptorClass="..." beanName="..."/>       ...       <handlerMapping pattern="..." beanName="..."/>       <handlerMapping pattern="..." beanName="..."/>       ...       <copyResources dir="..." pattern="..."/>       <copyResources dir="..." pattern="..."/>       ...       <security ...>         ...       </security>     </spring-app>   </modules> </enunciate>

attributes

• The "enableSecurity" attribute specifies that security should be enabled. The default is "false."
• The "compileDebugInfo" attribute specifies that the compiled classes should be compiled with debug info. The default is "true."
• The "dispatcherServletClass" attribute specifies the FQN of the class to use as the Spring dispatcher servlet. The default is "org.springframework.web.servlet.DispatcherServlet".
• The "contextLoaderListenerClass" attribute specifies that FQN of the class to use as the Spring context loader listener. The default is "org.springframework.web.context.ContextLoaderListener".
• The "defaultDependencyCheck" attribute specifies that value of the "default-dependency-check" for the generated spring file.
• The "defaultAutowire" attribute specifies that value of the "default-autowire" for the generated spring file.
• The "doCompile" attribute specifies whether this module should take on the responsibility of compiling the server-side classes. This may not be desired if the module is being used only for generating the war structure and configuration files. Default: "true".
• The "doLibCopy" attribute specifies whether this module should take on the responsibility of copying libraries to WEB-INF/lib. This may not be desired if the module is being used only for generating the war structure and configuration files. Default: "true".
• The "doPackage" attribute specifies whether this module should take on the responsibility of packaging (zipping) up the war. This may not be desired if the module is being used only for generating the war structure and configuration files. Default: "true".

The "war" element

The "war" element is used to specify configuration for the assembly of the war. It supports the following attributes:

• The "name" attribute specifies the name of the war. The default is the enunciate configuration label.
• The "docsDir" attribute specifies a different directory in the war for the documentation (including WSDL and schemas). The default is the root directory of the war.
• The "gwtAppDir" attribute specifies a different directory in the war for the GWT appliction(s). The default is the root directory of the war.
• The "flexAppDir" attribute specifies a different directory in the war for the flex appliction(s). The default is the root directory of the war.
• The "webXMLTransform" attribute specifies the XSLT tranform file that the web.xml file will pass through before being copied to the WEB-INF directory. No tranformation will be applied if none is specified.
• The "webXMLTransformURL" attribute specifies the URL to an XSLT tranform that the web.xml file will pass through before being copied to the WEB-INF directory. No tranformation will be applied if none is specified.
• The "preBase" attribute specifies a directory (could be gzipped) that supplies a "base" for the war. The directory contents will be copied to the building war directory before it is provided with any Enunciate-specific files and directories.
• The "postBase" attribute specifies a directory (could be gzipped) that supplies a "base" for the war. The directory contents will be copied to the building war directory after it is provided with any Enunciate-specific files and directories.
• The "includeClasspathLibs" attribute specifies whether Enunciate will use the libraries from the classpath for applying the include/exclude filters. If "false" only the libs explicitly included by file (see below) will be filtered.
• The "excludeDefaultLibs" attribute specifies whether Enunciate should perform its default filtering of known compile-time-only jars.

Including or excluding jars from the war

By default, the war is constructed by copying jars that are on the classpath to its "lib" directory (the contents of directories on the classpath will be copied to the "classes" directory). You add a specific file to this list with the "file" attribute of the "includeLibs" element of the "war" element.

Once the initial list of jars to be potentially copied is created, it is passed through an "include" filter that you may specify with nested "includeLibs" elements. For each of these elements, you can specify a set of files to include with the "pattern" attribute. This is an ant-style pattern matcher against the absolute path of the file (or directory). By default, all files are included.

Once the initial list is passed through the "include" filter, it will be passed through an "exclude" filter. There is a set of known jars that by default will not be copied to the "lib" directory. These include the jars that ship by default with the JDK and the jars that are known to be build-time-only jars for Enunciate. You can disable the default filter with the "excludeDefaultLibs" attribute of the "war" element. You can also specify additional jars that are to be excluded with an arbitrary number of "excludeLibs" child elements under the "war" element in the configuration file. The "excludeLibs" element supports either a "pattern" attribute or a "file" attribute. The "pattern" attribute is an ant-style pattern matcher against the absolute path of the file (or directory) on the classpath that should not be copied to the destination war. The "file" attribute refers to a specific file on the filesystem (relative paths are resolved relative to the configuration file). Furthermore, the "excludeLibs" element supports a "includeInManifest" attribute specifying whether the exclude should be listed in the "Class-Path" attribute of the manifest, even though they are excluded in the war. The is useful if, for example, you're assembling an "ear" with multiple war files. By default, excluded jars are not included in the manifest.

You can customize the manifest for the war by the "manifest" element of the "war" element. Underneath the "manifest" element can be an arbitrary number of "attribute" elements that can be used to specify the manifest attributes. Each "attribute" element supports a "name" attribute, a "value" attribute, and a "section" attribute. If no section is specified, the default section is assumed. If there is no "Class-Path" attribute in the main section, one will be provided listing the jars on the classpath.

The "springImport" element

The "springImport" element is used to specify a spring configuration file that will be imported by the main spring servlet config. It supports the following attributes:

• The "file" attribute specifies the spring import file on the filesystem. It will be copied to the WEB-INF directory.
• The "uri" attribute specifies the URI to the spring import file. The URI will not be resolved at compile-time, nor will anything be copied to the WEB-INF directory. The value of this attribute will be used to reference the spring import file in the main config file. This attribute is useful to specify an import file on the classpath, e.g. "classpath:com/myco/spring/config.xml".

One use of specifying spring a import file is to wrap your endpoints with spring interceptors and/or XFire in/out/fault handlers. This can be done by simply declaring a bean that is an instance of your endpoint class. This bean can be advised as needed, and if it implements org.codehaus.xfire.handler.HandlerSupport (perhaps through the use of a mixin?), the in/out/fault handlers will be used for the XFire invocation of that endpoint.

It's important to note that the type on which the bean context will be searched is the type of the endpoint interface, and then only if it exists. If there are more than one beans that are assignable to the endpoint interface, the bean that is named the name of the service will be used. Otherwise, the deployment of your endpoint will fail.

The same procedure can be used to specify the beans to use as REST endpoints, although the XFire in/out/fault handlers will be ignored. In this case, the bean context will be searched for each REST interface that the endpoint implements. If there is a bean that implements that interface, it will used instead of the default implementation. If there is more than one, the bean that is named the same as the REST endpoint will be used.

There also exists a mechanism to add certain AOP interceptors to all service endpoint beans. Such interceptors are referred to as "global service interceptors." This can be done by using the "globalServiceInterceptor" element (see below), or by simply creating an interceptor that implements org.codehaus.enunciate.modules.spring_app.EnunciateServiceAdvice or org.codehaus.enunciate.modules.spring_app.EnunciateServiceAdvisor and declaring it in your imported spring beans file.

Each global interceptor has an order. The default order is 0 (zero). If a global service interceptor implements org.springframework.core.Ordered, the order will be respected. As global service interceptors are added, it will be assigned a position in the chain according to it's order. Interceptors of the same order will be ordered together according to their position in the config file, with priority to those declared by the "globalServiceInterceptor" element, then to instances of org.codehaus.enunciate.modules.spring_app.EnunciateServiceAdvice, then to instances of org.codehaus.enunciate.modules.spring_app.EnunciateServiceAdvisor.

For more information on spring bean configuration and interceptor advice, see the spring reference documentation.

The "globalServiceInterceptor" element

The "globalServiceInterceptor" element is used to specify a Spring interceptor (instance of org.aopalliance.aop.Advice or org.springframework.aop.Advisor) that is to be injected on all service endpoint beans.

• The "interceptorClass" attribute specified the class of the interceptor.

• The "beanName" attribute specifies the bean name of the interceptor.

The "handlerInterceptor" element

The "handlerInterceptor" element is used to specify a Spring interceptor (instance of org.springframework.web.servlet.HandlerInterceptor) that is to be injected on the handler mapping.

• The "interceptorClass" attribute specifies the class of the interceptor.

• The "beanName" attribute specifies the bean name of the interceptor.

For more information on spring bean configuration and interceptor advice, see the spring reference documentation.

The "handlerMapping" element

The "handlerMapping" element is used to specify a custom Spring handler mapping.

• The "pattern" attribute specifies the pattern that maps to the handler.

• The "beanName" attribute specifies the bean name of the handler.

For more information on spring handler mappings, see the spring reference documentation.

The "copyResources" element

The "copyResources" element is used to specify a pattern of resources to copy to the compile directory. It supports the following attributes:

• The "dir" attribute specifies the base directory of the resources to copy.
• The "pattern" attribute specifies an Ant-style pattern used to find the resources to copy. For more information, see the documentation for the ant path matcher in the Spring JavaDocs.

Artifacts

The spring app deployment module exports the following artifacts:

• The "spring.app.dir" artifact is the (expanded) web app directory, exported during the build step.
• The "spring.war.file" artifact is the packaged war, exported during the package step.