LibraryPrintFeedback

Using Java Business Integration

Version 7.1

December 2012
Trademark Disclaimer
Third Party Acknowledgements

Updated: 08 Jan 2014

Table of Contents

I. Overview of Java Business Integration
1. Introduction to JBI
2. The Component Framework
3. The Normalized Message Router
4. Management Structure
II. Deploying JBI Artifacts into the Fuse ESB Enterprise Runtime
5. Clustering JBI Endpoints
6. Using the JBI Ant Tasks
Using the tasks as commands
Using the tasks in build files
7. Building JBI Components Using Maven
8. Deploying JBI Endpoints Using Maven
Setting up a Fuse ESB Enterprise JBI project
A service unit project
A service assembly project
A. Using the JBI Console Commands
Index

List of Figures

1.1. The JBI architecture
4.1. JBI component life-cycle
4.2. Service unit life-cycle

List of Tables

6.1. Options for installing a JBI component with an Ant command
6.2. Options for removing a JBI component with an Ant command
6.3. Options for starting a JBI component with an Ant command
6.4. Options for stopping a JBI component with an Ant command
6.5. Options for shutting down a JBI component with an Ant command
6.6. Options for installing a shared library with an Ant command
6.7. Options for removing a shared library with an Ant command
6.8. Attributes for installing a JBI component using an Ant task
6.9. Attributes for removing a JBI component using an Ant task
6.10. Attributes for starting a JBI component using an Ant task
6.11. Attributes for stopping a JBI component using an Ant task
6.12. Attributes for shutting down a JBI component using an Ant task
6.13. Attributes for installing a shared library using an Ant task
6.14. Attributes for removing a shared library using an Ant task
8.1. Service unit archetypes
A.1. JBI Commands

List of Examples

5.1. Default cluster engine configuration
5.2. OSGi packaged JBI endpoint
5.3. JBI packaged endpoint
5.4. Static configuration
5.5. Multicast configuration
6.1. Installing a component using an Ant command
6.2. Removing a component using an Ant command
6.3. Starting a component using an Ant command
6.4. Stopping a component using an Ant command
6.5. Adding the JBI tasks to an Ant build file
6.6. Ant target that installs a JBI component
6.7. Ant target that removes a JBI component
6.8. Ant target that starts a JBI component
6.9. Ant target that stops a JBI component
6.10. Ant target that shuts down a JBI component
7.1. POM elements for using Fuse ESB Enterprise Maven tools
7.2. Command for JBI maven archetypes
7.3. Specifying that a maven project results in a JBI component
7.4. Plug-in specification for packaging a JBI component
7.5. Specifying that a maven project results in a JBI shared library
8.1. POM elements for using Fuse ESB Enterprise Maven tooling
8.2. Top-level POM for a Fuse ESB Enterprise JBI project
8.3. Maven archetype command for service units
8.4. Configuring the maven plug-in to build a service unit
8.5. Specifying the target components for a service unit
8.6. Specifying a target component for a service unit
8.7. POM file for a service unit project
8.8. Maven archetype command for service assemblies
8.9. Configuring the Maven plug-in to build a service assembly
8.10. Specifying the target components for a service unit
8.11. POM for a service assembly project

Complete the following steps to set up JBI endpoint clustering:

  1. Install the jbi-cluster feature included in Fuse ESB Enterprise. See Installing the clustering feature.

  2. Optionally, configure the clustering engine with a JMS broker other than the Apache ActiveMQ. See Changing the JMS broker.

  3. Optionally, change the default clustering engine configuration to specify different cluster and destination names. See Changing the default configuration.

  4. Add endpoints and register the endpoint definition in the Spring configuration. See Using clustering in an application.

See the following sections for additional information:

Fuse ESB Enterprise has a pre-installed clustering engine that is configured to use the included Apache ActiveMQ. The default configuration for the Fuse ESB Enterprise cluster engine is defined in the jbi-cluster.xml file in the org.apache.servicemix.jbi.cluster.config bundle. This bundle is located in the installation directory in \system\org\apache\servicemix\jbi\cluster.

The default cluster engine configuration, shown in Example 5.1, is designed to meet most basic requirements.

Example 5.1. Default cluster engine configuration

<bean id="clusterEngine" class="org.apache.servicemix.jbi.cluster.engine.ClusterEngine">
  <property name="pool">
    <bean class="org.apache.servicemix.jbi.cluster.requestor.ActiveMQJmsRequestorPool">
     <property name="connectionFactory" ref="connectionFactory" />
     <property name="destinationName" value="${destinationName}" />
    </bean>
  </property>
  <property name="name" value="${clusterName}" />
