JBI Component Framework

JCF (JBI Component Framework) is a ServiceMix subproject aiming at simplifying the writing of standard JBI components. This helps you focusing on the business logic (for a Service Engine) or the protocol side (Binding Component), instead of having to dive into the JBI Api and the JBI specification (though the spec is really readable, an overview is given here).

Contents

Other Links

Mandatory concepts

The two most important concepts in JCF are Endpoints and Component. An JCF endpoint represents a JBI endpoint: usually a Service Unit deployed on this component will contain a JCF endpoint definition. When started, this JCF endpoint will activate a JBI endpoint so that it can receive and process JBI exchanges. The component is a container of endpoints and manages their lifecycles, deployment, etc ...

Component

The component is one of the two mandatory classes that you will have to implement. JCF provides a very easy to use class that you should inherit called DefaultComponent.

The same class will be used to implement a Binding Component and a Service Engine. It handles the JBI component life cycle, service unit management, and all the services defined in the JBI specification.

This class is abstract and you will need to implement a few methods to start using it. Those are:

Those methods are related to the next concept, but are quite easy to grok. The getConfiguredEndpoints is used in the lightweight deployment mode, where the component is configured statically with its endpoints. This method will return the list of JCF endpoints contained by this component.
The getEndpointClasses method is used when validating a XBean based deployment, to make sure the deployed endpoint is correct. The component should return a list of known endpoint classes that will be accepted.

The code snippet on the right shows the most simple component. This rather simple code will create a full-blown JBI component, supporting deployment of service units, and all the advanced features provided by JCF !

Note the @XBean pseudo-annotation which is used by the xbean plugin to generate an xml schema we will leverage for deployment ...

Simple component

package com.foo;

import java.util.List;
import org.apache.servicemix.common.DefaultComponent;

/**
 * @org.apache.xbean.XBean element="component"
 */
public class MyComponent extends DefaultComponent {
  private MyEndpoint[] endpoints;

  public MyEndpoint[] getEndpoints() {
    return endpoints;
  }
  public void setEndpoint(MyEndpoint[] endpoints) {
    this.endpoints = endpoints;
  }

  protected List getConfiguredEndpoints() {
    return asList(endpoints);
  }

  protected Class[] getEndpointClasses() {
    return new Class[] { MyEndpoint.class };
  }
}

Endpoints

Endpoints are the most important concept in JCF. This is where the business logic or the specific protocol handling will take place. A JCF endpoint is the configuration unit for a given component: endpoints can be deployed inside a service unit, or configured in a static configuration file. They are mapped to JBI endpoints and can be divided in two categories:

provider endpoints will receive and process JBI exchanges, either to implement business logic in a Service Engine, or to proxy an external service in a Binding Component
consumer endpoints will receive requests from an external service and send a JBI exchange (Binding Component)

All endpoints must inherit the Endpoint class, but you will usually prefer a more specialized derived class from the following hierarchy:

Endpoint
- SimpleEndpoint
  - ConsumerEndpoint: base class for BCs consumer endpoints
    - PollingEndpoint: specialized class for consumer enpoints in Binding Components working with a polling method
  - ProviderEndpoint: base class for SEs endpoints and provider endpoints in BCs

Provide endpoint

package com.foo;

import javax.jbi.messaging.MessageExchange;
import javax.jbi.messaging.NormalizedMessage;

import org.apache.servicemix.common.endpoints.ProviderEndpoint;

/**
 * @org.apache.xbean.XBean element="provider"
 */
public class MyProviderEndpoint extends ProviderEndpoint {

    protected void processInOut(
                  MessageExchange exchange, 
                  NormalizedMessage in, 
                  NormalizedMessage out) throws Exception {
      // TODO: process in message and populate out message
    }

}