Standard APIs for a Queue Handler (Oracle Workflow Developer's Guide)

Oracle Workflow Developer's Guide
Release 2.6.3.5
Part Number B12161-02


	Previous	Next		Contents	Index	Glossary

Standard APIs for a Queue Handler

When you define an agent in the Business Event System, you must assign the agent a queue handler. The queue handler is a package that translates between the standard Workflow event message format defined by the WF_EVENT_T datatype and the message format required by the queue associated with the agent. In Oracle Applications, a Java queue handler translates between the BusinessEvent object format and the queue's message format.

Oracle Workflow provides two standard queue handlers for queues that use the WF_EVENT_T format, WF_EVENT_QH for normal processing and WF_ERROR_QH for error queues. Oracle Workflow also provides a standard queue handler named WF_EVENT_OJMSTEXT_QH for queues that use JMS Text messages as their payload format.

You can also create your own custom queue handlers for queues that use other formats. If you create a custom queue handler, you must provide standard enqueue and dequeue APIs in your package. Java queue handlers must also include some other standard APIs.

Standard APIs for a PL/SQL Queue Handler

Enqueue

The Enqueue procedure in a queue handler package must enqueue an event message onto a queue associated with an outbound agent. You can optionally specify an override agent where you want to enqueue the event message. Otherwise, the event message is enqueued on the From Agent specified within the message. The Enqueue procedure transforms the event message's header information if necessary to enqueue the message in the format required by the queue.

When an event message is being sent, the generic WF_EVENT.Enqueue procedure determines which queue handler is associated with the specified outbound agent and calls the Enqueue procedure in that queue handler to enqueue the message.

The PL/SQL Enqueue procedure must have the following standard API:

procedure enqueue (p_event in WF_EVENT_T,

                   p_out_agent_override in WF_AGENT_T);

The arguments for the procedure are as follows:

p_event The event message.

p_out_agent_ override The outbound agent on whose queue the event message should be enqueued.

Dequeue

The Dequeue procedure in a queue handler package must dequeue an event message from the queue associated with the specified inbound agent, selecting the message to dequeue by the message priority. The procedure transforms the event message's header information if necessary and returns the event message in the standard WF_EVENT_T structure. Additionally, the Dequeue procedure can set the date and time when the message is dequeued into the RECEIVE_DATE attribute of the event message.

When an event message is being received, the WF_EVENT.Listen procedure determines which queue handler to use with the specified inbound agent and calls the Dequeue procedure in that queue handler to dequeue the message.

The PL/SQL Dequeue procedure must have the following standard API:

procedure dequeue (p_agent_guid in raw,

                   p_event out WF_EVENT_T);

The arguments for the procedure are as follows:

p_agent_guid The globally unique identifier of the inbound agent from whose queue the event message should be dequeued.

p_event The event message.

Standard APIs for a Java Queue Handler

In Oracle Applications only, you can provide a Java queue handler to be executed during Java event message processing in the middle tier, instead of a PL/SQL queue handler. A Java queue handler must be a Java class using the following Java interface:

public interface QueueHandlerInterface

{

  public void init(Connection conn,

                  AgentEO agent,

                  Log log,  

                  String uniqueLogId,

                  Properties props)

    throws QueueHandlerException;



  public String enqueue(BusinessEvent event) 

    throws QueueHandlerException;



  public BusinessEvent dequeue()

    throws QueueHandlerException;



  public void destroy(); 



  public String getMsgId()

    throws QueueHandlerException;



  public CLOB getEventData();

}

In addition to the enqueue and dequeue APIs, a Java queue handler must also contain methods to initialize the connection to the agent, destroy objects created during queue processing after the processing is complete, retrieve a message ID from a message on the queue, and retrieve the CLOB reference to the event data of the last business event dequeued by the queue handler.

The arguments for the init method are as follows:

conn The JDBC connection used to establish the connection with the queue.

agent The AgentEO object that contains the information for this agent and its queue.

log The Log object which can be used for logging.

uniqueLogId The log ID for recording debug messages.

props The property mapping for enqueue and dequeue operations.

The argument for the enqueue method is as follows:

event The BusinessEvent object to be enqueued.