</bean>
<osgi:list id="clusterRegistrations"
      interface="org.apache.servicemix.jbi.cluster.engine.ClusterRegistration" 
      cardinality="0..N">
  <osgi:listener ref="clusterEngine" bind-method="register" unbind-method="unregister" />
</osgi:list>        
<osgi:reference id="connectionFactory" interface="javax.jms.ConnectionFactory" />       
<osgi:service ref="clusterEngine">
  <osgi:interfaces>
    <value>org.apache.servicemix.nmr.api.Endpoint</value>
    <value>org.apache.servicemix.nmr.api.event.Listener</value>
    <value>org.apache.servicemix.nmr.api.event.EndpointListener</value>
    <value>org.apache.servicemix.nmr.api.event.ExchangeListener</value>
  </osgi:interfaces>
  <osgi:service-properties>
    <entry key="NAME" value="${clusterName}" />
  </osgi:service-properties>
</osgi:service>        
<osgix:cm-properties id="clusterProps" 
        persistent-id="org.apache.servicemix.jbi.cluster.config">
  <prop key="clusterName">${servicemix.name}</prop>
  <prop key="destinationName">org.apache.servicemix.jbi.cluster</prop>
</osgix:cm-properties>       
<ctx:property-placeholder properties-ref="clusterProps" />
</beans>

Fuse ESB Enterprise has a preconfigured Apache ActiveMQ instance that automatically starts when the container is started. This means you do not have to start a broker instance for the clustering engine to work.

To create a network of JBI containers, you must establish network connections between each of the containers in the network, and then establish a network connection between the active containers. You can configure these network connections as either static or multicast connections.

When a network connection is established, each container discovers the other containers' remote components and can route to them.

The JBI specification defines a number of Ant tasks that can be used to manage JBI components. These tasks allow you to install, start, stop, and uninstall components in the Fuse ESB Enterprise container. You can use the JBI Ant tasks as either command line commands or as part of an Ant build file.

Before you can use the JBI tasks in an Ant build file, you must add the tasks using a taskdef element, as shown in Example 6.5.

Example 6.5. Adding the JBI tasks to an Ant build file

...
<property name="fuseesb.install_dir" value="/home/fuse_esb"/> 1

<taskdef file="${fuseesb.install_dir}/ant/servicemix_ant_taskdef.properties"> 2
  <classpath id="fuseesb.classpath"> 3
    <fileset dir="${fuseesb.install_dir}">
       <include name="*.jar"/>
     </fileset>
     <fileset dir="${fuseesb.install_dir}/lib">
        <include name="*.jar"/>
      </fileset>
  </classpath>
</taskdef>
...

The build file fragment in Example 6.5 does the following:

1

Sets a property, fuseesb.install_dir, the installation directory for Fuse ESB Enterprise

2

Loads the tasks using the ant/servicemix_ant_taskdef.properties

3

Sets the classpath to make all of the required jars from the Fuse ESB Enterprise installation available

As shown in Example 7.3, you specify a value of jbi-component for the project's packaging element, which informs the Fuse ESB Enterprise Maven tooling that the project is for a JBI component.


The plugin element responsible for packaging the JBI component is shown in Example 7.4. The groupId element, the artifactId element, the version element, and the extensions element are common to all instances of the Fuse ESB Enterprise Maven plug-in. If you use the Maven archetypes to generate the project, you should not have to change them.


The configuration element, along with its children, provides the Fuse ESB Enterprise tooling with the metadata necessary to construct the jbi.xml file required by the component.

Once the project is properly configured, you can build the JBI component by using the mvn install command. The Fuse ESB Enterprise Maven tooling will generate a standard jar containing both the component and an installable JBI package for the component.

The tooling provides you with a number of benefits, including:

  • Automatic generation of JBI descriptors

  • Dependency checking

  • Service assembly deployment

Because Fuse ESB Enterprise only allows you to deploy service assemblies, you must do the following when using Maven tooling:

  1. Set up a top-level project to build all of the service units and the final service assembly (see Setting up a Fuse ESB Enterprise JBI project).

  2. Create a project for each of your service units (see A service unit project).

  3. Create a project for the service assembly (see A service assembly project).

Example 8.2 shows a top-level POM for a project that contains a single service unit.

