LibraryPrintFeedback

Getting Started

Version 7.1

December 2012
Trademark Disclaimer
Third Party Acknowledgements

Updated: 08 Jan 2014

Table of Contents

1. Basic Concepts for Developers
Development Environment
Development Model
Maven Essentials
Dependency Injection Frameworks
2. Getting Started with Developing
Create a Web Services Project
Create a Router Project
Create an Aggregate Maven Project
Define a Feature for the Application
Configure the Application
Troubleshooting
3. Getting Started with Deploying
Scalable Deployment with Fuse Fabric
Deploying to a Fabric
Create a Fabric
Create Fabric Profiles
Deploy the Profiles
Update a Profile

List of Figures

1.1. Developing a Fuse ESB Enterprise Project
3.1. Containers in a Fabric
3.2. A Sample Fabric with Child Containers

List of Examples

1.1. Standard Maven Directory Layout
2.1. Spring XML for Web Services Endpoint
2.2. Configuring the Port Number in Spring XML
2.3. Configuring the Port Number in Blueprint XML

The recommended build system for developing Fuse ESB Enterprise applications is Apache Maven version 3.0.x. See Installation Guide for more details.

Maven is more than a build system, however. Just as importantly, Maven also provides an infrastructure for distributing application components (typically JAR files; formally called artifacts). When you build an application, Maven automatically searches repositories on the Internet to find the JAR dependencies needed by your application, and then downloads the needed dependencies. See Maven Essentials for more details.

Figure 1.1 shows an overview of the development model for building an OSGi bundle or a Fuse Application Bundle that will be deployed into the Fuse ESB Enterprise container.


A Maven repository is a place where Maven can go to search for artifacts. Because Maven repositories can be anywhere—and that includes anywhere on the Internet—the Maven build system is inherently distributed. The following are the main categories of Maven repository:

For more details about Maven repositories, see Preparing to use Maven in Deploying into the Container.

Spring is fundamentally a dependency injection framework, but it also includes a suite of services and APIs that enable it to act as a fully-fledged container. A Spring XML configuration file can be used in the following ways:

  • An injection framework—Spring is a classic injection framework, enabling you to instantiate Java objects using the bean element and to wire beans together, either explicitly or automatically. For details, see The IoC Container from the Spring Reference Manual.

  • A generic XML configuration file—Spring has an extensibility mechanism that makes it possible to use third-party XML configuration schemas in a Spring XML file. Spring uses the schema namespace as a hook for finding an extension: it searches the classpath for a JAR file that implements that particular namespace extension. In this way, it is possible to embed the following XML configurations inside a Spring XML file:

    • Apache Camel configuration—usually introduced by the camelContext element in the schema namespace, http://camel.apache.org/schema/spring.

    • Apache CXF configuration—uses several different schema namespaces, depending on whether you are configuring the Bus, http://cxf.apache.org/core, a JAX-WS binding, http://cxf.apache.org/jaxws, a JAX-RS binding, http://cxf.apache.org/jaxrs, or a Simple binding, http://cxf.apache.org/simple.

    • Apache ActiveMQ configuration—usually introduced by the broker element in the schema namespace, http://activemq.apache.org/schema/core.

    [Note]Note

    When packaging your project as an OSGi bundle, the Spring XML extensibility mechanism can introduce additional dependencies. Because the Maven bundle plug-in does not have the ability to scan the Spring XML file and automatically discover the dependencies introduced by schema namespaces, it is generally necessary to add the additional dependencies explicitly to the maven-bundle-plugin configuration (by specifying the required Java packages).

  • An OSGi toolkit—Spring also has features (provided by Spring Dynamic Modules) to simplify integrating your application with the OSGi container. In particular, Spring DM provides XML elements that make it easy to export and consume OSGi services. For details, see The Service Registry from the Spring DM Reference Manual.

  • A provider of container services—Spring also supports typical container services, such as security, persistence, and transactions. Before using such services, however, you should compare what is available from the Fuse ESB Enterprise container itself. In some cases, the Fuse ESB Enterprise container already layers a service on top of Spring (as with the transaction service, for example). In other cases, the Fuse ESB Enterprise container might provide an alternative implementation of the same service.

Blueprint is a dependency injection framework defined in the OSGi specification. Historically, blueprint was originally sponsored by Spring and was based loosely on Spring DM. Consequently, the functionality offered by blueprint is quite similar to Spring XML, but blueprint is a more lightweight framework and it has been specially tailored for the OSGi container.

  • An injection framework—blueprint is a classic injection framework, enabling you to instantiate Java objects using the bean element and to wire beans together, either explicitly or automatically. For details, see The Blueprint Container in Deploying into the Container.

  • A generic XML configuration file—blueprint has an extensibility mechanism that makes it possible to use third-party XML configuration schemas in a blueprint XML file. Blueprint uses the schema namespace as a hook for finding an extension: it searches the classpath for a JAR file that implements that particular namespace extension. In this way, it is possible to embed the following XML configurations inside a blueprint XML file:

    • Apache Camel configuration—usually introduced by the camelContext element in the schema namespace, http://camel.apache.org/schema/blueprint.

    • Apache CXF configuration—uses several different schema namespaces, depending on whether you are configuring the Bus, http://cxf.apache.org/blueprint/core, a JAX-WS binding, http://cxf.apache.org/blueprint/jaxws, a JAX-RS binding, http://cxf.apache.org/blueprint/jaxrs, or a Simple binding, http://cxf.apache.org/blueprint/simple.

    • Apache ActiveMQ configuration—usually introduced by the broker element in the schema namespace, http://activemq.apache.org/schema/core.

    [Note]Note

    When packaging your project as an OSGi bundle, the blueprint XML extensibility mechanism can introduce additional dependencies, through the schema namespaces. Blueprint automatically resolves the dependencies implied by the schema namespaces at run time.

  • An OSGi toolkit—blueprint also has features to simplify integrating your application with the OSGi container. In particular, blueprint provides XML elements that make it easy to export and consume OSGi services. For details, see Exporting a Service in Deploying into the Container and Importing a Service in Deploying into the Container.

You can create a Maven project directly from the command line, by invoking the archetype:generate goal. First of all, create a directory to hold your getting started projects. Open a command prompt, navigate to a convenient location in your file system, and create the get-started directory, as follows:

mkdir get-started
cd get-started

You can now use the archetype:generate goal to invoke the servicemix-cxf-code-first-osgi-bundle archetype, which generates a simple Apache CXF demonstration, as follows:

[Note]Note

The arguments of the preceding command are shown on separate lines for readability, but when you are actually entering the command, the entire command must be entered on a single line.

You will be prompted to confirm the project settings, with a message similar to this one:

[INFO] Using property: groupId = org.fusesource.example
[INFO] Using property: artifactId = cxf-basic
[INFO] Using property: version = 1.0-SNAPSHOT
[INFO] Using property: package = org.fusesource.example
Confirm properties configuration:
groupId: org.fusesource.example
artifactId: cxf-basic
version: 1.0-SNAPSHOT
package: org.fusesource.example
Y: :

Type Return to accept the settings and generate the project. When the command finishes, you should find a new Maven project in the get-started/cxf-basic directory.

If you look in the cxf-basic/src/main/resources/META-INF/spring/beans.xml file, you can see an example of Spring XML configuration, as follows:


The purpose of this Spring XML file is to create a WS endpoint (that is, an instance of a Web service). The jaxws:endpoint element creates the WS endpoint and, in this example, it requires two attributes, as follows:

implementor

Specifies the class that implements the Service Endpoint Interface (SEI).

address

Specifies the WS endpoint address. In this example, instead of a HTTP URL, the address is specified as a relative path. In the context of Fuse ESB Enterprise, this is taken to mean that the Web service should be installed into the Fuse ESB Enterprise container's default Jetty container. By default, the specified path gets prefixed by http://localhost:8181/cxf/, so the actual address of the Web service becomes:

http://localhost:8181/cxf/PersonServiceCF

Open a command prompt and change directory to the get-started directory. You can now use the archetype:generate goal to invoke the camel-archetype-blueprint archetype, which generates a simple Apache Camel demonstration, as follows:

mvn archetype:generate
-DarchetypeGroupId=org.apache.camel.archetypes
-DarchetypeArtifactId=camel-archetype-blueprint
-DarchetypeVersion=2.10.0.fuse-71-047
-DgroupId=org.fusesource.example
-DartifactId=camel-basic
-Dversion=1.0-SNAPSHOT
[Note]Note

