Tutorial: Creation of a Hello World Style of JBI Component

This tutorial describes how to create a very simple Hello World style of JBI service engine (SE) component. It demonstrates some best practices for creating JBI components. The example in this tutorial is as minimalistic as possible so as to focus on key concepts and not drown in details. The example component will respond to all requests with the message:

Prerequisites

• Maven 2.0.4 or higher
  • If you have never used Maven previously the Maven Getting Started Guide explains some valuable concepts surrounding Maven
• ServiceMix 3.0 or higher
  • See the ServiceMix downloads
• A broadband internet connection (so Maven can automatically download dependencies)

A Very Brief Introduction to Java Business Integration

The Java Business Integration (JBI) spec provides a standards-based, service-oriented approach to application integration through the use of an abstract messaging model, without reference to a particular protocol or wire encoding. JBI introduces the concepts of Binding Components (BCs), Service Engines (SEs) to Service Units (SUs) and Service Assemblies (SAs) to define an architecture for vendor-neutral pluggable components. The purpose of this architecture is to provide standards-based interoperability amongst components/services.

JBI components are can be thought of as the smallest applications or services accessible in a service-oriented architecture. Each service has a very specific purpose and therefore a narrow scope and set of functionality. Components come in two flavours: Service Engine (SE) and Binding Components (BC). Several SUs are packed into a SA. An SA is a complete application consisting of one or more services interacting with one another.

See also the page providing information on working with service units

Below are some quick definitions:

• Component Architecture
  • Binding Components - Components that provide or consume services via some sort of communications protocol or other remoting technology
  • Service Engines - Components that supply or consume services locally (within the JBI container)

• Component Packaging
  • Service Units - Packaging for an individual service that allows deployment to the JBI container; similar to a WAR file from J2EE
  • Service Assemblies - Packaging for groups of SUs for deployment to the JBI container; similar to an EAR file from J2EE

For further reading, see the JBIforSOI document for a good introduction to JBI.

Creating the Maven Projects for Each Component

Creating a Skeleton Project For the JBI Service Engine (SE)

The focus of this section is on the creation of a JBI component. For this task, a Maven archetype will be used to create a Maven project skeleton to house the component. Maven archetypes are templates for Maven projects that jumpstart project creation via the automation of repetitive tasks by following standard conventions. The result of using an archetype to create a Maven project is a directory structure, a Maven POM file and, depending on the archetype being used, sometimes Java objects and JUnit tests.

1) Create a directory named hello-world-se:

$ mkdir hello-world-se

2) Use a Maven archetype to generate a Maven project for the SE:

The first three parameters to the mvn command (-DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-service-engine -DarchetypeVersion=3.1-incubating-SNAPSHOT) identify which Maven archetype to use for the archetype:create goal, while the last two parameters (-DgroupId=org.apache.servicemix.samples.helloworld -DartifactId=hello-world-se) uniquely identify the Maven project that is being generated. The groupId (printed in pink) is used as the Java package and the artifactId is used as the project name. Therefore, only alphanumeric characters valid values for the groupId and artifactId parameters.

The output from executing the archetype:create goal is shown below (only relevant information has been preserved):

Maven creates a directory using the artifactId provided (printed in green in the command and output). Inside this directory resides the pom.xml and the src directory.

\~/.m2/repository/org/apache/maven/plugins/maven-archetype-plugin 

C:\Documents and Settings\<USERNAME_>

<?xml version="1.0" encoding="UTF-8"?>
<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">

  <modelVersion>4.0.0</modelVersion>

  <groupId>mygroup</groupId>
  <artifactId>myartifact</artifactId>
  <version>myversion</version>
  <packaging>pom</packaging>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-archetype-plugin</artifactId>
          <version>1.0-alpha-4</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

Creating the Project For the SU and SA

The archetypes for SUs and SAs do not contain much code, but rather help with tasks related to Maven. Later, we will only need to adapt the POMs to our project - just little work.

From within the directory hello-world-se, execute the following commands to create the project for the SU:

mvn archetype:create -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-service-unit \
-DarchetypeVersion=3.1-incubating-SNAPSHOT -DgroupId=org.apache.servicemix.samples.helloworld -DartifactId=hello-world-su

From within the directory hello-world-se, execute the following commands to create the project for the SA:

mvn archetype:create -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-service-assembly \
-DarchetypeVersion=3.1-incubating-SNAPSHOT -DgroupId=org.apache.servicemix.samples.helloworld -DartifactId=hello-world-sa

The directory structures for each project should appear as follows:

C:\hello-world-se\hello-world-sa
C:\hello-world-se\hello-world-sa\pom.xml


C:\hello-world-se\hello-world-se
C:\hello-world-se\hello-world-se\pom.xml