Example 8.2. Top-level POM for a Fuse ESB Enterprise JBI project

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>com.widgets</groupId>
    <artifactId>demos</artifactId>
    <version>1.0</version>
  </parent>

  <groupId>com.widgets.demo</groupId>
  <artifactId>cxf-wsdl-first</artifactId>
  <name>CXF WSDL Fisrt Demo</name>
  <packaging>pom</packaging>
    
  <pluginRepositories> 1
    <pluginRepository>
      <id>fusesource.m2</id>
      <name> Open Source Community Release Repository</name>
      <url>http://repo.fusesource.com/maven2</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <releases>
        <enabled>true</enabled>
      </releases>
    </pluginRepository>
  </pluginRepositories>
  <repositories>
    <repository>
      <id>fusesource.m2</id>
      <name> Open Source Community Release Repository</name>
      <url>http://repo.fusesource.com/maven2</url>
      <snapshots>
         <enabled>false</enabled>
      </snapshots>
      <releases>
        <enabled>true</enabled>
      </releases>
    </repository>
    <repository>
      <id>fusesource.m2-snapshot</id>
      <name> Open Source Community Snapshot Repository</name>
      <url>http://repo.fusesource.com/maven2-snapshot</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
      <releases>
        <enabled>false</enabled>
      </releases>
    </repository>
  </repositories>
    
  <modules> 2
    <module>wsdl-first-cxfse-su</module>
     <module>wsdl-first-cxf-sa</module>
  </modules>
    
  <build>
    <plugins>
      <plugin> 3
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-assembly-plugin</artifactId>
         <version>2.1</version>
         <inherited>false</inherited>
           <executions>
             <execution>
                <id>src</id>
                <phase>package</phase>
                <goals>
                  <goal>single</goal>
                </goals>
                <configuration>
                  <descriptors>
                    <descriptor>src/main/assembly/src.xml</descriptor>
                  </descriptors>
                 </configuration>
               </execution>
             </executions>
           </plugin>
           <plugin> 4
             <groupId>org.apache.servicemix.tooling</groupId>
             <artifactId>jbi-maven-plugin</artifactId>
             <extensions>true</extensions>
           </plugin>
    </plugins>
  </build>
</project>

The top-level POM shown in Example 8.2 does the following:

1

Configures Maven to use the repositories for loading the Fuse ESB Enterprise plug-ins.

2

Lists the sub-projects used for this application. The wsdl-first-cxfse-su module is the module for the service unit. The wsdl-first-cxf-sa module is the module for the service assembly

3

Configures the Maven assembly plug-in.

4

Loads the Fuse ESB Enterprise JBI plug-in.

Fuse ESB Enterprise provides Maven artifacts for a number of service unit types. They can be used to seed a project with the smx-arch command. As shown in Example 8.3, the smx-arch command takes three arguments. The groupId value and the artifactId values correspond to the project's group ID and artifact ID.


[Important]Important

