Skip Navigation Links | |
Exit Print View | |
![]() |
Oracle Java CAPS POJO Service Engine User's Guide Java CAPS Documentation |
Providing and Consuming JBI Services
Getting the Consumer Instance Dynamically
Creating POJO Service Engine Projects
Creating a POJO Service Provider (Without Binding)
To Create a POJO Service Provider (Without Binding)
Creating a POJO Service Provider (With Binding)
To Create a POJO Service Provider (With Binding)
Creating a POJO Service Provider in an Existing Java Application
To Create a POJO Service Provider in a Java Application
Creating a POJO Service Consumer (Without Binding)
To Create a POJO Service Consumer (Without Binding)
Creating a POJO Service Consumer (With Binding)
To Create a POJO Service Consumer (With Binding)
POJO Service Provider Properties
POJO Service Properties for Binding
POJO Service Consumer Properties
Creating Composite Applications for POJO Service Engine Projects
Creating a Composite Application for a POJO Service Provider (Without Binding)
To Create a Composite Application for a POJO Service Provider (Without Binding)
Creating a Composite Application for a POJO Service Provider (With Binding)
To Create a Composite Application for a POJO Service Provider (With Binding)
Creating a Composite Application for a POJO Service Consumer (Without Binding)
To Create a Composite Application for a POJO Service Consumer (Without Binding)
Creating a Composite Application for a POJO Service Consumer (With Binding)
To Create a Composite Application for a POJO Service Consumer (With Binding)
Invoking POJO Services from a Business Process
To Invoke a POJO Service from a Business Process
To Create the Composite Application
Calling a Business Process From a POJO Service
To Call a Business Process From a POJO Service
To Create the Composite Application
Configuring Runtime Properties for the POJO Service Engine
To Configure POJO SE Runtime Properties
POJO Service Engine Runtime Property Descriptions
POJO Service Engine API Annotation and Classes
POJO Service Engine API Annotations
The following topics provide information to help you understand how services are provided and consumed using the POJO Service Engine:
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.
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.
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.
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);
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; } }
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 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.
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.