Free Trial

Safari Books Online is a digital library providing on-demand subscription access to thousands of learning resources.

  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL
Help

3. Populating Data Objects with Real-tim... > Using Enterprise Message Sources

Using Enterprise Message Sources

Using Enterprise Message Sources Enterprise Message Sources (EMS) provides direct Java Message Service (JMS) connectivity to the Oracle BAM Server, by mapping messages directly to Oracle BAM Data Objects. Oracle BAM Server can read data directly from any JMS-based message queue or topic through the Messaging Framework. BAM EMS supports the following JMS Servers or JMS providers: WebLogic Server JMS providerAQ JMSWebSphereMQTibcoSonicMQ In this section, you will learn how to create an EMS to populate the Data Object with messages received from JMS queues on the WebLogic JMS Server. Creating an EMS To create an EMS, you need to select Enterprise Messaging Sources from the list in the BAM Architect web application, and click on Create. In the EMS configuration page, provide details in the following sections: Configuring JMS Server connection properties EMS acts as a Java client that connects to the JMS Server to consume messages from JMS destinations (queues or topics). In the JMS programming model, use the Java Naming and Directory Interface (JNDI) to find a javax.jms.ConnectionFactory object and a javax.jms.Destination object. To perform JNDI lookup operations, EMS needs to instantiate a javax.naming.InitialContext class, using the following properties: javax.naming.Context.INITIAL_CONTEXT_FACTORYjavax.naming.Context.PROVIDER_URLjavax.naming.Context.SECURITY_PRINCIPALjavax.naming.Context.SECURITY_CREDENTIALS To configure the JMS Server connection details, enter the following details in the UI: Initial Context Factory: Enter a name that is used to set javax.naming.Context.INITIAL_CONTEXT_FACTORY. For Weblogic JMS Provider, enter weblogic.jndi.WLInitialContextFactory.JNDI Service Provider URL: Enter a URL that is used to set javax.naming.Context.PROVIDER_URL. For example , the URL of the WebLogic Server JMS provider could be t3://localhost:9001.Topic/Queue ConnectionFactory Name: Enter the JNDI name for TopicConnectionFactory or QueueConnectionFactory.Topic/Queue Name: Enter the JNDI name for JMS topic or queue.JNDI Username: Enter a name that is used to set javax.naming.Context.SECURITY_PRINCIPAL.JNDI Password: Enter the password that is used to set javax.naming.Context.SECURITY_CREDENTIALS. Configuring JMS message consumption properties In this section, set up the JMS Message consumption-related properties as follows: JMS Message Type: Select TextMessage or MapMessage.Durable Subscriber Name (Optional): Enter a durable subscriber name. A durable subscription can preserve messages published on a topic while the subscriber is not active.Message Selector (Optional): Enter a name-value pair for filtering JMS messages. The name value pair format should be name=value. In the current release, only one name-value pair is supported. Tip The Message Selector option allows you to process multiple message types through a single JMS destination. However, you should be careful when using this option for high volume message processing, as it could dramatically impact performance. Configuring Data Object operation properties In this section, you specify how to populate BAM Data Object as follows: Data Object Name: Click on Browse to select the Data Object to which EMS sends the data.Operation: Select a Data Object operation name (Insert, Update, Upsert, or Delete).Batching: Specify whether the EMS communicates with the Oracle BAM Active Data Cache batching API for batch processing.Transaction: Choose Yes, if you want to enable transaction for Messaging batching processing. Tip By default, EMS sends individual JMS messages to the BAM Active Data Cache. If batching is enabled, EMS will send a batch of messages to BAM Active Data Cache, which will process it as a unit. As EMS resides in the same EJB container as Active Data Cache, and there is no network traffic between EMS and Active Data Cache, sending a batch of messages does not make much difference than sending one message at a time, in terms of performance. Configuring other properties You need to set up the following properties as well: Name: Enter the name of the EMSStart when BAM Server starts: Specify whether the EMS should be automatically started after Oracle BAM Server starts Tip Every time you apply the changes for EMS configurations, EMS will be stopped automatically. When EMS is at Stopped status, it cannot consume any messages. So, you need to restart it manually by clicking on the Start link. A case study Suppose that we have an inventory system, which will send an XML message containing warehouse stock level information to the WebLogic JMS queue when certain conditions are met. Now, we have a new requirement, which is to use EMS to consume the message from the queue, and invoke BAM Active Data Cache API to persist the data to the /BookstoreDemo/Inventory Data Object. The following is an example that demonstrates how to configure EMS: In this configuration, we do not specify the JNDI Username and the JNDI Password, as InitialContext instantiation does not require these properties when the BAM and the JMS server reside in the same WebLogic Server container. XML formatting XML formatting is used to specify how to parse the JMS messages received by EMS, which are in XML format. Enter the following details to configure XML formatting: Pre-Processing: Check this option, if you want to apply XSL transformation code to pre-process the XML messages consumed by EMS. Instead of the original document, the transformation result is parsed by the XML parser.Message Element Name: Specify the XML element whose child elements or attributes are the ones used for XML to the Data Object mapping.Column Value: Choose Element Tag if the data are stored in sub elements. Choose Attribute if the data are stored in attributes. Note Pre-processing is also required to transform the message consumed from JMS sources from a complex structure (XML elements with hierarchies) to a flat structure (a single level XML fragments) that can then be mapped to Data Object fields. You will see an example in Chapter 5, . Suppose that EMS receives the following messages from a JMS Queue: <Inventory xmlns="http://www.packtpub.com/5443/samples/inventory"> <ProductID>1</ProductID> <WarehouseID>101</WarehouseID> <InventoryLevel>200</InventoryLevel> </Inventory> The XML Formatting configuration should look as follows: Suppose that the JMS message received by EMS contains a collection of items as follows: <InventoryBatch> <Inventory> <ProductID>1</ProductID> <WarehouseID>101</WarehouseID> <InventoryLevel>200</InventoryLevel> </Inventory> <Inventory> <ProductID>2</ProductID> <WarehouseID>101</WarehouseID> <InventoryLevel>400</InventoryLevel> </Inventory> </InventoryBatch> To parse this XML document, you need to check the Message Batching option, and then enter InventoryBatch for Batch Element Name. Tip Message Batching is an indicator that tells EMS to parse XML messages, which contain a collection of items. When Message Batching is selected, ensure that you also set the Transaction property in the basic configuration section to Yes, which reinforces transactional behavior when processing a batch of messages. Note that Message Batching is different than the batching property for the BAM Adapter. Source value formatting (optional) When the XML data type is xs:dateTime, you can skip the source value formatting. This step is only required if XML messages contain DateTime values, which are not in xs:dateTime format. To format DateTime source values, you need to specify a correct pattern for java.text.SimpleDateFormat. For details about java.text.SimpleDateFormat, refer to the Java6 API documentation at the following URL: http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html Configuring XML to Data Object mapping To configure a XML to Data Object mapping, click on Add to add a mapping rule. The following is an example of XML to Data Object mapping: As you can see, the XML elements ProductID, WarehouseID, and Inventorylevel are mapped to the corresponding Data Object fields. And ProductID and WarehouseID are selected as Keys. After you complete this section, you can click on Save to create the EMS. Testing EMS EMS defines the JMS connection, transformation, formatting, and mapping information. To verify the behavior of the EMS you configured, you need to perform testing, which covers end-to-end messaging flow in EMS. In the BAM Architect web application, you can click on Test to perform basic testing, which only tests the connection details to a JMS provider. To verify the transformation, value formatting, mapping, and Data Object operations, you need to perform end-to-end testing, which often involves a JMS client, and, sometimes, a demo report. Testing EMS Using WebLogic Server console To use WebLogic Server console as a JMS client to test EMS, perform the following steps: Log in to the WebLogic Server console that hosts the JMS queue/topic that you want to test.In the Domain Structure page in the WebLogic Server console, navigate to Services | Messaging | JMS Modules.Click on the JMS module and the queue/topic that your EMS connects to.Click on the Monitoring tab, and then check the checkbox in front of the queue/topic that you want to test. Click on Show Messages.Click on New. The Produce JMS Message page appears.Provide the XML payload in the Body text area. Click on OK to produce the message.Verify if the new record is populated into the Data Object in the BAM Architect web application. For example, suppose that you provide the following XML payload: <Inventory xmlns="http://www.packtpub.com/5443/samples/inventory"> <ProductID>1</ProductID> <WarehouseID>101</WarehouseID> <InventoryLevel>200</InventoryLevel> </Inventory> You can verify the test result by viewing the records in the Data Object. If testing is successful, you should see a record in the Data Object contents view, as shown in the following screenshot: You can also inspect the statistics for the EMS to verify your test result. If you click on Metrics in the EMS page, the Statistics for Enterprise Message Source table appears. Note The statistics show the total number of received, committed, and lost messages, based on the rule as follows: Total Messages Received = Total Messages committed in ADC + Total Messages Lost If Total Messages Lost is zero or unchanged since the previous test, testing is successful; otherwise, testing fails, and JMS messages are lost. This means that BAM received the message, but was unable to process it in the Data Object. A reason for this could be that the message was in an invalid XML format. Transaction and fault handling EMS supports the JTA transaction. The Messaging Framework, which handles JMS message consumption, does not propagate JTA transaction to EMS. Thus, EMS always starts a new transaction after a JMS message is delivered to EMS. Therefore, the transaction boundary in BAM is actually between the EMS and the Active Data Cache, and not between the Messaging Framework and the Active Data Cache. Note When there is a fault happening in the message flow from EMS to Active Data Cache, the current transaction rolls back, but only to the point where it is started in EMS. Since JMS message consumption is not a part of this transaction, messages are discarded in the end. Thus, it is highly recommended to use the fault handling mechanism to keep track of the error messages and payloads. You can handle faults in the following ways: Log faulted messages with or without payloadsWrite faulted messages to Data Objects or a separate JMS queue/topic The following is an example of fault handling in the EMS configuration page: Suppose you send the following payload to a JMS Queue: <Inventory xmlns="http://www.packtpub.com/5443/samples/inventory"> <ProductID>1</ProductID> <WarehouseID>101</WarehouseID> <InventoryLevel>Null</InventoryLevel> </Inventory> As<InventoryLevel> contains an invalid value, it causes a transaction rollback. The message is lost in this case. You should be able to see the faulted message and the XML payload in the server's log file, and the ErrorMessage field in the /BookstoreDemo/Error_Hospital Data Object, as shown in the following screenshot:

  

You are currently reading a PREVIEW of this book.

                                                                                                                    

Get instant access to over $1 million worth of books and videos.

  

Start a Free Trial


  
  • Safari Books Online
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint