POJO Service Engine API Annotation and Classes

The POJO Service Engine provides a very simple API for defining consumers and providers using POJO. Some of the objects are annotated for ease of use. The complete POJO Service Engine API Javadoc is at /https://open-esb.dev.java.net/nonav/pojose/javadoc/.

The following sections list and describe the POJO annotations and classes, along with the relevant JBI classes:

• POJO Service Engine API Annotations

• POJO Service Engine Non-Annotated Classes

• JBI API Classes Relevant to the POJO Service Engine

POJO Service Engine API Annotations

The annotations listed and described below are provided in the POJO Service Engine API to simplify the necessary coding.

• Provider - org.glassfish.openesb.pojose.api.annotation.Provider

  A class-level annotation that designates a Java class as a POJO service.

• Operation - org.glassfish.openesb.pojose.api.annotation.Operation

  A method-level annotation that designates an operation as a POJO service method.

• ConsumerEndpoint - org.glassfish.openesb.pojose.api.annotation.ConsumerEndpoint

  A field-level annotation that designates fields of the type org.glassfish.openesb.pojose.api.Consumer. The POJO SE injects this instance before calling the POJO operation method.

• Resource - org.glassfish.openesb.pojose.api.annotation.Resource

  A field-level annotation that designates field of the type org.glassfish.openesb.pojose.api.res.Context. The POJO SE injects the instance before calling the POJO operation method.

• OnReply - org.glassfish.openesb.pojose.api.annotation.OnReply

  A method-level annotation that designates a method to be invoked when the reply message from the asynchronously called JBI service is received.

  ---

  Note –

  Fault and error messages are only handled by methods annotated with OnFault and OnError and will not get routed to methods annotated with OnReply. If you do not have OnFault or OnError annotated methods, faults or error messages are ignored after they are logged at the Severe level.

  ---

• OnDone - org.glassfish.openesb.pojose.api.annotation.OnDone

  A method-level annotation that designates a method to be invoked when all the outstanding reply messages from asynchronously called JBI services are received.

• OnError - org.glassfish.openesb.pojose.api.annotation.OnError

  A method-level annotation that designates a method to be invoked when an asynchronous JBI services call results in a JBI error status. See the note above for information about using OnReply, OnError, and OnFault.

• OnFault - org.glassfish.openesb.pojose.api.annotation.OnFault

  A method-level annotation that designates a method to be invoked when an asynchronous JBI services call results in a JBI fault status.

POJO Service Engine Non-Annotated Classes

The classes listed and described below define the non-annotated objects of the POJO Service engine API.

• Context - org.glassfish.openesb.pojose.api.res.Context

  When a field is annotated with @Resource (org.glassfish.openesb.pojose.api.annotation.Resource), the POJO SE inserts an instance of Context before invoking the POJO instance method. A Context instance can be used to look up JNDI resources, look up service endpoints, retrieve an instance of Consumer, access a MessageExchange object, and create a new MessageExchange object.

• Consumer - org.glassfish.openesb.pojose.api.Consumer

  When a field is annotated with @ConsumerEndpoint (org.glassfish.openesb.pojose.api.annotation.ConsumerEndpoint), the POJO SE inserts an instance of Consumer before invoking the POJO instance method. A Consumer instance can be used to consume JBI services both synchronously and asynchronously. Consumer.sendSynchInOnly() and sendSynchInOut methods are used to send messages in synchronous mode, and sendInOnly() and sendInOut are used to send and receive messages asynchronously. A Consumer instance can also be used to create a MessageExchanges object specific to the ServiceEndpoint that annotates the field.

• ErrorMessage - org.glassfish.openesb.pojose.api.ErrorMessage

  A POJO class can throw an ErrorMessage object from its @Opeation method to send the JBI error status to the caller of the service.

  ---

  Note –

  You need to specifically throw a FaultMessage exception to return a fault message; otherwise, throw an ErrorMessage exception to return the MessageExchange with the error status and exception. If there is a runtime exception, the MessageExchange is returned with a status of "error" and an exception.

  ---

• FaultMessage - org.glassfish.openesb.pojose.api.FaultMessage

  A POJO class can throw a FaultMessage object from its @Operation method to send the JBI fault status to the caller of the service. See the above note for information about when to use ErrorMessage and when to use FaultMessage.

JBI API Classes Relevant to the POJO Service Engine

The following classes from the JBI API are used with the POJO Service Engine:

• NormalizedMessage (javax.jbi.messaging.NormalizedMessage)

• MessageExchange (javax.jbi.messaging.MessageExchange)

• ServiceEndpoint (javax.jbi.servicedesc.ServiceEndpoint)