C:\hello-world-se\hello-world-se\src\main\java\org\apache\servicemix\samples\helloworld
C:\hello-world-se\hello-world-se\src\main\java\org\apache\servicemix\samples\helloworld\MyBootstrap.java
C:\hello-world-se\hello-world-se\src\main\java\org\apache\servicemix\samples\helloworld\MyComponent.java
C:\hello-world-se\hello-world-se\src\main\java\org\apache\servicemix\samples\helloworld\MyDeployer.java
C:\hello-world-se\hello-world-se\src\main\java\org\apache\servicemix\samples\helloworld\MyEndpoint.java
C:\hello-world-se\hello-world-se\src\main\java\org\apache\servicemix\samples\helloworld\MyLifeCycle.java
C:\hello-world-se\hello-world-se\src\main\java\org\apache\servicemix\samples\helloworld\MySpringComponent.java

C:\hello-world-se\hello-world-se\src\test\java\org\apache\servicemix\samples\helloworld
C:\hello-world-se\hello-world-se\src\test\java\org\apache\servicemix\samples\helloworld\MySpringComponentTest.java

C:\hello-world-se\hello-world-se\src\test\resources
C:\hello-world-se\hello-world-se\src\test\resources\spring.xml


C:\hello-world-se\hello-world-su
C:\hello-world-se\hello-world-su\pom.xml
C:\hello-world-se\hello-world-su\src\main\resources

According to the template rules, all Java objects are prefixed with the word My. These Java objects can be renamed to whatever you prefer, making sure to also change the names in the corresponding resource files (all tests and {{pom.xml}}s) as well.

Incorporating the SU and SA Into the Top Level POM

Now that we have created the SU and SA projects, the top level pom.xml} must be made aware of each one. In the {{hello-world-se directory create a file named pom.xml containing the following content:

<project>
  <modelVersion>4.0.0</modelVersion>

  <groupId>org.apache.servicemix.samples</groupId>
  <artifactId>hello-world-se</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <modules>
    <module>hello-world-sa</module>
    <module>hello-world-su</module>
  </modules>

  <dependencies>
    <dependency>
      <groupId>org.apache.servicemix.samples.helloWorldse</groupId>
      <artifactId>hello-world-su</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>

</project>

The <modules> element denotes the child projects that were created using the Maven archetypes and the <dependencies> element tells Maven to include the SU into the SA when it is constructed.

Using Maven to Build and Package the Components

By now, it is already possible to call Maven with the relevant goals.

Compiling the Components

In order to build, package and place a copy of each component in the Maven repository onyour local machine, execute the following from within hello-world-se directory:

mvn install 

in the hello-world-SE-SU-SA/hello-world-SE directory and Maven shall present as one of the last lines of output

[INFO] BUILD SUCCESSFUL

In case this success information does not appear, the output will provide some information about what might have gone awry. Assistance with any issue you might experience is available from the ServiceMix community via the ServiceMix mailing lists archive.

Testing the Components

Performing automated testing of the components is possible via Maven as well. Because the ServiceMix root POM prevents tests from being executed at the top level, this functionality must be activated so that the coponents can be tested. To do so, the <build> element of the hello-world-se/pom.xml must be augmented using the following content:

<pluginManagement>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <skip>false</skip><!-- this overrides the ServiceMix root POM's setting for test execution -->
        </configuration>
      </plugin>
   </plugins>
</pluginManagement>

By adding the configuation above, the install goal will now including test execution in addition to building and packaging the components. To run the tests, execute the test goal this time and you should see the following output:

$ mvn test

[INFO] Scanning for projects...
[INFO] ----------------------------------------------------------------------------
[INFO] Building A custom project
[INFO]    task-segment: [test]
[INFO] ----------------------------------------------------------------------------
...
[INFO] [compiler:compile]
...
[INFO] [surefire:test]
[INFO] Setting reports dir: c:\java\tmp\servicemix-helloWorldSE\target/surefire-reports
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
[surefire] Running org.apache.servicemix.samples.helloWorldSE.MySpringComponentTest
...
[surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1,422 sec
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...

Generation and Deployment of the SA

The execution of the install goal above packages not only each component individually, it also packages the components together into a single SA. Of course, the code does not yet do anything, but we can already deploy the SA ServiceMix by switching to the hello-world-se/hello-world-sa directory and executing the jbi:projectDeploy goal like so:

$ mvn jbi:projectDeploy

This tells the Maven JBI plugin to deploy the components to ServiceMix. When the deployment is complete, ServiceMix will output the following:

INFO  - ServiceAssemblyLifeCycle       - Starting service assembly: hello-world-sa

This output tells us that the SA was successfully deployed to ServiceMix.

<build>
<plugins>
  <plugin>
    <artifactId>jbi-maven-plugin</artifactId>
    <configuration>
      <deployDependencies>false</deployDependencies>
    </configuration>
  </plugin>
</plugins>
</build>

Adding Functionality to the Component

We're now ready to add a bit of functionality to the component. Using an IDE like IntelliJ IDEA or Eclipse make this task much easier. The steps described here apply to Eclipse.