Introduction
Explain diff between std jbi component and lw component and the static use of ServiceMix.
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 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 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 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 This tutorial focuses on deploying lightweight components to the servicemix-lwcontainer
.
Components can be deployed on ServiceMix in various configurations. For example, components can be deployed on ServiceMix running stand-alone or components can be deployed on ServiceMix which itself is deployed on an application server such as Geronimo.
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.
Just a brief background: 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 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. In addition to deploying components, ServiceMix allows servicemix.xml
files to be deployed in a similar method to deploying a component.
Deploying JBI Components on ServiceMix Running Stand-Alone
This section is included to show how to deploy a ServiceMix component on ServiceMix running stand-alone. It is helpful to see how this deployment is done to build up to the deployment on Geronimo.
Note: These steps work on ServiceMix versions prior to 2.0, but it is now broken. Please see Jira issue: SM-154.
The following example shows a component "org.servicemix.components.servicemix.ServiceMixComponent" being deployed and then a service unit (Quartz) being deployed to the ServiceMixComponent. Note: that the service unit is a servicemix.xml
file.
These steps were performed with a source distribution of ServiceMix 2.0.2 on Windows XP. The existing quartz binding example is modified in this example to turn it into a deployement unit.
Wiki Markup Modify the quartz binding {{servicemix.xml}} file to change it into a service unit. The {{servicemix.xml}} file is located in {{\[servicemix_src_install_dir\]\assembly\target\servicemix-2.0.2\bin\servicemix-2.0.2\examples\quartz-binding}}, where \[servicemix_src_install_dir\] is the directory in which the source distribution of ServiceMix is located.
- Create a directory elsewhere, such as \temp\JBIcomponent
- Copy servicemix.xml to \temp\JBIcomponent
- cd \temp\JBIcomponent
- Edit the
servicemix.xml
file. Change the "container" tags to "serviceunit" and save the file. The file should match the following:
This file will be used in a later step.Code Block <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://xbean.org/schemas/spring/1.0" xmlns:spring="http://xbean.org/schemas/spring/1.0" xmlns:sm="http://servicemix.org/config/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xbean.org/schemas/spring/1.0 ../../conf/spring-beans.xsd http://servicemix.org/config/1.0 ../../conf/servicemix.xsd" xmlns:my="http://servicemix.org/demo/"> <!-- the JBI container --> <sm:serviceunit spring:id="jbi"> <sm:activationSpecs> <!-- lets kick off a timer every 5 seconds --> <sm:activationSpec componentName="timer" service="my:timer" destinationService="my:trace"> <sm:component> <bean xmlns="http://xbean.org/schemas/spring/1.0" class="org.servicemix.components.quartz.QuartzComponent"> <property name="triggers"> <map> <entry> <key> <bean class="org.quartz.SimpleTrigger"> <property name="repeatInterval" value="5000" /> <property name="repeatCount" value="-1" /> </bean> </key> <bean class="org.quartz.JobDetail"> <property name="name" value="My Example Job" /> <property name="group" value="ServiceMix" /> </bean> </entry> </map> </property> </bean> </sm:component> </sm:activationSpec> <!-- Route the event to a trace component that just outputs the event to the console --> <sm:activationSpec componentName="trace" service="my:trace"> <sm:component> <bean xmlns="http://xbean.org/schemas/spring/1.0" class="org.servicemix.components.util.TraceComponent" /> </sm:component> </sm:activationSpec> </sm:activationSpecs> </sm:serviceunit> </beans>
- 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 componentjbi.xml
file. When this is copied to thedeploy
directory it deploys theServiceMixComponent
component. The second jar file will contain the service assembly and thejbi.xml
descriptor file. When it is copied to thedeploy
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 Block <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:Code Block 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 theservicemix.xml
file and it should be called su1.zip to match the name it is called in thejbi.xml
file. See theartifacts-name
tag in thejbi.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 assemblyjbi.xml
should be match the following:
Copy theCode Block <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>
jbi.xml
file to an empty META-INF directory, then create the jar file:Code Block In a directory which contains these files, create the jar file: META-INF/jbi.xml su1.zip jar cvf sa_quartz.jar *
- The file service component
Wiki Markup 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 Block 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>
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 Block java -jar geronimo-1.0-SNAPSHOT/bin/deployer.jar --user system --password manager deploy jbcomponent.jar
That should deploy the component to geronimo. To check, just take a look at the geronimo logs for a message similar to:
Code Block |
---|
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'
|
Related Documentation
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 their respective components in the JBI container.
The following provides details on each step above using the loan-broker 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:
Code Block |
---|
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. The service unit can also contain ajbi.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.- 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 it is used in the Service Assembly'sjbi.xml
file, so to match the example call itloanbroker-su.zip
. - 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 thebuild.xml
file you will see thebuild-su
target does exactly what we just did manually.
- 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
- Create the Service Assembly. A service assembly is a zip file containing one or more service units and a
jbi.xml
file. Thejbi.xml
file must be in theMETA-INF
directory. you may also include other files in theMETA-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
Thejbi.xml
looks like this: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 thejbi.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 theartifacts-name
tag) and the component to which it will be deployed isservicemix-lwcontainer
(see the <component-name> tag). There could be multiple service units in a service assembly and they would each be included in thejbi.xml
file with the same type of information for each.
Create the service assembly ZIP file and include theloanbroker-su.zip
file and theMETA-INF\jbi.xml
directory and file in it. To remain consistent with our example, call the zip fileloanbroker-sa.zip
.
Put theloanbroker-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. - 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
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:
Code Block |
---|
<import resource="classpath:otherBeans.xml" />
|
The resource is a SpringResource so the following also works:
Code Block |
---|
<import resource="file:path/to/file/jmx.xml" />
|
if you run ServiceMix (or JBoss) with a param:
Code Block |
---|
JAVA_OPTS="-DMYHOME=somepath/"
JAVA_OPTS=-DMYHOME=somepath/ # windows
|
then in the servicemix.xml and xbean.xml you can reference MYHOME.
eg:
Code Block |
---|
<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).
Code Block |
---|
<bean id="propertyConfigurer"
class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<property name="locations">
<list>
<value>${MYHOME}/conf/config.properties"</value>
</list>
</property>
</bean>
|
...