User Guide for Camel/JOnAS 5 integration.

JOnAS Team

This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,visit http://creativecommons.org/licenses/by-sa/2.0/deed.en or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

Abstract

This user guide is intended to those who want to use Camel within JOnAS 5.


Glossary
1. Introduction
1.1. Motivations for Camel/JOnAS 5 integration.
1.2. Camel in JOnAS 5.
2. Downloading Camel/JOnAS 5 integration.
3. Installing and running
4. Here is a description of Camel service provided in JOnAS 5.
4.1. Main features of Camel service.
5. Using registry for static directory.
5.1. Rationale
5.2. How does it work ?
6. The iPOJO CAMEL component for JOnAS.
6.1. Main features of the iPOJO CAMEL component for JOnAS.
6.2. How to use the iPOJO CAMEL component for JOnAS.

Glossary

Vocabulary

This glossary defines the vocabulary used by this user guide. A definition of common terms can be found on the glossary by Sun.

Apache Camel

Engine for messages routing and mediation.

OW2 JOnAS 5

Java Open Application Server version 5.

JVM

An instance of the Java Virtual Machine.

OSGi

acronym for Open Services Gateway initiative. The OSGi framework is a module system and service platform for the Java programming language that implements a complete and dynamic component model.

iPOJO

Dynamic service-oriented component runtime for OSGi.

Bundle

A Bundle object is the access point to define the lifecycle of a package installed on an OSGi platform.

Chapter 1. Introduction

This chapter gives the rationale of Camel/JOnAS 5 integration, and provides a few informations about its internals.

1.1. Motivations for Camel/JOnAS 5 integration.

JOnAS 5 is a modular application server that easily reconciles JavaEE and OSGi worlds. It integrates easily with other servers and tools, thus creating among other things, the possibility of extending its technical services. The integration of Camel in JOnAS 5 addresses the need for mediation and routing engine as technical service.

1.2. Camel in JOnAS 5.

In JOnAS 5, Camel is provided as a technical OSGi service. The main features will be presented later.

Chapter 2. Downloading Camel/JOnAS 5 integration.

Camel/JOnAS 5 integration, is delivered as a JOnAS assembly, extended with Camel bundles and configuration files.

Alternatively, you can also download the Camel bundles with the JOnAS deployment plans, in order to integrate it with any other version of JOnAS 5.x OSGi:

Chapter 3. Installing and running

As the project is a JOnAS 5 assembly, please refer to JOnAS 5 documentation.

Chapter 4. Here is a description of Camel service provided in JOnAS 5.

As said above, Camel is provided as a technical OSGi service. The OSGi service and Camel contexts can be injected into user applications thanks to iPOJO.

Get injected Camel service:

    <component classname="componentClass"
    name="instanceName" public="false" immediate="true"> 
       <requires  field="camelService" /> 
    </component>

Get injected Camel context:

    <component classname="componentClass"
    name="instanceName" public="false" immediate="true">
       <requires  field="camelContext" /> 
    </component>

4.1. Main features of Camel service.

- Start/Stop the service.

- Create and register a Camel context wich is associated a given name, or get an existing one by providing its name.

- Start a Camel context(create it or not) and return its reference or name.

- Stop a Camel context by providing its name.

- Get the names of Camel contexts managed by the service.

- Add a route to a given Camel context.

- Get all the routes of a given Camel context.

- Add/Remove entries parsed from a registry(xml) file to/from the registry of a given context.

- Add a component (org.apache.camel.Component) to a given Camel context.

Chapter 5. Using registry for static directory.

This chapter explains how to manipulate the registry which is devoted to interactions with a static directory(xml file), aka file registry.

5.1. Rationale

Why a special registry is dedicated to static directory ?

The Camel context represents a single Camel routing rulebase wich is associated a regitry. Camel built in JOnAS 5, implements the specialization of the registry. Users interact with a single registry, wich is actually a federation of several registries. The first one is a JNDI registry, which is associated to any Camel context by default. Another one is dedicated to objects registered via the OSGi platform. A third one, which interests us, is devoted to interactions with a static directory.

5.2. How does it work ?

The file registry could be associated to a Camel context through the wrapper class org.ow2.jonas.camel.registry.api.RegistryWrapper. This wrapper also allows to register / unregister entries from xml file.

