Subscribers and Dequeuing Messages

16-6 Oracle Fusion Middleware Developers Guide for Oracle Portal – In PLSQL you supply the consumer name using the CONSUMER_NAME field in the DEQUEUE_OPTIONS_T record. – In OCI you supply the consumer name using the OCISetAttr procedure to specify a text string as the OCI_ATTR_CONSUMER_NAME of an OCI_ DTYPE_AQDEQ_OPTIONS descriptor. – In Visual Basic OO4O you supply the consumer name by setting the consumer property of the OraAQ object. Multiple processes or operating system threads can use the same to dequeue concurrently from a queue. Unless the message ID of a specific message is specified during dequeue, the consumers can dequeue messages that are in the READY state.

16.2.3 Exception Handling

A message is considered processed when all intended consumers have successfully dequeued the message. If a message cannot be processed for some reason, it moves to an exception queue. A message is considered expired if one or more consumers does not dequeue it before the expiration time. Expired messages also move to an exception queue. An exception queue is a repository for all expired or unserviceable messages. Applications cannot directly enqueue into exception queues. Also, an exception queue cannot have subscribers associated with it. However, an application that intends to handle these expired or unserviceable messages must dequeue from the exception queue. CMEF exceptions are sent to the WWSBR_EVENT_ERR_Q exception queue. Expired messages from the WWSBR_EVENT_Q multiconsumer queue cannot be dequeued by the intended recipients of the message. However, they can be dequeued in REMOVE mode once by specifying a NULL consumer name in the dequeue options. The queue monitor removes expired messages from multiconsumer queues. This allows dequeuers to complete the dequeue operation by not locking the message in the queue table. Since the queue monitor removes messages that have been processed by all consumers from multiconsumer queues at regular intervals, users may see a delay between when the messages have been completely processed and when they are physically removed from the queue.

16.2.4 Listening for Messages

Oracle Streams AQ can monitor multiple queues for messages with a single LISTEN call. A subscriber can use LISTEN to wait for messages for multiple subscriptions. It can also be used by gateway applications to monitor multiple queues. If the LISTEN call returns successfully, a dequeue must be used to retrieve the message. Without the LISTEN call, an application which sought to dequeue from a set of queues would have to continuously poll the WWSBR_EVENT_Q queue to determine if there is a message. Note: You should not need to use the Search parameters to dequeue CMEF events. Note: The WWSBR_EVENT_ERR_Q exception queue, like all exception queues, is a single-consumer queue. Using the Content Management Event Framework 16-7 Alternatively, you could design your subscriber to have a separate dequeue process for each queue. However, if there are long periods with no traffic in any of the queues, including WWSBR_EVENT_Q, these approaches will create unacceptable overhead. The LISTEN call is well suited for such subscribers. When there are messages for multiple agents in the agent list, LISTEN returns with the first agent for whom there is a message. You can use the LISTEN call to monitor receipt of messages on one or more queues on behalf of a list of agents. The call takes a list of agents as an argument. You specify the queue to be monitored in the address field of each agent listed. You also must specify the name of the agent when monitoring multiconsumer queues. Example 16–3 shows how to use the LISTEN call to listen to messages on multiple queues. Example 16–3 Listening to Messages on Multiple Queues declare agent_w_msg aqagent; qlist dbms_aq.agent_list_t; begin -- MYQ1, MYQ2, MYQ3 are multiconsumer queues in the SCOTT schema. qlist1 := aqagentagent1, scott.MYQ1, null; qlist2 := aqagentnull, scott.MYQ2, null; qlist3 := aqagentagent3, scott.MYQ3, null; -- Listen with a timeout of 100 seconds. dbms_aq.listen agent_list = qlist, wait = 100, agent = agent_w_msg ; dbms_output.put_lineMSG in Q: ||agent_w_msg.address||for ||agent_w_msg.name; dbms_output.put_line; end; This is a blocking call that returns when there is a message ready for consumption for an agent in the list. If there are messages for more than one agent, only the first agent listed is returned. If there are no messages found when the wait time expires, an error is raised. A successful return from the call is only an indication that there is a message for one of the listed agents in one of the specified queues. The interested agent should dequeue the relevant message. Example 16–4 illustrates the dequeue process combined with listening. Here, we dequeue the messages for the subscriber, JAY, for a certain time period. Example 16–4 Listening and Dequeuing Messages begin agent_list1 := sys.aq_agentJAY, WWSBR_EVENT_Q, null; wait_time integer := 100; loop -- Wait for order status messages. dbms_aq.listen agent_list = agent_list, wait = wait_time, agent = agent_w_message ; -- If there are messages for JAY, dequeue them. if agent_w_message.name = JAY then 16-8 Oracle Fusion Middleware Developers Guide for Oracle Portal dequeue_options.wait := dbms_aq.NO_WAIT; dequeue_options.consumer_name := JAY; dequeue_options.navigation := dbms_aq.FIRST_MESSAGE; dequeue_options.dequeue_mode := dbms_aq.BROWSE; dbms_aq.dequeue queue_name = item_queue, dequeue_options = dequeue_options, message_properties = message_properties, payload = message, msgid = message_handle ; end if; end loop; exception when NO_MESSAGES then dbms_output.put_lineNo more messages for Jay; end;