The arguments of the preceding command are shown on separate lines for readability, but when you are actually entering the command, the entire command must be entered on a single line.

You will be prompted to confirm the project settings, with a message similar to this one:

[INFO] Using property: groupId = org.fusesource.example
[INFO] Using property: artifactId = camel-basic
[INFO] Using property: version = 1.0-SNAPSHOT
[INFO] Using property: package = org.fusesource.example
[INFO] Using property: camel-version = 2.9.0.fuse-7-032
[INFO] Using property: log4j-version = 1.2.16
[INFO] Using property: maven-bundle-plugin-version = 2.3.4
[INFO] Using property: maven-compiler-plugin-version = 2.3.2
[INFO] Using property: maven-surefire-plugin-version = 2.11
[INFO] Using property: slf4j-version = 1.6.1
Confirm properties configuration:
groupId: org.fusesource.example
artifactId: camel-basic
version: 1.0-SNAPSHOT
package: org.fusesource.example
camel-version: 2.9.0.fuse-7-032
log4j-version: 1.2.16
maven-bundle-plugin-version: 2.3.4
maven-compiler-plugin-version: 2.3.2
maven-surefire-plugin-version: 2.11
slf4j-version: 1.6.1
Y: :

Type Return to accept the settings and generate the project. When the command finishes, you should find a new Maven project in the get-started/camel-basic directory.

You are going to modify the default route generated by the archetype and change it into a route that implements a HTTP bridge. This bridge will be interposed between the WS client and Web service, enabling us to apply some routing logic to the WSDL messages that pass through the route.

Using your favorite text editor, open camel-basic/src/main/resources/OSGI-INF/blueprint/blueprint.xml. Remove the existing bean element and the camelContext element and replace them with the camelContext element highlighted in the following example:

The from element defines a new HTTP server port, which listens on IP port 8282. The to element defines a HTTP client endpoint that attempts to connect to the real Web service, which is listening on IP port 8181. To make the route a little more interesting, we add a delay element, which imposes a five second (5000 millisecond) delay on all requests passing through the route.

For a detailed discussion and explanation of the HTTP bridge, see Proxying with HTTP in Web Services and Routing with Camel CXF.

If you have not already started the Fuse ESB Enterprise container and deployed the Web services bundle, you should do so now—see Deploy and start the WS server.

To install the camel-basic route as an OSGi bundle, enter the following console command:

karaf@root> install mvn:org.fusesource.example/camel-basic/1.0-SNAPSHOT

If the bundle is successfully resolved and installed, the container responds by giving you the ID of the newly created bundle—for example:

Bundle ID: 230

You can now start up the Web service using the start console command, specifying the bundle ID, as follows:

karaf@root> start 230

You have a few different options for deploying features, as follows:

For more details about the feature deployment options, see Deploying a Feature in Deploying into the Container.

Create a sub-directory to hold the features repository. Under the get-started project directory, create all of the directories in the following path:

get-started/features/src/main/resources/

Under the get-started/features/src/main/resources directory, use a text editor to create the get-started.xml file and add the following contents:

Under the get-started/features/ directory, use a text editor to create the Maven POM file, pom.xml, and add the following contents to it:

In the cxf-basic project, any XML files from the following location are treated as Spring XML files (the standard Maven location for Spring XML files):

cxf-basic/src/main/resources/META-INF/spring/*.xml

Edit the beans.xml file from the preceding directory and add the XML contents shown in Example 2.2.


The highlighted text shows what is changed from the original beans.xml file, in order to integrate the OSGi Config Admin service. Apart from defining the osgix and ctx namespaces, the main changes are as follows:

To use blueprint configuration instead of Spring configuration, replace the Spring XML file by a blueprint XML file, where the blueprint file must be added to the following location in the cxf-basic project:

cxf-basic/src/main/resources/OSGI-INF/blueprint/*.xml

Create a beans.xml file in the preceding location and add the XML contents shown in Example 2.3.


The highlighted text shows the parts of the blueprint configuration that are relevant to the OSGi Config Admin service. Apart from defining the cm namespace, the main changes are as follows:

  1. The cm:property-placeholder bean contacts the OSGi Config Admin service and retrieves all of the property settings from the org.fusesource.example.get.started PID. The key-value pairs in the cm:default-properties/cm:property elements specify default values for the properties (which are overridden, if corresponding settings can be retrieved from the OSGi Config Admin service).

  2. The {{portNumber}} placeholder is used to specify the IP port number used by the PersonService Web service.

[Note]Note

If you want to try out the blueprint XML configuration, you must ensure that the instructions for the maven-bundle-plugin in the project's pom.xml file include the wildcard, *, in the packages listed in the Import-Package element (if the Import-Package element is not present, the wildcard is implied by default). Otherwise, you will get the error: Unresolved references to [org.osgi.service.blueprint] by class(es) on the Bundle-Classpath[Jar:dot]: [].

To deploy the configurable Web service from the cxf-basic project, perform the following steps:

  1. Edit the Spring XML file, beans.xml, to integrate the OSGi Config Admin service, as described in Example 2.2.

  2. Rebuild the cxf-basic project with Maven. Open a command prompt, change directory to the get-started/cxf-basic directory, and enter the following Maven command:

    mvn clean install
  3. Create the following configuration file in the etc/ directory of your Fuse ESB Enterprise installation:

    ESBInstallDir/etc/org.fusesource.example.get.started.cfg

    Edit the org.fusesource.example.get.started.cfg file with a text editor and add the following contents:

    portNumber=8182
  4. If you have previously deployed the get-started-basic feature (as described in Define a Feature for the Application), uninstall it now:

    karaf@root> features:uninstall get-started-basic
  5. Deploy the get-started-cxf feature, by entering the following console command:

    karaf@root> features:install get-started-cxf
  6. After waiting a few seconds for the bundles to start up, you can test the application by opening a command prompt, changing directory to get-started/cxf-basic, and entering the following command:

    mvn -Pclient -Dexec.args="http://localhost:8182/PersonServiceCF"
    [Important]Important

    The URL in this command has a slightly different format from the URLs used in the previous client commands: the path part of the URL is /PersonServiceCF, instead of /cxf/PersonServiceCF.

  7. To uninstall the feature, enter the following console command:

    features:uninstall get-started-cxf

Figure 3.1 shows an example of a distributed collection of containers that belong to a single fabric.


A Fabric Ensemble is a collection of Fabric Servers and Fabric Containers that collectively maintain the state of the fabric registry. The Fabric Ensemble implements a replicated database and uses a quorum-based voting system to ensure that data in the fabric registry remains consistent across all of the fabric's containers. To guard against network splits in a quorum-based system, it is a requirement that the number of Fabric Servers in a Fabric Ensemble is always an odd number.

The number of Fabric Servers in a fabric is typically 1, 3, or 5. A fabric with just one Fabric Server is suitable for experimentation only. A live production system should have at least 3 or 5 Fabric Servers, installed on separate hosts, to provide fault tolerance.

A Fabric Server has a special status in the fabric, because it is responsible for maintaining a replica of the fabric registry. In each Fabric Server, a registry service is installed (labeled R in Figure 3.1). The registry service (based on Apache ZooKeeper) maintains a replica of the registry database and provides a ZooKeeper server, which ordinary agents can connect to in order to retrieve registry data.

A Fabric Container is aware of the locations of all of the Fabric Servers, and it can retrieve registry data from any Fabric Server in the Fabric Ensemble. A Fabric Agent (labeled A in Figure 3.1) is installed in each Fabric Container. The Fabric Agent actively monitors the fabric registry, and whenever a relevant modification is made to the registry, it immediately updates its container to keep the container consistent with the registry settings.

A Fabric profile is an abstract unit of deployment, which is capable of holding all of the data required for deploying an application into a Fabric Container. Profiles are used exclusively in the context of fabrics. Features or bundles deployed directly to Fabric Containers are short lived.

[Important]Important

The presence of a Fabric Agent in a container completely changes the deployment model, requiring you to use profiles exclusively as the unit of deployment. Although it is still possible to deploy an individual bundle or feature (using osgi:install or features:install, respectively), these modifications are impermanent. As soon as you restart the container or refresh its contents, the Fabric Agent replaces the container's existing contents with whatever is specified by the deployed profiles.

Figure 3.2 shows an overview of a sample fabric that you will create. The Fabric Ensemble consists of just one Fabric Server (making this fabric suitable only for experimental use) and two managed child containers.


Creating one or more child containers is the simplest way to extend a fabric. As shown in Figure 3.2, the first container in the fabric is a root container, and both child containers are descended from it.

Each child container is an independent Fuse ESB Enterprise container instance, which runs in its own JVM instance. The data files for the child containers are stored under the ESBInstallDir/instances directory.

To create the simple fabric shown in Figure 3.2, follow these steps:

  1. (Optional) Customise the name of the root container by editing the ESBInstallDir/etc/system.properties file and specifying a different name for this property:

    karaf.name=root
    [Note]Note

    For the first container in your fabric, this step is optional. But at some later stage, if you want to join a root container to the fabric, you must customise the new container's name to prevent it from clashing with any existing root containers in the fabric.

  2. If you have not already done so, create one (or more users) by adding a line of the following form to the ESBInstallDir/etc/users.properties file:

    Username=Password[,RoleA][,RoleB]...

    At least one of the users must have the admin role, to enable administration of the fabric. For example:

    admin=secretpassword,admin

    When you create the fabric, the entries in users.properties are used to initialize the user data for the Zookeeper login module, which provides security for the fabric.

    [Note]Note

    The initialization of user data from users.properties happens only once, at the time the fabric is created. After the fabric has been created, any changes you make to users.properties will have no effect on the fabric's user data.

  3. To create the first fabric container, which acts as the seed for the new fabric, enter this console command:

    karaf@root> fabric:create --zookeeper-password admin

    The current container, named root by default, becomes a Fabric Server with a registry service installed. Initially, this is the only container in the fabric. The Zookeeper password is used to protect sensitive data in the Fabric registry service (all of the nodes under /fabric).

    [Tip]Tip

    Most of the time, you are not prompted to enter the Zookeeper password when accessing the registry service, because it is cached in the current session. When you join a container to a fabric, however, you must provide the fabric's Zookeeper password.

  4. Create two child containers. Assuming that your root container is named root, enter this console command:

    karaf@root> fabric:container-create-child root child 2
    Jmx Login for root: admin
    Jmx Password for root: 
    The following containers have been created successfully:
    	Container: child1.
    	Container: child2.

    You are prompted to enter a JMX username and password (the JMX port is integrated with the JAAS authentication service). Enter one of the username/password combinations that you defined in step 2.

  5. Invoke the fabric:container-list command to see a list of all containers in your new fabric. You should see a listing something like this:

    karaf@root> fabric:container-list
    [id]                           [version] [alive] [profiles]                     [provision status]
    root                           1.0       true    fabric, fabric-ensemble-0000-1, fuse-esb-full success
      child1                       1.0       true    default                        success
      child2                       1.0       true    default                        success

To create the gs-cxf-base profile, follow these steps:

  1. Create the gs-cxf-base profile by entering this console command:

    karaf@root> fabric:profile-create --parents cxf gs-cxf-base
  2. Add the get-started features repository (see Define a Feature for the Application) to the gs-cxf-base profile by entering this console command:

    karaf@root> profile-edit -r mvn:org.fusesource.example/get-started/1.0-SNAPSHOT/xml/features gs-cxf-base
  3. Now add the get-started-cxf feature (which provides the Web service example server) to the gs-cxf-base profile. Enter the following console command:

    karaf@root> profile-edit --features get-started-cxf gs-cxf-base

Having created the child containers, as described in Create a Fabric, and the profiles, as described in Create Fabric Profiles, you can now deploy the profiles. To do so, follow these steps:

  1. Deploy the gs-cxf-01 profile into the child1 container by entering this console command:

    karaf@root> fabric:container-change-profile child1 gs-cxf-01
  2. Deploy the gs-cxf-02 profile into the child2 container by entering this console command:

    karaf@root> fabric:container-change-profile child2 gs-cxf-02

You can test the deployed profiles using the WS client from the cxf-basic Maven project described in Create a Web Services Project. To do so, follow these steps:

  1. Open a new command prompt and cd to get-started/cxf-basic.

  2. Test the gs-cxf-01 profile (which deploys a Web service listening on port 8185) by entering this command:

    mvn -Pclient -Dexec.args="http://localhost:8185/PersonServiceCF"
  3. Test the gs-cxf-02 profile (which deploys a Web service listening on port 8186) by entering this command:

    mvn -Pclient -Dexec.args="http://localhost:8186/PersonServiceCF"