User Guide 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.

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

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

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

- 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.

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.

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>
    

- 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.

- 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>