Page History

...

This document discusses how to package and deploy a lightweight component to the ServiceMix lightweight container (servicemix-lwcontainer). The ServiceMix lightweight container is a service engine JBI component whose purpose is to allow lightweight components (POJOs) to be deployed similarily to a standard JBI component would be.at runtime rather than only deploying them statically via the servicemix.xml file. 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 ServiceMix 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. Just a brief 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. A 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.

...

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.

...

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

Wiki MarkupThis 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.

1. 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:
   file. The service unit can also contain a jbi.xml which provides information about services statically provided and consumed. In ServiceMix it is optional to include this file. In the case of our example, we have not included it.
   
   
   1. Use a ZIP compression tool, such as Winzip or gzip to create a zip file containing the classes in [servicemix_dir Wiki MarkupUse 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 it is used in the Service Assembly's {{jbi.xml}} file, so to match the example call it {{loanbroker-su.zip}}. \\
      
   2. Wiki MarkupPut 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
      
      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. \\
      
      
2. Create the Service Assembly. A service assembly is a zip file containing one or more service units and a jbi.xml file. The jbi.xml file must be in the META-INF directory. you may also include other files in the META-INF directory. The ZIP file directory structure for our example looks like this:

   Code Block
   loanbroker-su.zip META-INF\ jbi.xml LICENSE.txt DISCLAIMER.txt

   
   
   The jbi.xml looks like this: unmigrated-wiki-markup

   Code Block
   <?xml version="1.0" encoding="UTF-8"?> <jbi xmlns="http://java.sun.com/xml/ns/jbi" version="1.0"> <service-assembly> <identification> <name>loanbroker</name> <description>LoanBroker Service Assembly</description> </identification> <service-unit> <identification> <name>loanbroker</name> <description>LoanBroker Service Unit</description> </identification> <target> <artifacts-zip>loanbroker-su.zip</artifacts-zip> <component-name>servicemix-lwcontainer</component-name> </target> </service-unit> </service-assembly> </jbi>
   \\ \\

   
   
   The interesting thing to note is that the {{jbi.xml}} file tells the JBI container what service units are in the service assembly and where to deploy them. There is only one service unit in our example, which is "loanbroker" (see the {{artifacts-name}} tag) and the component to which it will be deployed is {{servicemix-lwcontainer}} (see the <component-name> tag). There could be multiple service units in a service assembly and they would each be included in the {{jbi.xml}} file with the same type of information for each. \\
   Create the service assembly ZIP file and include the {{loanbroker-su.zip}} file and the {{META-INF\jbi.xml}} directory and file in it. To remain consistent with our example, call the zip file {{loanbroker-sa.zip}}. \\ Put the {{.
   Put the loanbroker-sa.zip}} file in the {{\[servicemix_dir\]\examples\loan-broker\build}} directory for later use. Note: in a real world application you may store the zip file anywhere.
   
3. The final step is to deploy the service assembly to the JBI container. To do this copy the loanbroker-sa.zip file to the [servicemix_dir]\deploy directory. If ServiceMix is already running it will detect the file is there and start it. If ServiceMix is not running, start it to see the example start running:

   Code Block
   ..\..\bin\servicemix servicemix.xml store the zip file anywhere.

Related Documentation

The JBI spec describes in detail how to create a valid JBI deployment unit. Please see JSR 208.

Spring Related information

Inside the servicemix.xml file, the ability to import the common beans using the following:

<import resource="classpath:otherBeans.xml" />

The resource is a SpringResource so the following also works:

<import resource="file:path/to/file/jmx.xml" />

if you run ServiceMix (or JBoss) with a param:

JAVA_OPTS="-DMYHOME=somepath/"
JAVA_OPTS=-DMYHOME=somepath/ # windows

then in the servicemix.xml and xbean.xml you can reference MYHOME.

eg:

<import resource="file:${MYHOME}/path/to/file/jmx.xml" />

Then you can also import a properties file from this same path to pull in other config you may need. (that you want outside an SU/SA bundle).

<bean id="propertyConfigurer"
  class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
  <property name="locations">
    <list>
      <value>${MYHOME}/conf/config.properties"</value>
    </list>
  </property>
</bean>