Fuse ESB - Deploying into the OSGi Container

Overview

The simplest way to get started with Maven is to generate a new project using a Maven archetype. This section describes how to set up Maven to use the Fuse ESB archetypes, which can generate starting points for different kinds of bundle application.

Prerequisites

In order to build a project using Maven, you must have the following prerequisites:

Maven installation—Maven is a free, open source build tool from Apache. You can download the latest version from the Maven download page (minimum version is 2.2.1).
Internet connection—whilst performing a build, Maven dynamically searches external repositories and downloads the required artifacts on the fly. In order for this to work, your build machine must be connected to the Internet.

Adding the fusesource repository

In order to access artifacts from the ESB Maven repository, you need to add the fusesource repository to Maven's settings.xml file. Maven looks for your settings.xml file in the following standard location:

UNIX: home/User/.m2/settings.xml
Windows: Documents and Settings\User\.m2\settings.xml

If there is currently no settings.xml file at this location, you need to create a new settings.xml file. Modify the settings.xml file by adding the repository element for fusesource, as shown in bold text in the following example:

<settings>
    <profiles>
        <profile>
            <id>my-profile</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <repositories>
                <repository>
                    <id>fusesource</id>
                    <url>http://repo.fusesource.com/maven2</url>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                </repository>
               <repository>
                    <id>fusesource.snapshot</id>
                    <url>http://repo.fusesource.com/maven2-snapshot</url>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                    <releases>
                        <enabled>false</enabled>
                    </releases>
                </repository>
                <repository>
                    <id>apache-public</id>
                    <url>https://repository.apache.org/content/groups/public/</url>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                </repository>
                ...
            </repositories>
        </profile>
    </profiles>
    ...
</settings>

The preceding example also shows repository element for the following repositories:

fusesource-snapshot repository—if you want to experiment with building your application using an Fuse ESB snapshot kit, you can include this repository.
apache-public repository—you might not always need this repository, but it is often useful to include it, because Fuse ESB depends on many of the artifacts from Apache.

Artifacts and bundles

The basic building block in the Maven build system is an artifact. When using Maven to build an OSGi project, there is a natural mapping between an OSGi bundle and a Maven artifact: a bundle is simply an artifact whose packaging type is set to bundle.

Maven coordinates

A key aspect of Maven functionality is the ability to locate artifacts and manage the dependencies between them. Maven defines the location of an artifact using the system of Maven coordinates, which uniquely define the location of a particular artifact. A basic coordinate tuple has the form, {groupId, artifactId, version}. Sometimes Maven augments the basic set of coordinates with the additional coordinates, packaging and classifier. A tuple can be written with the basic coordinates, or with the additional packaging coordinate, or with the addition of both the packaging and classifier coordinates, as follows:

groupdId:artifactId:version
groupdId:artifactId:packaging:version
groupdId:artifactId:packaging:classifier:version

Each coordinate can be explained as follows:

groupdId: Defines a scope for the name of the artifact. You would typically use all or part of a package name as a group ID—for example, org.fusesource.example.
artifactId: Defines the artifact name (relative to the group ID).
version: Specifies the artifact's version. A version number can have up to four parts: n.n.n.n, where the last part of the version number can contain non-numeric characters (for example, the last part of 1.0-SNAPSHOT is the alphanumeric substring, 0-SNAPSHOT).
packaging: Defines the packaged entity that is produced when you build the project. For OSGi projects, the packaging is bundle. The default value is jar.
classifier: Enables you to distinguish between artifacts that were built from the same POM, but have different content.

The group ID, artifact ID, packaging, and version are defined by the corresponding elements in an artifact's POM file. For example:

<project ... >
  ...
  <groupId>org.fusesource.example</groupId>
  <artifactId>bundle-demo</artifactId>
  <packaging>bundle</packaging>
  <version>1.0-SNAPSHOT</version>
  ...
</project>

For example, to define a dependency on the preceding artifact, you could add the following dependency element to a POM:

<project ...>
  ...
  <dependencies>
    <dependency>
      <groupId>org.fusesource.example</groupId>
      <artifactId>bundle-demo</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>
  ...
</project>

	Note
	It is not necessary to specify the `bundle` package type in the preceding dependency, because a bundle is just a particular kind of JAR file and `jar` is the default Maven package type. If you do need to specify the packaging type explicitly in a dependency, however, you can use the `type` element.

Generating projects with Maven archetypes

To help you get started quickly, you can invoke a Maven archetype to generate the initial outline of a Maven project (a Maven archetype is analogous to a project wizard). The following Maven archetypes can generate projects for building OSGi bundles:

Fuse Service Framework code-first archetype

The Fuse Service Framework code-first archetype creates a project for building a service from Java. To generate a Maven project with the coordinates, GroupId:ArtifactId:Version, enter the following command:

mvn archetype:create
-DarchetypeGroupId=org.apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-cxf-code-first-osgi-bundle
-DarchetypeVersion=2011.02.1-fuse-00-08
-DgroupId=GroupId
-DartifactId=ArtifactId
-Dversion=Version

	Note
	The arguments to the `mvn` command are shown on separate lines purely for the sake of readability. When you are entering the command at a command prompt, you must ensure that all of the parameters are on the same line.

Fuse Service Framework WSDL-first archetype

The Fuse Service Framework WSDL-first archetype creates a project for building a service from WSDL. To generate a Maven project with the coordinates, GroupId:ArtifactId:Version, enter the following command:

mvn archetype:create
-DarchetypeGroupId=org.apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-cxf-wsdl-first-osgi-bundle
-DarchetypeVersion=2011.02.1-fuse-00-08
-DgroupId=GroupId
-DartifactId=ArtifactId
-Dversion=Version

Fuse Mediation Router archetype

The Fuse Mediation Router OSGi archetype creates a project for building a route that can be deployed into the OSGi container. To generate a Maven project with the coordinates, GroupId:ArtifactId:Version, enter the following command:

mvn archetype:create
-DarchetypeGroupId=org.apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-camel-osgi-bundle
-DarchetypeVersion=2011.02.1-fuse-00-08
-DgroupId=GroupId
-DartifactId=ArtifactId
-Dversion=Version

Building the bundle

By default, the preceding archetypes create a project in a new directory, whose names is the same as the specified artifact ID, ArtifactId. To build the bundle defined by the new project, open a command prompt, go to the project directory (that is, the directory containing the pom.xml file), and enter the following Maven command:

mvn install

The effect of this command is to compile all of the Java source files, to generate a bundle JAR under the ArtifactId/target directory, and then to install the generated JAR in the local Maven repository.

	Note
	You can skip the final build step (installing the generated JAR in the local Maven repository) by entering the `mvn package` command. But only do this, if you are sure that no other local Maven projects depend on this artifact.