Here is an example code.

 
    // Create the registry wrapper. RegistryWrapper
    registryWrapper = new RegistryWrapper(); 
    // Get a Camel context. 
    CamelContext ctxt = new DefaultCamelContext();
    // Assign the context to the registry.
    registryWrapper.createRegistryAssign2Context((DefaultCamelContext) ctxt);
    

In this example, The wrapper performs its association with a org.apache.camel.impl.DefaultCamelContext through the method addToTheRegistryThis method creates a composite registry, containing the current registry in the context, and a file registry. The resulting registry is then associated to the current context. A org.apache.camel.impl.DefaultCamelContext is required to do so, as the base API org.apache.camel.CamelContext does not allow to assign registry to a context.

This limitation is bypassed by following these steps.

 
    // Get the Camel context. CamelContext ctxt = new
    DefaultCamelContext(); 
    // Create the registry wrapper RegistryWrapper
    registryWrapper = new RegistryWrapper(); 
    // Create the registry, and assign the context to it. Registry reg =
    this.registryWrapper.createRegistry(ctxt); 
    // Assign the registry to the context. 
    ((DefaultCamelContext) ctxt).setRegistry(reg);

In the above example, the wrapper merely creates the composite registry, and assign the context to it. The caller assumes to assign the resgistry to the context.

Once the registry is created, it's possible to register/unregister entries into/from it.

 
    // Load the registry file. 
    InputStream stream = Thread.currentThread().getContextClassLoader().getResourceAsStream("registry-add.xml");
    // Register entries.
    registryWrapper.addToTheRegistry(stream);
 
    // Load registry file. 
    InputStream stream = Thread.currentThread().getContextClassLoader().getResourceAsStream("registry-remove.xml");
    // Unregister entries.
    registryWrapper.removeFromTheRegistry(stream);

Here is an example of registry file.

    <registry xmlns="http://jonas.ow2.org/camel-file-registry-1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://jonas.ow2.org/camel-file-registry-1.0 
    http://jonas.ow2.org/ns/camel-registry-api/file-registry-1.0.xsd">
       <entry> 
           <logicalName>queue</logicalName>
           <technicalName> test-jms:queue:sampleQueue </technicalName>
      </entry> 
      <entry> 
           <logicalName>queue2</logicalName>
           <technicalName>test-jms:queue:sampleQueue2</technicalName>
      </entry> 
      <entry>
           <logicalName>multiline-with-spaces</logicalName>
           <technicalName>file://C:/Documents and Settings/My User</technicalName> 
      </entry>
    </registry>
    

Chapter 6. The iPOJO CAMEL component for JOnAS.

For easier usage, the camel-component-for-jonas module can also be used for instanciation CAMEL routes. That component creates a CAMEL context (that's at the same time an iPOJO context as well) with:

6.1. Main features of the iPOJO CAMEL component for JOnAS.

- CAROL classes accessed, so that the BND tool automatically adds CAROL-related classes to the bundle's Import-Package declarations.

- All CAMEL XML registry files and XML registry property files read from $JONAS_BASE/conf and injected into the CAMEL context.

- The local JNDI registry added to the CAMEL context's registry, to ease lookups with the jdbc component for instance.

- The JMS component bound on the JNDI registry.

- The bundle's class loader positioned on the current thread, to avoid any class loading issues with dynamic components such as JNDI, JMS or CXF.

- The CAMEL trace component logging into the logger named org.ow2.jonas.camel.traces.

- If RouteBuilderComponent.traceDestination is not null, traces also sending a message to that endpoint.

In order to use it:

6.2. How to use the iPOJO CAMEL component for JOnAS.

- Override the RouteBuilderComponent.configure() method, making sure you first call super.configure() in your implementation.

- Make sure the org.ow2.jonas.camel.component package is in your bundle's Private-Package list.

- Make sure the metadata.xml file has the required definitions:

<ipojo ...
...
  <component ...
...
     <requires optional="false"
                  specification="org.ow2.jonas.camel.service.api.ICamelService">
       <callback type="bind" method="setCamelService" />
     </requires>
 
     <callback transition="validate" method="start" />
     <callback transition="invalidate" method="stop" />
...
  </component>
...
</ipojo>