I’ve recently been investigating the use of the JBI4Corba JBI Binding Component with the Apache ServiceMix Enterprise Service Bus. JBI4Corba permits a JBI compliant ESB to call corba code running outside of the bus (the consumer scenario) and to external code to call endpoints published on the bus via corba (the provider scenario).

Why is this useful? Well, there is quite a lot of corba code out there but new applications are not generally written to use corba technologies. JBI4Corba permits you to make services offered by legacy corba code available to new applications and enables existing corba code to call services published on the ESB. This means you don’t have to rewrite code that uses corba in order to integrate it into an SOA architecture.

This post will show you how to get started with JBI4Corba and Apache ServiceMix, using an example taken from the JBI4Corba integration tests. The idea is to show from “first principles” how to arrive at a simple JBI4Corba solution, which is something that I have failed to find myself on the web.

In this example, we have a simple ‘legacy’ corba interface which just has one method that echos an input parameter String back to the caller. This interface is implemented in a Java corba Servant. We wish to make this corba interface available as a web service and call it using a standard HTTP client - which knows nothing about corba. The diagram below (taken from the JBI4Corba website) indicates how the various components will interact in this example:

To get started, download this code from here and unzip it to a folder on your local machine. This example requires you to have Maven and Apache Servicemix installed on your machine. I have versions 2.09 and 3.3.1 of these two products, respectively.

The Corba Code

Once you have downloaded the code, run

mvn install

in the root directory in which you unzipped the code. The provider-simple-servant project contains the existing Corba code. In src/main/idl, you will find the Corba IDL file which expresses the Corba interfaces. In this case, it is a very simple interface:

module it{
	module imolinfo{
		module jbi4corba{
			module test{
				module testprovidersimple{
						interface Echo {
							string echo(in string msg);
						};
				};
			};
		};
	};
};

In this project, we use the Maven idlj plugin to generate the Java classes from this Corba IDL file. Below is the pom.xml configuration:

      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>idlj-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <debug>true</debug>
          <sources>
            <source>
              <includes>
                <include>Echo.idl</include>
              </includes>
			  <emitStubs>true</emitStubs>
              <emitSkeletons>true</emitSkeletons>
              <compatible>false</compatible>
            </source>
		</sources>
	    </configuration>        
      </plugin>

When you run the maven generate-sources goal or a later goal (such as compile or install), idlj generates the Corba Java classes and puts them in the /target/generated-sources/idl directory, which is on the classpath.

The /src/main/java/it/imolinfo/jbi4corba/test/servant/testprovidersimple/EchoSimpleImpl.java class is a Corba Servant that provides the behaviour for the Echo Corba interface. To run it, we must first be running the Sun Corba ORB daemon, which depends on your OS. Unix:

  orbd -ORBInitialPort 1050 -ORBInitialHost localhost&

Windows:

  start orbd -ORBInitialPort 1050 -ORBInitialHost localhost

Once this is running ok, we run the Echo server by executing the following Maven command in the /provider-simple-servant directory:

mvn exec:java -Dexec.mainClass="it.imolinfo.jbi4corba.test.servant.testprovidersimple.EchoSimpleImpl" -Dexec.args="sunorb.properties"

In another command window, execute the following in the same /provider-simple-servant directory to run the EchoClient that tests that the server is working ok:

mvn exec:java -Dexec.mainClass="it.imolinfo.jbi4corba.test.servant.testprovidersimple.EchoClient" -Dexec.args="-ORBInitialPort 1050 -ORBInitialHost localhost"

When you run the client, you should see output like that below:

.....
[INFO] [exec:java]
Obtained a handle on server object: IOR:000000000000003b49444c3a69742f696d6f6c696e666f2f6a626934636f7262612f746573742f7465737470726f766964657273696d706c652f4563686f3a312e300000000000010000000000000082000102000000000a3132372e302e312e3100881a00000031afabcb0000000020cd9636e200000001000000000000000100000008526f6f74504f410000000008000000010000000014000000000000020000000100000020000000000001000100000002050100010001002000010109000000010001010000000026000000020002
  result: test
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
....

If not, your Echo server is not correctly working and you need to fix this before continuing with the rest of the post.

IMPORTANT: Leave the Echo server running - we will need it later on in the post.

Introducing JBI4Corba

Now that we know that the Corba code is working ok, we can create a JBI service unit that uses JBI4Corba to publish this Corba application on the ServiceMix ESB. The configuration to do this is in the provider-simple-jbi4corba-provider project. Unfortunately, there do not seem to be any Maven archetypes for JBI4Corba projects so we won’t look at how to create this project completely from scratch, but we will see the important steps.

You must generate a WSDL that describes your Corba interface so that it can be used with JBI4Corba. This can be done with the IDL to WSDL tool. Download this tool from here, and modify the shell/batch script that is in the /bin directory (if necessary) to point to your JDK installation. Once you have it installed, run the following command in the /provider-simple-jbi4corba-provider/src/main/resources directory, substituting [path-to] for the path where you installed IDL2WSDLTool:

 /[path-to]/bin/IDL2WSDLTool Echo.idl jbi4corba.properties

This generates the Echo.wsdl file which describes the Corba IDL in a WSDL format that JBI4Corba understands. The generation of this file is a bit of a pain in the neck to be honest. You have to generate a properties file which describes the IDL file, such as provider-simple-jbi4corba-provider/src/main/resources/jbi4corba.properties:

InterfaceCount=1
Interface0.FileName=Echo.wsdl
Interface0.IDLInterfaceName=Echo
Interface0.Address=Echo
Interface0.LocalizationType=NameService
Interface0.ORBPropertiesCount=3
Interface0.ORBPropertyName0=org.omg.CORBA.ORBInitialPort
Interface0.ORBPropertyValue0=1050
Interface0.ORBPropertyName1=org.omg.CORBA.ORBClass
Interface0.ORBPropertyValue1=com.sun.corba.ee.impl.orb.ORBImpl
Interface0.ORBPropertyName2=org.omg.CORBA.ORBInitialHost
Interface0.ORBPropertyValue2=localhost

This file states that there is 1 interface in the IDL file, that it is called “Echo” and that it should be published at address “Echo” in the NameService. The WSDL file generated is Echo.wsdl.

