Deploying Lightweight Components Tutorial

Introduction

Please see What is a Lightweight Component for a good explanation of the different types of JBI components.

As explained in "What is a Lightweight Component" there are two main use cases for ServiceMix:
1. As a full JBI container - using SMX as a full JBI container in which you can deploy Service Assemblies and standard JBI components. And you may also deploy lightweight components in this mode - they must be deployed to the servicemix-lwcontainer.

2. Embedded - this is a static configuration used mainly for testing or perhaps for encapsulating ServiceMix into a web application. This uses the servicemix.xml file to configure components thare are only deployed when ServiceMix is started, not at runtime. You cannot deploy service units to this type of ServiceMix configuration at runtime. You would have to shutdown, reconfigure and then restart.

This tutorial focuses on deploying lightweight components to the servicemix-lwcontainer.

First some background. A JBI component is either a service engine (SE) or a binding component (BC). These terms are defined in Introduction to ESB and/or the Glossary. A BC/SE is installed on ServiceMix by copying it into the install directory which resides under the ServiceMix home directory. So what gets deployed? JBI components can act as containers themselves. Artifacts can be deployed to an existing BC or SE to add more functionality to that component. Adding artifacts to installed components is called deployment. To deploy artifacts to a component the artifacts can be placed in the deploy directory under the ServiceMix home directory. Another term that is important to know is service assembly. A service assembly is a collection of deployment artifacts and metadata. A service unit is a single deployment artifact which is deployed on a single component. For deployment to happen, the artifacts must be in a very specific format, which is specified in the JSR 208 specification. Please see chapter 6 of the JSR 208 specification for more details. In addition to deploying components, ServiceMix allows servicemix.xml files to be deployed in a similar method to deploying a component.

Manually Creating a Service Unit and Service Assembly

We are going to use the existing ServiceMix Loan Broker example, which can be found Loan Broker Demo for ServiceMix, as the basis for this discussion.

There are several things to note about this example. First of all it is meant to be run stand-alone. Specifically, when running this example, ServiceMix will be started for you, then the loan broker is deployed and run. Therefore, there is a servicemix.xml file in the loan-broker directory. This servicemix.xml file is used for configuring the ServiceMix JBI container upon ServiceMix starting up. This is not to be confused with the servicemix.xml located in the loan-broker\src\su directory. The SU servicemix.xml file is used to configure the servicemix-lwcontainer. Every service unit must contain some kind of configuration file. For example, if we were creating a service unit for the BPEL service engine there would also be a configuration file, but it would not be a servicemix.xml file, such as the one used for configuring the lightweight container.

NOTE: There are two major phases to creating a lightweight component that is ready for deployment: one, is the development phase of the component, which includes coding and compiling and building the code, the second phase is creating the packaging necessary for the component to be installed onto the JBI container. This document will focus on the second part. Any steps relating to compilation are simply performed here to get us to the point that we can assemble the component into a JBI service assembly or service unit.

In general there are three steps to creating the SA and deploying it to the ServiceMix container.

Create the service units.
Create the service assemblies.
Deploy the service assemblies to the JBI container.

The following provides details on each general step using an example to illustrate.

Although we are not covering the component development phase in this case we do need to perform a compile. We will use Apache Ant to compile the loan-broker demo components:

cd [servicemix_dir]\examples\loan-broker
ant build-components

This will compile the Java code and put the Java class files into the [servicemix_dir]\examples\loan-broker\build\loanbroker\components directory.

Now we are ready to assemble the lightweight components together. The loan broker demo supplies us with a build.xml file (which was used in the compile step above). The build.xml contains targets for creating service units and service assemblies. If you run "ant setup" a service unit and service assembly will automatically be created. Ultimately, this is what you will want to do, however, the following procedure gives the manual steps for creating a service unit and service assembly, to facilitate in understanding the contents of a SUs and SAs.

First create the service unit. The service unit is a ZIP file that will contain your application's Java class files and the servicemix.xml configuration file. For example:
1. Use a ZIP compression tool, such as Winzip or gzip to create a zip file containing the classes in [servicemix_dir]\examples\loan-broker\build\loanbroker\components and the servicemix.xml file which can be found in [servicemix_dir]\src\su. The zip file name is arbitrary, but to match the example call it {{loanbroker-su.zip.
2. Put the loanbroker-su.zip file in the [servicemix_dir]\examples\loan-broker\build directory for later use. Note: you may store the zip file anywhere.
  
  The above two steps can be done automatically using the ant script: "ant build-su". If you look in the build.xml file you will see the build-su target does exactly what we just did manually.
Create the Service Assembly.

--------------------------------------------------------------------------------------

Two jar files must be created. These jar files will be copied into the ServiceMix deploy directory. The first jar file will contain the service component jbi.xml file. When this is copied to the deploy directory it deploys the ServiceMixComponent component. The second jar file will contain the service assembly and the jbi.xml descriptor file. When it is copied to the deploy directory of ServiceMix it deploys the service unit (Quartz) to the previously deployed component, ServiceMixComponent.

The file service component jbi.xml file should contain:

<jbi xmlns="http://java.sun.com/xml/ns/jbi" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://java.sun.com/xml/ns/jbi" 
     version="1.0">

  <component type="service-engine">
    <identification>
      <name>servicemix-component</name>
      <description>A ServiceMix Component that can be used to deploy servicemix.xml artifacts.</description>
    </identification>
    <component-class-name>org.servicemix.components.servicemix.ServiceMixComponent</component-class-name>
    <component-class-path/>
  </component>

</jbi>

Put jbi.xml in an empty META-INF directory and put that into a jar file:

mkdir META-INF
copy jbi.xml META-INF
jar cvf service-component.jar *

Create a zip file of the servicemix.xml file you modified above. The zip file should contain the servicemix.xml file and it should be called su1.zip to match the name it is called in the jbi.xml file. See the artifacts-name tag in the jbi.xml file for the name of the zip file.

Create the second jar file--this is the service assembly jar file. It will contain another jbi.xml file that is used for the service assembly and it will also contain the zip file, su1.zip in the following structure:
The service assembly jbi.xml should be match the following:

<jbi xmlns="http://java.sun.com/xml/ns/jbi" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://java.sun.com/xml/ns/jbi" 
     version="1.0">
     
   <service-assembly>
     <identification>
       <name>AU_1</name>
       <description>Sample AU</description>
     </identification>
     <service-unit>
       <identification>
         <name>SU_1</name>
         <description>Sample</description>
       </identification>
       <target>
         <artifacts-zip>su1.zip</artifacts-zip>
         <component-name>servicemix-component</component-name>
       </target>
     </service-unit>
    </service-assembly>
    
</jbi>

Copy the jbi.xml file to an empty META-INF directory, then create the jar file:

In a directory which contains these files, create the jar file:
  META-INF/jbi.xml
  su1.zip

jar cvf sa_quartz.jar *

Deploy the two jar files. Copy service_component.jar and sa_quartz.jar to [servicemix_src_install_dir]\assembly\target\servicemix-2.0.\bin\servicemix-2.0.2\deploy. This can be done while ServiceMix is running or while ServiceMix is not running. In the second case, run ServiceMix to see the deployment. Output will be similar to:

The JBI spec describes in detail how to create a valid JBI deployment unit. In essence, it is a jar file with a META-INF/jbi.xml with other resource jars inside it. Please see Deployment Units for more information.

Child pages

Introduction

Manually Creating a Service Unit and Service Assembly

Related Documentation