h2. Introduction
Explain diff between std jbi component and lw component and the static use of ServiceMix.
See http://docs.codehaus.org/display/SM/What+is+a+lightweight+component for a good explanation of the different types of JBI components.
Two main use cases for ServiceMix:
1. As a ull 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 - static servicemix.xml file configuration used for testing or encapsulating ServiceMix into a web application as the entire use of ServiceMix. In other words, you will not be able to deploy other stuff onto 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|copy link here] 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. ]
h3. Explanation of Using the Lightweight Container and Deploying the ServiceMix Loan Broker Example
We are going to use the Loan Broker example which can be found [Loan Broker Demo for ServiceMix|http://www.servicemix.org/Loan+Broker+example].
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.
The following example shows several lightweight components (which make up the loan broker example) being deployed.
These steps were performed with a source distribution of ServiceMix 3.x on Windows XP.
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:
{code}
cd [servicemix_dir]\examples\loan-broker
ant build-components
{code}
This will compile the Java code and put the Java class files into the {{loan-broker\build\loanbroker\components}} directory.
Now we are ready to assemble the components together. The loan broker demo supplies us with the {{build.xml}} file (which was used in the compile step above as well). The {{build.xml}} contains targets for creating service units. If you run "ant setup" all the service unitsunit 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 serviceand unitSAs.
# First, create the service unit. The service unit is a ZIP file that will contain the youyour application's Java class files. For example:
{code}
# 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:
{code}
<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>
{code}
## Put {{jbi.xml}} in an empty META-INF directory and put that into a jar file:
{code}
mkdir META-INF
copy jbi.xml META-INF
jar cvf service-component.jar *
{code}
## 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:
{code}
<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>
{code}
Copy the {{jbi.xml}} file to an empty META-INF directory, then create the jar file:
{code}
In a directory which contains these files, create the jar file:
META-INF/jbi.xml
su1.zip
jar cvf sa_quartz.jar *
{code}
# 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:
{code}
ServiceMixComponent: deploy
ServiceMixComponent: init: SU_1 path: C:\tmp1\servicemix-1.1-SNAPSHOT\target\servicemix-1.1-SNAPSHOT\bin\servicemix-1.1-SNAPSHOT\bin\..\wdir
\defaultJBI\components\servicemix-component\serviceunit\SU_1
[INFO] XmlBeanDefinitionReader - -Loading XML bean definitions from URL [file:C:/tmp1/servicemix-1.1-SNAPSHOT/target/servicemix-1.1-SNAPSHOT
/bin/servicemix-1.1-SNAPSHOT/bin/../wdir/defaultJBI/components/servicemix-component/serviceunit/SU_1/servicemix.xml]
...
[INFO] DefaultListableBeanFactory - -Creating shared instance of singleton bean 'jbi'
ServiceMixComponent: start: SU_1
[INFO] JBIContainer - -Activating component for: [container=defaultJBI,name=timer,id=timer] with service: {http://servicemix.org/demo/}timer
component: org.servicemix.components.quartz.QuartzComponent@1ecfe07
[INFO] SimpleThreadPool - -Job execution threads will use class loader of thread: main
[INFO] RAMJobStore - -RAMJobStore initialized.
[INFO] StdSchedulerFactory - -Quartz scheduler 'DefaultQuartzScheduler' initialized from default resource file in Quartz package: 'quartz.pr
operties'
[INFO] StdSchedulerFactory - -Quartz scheduler version: 1.4.0
[INFO] ComponentContextImpl - -Component: timer activated endpoint: {http://servicemix.org/demo/}timer : timer
[INFO] JBIContainer - -Activating component for: [container=defaultJBI,name=trace,id=trace] with service: {http://servicemix.org/demo/}trace
component: org.servicemix.components.util.TraceComponent@8b8a47
[INFO] ComponentContextImpl - -Component: trace activated endpoint: {http://servicemix.org/demo/}trace : trace
[INFO] DeploymentService - -Deployed ServiceUnit SU_1 to Component: servicemix-component
[INFO] AutoDeploymentService - -Unpacked archive C:\tmp1\servicemix-1.1-SNAPSHOT\target\servicemix-1.1-SNAPSHOT\bin\servicemix-1.1-SNAPSHOT\
bin\..\deploy\comp.jar to C:\tmp1\servicemix-1.1-SNAPSHOT\target\servicemix-1.1-SNAPSHOT\bin\servicemix-1.1-SNAPSHOT\bin\..\wdir\defaultJBI\
tmp\comp.0.tmp
[INFO] XmlBeanDefinitionReader - -Loading XML bean definitions from URL [file:/C:/tmp1/servicemix-1.1-SNAPSHOT/target/servicemix-1.1-SNAPSHO
T/bin/servicemix-1.1-SNAPSHOT/bin/../wdir/defaultJBI/tmp/comp.0.tmp/META-INF/jbi.xml]
...
[INFO] DefaultListableBeanFactory - -Creating shared instance of singleton bean 'jbi'
[INFO] AutoDeploymentService - -Unpacked archive C:\tmp1\servicemix-1.1-SNAPSHOT\target\servicemix-1.1-SNAPSHOT\bin\servicemix-1.1-SNAPSHOT\
bin\..\deploy\sa_quartz.jar to C:\tmp1\servicemix-1.1-SNAPSHOT\target\servicemix-1.1-SNAPSHOT\bin\servicemix-1.1-SNAPSHOT\bin\..\wdir\defaul
tJBI\tmp\sa_quartz.0.tmp
[INFO] XmlBeanDefinitionReader - -Loading XML bean definitions from URL [file:/C:/tmp1/servicemix-1.1-SNAPSHOT/target/servicemix-1.1-SNAPSHO
T/bin/servicemix-1.1-SNAPSHOT/bin/../wdir/defaultJBI/tmp/sa_quartz.0.tmp/META-INF/jbi.xml]
[INFO] FileSystemXmlApplicationContext - -Bean factory for application context [org.springframework.context.support.FileSystemXmlApplication
[INFO] JBIContainer - -ServiceMix JBI Container (http://servicemix.org/) name: defaultJBI running version: ServiceMix.
[INFO] DeliveryChannel - -default destination serviceName for timer = {http://servicemix.org/demo/}trace
[INFO] QuartzScheduler - -Scheduler DefaultQuartzScheduler_$_NON_CLUSTERED started.
[INFO] TraceComponent - -Exchange: org.servicemix.jbi.messaging.InOnlyImpl@a7dd39 received IN message: org.servicemix.jbi.messaging.Normaliz
edMessageImpl@acdd02{properties: {org.servicemix.quartz.context=JobExecutionContext: trigger: 'ServiceMix.My Example Job job: ServiceMix.My
Example Job fireTime: 'Thu Dec 08 14:15:06 PST 2005 scheduledFireTime: Thu Dec 08 14:15:05 PST 2005 previousFireTime: 'null nextFireTime: Th
u Dec 08 14:15:06 PST 2005 isRecovering: false refireCount: 0, org.servicemix.quartz.detail=JobDetail 'ServiceMix.My Example Job': jobClass
: 'org.servicemix.components.quartz.ServiceMixJob isStateful: false isVolatile: false isDurable: false requestsRecovers: false, org.servicem
ix.component=org.servicemix.components.quartz.QuartzComponent@1ecfe07}}
[INFO] TraceComponent - -Body is: <?xml version="1.0" encoding="UTF-8"?><timer><name>My Example Job</name><group>ServiceMix</group><fullname
>ServiceMix.My Example Job</fullname><description/><fireTime>Thu Dec 08 14:15:06 PST 2005</fireTime></timer>
[INFO] TraceComponent - -Exchange: org.servicemix.jbi.messaging.InOnlyImpl@19ecd80 received IN message: org.servicemix.jbi.messaging.Normali
zedMessageImpl@c5aa00{properties: {org.servicemix.quartz.context=JobExecutionContext: trigger: 'ServiceMix.My Example Job job: ServiceMix.My
Example Job fireTime: 'Thu Dec 08 14:15:06 PST 2005 scheduledFireTime: Thu Dec 08 14:15:06 PST 2005 previousFireTime: 'Thu Dec 08 14:15:05
PST 2005 nextFireTime: Thu Dec 08 14:15:06 PST 2005 isRecovering: false refireCount: 0, org.servicemix.quartz.detail=JobDetail 'ServiceMix.M
y Example Job': jobClass: 'org.servicemix.components.quartz.ServiceMixJob isStateful: false isVolatile: false isDurable: false requestsReco
vers: false, org.servicemix.component=org.servicemix.components.quartz.QuartzComponent@1ecfe07}}
[INFO] TraceComponent - -Body is: <?xml version="1.0" encoding="UTF-8"?><timer><name>My Example Job</name><group>ServiceMix</group><fullname
>ServiceMix.My Example Job</fullname><description/><fireTime>Thu Dec 08 14:15:06 PST 2005</fireTime></timer>
{code}
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.
# Make sure that your geronimo server is running.
# Run the geronimo deploy tool against your deployment unit (in this case jbcomponent.jar): {code}
java -jar geronimo-1.0-SNAPSHOT/bin/deployer.jar --user system --password manager deploy jbcomponent.jar
{code}
That should deploy the component to geronimo. To check, just take a look at the geronimo logs for a message similar to:
{code}
11:44:24,865 INFO [Configuration] Started configuration example-engine-1
11:44:24,869 INFO [ServiceMixDeployment] Starting: /Users/chirino/sandbox/geronimo/modules/assembly/target/geronimo-1.0-SNAPSHOT/config-store/20/META-INF/jbi.xml
...
11:44:25,783 INFO [DefaultListableBeanFactory] Creating shared instance of singleton bean 'jbi'
{code}
h2. Related Documentation
* [Geronimo|http://apache.geronimo.org]
* [Tomcat Integration|http://www.servicemix.org/Tomcat+Integration].
|