When you define an agent in the Business Event System, you must assign the agent a queue handler. A PL/SQL 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. 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.

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:

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.

You can optionally call the dequeue navigation APIs WF_EVENT.setNavigationParams, WF_EVENT.resetNavigationParams, and WF_EVENT.getQueueNavigation within a custom Dequeue procedure to control the order in which messages are dequeued. See: Event APIs.

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:

You can optionally 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:

The argument for the enqueue method is as follows: