Creating a Hello World JBI Binding Component

Warning

title	ATTENTION!

*This tutorial page is a work in progress and it may contain outdated information or may not work at all.
There are currently no plans to resume work on this tutorial.

Tip

title	Should I Create My Own JBI Components?

NOTE: Before beginning this tutorial, please take the time to read the FAQ entry titled Should I Create My Own JBI Components?. It is very important that you understand the reason for developing a JBI binding component and this FAQ entry will explain this.

This tutorial describes how to create a very simple Hello World style of JBI binding component. This tutorial is as minimalistic as possible so as to focus on key concepts and not drown in details. The Hello World binding component will respond to all requests with the message:

unmigrated-wiki-markup

Panel

<hello>Hello World! Message \ [<original message here>\] contains \ [??\] bytes.</hello>

The following sections will walk through the creation, packaging, testing and deployment of the Hello World binding component.

Prerequisites

Maven 2.0.4 7 or higher
- If you have never used Maven previously the Maven Getting Started Guide explains some valuable concepts surrounding Maven
ServiceMix 3.2.1 -incubating-SNAPSHOT or higher
See the ServiceMix downloads to grab a nightly build as ServiceMix 3.1 has not yet been released
A broadband internet connection so Maven can automatically download dependencies

...

Code Block
$ mkdir hello-world-smx $ cd hello-world-smx

2) Use the servicemix-servicebinding-enginecomponent Maven archetype to generate a Maven project for the component.

...

Panel
$ mvn archetype:create \ -DarchetypeGroupId=org.apache.servicemix.tooling \ -DarchetypeArtifactId=servicemix-binding-component \ -DarchetypeVersion=3.2.1 -incubating-SNAPSHOT \ -DgroupId=org.apache.servicemix.samples.helloworld.bc \ -DartifactId=hello-world-bc -su

The command above will create a directory named hello-world-bc-su that houses a Maven project for the JBI service engine being created here. The name of the directory is taken from the artifactId parameter.

The first three parameters to the mvn command (-DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-binding-component -DarchetypeVersion=3.2.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.bc -DartifactId=hello-world-bc-su) uniquely identify the Maven project that is being generated. The groupId is used as the Java package and the artifactId is used as the project name. Therefore, only alphanumeric characters are valid values for the groupId and artifactId parameters.

Tip
The value of the `archetypeVersion` parameter in the command above (3.2.1-incubating-SNAPSHOT) may need to be updated to the current ServiceMix version in order for the command to work correctly. The latest version can always be found in the top level ServiceMix POM in the `<version>` element.

The output from executing the archetype:create goal is shown below:

No Format

[INFO] Scanning for projects...
[INFO] Reactor build order: 
[INFO]   A custom project
[INFO]   A custom project
[INFO]   Hello World JBI Component
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ----------------------------------------------------------------------------
[INFO] Building HelloMaven WorldDefault JBI ComponentProject
[INFO]    task-segment: [archetype:create] (aggregator-style)
[INFO] ----------------------------------------------------------------------------
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] ************************************************************** 
[INFO] Starting Jakarta Velocity v1.4
[INFO] RuntimeInstance initializing.
[INFO] Default Properties File: org/apache/velocity/runtime/defaults/velocity.properties
[INFO] Default ResourceManager initializing. (class org.apache.velocity.runtime.resource.ResourceManagerImpl)
[INFO] Resource Loader Instantiated: org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader
[INFO] ClasspathResourceLoader : initialization starting.
[INFO] ClasspathResourceLoader : initialization complete.
[INFO] ResourceCache : initialized. (class org.apache.velocity.runtime.resource.ResourceCacheImpl)
[INFO] Default ResourceManager initialization complete.
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Literal
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Macro
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Parse
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Include
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Foreach
[INFO] Created: 20 parsers.
[INFO] Velocimacro : initialization starting.
[INFO] Velocimacro : adding VMs from VM library template : VM_global_library.vm
[ERROR] ResourceManager : unable to find resource 'VM_global_library.vm' in any resource loader.
[INFO] Velocimacro : error using  VM library template VM_global_library.vm : org.apache.velocity.exception.ResourceNotFoundException: 
Unable to find resource 'VM_global_library.vm'
[INFO] Velocimacro :  VM library template macro registration complete.
[INFO] Velocimacro : allowInline = true : VMs can be defined inline in templates
[INFO] Velocimacro : allowInlineToOverride = false : VMs defined inline may NOT replace previous VM definitions
[INFO] Velocimacro : allowInlineLocal = false : VMs defined inline will be  global in scope if allowed.
[INFO] Velocimacro : initialization complete.
[INFO] Velocity successfully started.
[INFO] [archetype:create]
[INFO] Defaulting package to group ID: org.apache.servicemix.samples.helloworld.bc
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating Archetype: servicemix-binding-component:3.2.1-incubating-SNAPSHOT
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: org.apache.servicemix.samples.helloworld.bc
[INFO] Parameter: packageName, Value: org.apache.servicemix.samples.helloworld.bc
[INFO] Parameter: basedir, Value: /Users/bsnyder/src/hello-world-smx
[INFO] Parameter: package, Value: org.apache.servicemix.samples.helloworld.bc
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: artifactId, Value: hello-world-bc-su
[WARNING] org.apache.velocity.runtime.exception.ReferenceException: reference : template = archetype-resources/pom.xml [line 6885,column 16] : 
${servicemix-version} is not a valid reference.
[WARNING] org.apache.velocity.runtime.exception.ReferenceException: reference : template = archetype-resources/pom.xml [line 7390,column 16] : 
${servicemix-version} is not a valid reference.
[WARNING] org.apache.velocity.runtime.exception.ReferenceException: reference : template = archetype-resources/pom.xml [line 97115,column 18] : 
${xbean-version} is not a valid reference.
[INFO] ********************* End of debug info from resources from generated POM ***********************
[INFO] Archetype created in dir: /Users/bsnyder/src/hello-world-smx/hello-world-bc-su
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 23 seconds
[INFO] Finished at: MonTue JanMar 1506 1318:3527:4408 MST 2007
[INFO] Final Memory: 5M4M/10M8M
[INFO] ------------------------------------------------------------------------

...

Note

title	In case of a BUILD ERROR: Maven plugin version requirement

The maven-archetype-plugin 1.0-alpha4 or above is required for this tutorial. When an older version is installed, a build error will occur. The version of this plugin can be checked by verifying the name of the following directories:

Code Block

title	Unix

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

Code Block

title	Windows

C:\Documents and Settings\<USERNAME>\.m2\repository\org\apache\maven\plugins\maven-archetype-plugin

In case the only version available of the maven-archetype-plugin is an older one, a minimal pom.xml file will need to be created manually in the hello-world-bc-su directory. Below is a simple POM to use for this purpose:

Code Block

title	Minimal pom.xml

<?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 http://maven.apache.org/maven-v4_0_0.xsd">
    
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.apache.servicemix.samples.helloworld</groupId>
  <artifactId>hello-world-bc-su<bc</artifactId>
  <packaging>pom</packaging>
  <version>1.0-SNAPSHOT</version>

  <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>

...

Code Block
$ cd ./hello-world-bc-su $ mvn install

This command should produce the following output:

No Format

[INFO] Scanning for projects...
[INFO] artifact org.apache.servicemix.tooling:jbi-maven-plugin: checking for updates from apache.incubating
[INFO] ----------------------------------------------------------------------------
[INFO] Building A custom project
[INFO]    task-segment: [install]
[INFO] ----------------------------------------------------------------------------
[INFO] artifact [xbean:mapping {execution: default}]
Checking: org.apache.maven.plugins:maven-install-plugin: checking for updates from apache.incubating
Downloading: http://people.apache.org/repo/m2-incubating-repository/xml-security/xmlsec/1.3.0/xmlsec-1.3.0.pom
[WARNING] Unable to get resource from repository apache.incubating (http://people.apache.org/repo/m2-incubating-repository)
Downloading: http://repo.mergere.com/maven2/xml-security/xmlsec/1.3.0/xmlsec-1.3.0.pom
[WARNING] Unable to get resource from repository central (http://repo1.maven.org/maven2)
Downloading: http://people.apache.org/repo/m2-incubating-repository/wss4j/wss4j/1.5.0/wss4j-1.5.0.pom
[WARNING] Unable to get resource from repository apache.incubating (http://people.apache.org/repo/m2-incubating-repository)
Downloading: http://repo.mergere.com/maven2/wss4j/wss4j/1.5.0/wss4j-1.5.0.pom
[WARNING] Unable to get resource from repository central (http://repo1.maven.org/maven2)
[INFO] [xbean:mapping {execution: default}]
Checking: org.apache.servicemix.samples.helloworld.MyComponent
Checking: .servicemix.samples.helloworld.bc.MyComponent
Checking: org.apache.servicemix.samples.helloworld.bc.MyConsumerEndpoint
Checking: org.apache.servicemix.samples.helloworld.bc.MyProviderEndpoint
[INFO] Generating META-INF properties file: 
/Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/META-INF/services/org/apache/xbean/spring/http/
org.apache.servicemix.samples.helloworld.bc/1.0 for namespace: http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating Spring 2.0 handler mapping: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/META-INF/spring.handlers for namespace: 
http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating Spring 2.0 schema mapping: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/META-INF/spring.schemas for namespace: 
http://org.apache.servicemix.samples.helloworld.MyConsumerEndpoint
Checking: org.apache.servicemix.samples.helloworld.MyProviderEndpointbc/1.0
[INFO] Generating META-INFHTML propertiesdocumentation file: /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/xbean/META-INF/services/org/apache/xbean/spring/http/
org.apache.servicemix.samples.helloworld/1.0hello-world-bc.xsd.html for namespace: 
http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating Spring 2.0 handler mappingXSD file: /Users/bsnyder/src/hello-world-smx/hello-world-bc-su//target/xbean/META-INF/spring.handlers 
hello-world-bc.xsd for namespace: 
http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating SpringWIKI 2.0 schema mappingdocumentation file: /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/xbean/META-INF/spring.schemas 
hello-world-bc.xsd.wiki for namespace: 
\http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating HTML documentation file: /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/xbean/hello-world-bc-su.xsd.html 
for namespace: http://Warning, could not load class: org.apache.servicemix.samples.helloworld/1.0[INFO] Generating XSD file: 
/Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/xbean/hello-world-bc-su.xsd 
for namespace: http://.bc.MyEndpointType: java.lang.ClassNotFoundException: 
org.apache.servicemix.samples.helloworld/1.0.bc.MyEndpointType
[INFO] ...done.
[INFO] [jbi:generate-jbi-component-descriptor]
[INFO] Generating WIKI documentation file: /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/xbean/hello-world-bc-su.xsd.wiki 
for namespace: http://org.apache.servicemix.samples.helloworld/1.0Warning, could not load class: org.apache.servicemix.samples.helloworld.MyEndpointType: java.lang.ClassNotFoundException: org.apache.servicemix.samples.helloworld.MyEndpointType
[INFO] ...done.
[INFO] [jbi:generate-jbi-component-descriptor]
[INFO] Generating jbi.xmljbi.xml
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 5 source files to /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/classes
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:testCompile]
[INFO] Compiling 1 source file to /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/test-classes
[INFO] [surefire:test]
[INFO] Surefire report directory: /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/surefire-reports

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running org.apache.servicemix.samples.helloworld.bc.MySpringComponentTest
log4j:WARN No appenders could be found for logger (org.springframework.core.CollectionFactory).
log4j:WARN Please initialize the log4j system properly.
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.52431 sec

Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] [jar:jar]
[INFO] Building jar: /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/hello-world-bc-su-1.0-SNAPSHOT.jar
[INFO] [jbi:jbi-component]
[INFOWARNING] Generating installer /Users/bsnyder/src/Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[INFO] Generating installer /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/hello-world-bc-su-1.0-SNAPSHOT-installer.zip
[INFO] Building jar: /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/hello-world-bc-su-1.0-SNAPSHOT-installer.zip
[INFO] [install:install]
[INFO] Installing /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/hello-world-bc-su-1.0-SNAPSHOT.jar to 
/Users/bsnyder/.m2/repository/org/apache/servicemix/samples/helloworld/bc/hello-world-bc-su/1.0-SNAPSHOT/hello-world-bc-su-1.0-SNAPSHOT.jar
[INFO] Installing /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/xbean/hello-world-bc-su.xsd to 
/Users/bsnyder/.m2/repository/org/apache/servicemix/samples/helloworld/bc/hello-world-bc-su/1.0-SNAPSHOT/hello-world-bc-su-1.0-SNAPSHOT.xsd
[INFO] Installing /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/xbean/hello-world-bc-su.xsd.html to 
/Users/bsnyder/.m2/repository/org/apache/servicemix/samples/helloworld/bc/hello-world-bc-su/1.0-SNAPSHOT/hello-world-bc-su-1.0-SNAPSHOT-schema.html
[INFO] Installing /Users/bsnyder/src/hello-world-smx/hello-world-bc-su/target/hello-world-bc-su-1.0-SNAPSHOT-installer.zip to 
/Users/bsnyder/.m2/repository/org/apache/servicemix/samples/helloworld/bc/hello-world-bc-su/1.0-SNAPSHOT/hello-world-bc-su-1.0-SNAPSHOT-installer.zip
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1615 seconds
[INFO] Finished at: MonTue JanMar 1506 2118:4729:51 MST 2007
[INFO] Final Memory: 13M/31M28M
[INFO] ------------------------------------------------------------------------

Your output may look slightly different because Maven will download the required artifacts. Again, the key here is to make sure you see BUILD SUCCESSFUL. This means that the project skeleton created by the archetype was compiled, packaged and tested successfully. Now we just need to add some custom functionality.

...

Before we create any custom functionality, let's first examine some of the items generated by the servicemix-servicebinding-engine component Maven archetype in this simple component we're developing. These classes extend class from either the JBI spec APIs or from the servicemix-common package.

pom.xml - This is the Maven POM] file. This XML file contains all the metadata related to the project so Maven can carry out its functionality.

src/main/java/org/apache/servicemix/samples/bc/MyBootstrap.java - Implements javax.jbi.component.Boostrap which is called by the JBI container as part of the component lifecycle (i.e.g, when the component is installed and uninstalled). This is where you place logic to set up and tear down things when the component is started and stopped. This class is no longer needed.

src/main/java/org/apache/servicemix/samples/bc/MyComponent.java - Extends the DefaultComponent, a convenience class that makes creating JBI components much easier and provides some additional lifecycle management of components for the BC when it's deployed to the JBI container. This class should be fleshed out by overriding methods in the DefaultComponent to configure and initialize the component.

MyConsumerEndpoint.src/main/java/org/apache/servicemix/samples/bc/MyConsumerEndpoint.java - Extends ConsumerEndpoint and implements MyEndpointType. If you'd like to create a BC that fulfills the consumer role, implement the process() method in this class.

src/main/java/org/apache/servicemix/samples/bc/MyEndpointType.java - This class is simply an interface marker for Apache XBean so it can generate an XML schema document.

src/main/java/org/apache/servicemix/samples/bc/MyProviderEndpoint.java - Extends ProviderEndpoint and implements MyEndpointType. If you'd like to create a BC that fulfills the provider role, depending on the MEP being supported, you will need to implement the processInOnly() method or the processInOut() method in this class.

src/main/java/org/apache/servicemix/samples/bc/MyEndpointType.java - This is a marker interface used by XBean so it can generate a XML schema.

src/test/java/org/apache/servicemix/samples/bc/MySpringComponentTest.java - A simple JUnit test class that extends a helper class to make configuring ServiceMix very easy.

src/test/resources/spring.xml - The A very simple and generic ServiceMix configuration file for use with the MySpringComponentTest.

Now that we've gotten a bird's eye view of what we're working with, let's proceed to adding the custom functionality.

...

Before creating custom functionality for the BC, you need to understand the role of a JBI BC. A BC is simply a binding to a service that is external to the JBI normalized message router (NMR) using some type of communications protocol (e.g., FTP, HTTP, JMS, etc.). It's also the responsibility of the BC to handle any conversion of the message format into Normalized Messages a normalized message so that can be sent along to the NMR. This is known as message normalization.

For Just as an example, if we were to create a BC that uses SNMP as the application layer protocol, the SNMP RFC specifies the message format to be used with particular versions of SNMP. It would be the responsibility of the BC to handle not only the communication via the SNMP protocol but also to handling the marshalling of SNMP messages to/from JBI normalized messages. The BC would simply be a binding to a service external to the NMR that speaks SNMP messages via the SNMP protocol.

...

Note

title	Using an IDE

It is at this stage that you should employ the use of an IDE. An IDE can dramatically reduce the work necessary to import clases, override methods and so much more. Because Maven can easily generate project files for Eclipse and or IntelliJ IDEA, either one can be used. Throughout this tutorial, Eclipse will be used. To generate project files for Eclipse, execute the Maven eclipse:eclipse goal from the command line and then import the project into your Eclipse IDE.

...

Consumer - A consumer BC receives requests from an external service a service external to the JBI container and publishes those requests to the NMR.
Provider - A provider BC receives requests from the NMR and publishes those requests to an external servicea service that is external to the JBI container.

This is why both the MyConsumerEndpoint.java and the MyProviderEndpoint.java files exist when using the servicemix-binding-component archetype to create a Maven project for a SU. This way the BC that you're creating can play both either the consumer role and or the provider role or both. For the sake of this tutorial, we will create implement both roles. First letthe provider role. Let's proceed to implement the consumer provider functionality. To do so, open MyConsumerEndpointMyProviderEndpoint.java and let's take a look at he processprocessInOut() method as shown below:

Code Block

publicprotected void processprocessInOut(MessageExchange exchange, NormalizedMessage in, NormalizedMessage out) throws Exception {
    //throw TODO: As we act as a consumer (we just send JBI exchanges)
    // we will receive responses or DONE / ERROR status here
}
new UnsupportedOperationException("Unsupported MEP: " + exchange.getPattern());
}

One important item One important item of note before we get started is that this tutorial will not actually be accessing any services external to the JBI container. The reason for this is that setting up a service external to the JBI container would dramatically increase the complexity of this tutorial. Instead, we will just simulate such functionality by hard-coding some text to be returned.

This The processInOut() method is just a stub that needs to be filled in populated with our custom functionality. Take note of the comment in that method stub stating that this method will send JBI message exchanges and will receive responses or status messages in this method. Based on these comments, we know that we have a few tasks to handle in the implementation of this method. So let's get started. Below is the method body that can be copied and pasted into the method stub to being adding add some custom functionality. Following the display of this method, we will pick apart this method a bit to explain the various pieces of logic:

Code Block

title	The MyConsumerEndpoint.process() Method


public
protected void processprocessInOut(MessageExchange exchange), throwsNormalizedMessage Exceptionin, {
NormalizedMessage out) throws Exception {
	// Grab TODO:the Asin wemessage act
	SourceTransformer assourceTransformer a= consumernew SourceTransformer(we just send JBI exchanges)
    // we will receive responses or DONE / ERROR status here

    // The component acts as a consumer, this means this exchange is received because
    // we sent it to another component.  As it is active, this is either an out or a fault
    // If this component does not create / send exchanges, you may just throw an UnsupportedOperationException
    if (exchange.getRole() == MessageExchange.Role.CONSUMER) {
        // Exchange is finished
        if (exchange.getStatus() == ExchangeStatus.DONE) {
            return;
        // Exchange has been aborted with an exception
        } else if (exchange.getStatus() == ExchangeStatus.ERROR) {
            return;
        // Exchange is active
        } else {
            // Out message
            if (exchange.getMessage("out") != null) {
                // TODO ... handle the response
                exchange.setStatus(ExchangeStatus.DONE);
                getChannel().send(exchange);
            // Fault message
            } else if (exchange.getFault() != null) {
                // TODO ... handle the fault
                exchange.setStatus(ExchangeStatus.DONE);
                getChannel().send(exchange);
            // This is not compliant with the default MEPs
            } else {
                throw new IllegalStateException("Consumer exchange is ACTIVE, but no out or fault is provided");
            }
        }
    // Unknown role
    } else {
        throw new IllegalStateException("Unkown role: " + exchange.getRole());
    }
}

The method above takes into account a number of conditions, so let's go through it all. The first thing to note is that this method will only handle the consumer role. This can be seen the outermost condition as displayed below:

Code Block
if (exchange.getRole() == MessageExchange.Role.CONSUMER) { ... } else { throw new IllegalStateException("Unkown role: " + exchange.getRole()); }

If a request comes through for the provider role, an exception will be thrown. Next, the status of the message exchange is checked to make sure it is not an error or a completed situation:

Code Block
if (exchange.getStatus() == ExchangeStatus.DONE) { return; // Exchange has been aborted with an exception } else if (exchange.getStatus() == ExchangeStatus.ERROR) { return;

The exchange status comes directly from the JBI spec and can one of either ACTIVE, DONE or ERROR. As long a the status is ACTIVE the method proceeds on with the custom functionality. This is shown below but we have not implemented any custom logic yet:

Code Block


} else {
    // Out message
    if (exchange.getMessage("out") != null) {
        // TODO ... handle the response
        exchange.setStatus(ExchangeStatus.DONE);
        getChannel().send(exchange);
    // Fault message
    } else if (exchange.getFault() != null) {
        // TODO ... handle the fault
        exchange.setStatus(ExchangeStatus.DONE);
        getChannel().send(exchange);
    // This is not compliant with the default MEPs
    } else {
        throw new IllegalStateException("Consumer exchange is ACTIVE, but no out or fault is provided");
    }
}

Note

title	Important Information!

This tutorial will not be accessing any services external to the JBI container. Instead, we will just simulate such functionality by hard-coding some text to be returned.

imports

...

);
	DOMSource inMessageXml = (DOMSource) sourceTransformer.toDOMSource(in); 
	
	// Parse out the actual message content 
	CachedXPathAPI xpath = new CachedXPathAPI();
	Node inMessageNode = xpath.selectSingleNode(inMessageXml.getNode(), "/hello");
	String inMessage = inMessageNode.getTextContent(); 
	
	// Create the out message and set it 
	String outMessage = "<hello>Message [" + inMessage + "] contains [" + inMessage.getBytes().length + "] bytes</hello>";
	out.setContent(new StringSource(outMessage));
}

Adding this method will require the import of the following classes:

javax.xml.transform.dom.DOMSource
org.apache.servicemix.jbi.jaxp.SourceTransformer
org.apache.servicemix.jbi.jaxp.StringSource
org.apache.xpath.CachedXPathAPI
org.w3c.dom.Node

All of these classes can be found in either the servicemix-core project or its transitive dependencies. If you're using Eclipse, you can tell Eclipse to automatically import them by selecting Source->Organize Imports.

Note

title	Important Information!

This tutorial will not be accessing any services external to the JBI container. Instead, we will just simulate such functionality by hard-coding some text to be returned.

Now let's move on to testing this component and then we'll compile and test it.

Testing the Hello World Binding Component

Thanks to the Maven archetype, testing the component is very easy because it already created a test. The only change we'll make is to the string being sent by the client code. In the src/test/java directory is the org.apache.servicemix.samples.helloworld.bc.MySpringComponentTest test. Simply open this test and change line #36 from this:

Code Block
me.getInMessage().setContent(new StringSource("<hello>world</hello>"));

to something more meaningful, like this:

Code Block
me.getInMessage().setContent(new StringSource("<hello>Ski Colorado!</hello>"));

Also, add the following block of code to line # 40 below the comment:

Code Block


if (me.getStatus() == ExchangeStatus.ERROR) {
    if (me.getError() != null) { 
        throw me.getError();
    } else {
        fail("Received ERROR status");
    }       
} else if (me.getFault() != null) { 
    fail("Received fault: " + new SourceTransformer().toString(me.getFault().getContent()));
}
System.err.println(new SourceTransformer().toString(me.getOutMessage().getContent()));
client.done(me);

Though there are no asserts in the test, it is more about seeing visual confirmation of the message being output to the console when running the test. So to compile the source and to execute the test, simply run the Maven install goal on the command line from within the hello-world-bc directory like so:

Code Block
$ mvn install

Below is the output that will print to the console:

No Format


[INFO] Scanning for projects...
[INFO] ----------------------------------------------------------------------------
[INFO] Building A custom project
[INFO]    task-segment: [install]
[INFO] ----------------------------------------------------------------------------
[INFO] [xbean:mapping {execution: default}]
Checking: org.apache.servicemix.samples.helloworld.bc.MyComponent
Checking: org.apache.servicemix.samples.helloworld.bc.MyConsumerEndpoint
Checking: org.apache.servicemix.samples.helloworld.bc.MyProviderEndpoint
[INFO] Generating META-INF properties file: 
/Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/META-INF/services/org/apache/xbean/spring/http/org.apache.servicemix.samples.helloworld.bc/1.0 
for namespace: http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating Spring 2.0 handler mapping: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/META-INF/spring.handlers 
for namespace: http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating Spring 2.0 schema mapping: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/META-INF/spring.schemas 
for namespace: http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating HTML documentation file: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/hello-world-bc.xsd.html 
for namespace: http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating XSD file: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/hello-world-bc.xsd 
for namespace: http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] Generating WIKI documentation file: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/hello-world-bc.xsd.wiki 
for namespace: http://org.apache.servicemix.samples.helloworld.bc/1.0
[INFO] ...done.
[INFO] [jbi:generate-jbi-component-descriptor]
[INFO] Generating jbi.xml
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Nothing to compile - all classes are up to date
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:testCompile]
[INFO] Nothing to compile - all classes are up to date
[INFO] [surefire:test]
[INFO] Surefire report directory: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/surefire-reports

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running org.apache.servicemix.samples.helloworld.bc.MySpringComponentTest
log4j:WARN No appenders could be found for logger (org.springframework.core.CollectionFactory).
log4j:WARN Please initialize the log4j system properly.
<?xml version="1.0" encoding="UTF-8"?>
<hello>Message [Ski Colorado!] contains [13] bytes</hello>
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.635 sec

Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] [jar:jar]
[INFO] Building jar: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/hello-world-bc-1.0-SNAPSHOT.jar
[INFO] [jbi:jbi-component]
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[WARNING] Attempting to build MavenProject instance for Artifact of type: jar; constructing POM artifact instead.
[INFO] Generating installer /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/hello-world-bc-1.0-SNAPSHOT-installer.zip
[INFO] Building jar: /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/hello-world-bc-1.0-SNAPSHOT-installer.zip
[INFO] [install:install]
[INFO] Installing /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/hello-world-bc-1.0-SNAPSHOT.jar to 
/Users/bsnyder/.m2/repository/org/apache/servicemix/samples/helloworld/bc/hello-world-bc/1.0-SNAPSHOT/hello-world-bc-1.0-SNAPSHOT.jar
[INFO] Installing /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/hello-world-bc.xsd to 
/Users/bsnyder/.m2/repository/org/apache/servicemix/samples/helloworld/bc/hello-world-bc/1.0-SNAPSHOT/hello-world-bc-1.0-SNAPSHOT.xsd
[INFO] Installing /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/xbean/hello-world-bc.xsd.html to 
/Users/bsnyder/.m2/repository/org/apache/servicemix/samples/helloworld/bc/hello-world-bc/1.0-SNAPSHOT/hello-world-bc-1.0-SNAPSHOT-schema.html
[INFO] Installing /Users/bsnyder/src/hello-world-smx/hello-world-bc/target/hello-world-bc-1.0-SNAPSHOT-installer.zip to 
/Users/bsnyder/.m2/repository/org/apache/servicemix/samples/helloworld/bc/hello-world-bc/1.0-SNAPSHOT/hello-world-bc-1.0-SNAPSHOT-installer.zip
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 15 seconds
[INFO] Finished at: Tue Mar 06 19:59:50 MST 2007
[INFO] Final Memory: 13M/25M
[INFO] ------------------------------------------------------------------------

Notice that not only do we see that the build was successful, but also note the text in the output above that was printed by the test:

<?xml version="1.0" encoding="UTF-8"?><hello>Message [Ski Colorado!] contains [13] bytes</hello>

This is the message we were expecting to be output from the test. So if you see this, you just wrote a JBI component and tested your first JBI BC successfully.

Now let's look at how this component is deployed to ServiceMix.

Deploying the BC to ServiceMix

Thanks to Maven, this BC has already been packaged properly to be deployed to ServiceMix. Just take a look in the target directory of the project and you will see the zip file:

Panel

$ ls -l ./target | awk {'print $9'}

classes
hello-world-bc-1.0-SNAPSHOT-installer
hello-world-bc-1.0-SNAPSHOT-installer.zip
hello-world-bc-1.0-SNAPSHOT.jar
jbi.xml
surefire-reports
test-classes
xbean

This zip file contains everything needed to deploy the BC to ServiceMix. This can be done by simply copying the zip file to the ServiceMix component installation directory. By default, this is a directory named install. However, this does not complete the deployment of the BC.

In order to actually make use of the BC, you will need to create a JBI service unit (SU) that uses the BC. A SU is really just a configuration for a JBI component to tell it how to behave. Just like all the JBI components that come with ServiceMix, in order to use one, you will need to create a SU that configures it, telling the JBI container how the component should behave. But the situation with this component is a bit different. Because the Hello World BC contains a hard-coded message, there's not much configuration to be done other than just stating that it should be used. So let's create the SU for the Hello World BC and then we'll move on to testing it.

Creating a Hello World BC Service Unit

This is a work in progress

This is a work in progress. I will finish this up very soon.

Testing the Hello World Binding Component

Thanks to the archetype, testing the component is very easy because it already created a test. The only change we'll make is to the string being sent by the client code. In the src/test/java directory is the org.apache.servicemix.samples.helloworld.bc.MySpringComponentTest test. Simply open this test and change line #36 from this:

Code Block
me.getInMessage().setContent(new StringSource("<hello>world</hello>"));

to something more meaningful, like this:

Code Block
me.getInMessage().setContent(new StringSource("<hello>Ski Colorado!</hello>"));

To execute the test, simply run the Maven install goal from within the hello-world-bc-su directory like so:

Code Block
$ mvn install

Below is the output that will print to the console:

...

Wiki MarkupNotice that not only do we see that the build was successful, but also note the text in the output above that was printed by the test (*<hello>Hello World! Message \[<hello>Ski Colorado!</hello>\] contains \[28\] bytes.</hello>*). This is the message we were expecting to be output from the test. So if you see this, you just wrote a JBI component and tested it successfully. Now this SU needs to be wrapped in a SA so it can be deployed to the JBI container.

Wrapping the Service Unit in a Service Assembly

...

Code Block

$ pwd
/Users/bsnyder/src/hello-world-smx/hello-world-bc-su
$ cd .. 
$ mvn archetype:create \
    -DarchetypeGroupId=org.apache.servicemix.tooling \
    -DarchetypeArtifactId=servicemix-service-assembly \
    -DarchetypeVersion=3.2.1-incubating-SNAPSHOT \
    -DgroupId=org.apache.servicemix.samples.helloworld \
    -DartifactId=hello-world-sa

...

No Format

[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ----------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO]    task-segment: [archetype:create] (aggregator-style)
[INFO] ----------------------------------------------------------------------------
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] ************************************************************** 
[INFO] Starting Jakarta Velocity v1.4
[INFO] RuntimeInstance initializing.
[INFO] Default Properties File: org/apache/velocity/runtime/defaults/velocity.properties
[INFO] Default ResourceManager initializing. (class org.apache.velocity.runtime.resource.ResourceManagerImpl)
[INFO] Resource Loader Instantiated: org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader
[INFO] ClasspathResourceLoader : initialization starting.
[INFO] ClasspathResourceLoader : initialization complete.
[INFO] ResourceCache : initialized. (class org.apache.velocity.runtime.resource.ResourceCacheImpl)
[INFO] Default ResourceManager initialization complete.
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Literal
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Macro
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Parse
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Include
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Foreach
[INFO] Created: 20 parsers.
[INFO] Velocimacro : initialization starting.
[INFO] Velocimacro : adding VMs from VM library template : VM_global_library.vm
[ERROR] ResourceManager : unable to find resource 'VM_global_library.vm' in any resource loader.
[INFO] Velocimacro : error using  VM library template VM_global_library.vm : org.apache.velocity.exception.ResourceNotFoundException: 
Unable to find resource 'VM_global_library.vm'
[INFO] Velocimacro :  VM library template macro registration complete.
[INFO] Velocimacro : allowInline = true : VMs can be defined inline in templates
[INFO] Velocimacro : allowInlineToOverride = false : VMs defined inline may NOT replace previous VM definitions
[INFO] Velocimacro : allowInlineLocal = false : VMs defined inline will be  global in scope if allowed.
[INFO] Velocimacro : initialization complete.
[INFO] Velocity successfully started.
[INFO] [archetype:create]
[INFO] Defaulting package to group ID: org.apache.servicemix.samples.helloworld
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating Archetype: servicemix-service-assembly:3.2.1-incubating-SNAPSHOT
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: org.apache.servicemix.samples.helloworld
[INFO] Parameter: packageName, Value: org.apache.servicemix.samples.helloworld
[INFO] Parameter: basedir, Value: /Users/bsnyder/src/hello-world-smx
[INFO] Parameter: package, Value: org.apache.servicemix.samples.helloworld
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: artifactId, Value: hello-world-sa
[WARNING] org.apache.velocity.runtime.exception.ReferenceException: reference : template = archetype-resources/pom.xml [line 71,column 18] : 
${servicemix-version} is not a valid reference.
[INFO] ********************* End of debug info from resources from generated POM ***********************
[INFO] Archetype created in dir: /Users/bsnyder/src/hello-world-smx/hello-world-sa
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Fri Jan 05 23:40:32 MST 2007
[INFO] Final Memory: 4M/8M
[INFO] ------------------------------------------------------------------------

...

Code Block
$ ls hello-world-sa hello-world-bc-su

If you see the above directories, proceed to the next step below. If instead you see the BUILD FAILED output, you'll need to analyze the rest of the output to troubleshoot the issue. Assistance with any issue you might experience is available from the ServiceMix community via the ServiceMix mailing lists archive.

Now that we have a project for the SA, we need to edit the POM so that the project depends upon the JBI component we created above. This can be done by editing the POM for the SA to add a dependency upon the hello-world-bc-su as listed below:

Code Block
<dependency> <groupId>org.apache.servicemix.samples.helloworld.bc</groupId> <artifactId>hello-world-bc-su<bc</artifactId> <version>1.0-SNAPSHOT</version> </dependency>

...

Now that we have created the SU and SA projects, a top level pom.xml must be manually created and made aware of each subproject. This will allow all the projects to be built automatically without having to build each project in order manually. Maven will discover all the projects and build them in the proper order. In the hello-world-bc-susmx directory, create a file named pom.xml containing the following content:

Code Block

<?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 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>org.apache.servicemix.samples.helloworld</groupId>
  <artifactId>hello-world-smx</artifactId>
  <packaging>pom</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>Hello World JBI Component</name>

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

</project>

...

Code Block
$ ls hello-world-sa hello-world-bc-su pom.xml

All projects can now be built using the following command on the command-line from the top level hello-world-smx directory:

...

Edit hello-world-sa/pom.xml and replace <name>A custom project</name> with <name>Hello World Service Assembly</name>
Edit hello-world-bc-su/pom.xml and replace <name>A custom project</name> with <name>Hello World BC Service Unit</name>

...

Note

title	TODO

The default implementation of the component accepts InOut MEPs (ADD
LINK TO FURTHER READING CONCERNING MEPs) and return the input content
as the out message. This is already nearly what we want.

OUTLINE for further work:

Get Messages
read Messagesunmigrated-wiki-markup
count the bytes
Maybe easiest by XSLT endpoint (can be used to apply an XSLT stylesheet to the incoming exchange and will return the transformed result as the output message.)
see \ [ servicemix-saxon\|servicemix-saxon\]
send a message back
Configure SA so that the example receives messages
create & populate
C:\hello-world-SE-SU-SA\hello-world-SU\src\main\resources\servicemix.xml
as MyDeployer extends AbstractXBeanDeployer create xbean.xml for SU
make something send messages (eg quartz timer, HTTP POST,...) and dump the answer (eg TraceComponent, FireWriter, EIP,...)
add a chapter what user may do now / "how to continue when having the working example"

Classpath for SU to include manually till v3.1, see mail

manually editing http://goopen.org/confluence/display/SM/Working+with+Service+Units
manually editing http://www.servicemix.org/site/working-with-service-assemblies.html
use the SU archetype like in http://www.servicemix.org/site/creating-a-protocol-bridge.html
use the SA archetype like in http://www.servicemix.org/site/creating-a-protocol-bridge.html

INS When to use this JBI Component
INS Using the component that you created

provide exact position in the SVN!
/samples/hello-world-SE-SU-SA/
integrate from SVN source like it is done at Configuration at http://www.servicemix.org/site/visualisation.html

maybe moving the content of overlapping existing docus to this new tut and - where appropriate - delete the old ones (only leaving a redirect).
http://www.servicemix.org/site/notes-on-creating-jbi-component-using-maven2.html version14
http://www.servicemix.org/site/creating-a-standard-jbi-component.html version26
are already fully incorporated in the mentioned versions, so delete content and point from there to here (and delete note at the very top)

This shall already include everything stated at
http://www.servicemix.org/site/maven-jbi-plugin.html#MavenJBIplugin-GettingStarted
and
http://www.servicemix.org/site/working-with-components.html

provide additional reading
Creating a protocol bridge.for a "bigger" example
The examples page lists examples providing more information, showing further possibilities and components.

...

Child pages

Versions Compared

Old Version 6

New Version Current

Key

Creating a Hello World JBI Binding Component

Prerequisites

Testing the Hello World Binding Component

Deploying the BC to ServiceMix

Creating a Hello World BC Service Unit

Testing the Hello World Binding Component

Wrapping the Service Unit in a Service Assembly

Child pages

Page History

Versions Compared

Old Version 6

New Version Current

Key

Creating a Hello World JBI Binding Component

Prerequisites

Testing the Hello World Binding Component

Deploying the BC to ServiceMix

Creating a Hello World BC Service Unit

Testing the Hello World Binding Component

Wrapping the Service Unit in a Service Assembly