Maven JBI plugin

A key part of a productive development environment is the tooling, for Apache ServiceMix the tooling is provided in the form of a powerful and flexible Apache Maven plugin. The plugin has many useful features to enable you to work with the different project types available in JBI - such as Components, Service Assemblies, Service Units and Shared Librarys - and also allows you to work interact with a running Apache ServiceMix server by exposing the JSR-208 Ant Tasks as plugin goals.

Getting Started

In order to get started with the plugin you need to make it avilable to your project, this is done by adding the following to your pom.xml.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  ...    <pluginRepositories>
    <pluginRepository>
      <id>apache.snapshots</id>
      <name>Maven Central Plugins Development Repository</name>
      <url>http://cvs.apache.org/maven-snapshot-repository</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
      <releases>
         <enabled>false</enabled>
      </releases>
    </pluginRepository>
  </pluginRepositories>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.servicemix.tooling</groupId>
        <artifactId>jbi-maven-plugin</artifactId>
	<version>1.0-incubating-SNAPSHOT</version>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
</project>

The content of <version> may have to be changed from 1.0-incubating-SNAPSHOT to your used version (e.g. 3.0-incubating).

ServiceMix Archetypes

Instead of creating the aforementioned structures manually, you can also use Maven archetypes that create a Maven project for you. ServiceMix provides archetypes for many different purposes, such as for creation of JBI components, service assemblies or service units for particular ServiceMix components. You can take a look at the current list of available archetypes at http://people.apache.org/maven-snapshot-repository/org/apache/servicemix/tooling/ or in the archetypes directory in a ServiceMix source distribution.

You can utilize an archetype by issueing the following command:

mvn archetype:create \
    -DarchetypeGroupId=org.apache.servicemix.tooling \
    -DarchetypeArtifactId=servicemix-archetype-name \
    -DarchetypeVersion=SM-ARCHETYPE-VERSION \
    -DgroupId=org.apache.servicemix.samples.embedded \
    -DartifactId=servicemix-embedded-example

You need to replace servicemix-archetype-name by the name of the archetype you want to utilize and SM-ARCHETYPE-VERSION by the ServiceMix version you are using. (It goes without saying that you should also replace the groupId and artifactId parameters.)

Project Types

Once this plugin has been added to your POM you can start using the capabilities. In order to understand all the things you can do we have broken downs its functionality by the type of artifact you wish to create. JBI covers the creation of four different types of artifact these are:

Shared Libraries

These are bundles of code or JAR's that you can install onto a server (with a given version) to allow components (BC/SE's) to share physical code.

Working with Shared Libraries

Binding Components/Service Engines

These artifacts are the installers for components, allowing you to register a Component that can either start and operate immediately or can wait for the deployment of a service unit.

Working with Components

Service Units

These are zip archives created to contain configuration information of an instance of a service unit that can be deployed to a component (BC/SE)

Working with Service Units

Service Assembly

