33 Managing Business Events
This chapter includes the following topics:
-
Introduction to the Event Delivery Network and JMS Provider Types
-
Testing the Publishing of Business Events and Viewing the EDL File
-
Resolving Duplicate Messages for Subscribers in Clustered Environments
For information about troubleshooting business event issues, see Business Events and Event Delivery Network Troubleshooting.
For information about creating business events in Oracle JDeveloper, see Chapter "Using Business Events and the Event Delivery Network" of Developing SOA Applications with Oracle SOA Suite.
33.1 Introduction to the Event Delivery Network and JMS Provider Types
You create business events in Oracle JDeveloper and include them in SOA composite applications that you deploy to Oracle Enterprise Manager Fusion Middleware Control. Service components can subscribe to business events. When a business event is published, the entity subscribed to that event receives it.
EDN is the subsystem of Oracle SOA Suite that accepts published business events and delivers them to the subscribers. EDN uses a JMS topic as a back-end store. EDN provides two JMS-based types:
-
Oracle WebLogic Server JMS
EDN uses a default Oracle WebLogic Server JMS topic as the underlying JMS store for all event types. Figure 33-1 provides details.
Figure 33-1 JMS Topic of Oracle WebLogic Server JMS
Description of "Figure 33-1 JMS Topic of Oracle WebLogic Server JMS"The following JMS adapter connection factories are supported:
-
eis/wls/EDNxaDurableTopic (supports XA, durable topic with ClientID=edn_wljms_xa_client)
-
eis/wls/EDNxaTopic (supports XA)
-
eis/wls/EDNLocalTxDurableTopic (supports local transaction, durable topic with ClientID=edn_wljms_localtx_client)
-
eis/wls/EDNLocalTxTopic (supports a local transaction)
You can change the default JMS type. For information, see Changing the JMS Type. You can also create custom JMS topics and specify certain event types of interest to map to the custom topics.
-
-
Oracle Advanced Queueing (AQ) JMS
AQ JMS topics can also be created and used. EDN provides a preprovisioned AQ JMS topic out of the box. Figure 33-2 provides details.
AQ JMS is exposed through a foreign server.
The following JMS adapter connection factories are supported:
-
eis/aqjms/EDNxaDurableTopic (supports XA, durable topic with ClientID=edn_aqjms_xa_client)
-
eis/aqjms/EDNxaTopic (supports XA)
-
eis/aqjms/EDNLocalTxDurableTopic (supports local transaction, durable topic with ClientID=edn_aqjms_localtx_client)
-
eis/aqjms/EDNLocalTxTopic (supports a local transaction)
The following JDBC data sources are supported:
-
jdbc/EDNDataSource (supports XA)
-
jdbc/EDNLocalTxDataSource (supports local transaction)
The following foreign servers are supported:
-
EDNAQjmsForeignServer (supports XA)
-
EDNAQjmsLocalTxForeignServer (supports local transaction)
Table 33-1 describes the benefits of both JMS provider types.
Table 33-1 Comparison Between JMS Provider Types
| Oracle WebLogic Server JMS | AQ JMS |
|---|---|
|
|
Durable subscriptions are supported. This means that events are retained even if the subscriber is not up and running. Durable subscriptions continue to accumulate events. Table 33-2 describes how nondurable and durable subscriptions are handled in the various life cycle states of the SOA composite application.
Table 33-2 Business Events and Composite Life Cycle States
| The Composite Is... | Effect on Nondurable Subscribers | Effect on Durable Subscribers |
|---|---|---|
|
Deployed |
The subscriber is created and starts receiving events. |
The subscriber is created, a durable subscription is registered, and the subscriber starts receiving events. |
|
Undeployed |
The subscriber is removed and stops receiving events. |
The subscriber is removed, a durable subscription is unregistered, and the subscriber stops receiving events. |
|
Redeployed |
The durable subscription and subscriber are recreated. |
The durable subscription and its subscriber are recreated. |
|
Shut down |
The subscriber stops receiving events. |
The subscriber stops receiving events, but events continue to be queued (are not dropped) through durable subscriptions. |
|
Started up |
The subscriber starts receiving events. |
The subscriber receives events, including those queued up prior to startup. |
|
Retired |
The subscriber stops receiving events. |
The subscriber stops receiving events and events are not queued (are dropped). |
|
Activated |
The subscriber starts receiving events. |
The subscriber start receiving events. |
33.2 Mapping Business Events to JMS Topic Destinations
You can map the flow of different business events through different JMS destinations in Oracle Enterprise Manager Fusion Middleware Control. This mapping can reduce business event bottlenecks caused by mapping all business events through a single destination. After installation, all business events are mapped by default to a single, local Oracle WebLogic Server JMS topic. You can manually create additional JMS topics and map business events to the topics appropriate to your performance needs.
Note the following best practices when mapping business events to JMS topics other than the default.
-
Perform the mapping before messages flow into JMS topic destinations. This prevents existing events from flowing into old JMS topic destinations for which there are no subscribers.
-
Restart the subscribing SOA composite applications or the SOA server after completing the mapping. This enables subscribers to be associated with the new JMS topic destination.
-
Ensure that the JMS topic is configured in the Oracle WebLogic Server Administration Console. See Creating an JMS Topic .
-
Ensure that all JMS adapter connection factories are configured in the Oracle WebLogic Server Administration Console. See Optionally Creating JMS Adapter Connection Factories for JMS.
33.2.1 Creating an Oracle WebLogic Server JMS Topic
To create an Oracle WebLogic Server JMS topic:
- Create a new topic.
- Target it to SOAJMSServer.
33.2.2 Optionally Creating JMS Adapter Connection Factories for Oracle WebLogic Server JMS
It is typically unnecessary to create JMS Adapter connection factories because you can reuse the ones included with EDN installation. If you need to create connection factories (for example, for a separate management purpose), follow these steps.
To create JMS adapter connection factories for Oracle WebLogic Server JMS:
33.2.3 Creating an AQ JMS Topic
Open the Database Navigator (in Oracle JDeveloper) or SQL Developer as the soainfra user, and run the following script to create an AQ JMS topic:
define edn_user=soainfra_schema_user_here define topic=your_custom_aqjms_topic_name_here (for example, EDN_AQJMS_TOPIC_2) define topic_table=your_custom_aqjms_topic_table_here (EDN_AQJMS_TOPIC_ TABLE_2) begin DBMS_AQADM.stop_queue(queue_name => '&edn_user..&topic'); DBMS_AQADM.drop_queue(queue_name => '&edn_user..&topic'); DBMS_AQADM.drop_queue_table(queue_table => '&edn_user..&topic_table'); end; / begin dbms_aqadm.create_queue_table(queue_table => '&edn_user..&topic_table', queue_payload_type => 'SYS.AQ$_JMS_MESSAGE', multiple_consumers => true); dbms_aqadm.create_queue(queue_name => '&edn_user..&topic', queue_table => '&edn_user..&topic_table', max_retries => 256); dbms_aqadm.start_queue(queue_name => '&edn_user..&topic'); end; / commit;
The queue and queue table are created.
33.2.4 Exposing an AQ JMS Topic
If you created an AQ JMS topic in Creating an AQ JMS Topic , you must expose the topic to Oracle WebLogic Server applications, including Oracle SOA Suite applications. Use Oracle WebLogic Server Administration Console to either create a new foreign server or update the existing foreign server EDNAQjmsForeignServer to add AQ JMS topic mapping:
To expose an AQ JMS topic:
-
Optionally create a new foreign service:
-
Log in to Oracle WebLogic Server Administration Console.
-
In the Domain Structure, go to Services > Messaging > JMS Modules > SOAJMSModule.
-
Click New, and select Foreign Server.
-
Name the foreign server, target it to the SOA server, and click Finish.
-
Open the new foreign server, and go to Configuration > General.
-
Set the following properties.
Property Value JNDI Initial Context Factory
oracle.jms.AQjmsInitialContextFactory
JNDI Properties
For an EDN XA JDBC data source (for example, datasource=jdbc/EDNDataSource).
For an EDN non-XA JDBC data source (for example, datasource=jdbc/EDNLocalTxDataSource).
-
-
If you also create your custom JMS adapter connection factories for AQ JMS, then you must create a connection factory mapping:
-
Go to the Configuration > Connection Factories tab of this foreign server, and click New.
-
Provide the local JNDI name (which matches the value configured in the adapter's ConnectionFactoryLocation) and remote JNDI name, which is XATopicConnectionFactory for XA support.
-
If you must create another foreign server that uses a non-XA JDBC data source, set the remote JNDI name to TopicConnectionFactory for non-XA support.
-
-
Add mapping to the AQ JMS topic
-
Click New to create a new destination mapping in one of the newly created foreign servers or the existing foreign server EDNAQjmsForeignServer.
-
Map a local JNDI name to a remote JNDI name convention of Topics/custom_aqjms_topic_name.
-
33.2.5 Optionally Creating JMS Adapter Connection Factories for AQ JMS
It is typically unnecessary to create JMS adapter connection factories because you can reuse the ones included with EDN installation. If you must create connection factories (for example, for a separate management purpose), follow these steps.
To create JMS adapter connection factories for AQ JMS:
33.2.6 Enabling a Remote Client to Interact with an AQ JMS-Based Topic
If an event type is mapped to the default EDN AQ JMS topic or a custom AQ JMS topic, EDN enables Oracle SOA Suite publishers and subscribers to interact with this event type through the AQ JMS topic. However, EDN does not enable remote publishers or subscribers to interact by default.
To enable remote publishers, subscribers, or both, the EDN foreign servers (either the one installed by EDN or the custom foreign servers) must have their JNDI properties and credential updated, as shown in Table 33-3.
Table 33-3 JNDI Properties and Credentials
| Property Name | Property Value |
|---|---|
|
JNDI Properties |
Add: db_url=jdbc:oracle:thin:@host:port:service. java.naming.security.principal=soainfra_schema_user. |
|
JNDI Properties Credential |
Enter the password for oainfra_schema_user. |
Figure 33-3 provides details.
Figure 33-3 Enable a Remote Client to Interact with an AQ- MS-Based Topic
Description of "Figure 33-3 Enable a Remote Client to Interact with an AQ- MS-Based Topic"
33.2.7 Mapping Business Events to JMS Topic Destinations on the Business Events Page
You can map business events to JMS topic destinations on the Business Events page in Oracle Enterprise Manager Fusion Middleware Control.
To map business events to JMS topic destinations on the Business Events page:
- Access this page through one of the following options:
From the SOA Infrastructure Menu... From the SOA Folder in the Navigator... Select Business Events.
Right-click soa-infra and select Business Events.
The Business Events page displays the following details:
-
A utility for searching for a specific business event by specifying a full or partial name and clicking the Search icon. Click Help > Help For This Page under the weblogic menu for details.
-
Business events, including the namespace, event name, JMS type and mapping, number of subscriptions to each event, and number of failed event deliveries. Business events are contained within their namespace.
-
- Click the JMS topic mapping type in the column. For example, if Default is selected, the following details are displayed. The connection factory settings that are initially displayed are automatically set during installation.
For more information, see the following documentation:
-
Chapter "Using Business Events and the Event Delivery Network" of Developing SOA Applications with Oracle SOA Suite for details about business events
33.3 Testing the Publishing of Business Events and Viewing the EDL File
You can test the publishing of business events and view the EDL file contents. The business event is defined using EDL. EDL is a schema used to build business event definitions.
-
Access this page through one of the following options:
From the SOA Infrastructure Menu... From the SOA Folder in the Navigator... Select Business Events.
Right-click soa-infra and select Business Events.
The Business Events page displays the following details:
-
A utility for searching for a specific business event by specifying a full or partial name and clicking the Search icon. Click Help > Help for This Page under the weblogic menu for details.
-
Business events, including the namespace, the event name, the JMS type, the mapping between the business event and the JMS topic destination, the number of subscriptions to each event, and the number of failed event deliveries. Business events are contained within their namespace.
-
-
In the Namespaces and Events column, select a specific event to test.
-
Click Test to test the selected event. This action enables you to publish a test event that subscribers can act upon.
The Test Event dialog appears.
-
Specify the XML payload to use in the test.
-
Click Publish.
If publishing is successful, the following message is displayed.
The Event published successfully
-
-
In the Namespaces and Events column, select a specific event for which to display the EDL file.
-
Click Show Event Definition to display the EDL file for the selected event.
-
Click OK to close the message.
-
33.4 Viewing Business Event Subscribers
When business events are published, service components can subscribe to them. You can view the service components that have subscribed to business events. Service component subscriptions are created in Oracle JDeveloper during design time and cannot be modified in Oracle Enterprise Manager Fusion Middleware Control.
All business events are applicable to the entire Oracle SOA Suite domain instead of the individual partitions of the publishers and subscribers. Business events are also displayed as separate entries in the flow trace of the business flow instance.
Note:
-
If your SOA composite application includes a business event subscription, and you deploy different revisions of the composite, all event subscriptions from all revisions of the composite are active and receive messages. To receive the event with the latest revision of the composite only, it is recommended that you retire all previous revisions of the composite.
-
A BPEL component in a retired SOA composite application cannot receive a business event, even if the event is associated with a noninitiating receive activity of the BPEL process.
To view business event subscribers:
-
Access this page through one of the following options:
From the SOA Infrastructure Menu... From the SOA Folder in the Navigator... -
Select Business Events.
-
Right-click soa-infra.
-
Select Business Events.
-
-
Click Subscriptions.
The Subscriptions page displays the following details:
-
A utility for searching for a specific subscription by specifying criteria and clicking Search. You can search based on the namespace or event name. Click Help > Help for This Page under the weblogic menu for details.
-
The component subscriptions, including the event name, the namespace, the service component subscribing to the event, the SOA composite application, any optionally defined XPath filters, the consistency level (Guaranteed or OneAndOnlyOne), and the number of business events that failed to be delivered.
-
-
In the Subscription Component column, click a service component to access its home page.
-
In the Composite column, click a SOA composite application to access its home page.
For more information about creating business events in Oracle JDeveloper, see Chapter "Using Business Events and the Event Delivery Network" of Developing SOA Applications with Oracle SOA Suite.
Note:
Enforcement of policies for event subscriptions is not supported in this release. You can attach or detach a policy to or from a service component that subscribes to a business event (such as Oracle Mediator) without being warned. This action does not result in any errors; policy enforcement simply does not occur.
33.5 Resolving Duplicate Messages for Subscribers in Clustered Environments
SOA composite subscribers can receive duplicate events in a multiple-node cluster. This occurs when EDN uses the default JMS type and topic (that is, Oracle WebLogic Server JMS). This occurs because the template used by Oracle SOA Suite installation defaults to a Uniform Distributed WebLogic JMS topic with a replicated (instead of partitioned) forwarding policy and does not support configuration of the forwarding policy.
To automatically configure an EDN JMS topic to be a partition-distributed topic in a clustered environment, change the EDN JMS topic from replicated to partitioned.
To change to the partitioned policy:
- Log in to Oracle WebLogic Server Administration Console.
- In the Domain Structure, select soainfra > Services > Messaging > JMS Modules > SOAJMSModule.
- Click the distributed EDN topic (dist_EDNTopic_auto).
- Go to Configuration > General tab.
- In the dropdown list, change Forwarding Policy from Replicated to Partitioned.
When set to Partitioned, the physical member receiving the message is the only member of the uniform distributed topic that is aware of the message. When a message is published to the logical name of a partitioned uniform-distributed topic, it only arrives at one specific, physical topic member. Once a message arrives at a physical topic member, the following occurs:
-
The message is not forwarded to the rest of the members of the uniform distributed destination.
-
Subscribers at other physical topic members do not receive a copy of the message.
33.6 Changing the JMS Type
You can change the default JMS provider type from Oracle WebLogic Server JMS to AQ JMS. or vice versa.
- Click the Search icon, enter EDNConfig, and click Find.
33.7 Configuring the Inbound Poller Thread Number
For each subscriber, EDN spawns poller threads (defaults to one worker thread) for the underlying JMS consumer. You can change the number of inbound poller threads is either of two ways:
33.7.1 Updating the Global Inbound Poller Thread Number in the System MBean Browser
You can update the inbound poller thread number at the SOA Infrastructure level with the (global) attribute value of ThreadsPerSubscriber.
To update the inbound poller thread number in the System MBean Browser:
- Click the Search icon, enter EDNConfig, and click Find.
- Click the ThreadsPerSubscriber attribute. Change the value from the default of
1to an appropriate integer, and click Apply.A confirmation message indicating that the ThreadsPerSubscriber attribute have been updated successfully is displayed. No restart of the SOA server or redeployment of SOA composite applications is necessary.
33.7.2 Updating the Local Inbound Poller Thread Number Value at the Service Component Level
You can update the local inbound poller thread number at the service component level with a System MBean property corresponding to the composite containing the event subscribing component (Oracle Mediator or BPEL process).