Providing and Consuming JBI Services

The following topics provide information to help you understand how services are provided and consumed using the POJO Service Engine:

• Providing a JBI Service

• Consuming a JBI Service

• Consuming Services Asynchronously

• Using Multiple Threads

Providing a JBI Service

With just two annotations, @Provider and @Operation, you can enable a Java class as JBI service. Below is an example of a simple POJO service provider.

package org.glassfish.openesb.pojo.sample;
import org.glassfish.openesb.pojose.api.annotation.Operation; 
import org.glassfish.openesb.pojose.api.annotation.Provider; 
@Provider 
public class Echo {
     @Operation (outMessageType="EchoOperationResponse", 
                 outMessageTypeNS="http://sample.pojo.openesb.glassfish.org/Echo/")
     public String receive(String input) {
            return input;
     } 
}

The properties for @Operation annotation are not mandatory, but may be needed if the JBI component interacting with the POJO SE expects the JBI message type QName on the JBI wrapper message element. Defaults are assumed for most of the information needed by JBI runtime. Some of the defaults are endpoint names and interface and service QNames. If not specified through @POJO annotation, the endpoint name defaults to the unqualified class name. The service and interface QName namespaces default to the HTTP URI made up of the package name in reverse with the endpoint name appended. For the above example, this would be http://tst.pojo.glassfishesb.org/Echo/. The local service name defaults to the endpoint name with “Service" appended. The local interface name defaults to the endpoint name with "Interface" appended. For the above example it will be "EchoService" and "EchoInterface" respectively.

Operation Parameter Types

The POJO SE supports the following input parameter types and return types for methods annotated with @Operation:

• java.lang.String

• org.w3c.dom.Node

• javax.xml.transform.Source

• javax.jbi.messaging.NormalizedMessage

• Document

• javax.jbi.messaging.MessageExchange (input parameter only)

• void (return type only)

When the return type is void, the JBI message exchange pattern is assumed to be InOnly. The POJO SE supports InOnly and InOut JBI message exchange patterns. For parameter and return types of String, Node, and Source, the POJO SE automates JBI WSDL 1.1 message unwrapping and wrapping.

Context

The POJO SE injects an instance of the class org.glassfish.openesb.pojose.api.res.Context when a field is annotated with @Resource (org.glassfish.openesb.pojose.api.annotation.Resource). The Context class includes the methods needed to retrieve an instance of the current MessageExchange object and a method to create a new MessageExchange objects for invoking JBI services.

Consuming a JBI Service

Using the Consumer instance inserted by the service engine, you can declare a field of the Consumer type (org.glassfish.openesb.pojose.api.Consumer) and annotate it with ConsumerEndpoint (org.glassfish.openesb.pojose.api.annotation.ConsumerEndpoint). The POJO SE uses the endpoint name and service QName specified on the ConsumerEndpoint annotation to find the ServiceEndpoint instance and insert it into the POJO instance before the operation method is called. You can optionally specify inMessageTypeQN and operationQN if required by the component being called.

Example 1 POJO Service Consumer Example

First declare the Consumer field as shown below.

@ConsumerEndpoint(name="asiaBPELProcess",
      serviceQN="AsiaSvc",
      interfaceQN="{wwOrderProcessNS}wwOrderProcessPortType",
      operationQN="{wwOrderProcessNS}wwOrderProcessOperation",
      inMessageTypeQN="{wwOrderProcessNS}wwOrderProcessOperationRequest") 
private Consumer asiaEp;

Use the Consumer instance inserted by the POJO SE, as shown below.

outputMsg = (Node) cons.sendSynchInOut(input, MessageObjectType.Node); 

Below is a complete example.

package org.glassfish.openesb.pojo.cbr;
import org.glassfish.openesb.pojose.api.annotation.Provider;
import org.glassfish.openesb.pojose.api.annotation.Operation;
import org.glassfish.openesb.pojose.api.annotation.ConsumerEndpoint;
import org.glassfish.openesb.pojose.api.Consumer;
import org.glassfish.openesb.pojose.api.Consumer.MessageObjectType;

import org.w3c.dom.Node;
import java.util.logging.Level;
import java.util.logging.Logger;

@Provider 
public class WWOrderRouter {
      @ConsumerEndpoint(name="asiaBPELProcess",
              serviceQN="AsiaSvc",
              interfaceQN="{wwOrderProcessNS}wwOrderProcessPortType",
              operationQN="{wwOrderProcessNS}wwOrderProcessOperation",
              inMessageTypeQN="{wwOrderProcessNS}wwOrderProcessOperationRequest")
     private Consumer asiaEp;

     @ConsumerEndpoint(name="europeBPELProcess",
              serviceQN="EuropeSvc",
              interfaceQN="{wwOrderProcessNS}wwOrderProcessPortType"
              operationQN="{wwOrderProcessNS}wwOrderProcessOperation",
              inMessageTypeQN="{wwOrderProcessNS}wwOrderProcessOperationRequest")

@Resource
private Context ctx;

public WWOrderRouter() {
}

@Operation(outMessageTypeQN="{http://cbr.pojo.openesb.glassfish.org/WWOrderRouter/}
  WWOrderRouterOperationResponse")
public Node receive(Node input) {
         try {
             Node outputMsg = input;

             location = ...

             Consumer cons = null;
             if ("Asia".equals(location)) {
                 svc2use = this.asiaSvcName;
                 cons = asiaEp;
             } else {
                 svc2use = this.europeSvcName;
                 cons = europeEp;
             }
             outputMsg = (Node) cons.sendSynchInOut(input, MessageObjectType.Node);

            return outputMsg;
         } catch (Exception ex) {
             Logger.getLogger(WWOrderRouter.class.getName()).log(Level.SEVERE, null,
                              ex);
         }
         return input;
     }
 }

Getting the Consumer Instance Dynamically

Use a Context method to retrieve the instance of ServiceEndpoint, and use it again to retrieve the instance of Consumer from the Context instance.

QName svc2use = ....;
String endpointName = ....;

ServiceEndpoint se = this.ctx.getEndpoint(svc2use, endpointName);
Consumer cons = this.ctx.getConsumer(se, this.consOpName, this.consInMsgType);
outputMsg = (Node) cons.sendSynchInOut(input, MessageObjectType.Node); 

Consuming Services Asynchronously

Consuming services in asynchronous mode can make using resources such as threads more efficient. Consuming services asynchronously in the POJO SE does not block the threads; instead, the control returns to the POJO code. This allows the POJO SE to execute more POJO services using fewer thread resources. Asynchronous service consumption is supported using annotated callback methods. Each of the callback methods are annotated in POJO using one of the following annotations: @OnReply, @OnError, @OnFault, or @OnDone.

The POJO SE calls the OnReply annotated method when the InOut message exchange pattern service is consumed asynchronously. This method takes two parameters. The first is of the type ServiceEndpoint and the second is one of the following types: String, Source, Node, NormalizedMessage, or MessageExchange.

The POJO SE calls the OnFault annotated method when the InOut message exchange pattern service is consumed asynchronously and the consumed service returns a fault message. This method also takes two parameters. The first is of the type ServiceEndpoint and second is of the type MessageExchange.

The POJO SE calls the OnError annotated method when the InOut message exchange pattern service is consumed asynchronously and the consumed service returns an error status. This method takes two parameters. The first one is of the type ServiceEndpoint and the second is of the type MessageExchange.

The POJO SE executes the OnDone annotated method when all the responses from asynchronously consumed services are received. Whenever POJO throws FaultMessage, ErrorMessage, or Exception back to the POJO SE, the POJO SE returns the fault message or error status back to the POJO service consumer. Further execution of callback and OnDone methods are aborted and outstanding responses from asynchronously consumed services by this POJO instance are ignored. Where possible, the error status is returned.

Using Multiple Threads

The annotations described above for asynchronous consumption are also used in the multi-threaded execution model. In this model, the POJO SE executes the POJO instance methods annotated with Operation, OnReply, OnFault, and OnError concurrently when the response messages are received. Since many transaction managers only allow one thread to be associated with a transaction, by default the transaction is not resumed while executing any of the POJO instance methods such as those annotated with Operation, OnReply, OnFault, OnError, and OnDone. Transaction objects are also not propagated to asynchronously consumed services.