A service assembly is a collection service units that can be deployed together, it creates a zip archive containing each of the service units (SU's)

Working with Service Assemblies

Running under ServiceMix

As shown in the project types, each different project type can be deployed to a server using the JBI plugin (through the ANT tasks defined in the JBI specification). The only issue here can be working out dependencies and trying to make sure that you deploy the dependencies. This means if you have a Service Assembly you wish to deploy you need to first get the dependent components (and maybe even the dependent shared libraries) to deploy. The Maven2 JBI plugin provides a couple of goals that can help you work through this.

mvn jbi:projectDeploy

If you have created you assemblies, service units, components and shared libraries as Maven projects (which all ServiceMix components are) you can use this goal. In essence the plugin will walk the dependencies starting in the current project then deploy each of the dependencies in reverse order. This can be very useful if you want to quickly get up and running with a new Service Assembly against an installed instance of Apache ServiceMix.

Deploying Dependencies

If you are working with the jbi:projectDeploy you should note that you may want to disable dependency deployment, if you are deploying to a server which has other components sharing these dependencies they you can get problems while trying to undeploy and redeploy them. Look for the plugin section for the jbi-maven-plugin and under configuration add a new element called deployDependencies with a value of false, this is usually in your service assembly's pom.xml or your component's. This setting will stop the plugin for undeploying and redeploying dependencies.

Starting from 3.0.1, the following options are available for customizing either from the pom.xml or from the command line:

Options

Name	Description	Default value
`deployDependencies`	Deploy all dependencies. If set to `false`, the plugin will only deploy the current artifact.	`true`
`deferExceptions`	This option instructs the plugin to use ServiceMix hot deployer feature, so that you can update a shared-lbrary or component without having to shutdown all dependent components or assemblies. If this property is set to `false`, exceptions may occur if some of the deployed artifacts are already used by other previously deployed artifacts.	`true`
`forceUpdate`	If set to `true`, all artifacts will be deployed, even those already deployed. Using default value will only deploy missing dependencies	`false`
`deployChildren`	When using from the command line in a reactor build, the plugin will scan all modules for jbi artifacts to deploy.	`true`

To override a default value from the command line, use the following syntax example:

mvn jbi:projectDeploy -DforceUpdate=true

mvn jbi:servicemix

If you quickly want to get up and running with Apache ServiceMix the best way is to use this goal. As an extension of the deployProject goal is works in much the same way, the difference is that this goal downloads and starts a copy of Apache ServiceMix within Maven so you don't need to have a version installed, this can be very useful if you are working on trying out functionality and want to simply test your projects.

Working with ServiceMix Embedded Configurations

You can also work run your Servicemix embedded configurations using the jbi:embeddedServicemix goal. This will look by default in the src/main/resources/ directory of your project for a servicemix.xml and use that to boot ServiceMix. If you want to try this feature out you can also use the servicemix-embeddded-simple archetype to create a simple project with the files in place.

mvn archetype:create \
    -DarchetypeGroupId=org.apache.servicemix.tooling \
    -DarchetypeArtifactId=servicemix-embedded-simple \
    -DarchetypeVersion=1.0-incubating-SNAPSHOT \
    -DgroupId=org.apache.servicemix.samples.embedded \
    -DartifactId=servicemix-embedded-example

Then simply go into the servicemix-embedded-example directory created by the archetype and run

mvn jbi:embeddedServicemix

Warning regarding local repository dependencies

If you are only using dependencies for your Component (or any project type) from remote repositories then you can ignore this section. However, if you have jars or zip files that which are perhaps internal to your company or a 3rd party jar which you just want to put in your local repository and use as a dependency then you need to be sure to generate a POM for these files. If you do not then these dependencies won't be included in the installer zip file for your jbi Component (or other project type) no matter what scope you specify. Here's how to tell maven 2 to install the jar and generate a pom for it:

mvn install:install-file -Dfile=abc.jar -DgroupId=com.mycompany.myproduct -DartifactId=abc -Dversion=1.0 -Dpackaging=jar -DgeneratePom=true

If you leave off the generatePom parameter, then in your local repository you'll just see the jar file with version attached, e.g. "abc-1.0.jar". But if you include the generatePom, then you'll also see "abc-1.0.pom". You add the dependency to your JBI project like this:

<dependency>
  <groupId>com.mycompany.myproduct</groupId>
  <artifactId>abc</artifactId>
  <version>1.0</version>
  <scope>compile</scope>
</dependency>

When you run "mvn install", you can see if it worked by looking for the following near the bottom of your build results:

[INFO] jbi:jbi-component[INFO] Including: com.mycompany.myproduct:abc:jar:1.0:compile

You can also double check by opening the installer zip file that is created for your jbi project and verifying that your dependency is showing up in the lib folder.

Full Plugin Information

For a more detailed breakdown of the plugin's functionality check out the Maven2 generated documentation.

Maven 1.x Support

Information on the Maven 1.x JBI plugin is available here.

Child pages