The double quotes(") are required when using the -DgroupId argument and the -DartifactId argument.

The suArchetypeName specifies the type of service unit to seed. Table 8.1 lists the possible values and describes what type of project is seeded.

Table 8.1. Service unit archetypes

NameDescription
camelCreates a project for using the Apache Camel service engine
cxf-seCreates a project for developing a Java-first service using the Apache CXF service engine
cxf-se-wsdl-firstCreates a project for developing a WSDL-first service using the Apache CXF service engine
cxf-bcCreates an endpoint project targeted at the Apache CXF binding component
http-consumerCreates a consumer endpoint project targeted at the HTTP binding component
http-providerCreates a provider endpoint project targeted at the HTTP binding component
jms-consumerCreates a consumer endpoint project targeted at the JMS binding component (see Using the JMS Binding Component)
jms-providerCreates a provider endpoint project targeted at the JMS binding component (see Using the JMS Binding Component)
file-pollerCreates a polling (consumer) endpoint project targeted at the file binding component (see Using Poller Endpoints in Using the File Binding Component)
file-senderCreates a sender (provider) endpoint project targeted at the file binding component (see Using Sender Endpoints in Using the File Binding Component)
ftp-pollerCreates a polling (consumer) endpoint project targeted at the FTP binding component
ftp-senderCreates a sender (provider) endpoint project targeted at the FTP binding component
jsr181-annotatedCreates a project for developing an annotated Java service to be run by the JSR181 service engine [a]
jsr181-wsdl-firstCreates a project for developing a WSDL generated Java service to be run by the JSR181 service engine [a]
saxon-xqueryCreates a project for executing xquery statements using the Saxon service engine
saxon-xsltCreates a project for executing XSLT scripts using the Saxon service engine
eipCreates a project for using the EIP service engine. [b]
lwcontainerCreates a project for deploying functionality into the lightweight container [c]
beanCreates a project for deploying a POJO to be executed by the bean service engine
odeCreate a project for deploying a BPEL process into the ODE service engine

[a] The JSR181 has been deprecated. The Apache CXF service engine has superseded it.

[b] The EIP service engine has been deprecated. The Apache Camel service engine has superseded it.

[c] The lightweight container has been deprecated.


To correctly fill in the metadata required for packaging a service unit, the Maven plug-in must be told what component (or components) the service unit is targeting. If your service unit only has a single component dependency, you can specify it in one of two ways:

  • List the targeted component as a dependency

  • Add a componentName property specifying the targeted component

If your service unit has more than one component dependency, you must configure the project as follows:

  1. Add a componentName property specifying the targeted component.

  2. Add the remaining components to the list dependencies.

Example 8.5 shows the configuration for a service unit targeting the Apache CXF binding component.


The advantage of using the Maven dependency mechanism is that it allows Maven to verify if the targeted component is deployed in the container. If one of the components is not deployed, Fuse ESB Enterprise will not hold off deploying the service unit until all of the required components are deployed.

[Tip]Tip

Typically, a message identifying the missing component(s) is written to the log.

If your service unit's targeted component is not available as a Maven artifact, you can specify the targeted component using the componentName element. This element is added to the standard Maven properties block and it specifies the name of a targeted component, as specified in Example 8.6.


When you use the componentName element, Maven does not check to see if the component is installed, nor does it download the required component.

Example 8.7 shows the POM file for a project that is building a service unit targeted to the Apache CXF binding component.

Example 8.7. POM file for a service unit project

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent> 1
        <groupId>com.widgets.demo</groupId>
        <artifactId>cxf-wsdl-first</artifactId>
        <version>1.0</version>
    </parent>

  <groupId>com.widgets.demo.cxf-wsdl-first</groupId>
  <artifactId>cxfse-wsdl-first-su</artifactId>
  <name>CXF WSDL Fisrt Demo :: SE Service Unit</name>
  <packaging>jbi-service-unit</packaging> 2

  <dependencies> 3
    <dependency>
      <groupId>org.apache.servicemix</groupId>
      <artifactId>servicemix-cxf-bc</artifactId>
      <version>3.3.1.0-fuse</version>
    </dependency>
  >/dependencies>

  <build>
    <plugins>
      <plugin> 4
        <groupId>org.apache.servicemix.tooling</groupId>
        <artifactId>jbi-maven-plugin</artifactId>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
</project>

The POM file in Example 8.7 does the following:

1

Specifies that it is a part of the top-level project shown in Example 8.2

2

Specifies that this project builds a service unit

3

Specifies that the service unit targets the Apache CXF binding component

4

Specifies to use the Fuse ESB Enterprise Maven plug-in



[1] You replace this with the version of Apache CXF you are using.

Example 8.11 shows a POM file for a project that is building a service assembly.

Example 8.11. POM for a service assembly project

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent> 1
        <groupId>com.widgets.demo</groupId>
        <artifactId>cxf-wsdl-first</artifactId>
        <version>1.0</version>
    </parent>

  <groupId>com.widgets.demo.cxf-wsdl-first</groupId>
  <artifactId>cxf-wsdl-first-sa</artifactId>
  <name>CXF WSDL Fisrt Demo ::  Service Assemby</name>
  <packaging>jbi-service-assembly</packaging> 2

  <dependencies> 3
    <dependency>
      <groupId>com.widgets.demo.cxf-wsdl-first</groupId>
      <artifactId>cxfse-wsdl-first-su</artifactId>
      <version>1.0</version>
    </dependency>
    <dependency>
      <groupId>com.widgets.demo.cxf-wsdl-first</groupId>
      <artifactId>cxfbc-wsdl-first-su</artifactId>
      <version>1.0</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin> 4
        <groupId>org.apache.servicemix.tooling</groupId>
        <artifactId>jbi-maven-plugin</artifactId>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
</project>

The POM in Example 8.11 does the following:

1

Specifies that it is a part of the top-level project shown in Example 8.2

2

Specifies that this project builds a service assembly

3

Specifies the service units being bundled by the service assembly

4

Specifies to use the Fuse ESB Enterprise Maven plug-in

A

Ant task
install-component, Installing a component
install-shared-library, Installing a shared library
installing components, Installing a component, Installing a component
installing shared libraries, Installing a shared library, Installing a shared library
jbi-install-component, Installing a component
jbi-install-shared-library, Installing a shared library
jbi-shut-down-component, Shutting down a component
jbi-start-component, Starting a component
jbi-stop-component, Stopping a component
jbi-uninstall-component, Removing a component
jbi-uninstall-shared-library, Removing a shared library
removing components, Removing a component, Removing a shared library, Removing a component
removing shared libraries, Removing a shared library
shutdown-component, Shutting down a component
shutting down components, Shutting down a component, Shutting down a component
start-component, Starting a component
starting components, Starting a component, Starting a component
stop-component, Stopping a component
stopping components, Stopping a component, Stopping a component
uninstall-component, Removing a component
uninstall-shared-library, Removing a shared library
uninstalling components, Removing a component, Removing a shared library, Removing a component

B

binding component, Component types

C

clustering JBI endpoints, Overview
component life-cycle, Managing JBI components
componentName, Specifying the target components
consumer, Component roles

J

Java Management Extenstions, JMX
JBI clustering, Overview
jbi-install-component, Installing a component
failOnError, Installing a component
file, Installing a component
host, Installing a component
password, Installing a component
port, Installing a component
username, Installing a component
jbi-install-shared-library, Installing a shared library
failOnError, Installing a shared library
file, Installing a shared library
host, Installing a shared library
password, Installing a shared library
port, Installing a shared library
username, Installing a shared library
jbi-shut-down-component, Shutting down a component
failOnError, Shutting down a component
host, Shutting down a component
name, Shutting down a component
password, Shutting down a component
port, Shutting down a component
username, Shutting down a component
jbi-start-component, Starting a component
failOnError, Starting a component
host, Starting a component
name, Starting a component
password, Starting a component
port, Starting a component
username, Starting a component
jbi-stop-component, Stopping a component
failOnError, Stopping a component
host, Stopping a component
name, Stopping a component
password, Stopping a component
port, Stopping a component
username, Stopping a component
jbi-uninstall-component, Removing a component
failOnError, Removing a component
host, Removing a component
name, Removing a component
password, Removing a component
port, Removing a component
username, Removing a component
jbi-uninstall-shared-library, Removing a shared library
failOnError, Removing a shared library
host, Removing a shared library
name, Removing a shared library
password, Removing a shared library
port, Removing a shared library
username, Removing a shared library
JMX, JMX

M

Maven tooling
binding component, JBI components
component bootstrap class, JBI components
component implementation class, JBI components
component type, JBI components
JBI component, JBI components
project creation, Creating a JBI Maven project
service engine, JBI components
set up, Setting up the Maven tools, Setting up the Maven tools
shared libraries, Shared libraries
message exchange patterns, Message exchange patterns
in-only, Message exchange patterns
in-optional-out, Message exchange patterns
in-out, Message exchange patterns
robust-in-only, Message exchange patterns

P

provider, Component roles

S

service assembly, Packaging
seeding, Seeding a project using a Maven artifact
specifying the service units, Specifying the target components
service consumer, Component roles
service engine, Component types
service provider, Component roles
service unit, Packaging
seeding, Seeding a project using a Maven artifact
specifying the target component, Specifying the target components
service unit life-cycle, Managing service units
shutdown-component, Shutting down a component
sm.component.name, Shutting down a component
sm.host, Shutting down a component
sm.password, Shutting down a component
sm.port, Shutting down a component
sm.username, Shutting down a component
sm.component.name, Removing a component, Starting a component, Stopping a component, Shutting down a component
sm.host, Installing a component, Removing a component, Starting a component, Stopping a component, Shutting down a component, Installing a shared library, Removing a shared library
sm.install.file, Installing a component, Installing a shared library
sm.password, Installing a component, Removing a component, Starting a component, Stopping a component, Shutting down a component, Installing a shared library, Removing a shared library
sm.port, Installing a component, Removing a component, Starting a component, Stopping a component, Shutting down a component, Installing a shared library, Removing a shared library
sm.shared.library.name, Removing a shared library
sm.username, Installing a component, Removing a component, Starting a component, Stopping a component, Shutting down a component, Installing a shared library, Removing a shared library
smx-arch, Seeding a project using a Maven artifact, Seeding a project using a Maven artifact
start-component, Starting a component
sm.component.name, Starting a component
sm.host, Starting a component
sm.password, Starting a component
sm.port, Starting a component
sm.username, Starting a component
stop-component, Stopping a component
sm.component.name, Stopping a component
sm.host, Stopping a component
sm.password, Stopping a component
sm.port, Stopping a component
sm.username, Stopping a component