POJO Service Engine User Guide

POJO Service Engine

POJO service engine lets user use annotations and simple API classes to develop JBI services and consume JBI services.

Complete POJO SE API Java Doc is here.

API Annotations and classes

POJO Service Engine API defines below annotations.

Provider - org.glassfish.openesb.pojose.api.annotation.Provider
A class level annotation used to designate a Java class as POJO service.

Operation - org.glassfish.openesb.pojose.api.annotation.Operation
A method level annotation used to designate a operation as POJO service method.

ConsumerEndpoint - org.glassfish.openesb.pojose.api.annotation.ConsumerEndpoint
A field level annotation to designate field of type org.glassfish.openesb.pojose.api.Consumer. POJO SE will inject this instance before calling POJO operation method.

Resource - org.glassfish.openesb.pojose.api.annotation.Resource
A field level annotation to designate field of type org.glassfish.openesb.pojose.api.res.Context. POJO SE will inject instance before calling POJO operation method.

OnReply - org.glassfish.openesb.pojose.api.annotation.OnReply
A method level annotation used to designate a method to be invoked when reply message from JBI Service called asynchronously is received.
Note fault and error messages are only handled by methods annotated with OnFault and OnError and will not get routed to method annotated with OnReply.
If user does not have OnFault or OnError annotated methods, faults or error messages are ignored after they are logged at Severe level.

OnDone - org.glassfish.openesb.pojose.api.annotation.OnDone
A method level annotation used to designate a method to be invoked when all the outstanding reply messages from JBI Services called asynchronously are received.

OnError - org.glassfish.openesb.pojose.api.annotation.OnError
A method level annotation used to designate a method to be invoked when asynchronous JBI Services call results in JBI error status.
Note fault and error messages are only handled by methods annotated with OnFault and OnError and will not get routed to method annotated with OnReply.
If user does not have OnFault or OnError annotated methods, faults or error messages are ignored after they are logged at Severe level.

OnFault - org.glassfish.openesb.pojose.api.annotation.OnFault
A method level annotation used to designate a method to be invoked when asynchronous JBI Services call results in JBI fault status.
Note fault and error messages are only handled by methods annotated with OnFault and OnError and will not get routed to method annotated with OnReply.
If user does not have OnFault or OnError annotated methods, faults or error messages are ignored after they are logged at Severe level.

POJO Service Engine API non annotation classes

Context - org.glassfish.openesb.pojose.api.res.Context
When field is annotated with @Resource (i.e org.glassfish.openesb.pojose.api.annotation.Resource), an instance of Context is inject by POJO SE, before POJO instance method is invoked.
Context instance can be used to lookup JNDI resources, lookup ServiceEndpoints, get an instance of Consumer, access MessageExchange, and create new MessageExchange.

Consumer - org.glassfish.openesb.pojose.api.Consumer
When field is annotated with @ConsumerEndpoint(i.e org.glassfish.openesb.pojose.api.annotation.ConsumerEndpoint), an instance of Consumer is inject by POJO SE, before POJO instance method is invoked. Consumer instance can be used to consume JBI services both synchronously and asynchronously. Consumer.sendSynchInOnly()
and sendSynchInOut methods can be used to send messages in synchronous mode and methods sendInOnly() and sendInOut for sending and receiving messages
asynchronously. Consumer instance can also be used to create MessageExchanges specific to the ServiceEndpoint the field is annotated with.

ErrorMessage - org.glassfish.openesb.pojose.api.ErrorMessage
A POJO class can throw this object from its @Opeation method to send JBI error status to the caller of the service. \Noteuser needs to specifically throw FaultMessage if he intends to send back fault message or else ErrorMessage if ME needs to be returned with error status and Exception. If there is runtime exception, ME with "error" status and exception will be sent back.

FaultMessage - org.glassfish.openesb.pojose.api.FaultMessage
A POJO class can throw this object from its @Opeation method to send JBI fault status to the caller of the service. \Noteuser needs to specifically throw FaultMessage if he intends to send back fault message or else ErrorMessage if ME needs to be returned with error status and Exception. If there is runtime exception, ME with "error" status and exception will be sent back.

Deprecated API classes

Click here to see deprecated API Classes.

Relevant JBI API classes

NormalizedMessage - javax.jbi.messaging.NormalizedMessage
MessageExchange - javax.jbi.messaging.MessageExchange
ServiceEndpoint - javax.jbi.servicedesc.ServiceEndpoint


Return to the top

Transaction And Security Context Propagation

POJO SE propagates Transaction context, security Subject to all the services called in synch mode.
POJO SE also sets the transaction context onto the Thread executing POJO operation. Thus XA resources access will be automatically enlisted in global transaction.
See Consuming Services Synchronously and Consuming Services Asynchronously for more details.

Return to the top

Accessing Glassfish JNDI context

Glassfish JNDI context can be accessed when POJO SE is running in Glassfish environment through POJO SE Context object as shown below.

@Resource
org.glassfish.openesb.pojose.api.res.Context jbiCtx;
...
public String someOperation(String inp){
    ...
    javax.naming.InitialContext context = jbiCtx.getNamingContext();
    DataSource ds = (DataSource) context.lookup("jdbc/sampleDerbyXA");
    ...
}
...

Return to the top

Consuming Services Asynchronously

Click here for details.

POJO SE Threading Model

Click here for the proposed POJO SE Threading Model.

Configuring runtime parameters

POJO SE exposes MBeans which can be used from NB IDE, Glassfish Web Admin console and JConsole to configure runtime parameters.

POJO SE internally uses ThreadPoolExecutor to process incoming MessageExchanges. Below ThreadPoolExecutor parameters can be configured thru POJO SE MBeans.

Configuring runtime parameters using Netbeans IDE.

If you have IDE installed using Glassfish ESB or OpenESB installer you may already have the components needed.
Click of "Services" tab, select "Servers" node, start the Glassfish server is it is not.
Expand "JBI" and then "Service Engines" node. Right click on "openesb-pojo-engine" node, select "properties".





You can also configure the parameters while installing Service Engine thru IDE.
IDE will prompt with screen containing the parameters.

Systemic Qualities

Click here details on Systemic Qualities in POJO SE.


Return to the top


Access complete POJO SE API Java Doc from here.

Return to the top

Return to POJO SE Page

This page (revision-37) was last changed on 06-Nov-09 17:31 PM, -0800 by GirishPatil.
This page was created on 18-Sep-08 09:39 AM, -0700 by GirishPatil.

More info...