16.3 Using the Content Management Event Framework

Every portal item and page action generates a CMEF message that is enqueued to the WWSBR_EVENT_Q queue. A subscriber can use the information contained within this message to perform various actions using the Oracle Portal PLSQL APIs. There are three basic steps in handling CMEF events, each of which is described and illustrated later in this section. These steps are as follows: 1. Section 16.3.1, Creating Subscriber Code 2. Section 16.3.2, Adding a Subscriber to WWSBR_EVENT_Q 3. Section 16.3.3, Enabling CMEF Events at the Page Group Level This section also provides a description of the message payload, followed by several examples of common portal actions and the events they generate.

16.3.1 Creating Subscriber Code

Oracle Streams AQ offers a content-based subscription model. Subscriber applications can specify interest based on message content. You should execute CMEF event subscriber code in the Oracle Portal schema. Example 16–5 shows a sample subscriber. Example 16–5 An Example Subscriber create or replace procedure name as agent_list dbms_aq.aq_agent_list_t; wait_time integer := time in seconds; agent_w_message sys.aq_agent; dequeue_options dbms_aq.dequeue_options_t; message_properties dbms_aq.message_properties_t; message_handle raw16; message portal schema.wwsbr_event; l_subscriber varchar230 := subscriber name; l_queue varchar230 := PORTAL.WWSBR_EVENT_Q; l_mode binary_integer := dbms_aq.[BROWSE|LOCK|REMOVE|REMOVE_NODATA]; ... additional parameters ... BEGIN Using the Content Management Event Framework 16-9 agent_list1 := sys.aq_agentl_subscriber, l_queue, null; loop -- Listen for messages. dbms_aq.listen agent_list = agent_list, wait = wait_time, agent = agent_w_message ; -- If there are messages for the subscriber then dequeue them. if agent_w_message.name = l_subscriber then dequeue_options.wait := dbms_aq.NO_WAIT; dequeue_options.consumer_name := l_subscriber; dequeue_options.navigation := dbms_aq.[NEXT_MESSAGE|FIRST_MESSAGE]; dequeue_options.dequeue_mode := l_mode; -- Dequeue messages. dbms_aq.dequeue queue_name = l_queue, dequeue_options = dequeue_options, message_properties = message_properties, payload = message, msgid = message_handle ; -- Determine the type of event that occurred and act accordingly. ... your code here ... end if; end loop; -- Process cache invalidation messages. wwpro_api_invalidation.execute_cache_invalidation; end;

16.3.2 Adding a Subscriber to WWSBR_EVENT_Q

A subscriber subscribes to a queue from where it consumes messages. You have to add a subscriber to the WWSBR_EVENT_Q queue in order to process CMEF event messages, as shown in Example 16–6 . Example 16–6 Adding a Subscriber to WWSBR_EVENT_Q declare subscriber sys.aq_agent; begin subscriber := sys.aq_agentsubscriber, null, null; dbms_aqadm.add_subscriber queue_name = portal schema.wwsbr_event_q, subscriber = subscriber ; end;

16.3.3 Enabling CMEF Events at the Page Group Level

In Oracle Portal, CMEF is enabled or disabled at the page group level. By default, CMEF is enabled when a user creates a page group, and thus, events are triggered whenever changes occur within the Oracle Portal user interface or WebDAV. To enable or disable CMEF for a page group, perform the following steps: