How to install a Spring in a JBoss Module in JBoss EAP ?

Solution Verified - Updated -

Environment

  • Red Hat JBoss Enterprise Application Platform (EAP)
    • 7.x
    • 6.x

Issue

  • The documentation for JBossWS indicates that Spring must be installed as a module before a web service endpoint can be configured with jbossws-cxf.xml. How is this done?
  • How can Spring be installed as a common library in JBoss EAP 6 ?
  • What versions of Spring are supported with JBossWS in JBoss EAP 6 ?
  • How to install Spring as Module on JBoss EAP 7 ?
  • What versions of Spring are supported on JBoss EAP 7 ?

Resolution

  1. Download the desired version of Spring. For this example we are using Spring 3.1.1.
  2. Create the directory $JBOSS_HOME/modules/org/springframework/spring/main.
  3. Copy the Spring libraries you downloaded to that directory.
  4. Create module.xml with the following contents under that directory. Make sure these <resource-root path="XXX"/> correspond to the libraries names:

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.1" name="org.springframework.spring">
      <resources>
        <resource-root path="org.springframework.aop-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.asm-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.aspects-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.beans-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.context-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.context.support-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.core-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.expression-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.instrument-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.instrument.tomcat-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.jdbc-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.jms-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.orm-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.oxm-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.test-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.transaction-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.web-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.web.portlet-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.web.servlet-3.1.1.RELEASE.jar"/>
        <resource-root path="org.springframework.web.struts-3.1.1.RELEASE.jar"/>
      </resources>
      <dependencies>
        <module name="org.apache.commons.logging"/>
        <module name="javax.api" export="true"/>
        <module name="org.jboss.vfs"/> 
      </dependencies>
    </module>
    

    Here is an absolute minimal module.xml (the different Spring version is irrelevant):

    <?xml version="1.0"?>
    <module xmlns="urn:jboss:module:1.1" name="org.springframework.spring">
      <resources>
        <resource-root path="spring-aop-3.2.3.RELEASE.jar"/>
        <resource-root path="spring-beans-3.2.3.RELEASE.jar"/>
        <resource-root path="spring-context-3.2.3.RELEASE.jar"/>
        <resource-root path="spring-core-3.2.3.RELEASE.jar"/>
        <resource-root path="spring-expression-3.2.3.RELEASE.jar"/>
      </resources>
      <dependencies>
        <module name="javax.api"/>
        <module name="org.apache.commons.logging"/>
      </dependencies>
    </module>
    
  5. Put the following jboss-deployment-structure.xml in your application archive (WEB-INF/jboss-deployment-structure.xml for WAR or META-INF/jboss-deployment-structure.xml for EAR or EJB-jar) to use the above module:

**Make sure to specify the namespace 1.2 as shown in the example, which is needed for the 'meta-inf' attribute.

- `JBoss EAP 6.1.x` and greater: 

        <?xml version="1.0" encoding="UTF-8"?>
        <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
          <deployment>
            <dependencies>
              <module name="org.springframework.spring" export="true" meta-inf="export"/>
            </dependencies>
          </deployment>
        </jboss-deployment-structure>

- `JBoss EAP 6.0.x` :

        <?xml version="1.0" encoding="UTF-8"?>
        <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
          <deployment>
            <dependencies>
              <module name="org.springframework.spring" export="true">
                <imports>
                  <include path="META-INF**"/>
                  <include path="org**"/>
                </imports>
                <exports>
                  <include path="META-INF**"/>
                  <include path="org**"/>
                </exports>
              </module>
            </dependencies>
          </deployment>
        </jboss-deployment-structure>

Note: The meta-inf on the module in the jboss-deployment-structure.xml was added in JBoss EAP 6.1.0 , which allows the files in the META-INF of a resource to be visible. Since this was not available in JBoss EAP 6.0.x , the <imports> section allows you to get access to the META-INF directory which is not visible by default.

Note: The Spring Framework module should not include resources such as servlet-api.jar, xml-apis.jar, jta-api.jar, and other APIs. These APIs are implemented by either the JDK or JBoss EAP and trying to use a different version of the API will lead to classloading issues and other problems.

Note: The Spring module should include all of its non Java / JavaEE dependencies. The Spring module can depend on javax.api / javaee.api provided by JBoss EAP and any public JBoss EAP module , but for other dependencies Spring has such as aopalliance, they would need to be included as resources in the module or in another custom module.

Note: If any Spring jars or other jars that you put in the custom JBoss Module have annotated classes that the deployments will need to see, then jandex will need to be run on those jars to add a jandex index file to the jar so that the annotations will be loaded. Spring Boot has a spring-boot-autoconfigure which has some annotated classes, which means jandex would be needed for it, or the jar would need to be moved into the application. See [5] and [7]

If you have trouble after installing the Spring module , here are a few solutions to some common problems:

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.

Comments