Version 42

    This page contains information regarding integrating/supporting ESB4.x with AS5.1.0.GA

    Directory structure change

    The majority of jars that were previously located in jbossesb.sar/lib have been moved to deployers/esb.deployer/lib.




    In AS5 the single JBoss4ESBDeployer is replaced by a number of JBoss AS deployers and supporting classes to deploy .esb (4.x) archives on JBoss AS 5.x.


    The different deployers come into play at different stages of deployment. The deployers don't really deploy anything but only create/add metadata (EsbMetaData) information that will later be used to by the EsbDeployer to create a BeanMetaData representing an EsbDeployment.

    The MicroContainer will take care of creating the real EsbDeployment instance and take care of calling its lifecycle metods for us.


    PARSEEsbConfigParserIs responsible for parsing the .esb configuration and creating an EsbMetaData instance representing the deployment.
    POST_PARSEEsbWebServiceDeployerIs responsible for examining the EsbMetaData and generating web service metadata that will be picked up by JBoss Web Service deployers.
    POST_CLASSLOADEREsbWsdlDeployerIs responsible for examining the EsbMetaData and generating the wsdl, which requries usage of classloaders hence this deployer is targeted after classloaders have been created.
    EsbDeployerThis is where the actual bean meta data that represents an esb deployment is created, EsbDeployment.



    Deployers configuration

    The deployers configuration is located in <server-name>/deployers/esb.deployers.

    Directory structure for esb.deployers

    actionArtifactMap.propertiesProperties file containing an action name to .esb archive mapping.This enables a set of "default" actions to be specified in jboss-esb.xml files without the need to explictly add the .esb archives of those actions to the depends element in deployment.xml
    esb.juddi.xmlJuddi configuration.
    jbossesb-properties.xmlThe ESB configuration file.
    libThe main jars for the ESB.
    META-INF/esb-deployers-jboss-beans.xmlThe beans (deployers) configuration for the Microcontainer.
    META-INF/jboss-structure.xmlA Microcontainer configuration file that describes the structure for the esb.deployer. For example it specifies that the jars can be located in the lib directory.
    privateKeyStoreThe private keystore.
    publicKeyStoreThe public keystore.

    EsbConfigParser configuration

    As the other deployers this deployer is configured in esb-deployers-jboss-beans.xml.

    A configuration example:


    <bean name="EsbConfigParser" class="">
        <property name="esbDeploymentPrefix">jboss.esb:deployment=</property>
        <property name="warDeploymentPrefix">jboss.web.deployment:war=</property>
        <property name="actionArtifactsFile">/</property>


    esbDeploymentPrefixThis is the prefix that a ESB archive deployments will have in JBoss AS. Defaults to 'jboss.esb:deployment='
    warDeploymentPrefixThis is the prefix that a war archive deployments will have in JBoss AS. These are used for .war archives specified in the 'esb-depends' section of a deployment.xml file. Defaults to 'jboss.web.deployment:war='.
    actionArtifactsFileProperties file containing an action name to .esb archive mapping. Defaults to '/'.


    EsbWebServiceDeployer configuration

    Does not have any configuration properties.

    A configuration example:

    <bean name="EsbWebServiceDeployer" class=""/>


    EsbWsdlDeployer configuration

    Does not have any configuration properties.

    A configuration example:

    <bean name="EsbWsdlDeployer" class=""/>


    EsbDeployer configuration

    As the other deployers this deployer is configured in esb-deployers-jboss-beans.xml.

    A configuration example:


    <bean name="EsbDeployer" class="">
        <property name="esbBeanPrefix">jboss.esb</property>
        <property name="defaultDependencies">
            <list elementClass="java.lang.String">


    esbBeanPrefixPrefix used for the BeanMetaData and for the managenment bean name
    defaultDependenciesA list of additional dependencies that will be added to deployments as dependencies.



    How to try it out

    In the process of adding support for AS 5 we discovered a few issues that needed to be fixed in AS for the ESB to work. This is the reason why you will need to check out a specific branch of AS to be able to test this. These fixes are scheduled for the next release for AS which is 5.1.0.GA.

    If you'd like to try this out then please follow the instructions below.

    Installation steps.

    1. Download JBoss AS 5.1.0.GAand unzip it.
    2. svn checkout
    3. Run 'ant dist' from the product directory
    4. Edit product/install/ and set org.jboss.esb.server.home to point to the unzipped server from step 1.
    5. Run 'ant deploy' from the product/install directory.
    6. Startup the server (with JBOSS_HOME set to the install folder of JBoss AS 5.1.0.GA).
    7. Try out some quickstarts or deploy your .esb archive.


    Depending on whether you access certain application (like the jopr console) you might need to increase the memory settings when starting the server (in run.conf):

    -Xms128m -Xmx512m -XX:PermSize=200m -XX:MaxPermSize=500m

    Running the integration tests:

    1. Edit qa/ and set org.jboss.esb.server.home to point to the same location as in step 6 above.
    2. Run 'ant -f integration-build.xml integration' from the product directory.


    Java 6

    When using Java 6 the following jars are required to be available in <server_home>/lib/endorsed

    1. jaxb-api.jar

    2. jaxb-impl.jar

    3. jaxb-xjc.jar

    4. jbossws-native-jaxrpc.jar

    5. jbossws-native-jaxws-.jar

    6. jbossws-native-jaxws-ext.jar

    7. jbossws-native-saaj.jar

    Scoped Deployments

    In ESB 4.x you can specify that a deployment be scoped by configuring this in deployment.xml:


    The AS5 deployers ignore this section of deployment.xml. Instead a ESB 4.x scoped deployment
    users will be required to create a META-INF/jboss-classloading.xml:

    <classloading xmlns="urn:jboss:classloading:1.0" domain="simple-scoped" parent-first="false" />

    This was discussed and agreed upon in this dev forum thread.


    Prior to AS 5 sub-deployments in an .esb archive could be located anywhere, in the root, in a subdirectory somewhere. 
    This has changed with AS 5 and this post is meant to list the options that users have when upgrading.

    This really only effects users that currently have sub-deployments in a sub-directory. For those that have sub-deployments in the root of the .esb archive nothing needs to be done.

    We are now defining a GroupStructure in deployers/esb.deployers/META-INF/esb-deployers-jboss-beans.xml:

    <bean name="GroupingStructure" class="">
        <property name="shortCircuitFilter">
            <inject bean="EsbFilter"/>
        <property name="metaDataPaths">
             <array elementClass="java.lang.String">
        <property name="libs">
            <set elementClass="java.lang.String">
        <property name="libFilter">
            <inject bean="JarFilter"/>
        <property name="groups">
            <set elementClass="java.lang.String">
        <property name="groupFilter">
            <inject bean="WarFilter"/>

    <bean name="EsbFilter" class="">

    <bean name="JarFilter" class="">

    <bean name="WarFilter" class="">

    So by default we can have jars in either the root, or in a sub directory named 'jars'.
    And we can have wars in either the root, or in a sub directory named 'wars'.

    In the cases where users want to have wars (or other types of
    deployments) in sub-directories that have different names. they have
    the following options:

    1. Renaming their sub directory to 'wars'.
    2. Adding their sub directory names to the 'groups' list above.
    3. Add a META-INF/jboss-structure.xml to their .esb archive:
    <?xml version="1.0" encoding="UTF-8"?>
            <path name=""/>
                <path name="META-INF"/>
                <path name="."/>
                <path name=""/>
                <path name="." suffixes=".jar"/>
            <path name="subdir/testwar.war"/>
                <path name="WEB-INF"/>
                <path name="subdir/testwar.war/WEB-INF/classes"/>

    Windows script error

    The windows run.bat script, included in the AS 5.1.0 GA release, contains an error that prevents the JDK tools jar from being added to the classpath.  This is required for compilation of the wise WS proxies and can be fixed with a small modification.  Please refer to JBESB-2747 for details.


    CI Build

    Port Conflict

    When installing AS5 on the build servers I noticed a port conflict for the AJP Connector port 8009. This has now been configured in default/deploy/jbossweb.sar/server.xml to port 8019 as shown below:

      <!-- A AJP 1.3 Connector on port 8009 -->
      <Connector protocol="AJP/1.3" port="8019" address="${jboss.bind.address}"
             redirectPort="8443" />

    This port conflict is caused by the hudson service executing on the CI machines.