Note that the jbi-services.xml file in /provider-simple-jbi4corba-provider/src/main/resources makes reference to the target namespace (targetNamespace=”http://it.imolinfo.jbi4corba.test.testprovidersimple.Echo”) declared at the top of the Echo.wsdl file, as well as other attrributes contained within that file.

  <services binding-component="true" xmlns="http://java.sun.com/xml/ns/jbi" 
  xmlns:ns0="http://it.imolinfo.jbi4corba.test.testprovidersimple.Echo">
 
    <provides interface-name="ns0:Echo" 
              service-name="ns0:Echo" 
              endpoint-name="EchoCorbaPort"/>
  </services>

Once you have generated the WSDL file, run

mvn install

in the root of the provider-simple-jbi4corba-provider project to install the final version.

Accessing the Corba code via HTTP Web services

Now we will create a JBI Service Unit that publishes the Endpoint created in the JBI4Corba Service Unit via HTTP web services. To do this, we will use the Apache Servicemix maven archetypes which make it much easier to create JBI service unit projects since they auto-generate the relevant structure and file and create the JBI XML descriptor automatically at runtime. In the directory to which you downloaded the source code, run the following:

mvn archetype:create \
    -DarchetypeGroupId=org.apache.servicemix.tooling \
    -DarchetypeArtifactId=servicemix-http-consumer-service-unit \
    -DgroupId=it.imolinfo.jbi4corba.test-provider-simple \
    -DartifactId=provider-simple-http-consumer \
    -DremoteRepositories=http://people.apache.org/repo/m2-incubating-repository

You should now have a new project called “provider-simple-http-consumer”. Edit the provider-simple-http-consumer/src/main/resources/xbean.xml file and replace the contents with the following code:

<?xml version="1.0"?>
<beans
  xmlns:http="http://servicemix.apache.org/http/1.0"
  xmlns:jbi4corba-test="http://it.imolinfo.jbi4corba.test.testprovidersimple.Echo">      
  <http:endpoint
    service="jbi4corba-test:Echo"
    endpoint="EchoCorbaPort"
    interfaceName="jbi4corba-test:Echo"
    role="consumer"
    locationURI="http://localhost:8192/Service/test-provider-simple/"
    defaultMep="http://www.w3.org/2004/08/wsdl/in-out"
    soap="true" />
</beans>

This publishes a new HTTP web service at http://localhost:8192/Service/test-provider-simple/ which calls out to the jbi4corba-test:Echo Endpoint established by the provider-simple-jbi4corba-provider JBI service unit.

In the provider-simple-http-consumer/src/main/resources directory, create a new file called EchoSimple.wsdl and paste in the following content:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="EchoSimple" targetNamespace="urn:jbi4corba/test-provider-simple" xmlns:tns="http://it.imolinfo.jbi4corba.test.testprovidersimple.Echo" xmlns:imolacorba="uri://schemas.imola.it/jbi/wsdl-extensions/corba/" xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <wsdl:types>
    <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://it.imolinfo.jbi4corba.test.testprovidersimple.Echo" xmlns="http://it.imolinfo.jbi4corba.test.testprovidersimple.Echo" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 
   <xs:element name="echo">
        <xs:complexType>
            <xs:sequence>
                <xs:element minOccurs="0" name="msg" type="xs:string"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="echoResponse">
        <xs:complexType>
            <xs:sequence>
                <xs:element minOccurs="0" name="return" type="xs:string"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>
  </wsdl:types>
  <wsdl:message name="echo">
    <wsdl:part name="parameters" element="tns:echo">
    </wsdl:part>
  </wsdl:message>
  <wsdl:message name="echoResponse">
    <wsdl:part name="parameters" element="tns:echoResponse">
    </wsdl:part>
  </wsdl:message>
  <wsdl:portType name="EchoSimple">
    <wsdl:operation name="echo">
      <wsdl:input name="echo" message="tns:echo">
    </wsdl:input>
      <wsdl:output name="echoResponse" message="tns:echoResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
 <wsdl:binding name="EchoSimpleCorbaBinding" type="tns:EchoSimple">
 
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
    <wsdl:operation name="echo">
      <soap:operation/>
      <wsdl:input name="echo">
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="echoResponse">
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="EchoSimple">
    <wsdl:port name="EchoSimpleCorbaPort" binding="tns:EchoSimpleCorbaBinding">
      <soap:address location="http://localhost:8192/Service/test-provider-simple/"/>
    </wsdl:port>
  </wsdl:service>
<plnk:partnerLinkType name="EchoSimple">
<plnk:role name="EchoSimplePortTypeRole" portType="tns:EchoSimple"/>
</plnk:partnerLinkType>
</wsdl:definitions>

Run

mvn install

in the root of the project to create and install the JBI Service unit.

Creating the Service Assembly

A JBI Service assembly is a way of packaging up JBI Service units. We will create the Service Assembly maven project using another Servicemix archetype. Run the following in the directory to which you downloaded the source code:

mvn archetype:create \
    -DarchetypeGroupId=org.apache.servicemix.tooling \
    -DarchetypeArtifactId=servicemix-service-assembly \
    -DgroupId=it.imolinfo.jbi4corba.test-provider-simple \
    -DartifactId=provider-simple-service-assembly \
    -DremoteRepositories=http://people.apache.org/repo/m2-incubating-repository

This should create a new maven sub-project called provider-simple-service-assembly which just contains a pom.xml file. Edit this file and remove the Junit dependency. Add the following instead:

    <dependency>
      <groupId>${pom.groupId}</groupId>
      <artifactId>provider-simple-jbi4corba-provider</artifactId>
      <version>${pom.version}</version>
    </dependency>
    <dependency>
      <groupId>${pom.groupId}</groupId>
      <artifactId>provider-simple-http-consumer</artifactId>
      <version>${pom.version}</version>
    </dependency>

Run mvn install in the service assembly project directory and a new file should be created in the provider-simple-service-assembly/target directory called provider-simple-service-assembly-1.0-SNAPSHOT.jar. This is the file we will deploy to ServiceMix.

Deploying to ServiceMix

Download and install Apache ServiceMix 3.3.1 if you have not already done so. I will refer to the installation directory as $SERVICEMIX_HOME. Download Jbi4Corba and copy it into $SERVICEMIX_HOME/hotdeploy directory. Ensure you have a Java JDK installed. Copy the $JDK_HOME/lib/tools.jar file to $SERVICEMIX_HOME/lib/optional.

Start up ServiceMix by running the servicemix or servicemix.bat (depending on your OS) file in the $SERVICEMIX_HOME/bin folder.

Ensure that you still have the EchoServer running from earlier in this post. Now, copy the provider-simple-service-assembly/target/provider-simple-service-assembly-1.0-SNAPSHOT.jar file to the $SERVICEMIX_HOME/hotdeploy directory. You should see a whole bunch of messages on the ServiceMix console but hopefully no (serious) errors.

To test if the service assembly deployed ok, go to http://localhost:8192/Service/test-provider-simple/main.wsdl and you should see the WSDL descriptor for the HTTP web service. Save this WSDL file somewhere on your local machine.

Testing using SoapUI

SoapUI is a very effective tool for testing web services. If you have not already installed it, download and install the standard (free) edition and run it.

Select File > New soapUI project. Enter “test jbi4corba” as the project name and for the Initial WSDL/WADL field, browse for the WSDL file you saved from http://localhost:8192/Service/test-provider-simple/main.wsdl. Ensure the “create requests” option is ticked and click ok. Keep clicking OK till soapUI creates a TestSuite for you. Save the project.

Right-click on the “EchoCorbaPortBinding Test Suite” element. Choose “Launch Test Runner” and select “Launch” from the dialog. The test should complete successfully and you should see the message “message received: ?” in the debug output from the Corba Echo Server, proving that the message is making its way to the Corba code.

Conclusion

You can download the finished code from this article here.

With the aid of the ServiceMix Maven archetypes and a bit of knowledge of JBI4Corba, you can make services offered by legacy Corba applications available to modern Service Oriented Architecture components via an ESB, with all of the advantages that gives.

Check out the rest of the JBI4Corba integration tests, available here for more complex examples.