What is a JBI SA and how do I create one?
The JBI spec also includes a deployment unit known as a service assembly. SA is an abbreviation for a JBI service assembly. A JBI SA is used to package up JBI SUs in order to be deployed to a container. A SA can include one or more SUs. The concept of the JBI SA is similar to a JavaEE EAR file that is used to package up one or more WAR files. The SA is really just an archive to bundle up SUs for deployment to the JBI container.
Creating a SA
Creating a SA is rather simple once you have created at least one SU (see What is a JBI SU and how do I create one? for information on creating a SU). This example is generic because it works with any SUs. But the first task is to create a Maven project to house the SA configuration. To create a JBI SA, you will use the Maven archetypes that are provided with ServiceMix. Maven archetypes are used to create a Maven project skeleton to jumpstart project creation via the automation of repetitive tasks by following standard conventions. The result of using a Maven archetype to create a Maven project is a directory structure, a Maven POM file (pom.xml
) and, depending on the archetype being used, sometimes Java objects and JUnit tests.
Creating a SA Maven Project
Using a Maven archetype, we will create a simple project whose job is to simply bundle up other project. Below is the command to create the SA Maven project. You may replace the -DarchetypeVersion with whatever ServiceMix version you are using:
$ [SMX_HOME]/bin/smx-arch sa -DgroupId=com.mycompany \ -DartifactId=my-sa
The command above utilizes the servicemix-service-assembly Maven archetype to create a Maven project named my-sa. This command creates a directory named my-sa
that contains a Maven project skeleton meaning all the necessary files are in place, you simply need to enter the correct values for the configuration. Below is the directory structure created by this archetype:
./pom.xml
The only thing that is necessary in a SA Maven project is a the Maven pom.xml
file. The pom.xml
contains the necessary Maven JBI plugin configuration. This is a plugin that automatically generates the META-INF/jbi.xml
file based on other information in the pom.xml
file. The only thing you need to do is specify which SUs will be included in this SA.
Including SUs Inside the SA
In order to actually include SUs inside of the SA, all you need to do is list the SUs as dependencies in the pom.xml
file. Below is an example of including the my-consumer-su SU inside this SA:
<dependencies> <dependency> <groupId>com.mycompany</groupId> <artifactId>my-consumer-su</artifactId> <version>1.0-SNAPSHOT</version> </dependency> </dependencies>
This information was gleaned from the my-consumer-su pom.xml
file in the What is a JBI SU and how do I create one? FAQ entry. Now that we have a SU listed as a dependency, it's time to build and package the SA. Below is the Maven command to do this:
$ mvn install
You will need to have Maven 2.0.4 or higher installed in order to run this command. This packages up the my-consumer-su SU inside of the my-sa SA and places the my-sa build artifact in the target directory.
JBI SA Requirements
There are only two requirements of a JBI SA - that it contain a JBI deployment descriptor located in META-INF/jbi.xml
and that it contain at least one SU. Below is the hierarchy of the contents of the SU archive that is created when running the Maven install goal as noted above:
$ jar tvf ./target/my-sa-1.0-SNAPSHOT.jar 0 Wed Mar 28 21:10:02 MDT 2007 META-INF/ 126 Wed Mar 28 21:10:00 MDT 2007 META-INF/MANIFEST.MF 596 Wed Mar 28 21:10:00 MDT 2007 META-INF/jbi.xml 3391 Wed Mar 28 21:10:00 MDT 2007 my-consumer-su-1.0-SNAPSHOT.zip 0 Wed Mar 28 21:10:02 MDT 2007 META-INF/maven/ 0 Wed Mar 28 21:10:02 MDT 2007 META-INF/maven/com.mycompany/ 0 Wed Mar 28 21:10:02 MDT 2007 META-INF/maven/com.mycompany/my-sa/ 2461 Wed Mar 28 21:09:44 MDT 2007 META-INF/maven/com.mycompany/my-sa/pom.xml 110 Wed Mar 28 21:10:00 MDT 2007 META-INF/maven/com.mycompany/my-sa/pom.properties
Notice that the SA archive contains not only the required META-INF/jbi.xml
file, but also the included my-consumer-su-1.0-SNAPSHOT.zip
file. The META-INF/jbi.xml
file was generated by the JBI Maven plugin. Below is the contents of this file:
$ cat ./target/my-sa-1.0-SNAPSHOT-installer/META-INF/jbi.xml <?xml version="1.0" encoding="UTF-8"?> <jbi xmlns="http://java.sun.com/xml/ns/jbi" version="1.0"> <service-assembly> <identification> <name>my-sa</name> <description>A custom project</description> </identification> <service-unit> <identification> <name>my-consumer-su</name> <description>my-consumer-su</description> </identification> <target> <artifacts-zip>my-consumer-su-1.0-SNAPSHOT.zip</artifacts-zip> <component-name>servicemix-http</component-name> </target> </service-unit> </service-assembly>
This file is a deployment descriptor for the JBI container when the SA is deployed. Notice that it contains information about the SA in general but also information about the included SUs, including the JBI component on which the SU depends (the servicemix-http component).
This is all that is needed to create the SA. The SA can now be deployed by copying the my-sa-1.0-SNAPSHOT.jar file into the ServiceMix deploy directory, deployed via a JMX console or via the ServiceMix Ant Tasks. Happy deploying !
Deployment
To deploy the SA to ServiceMix, simply copy the SA JAR/ZIP file from the target directory to the ServiceMix deploy directory. The deployer should automatically pick up the SA and output some logging to both the console and the data/log/servicemix.log
file as the deployment takes place to let you know what is happening. You can also get more detail about the deployment by increasing the log level in the conf/log4j.xml
file from INFO to DEBUG. For more information on ServiceMix logging, see How do I change the logging.