Streams Messaging Sample Application

Table of Contents

• Overview of the Sample Application
• Application Usecase Diagram
• Installation and Configuration
• Description of Sample Files

Oracle Streams provides sharing and management of data and events in a stream. The stream can propagate this information within a database or from one database to another. Oracle Streams enable you to have a complete control on what information goes into the stream, how it is propagated to the destinations and how it is applied at the destinations. It also enables you to transform the data in streams at any stage as per the requirement.

Streams enables messaging with queues of type SYS.AnyData. These queues are called Streams queues. This sample demonstrates how to use Java Messaging Service (JMS) to access Streams Queue and get the XML Logical Change Records (LCR).

Streams queues can stage user messages whose payloads are of SYS.AnyData type. A SYS.AnyData payload can be a wrapper for payloads of different data types. Capture process captures database changes which include Data Manipulation Language(DML) and Data Definition Language(DDL) changes into an LCR (Logical Change Record) and enqueues to a queue of type SYS.AnyData. A capture process reformats changes captured from the redo log into LCR. An LCR is an object with a specific format that describes a database change. A capture process is always associated with a single SYS.AnyData queue, and it enqueues events into this queue only. To enqueue/dequeue a user message containing an LCR into a Streams queue using JMS, the LCR should be represented in XML format. Apply process applies changes based on rules defined. It applies these rules after dequeuing the LCRs and user messages from the queue.

The sample shows the scenario of a hypothetical Retail Shop which serves various customers all over the world. This retail shop has tied with several product manufacturers and sells their product directly to customers. This sample showcases the messaging capability of Streams. It shows how streams helps to replicate the data between databases and simplifies the work in such scenarios by interoperating with AQ. Brief description of the application is given below:

Lets us suppose that the retail shop is tied with a manufacturer who deals with the manufacturing of Computers. This manufacturer maintains a database (database 1)which is at a different physical location than the retail shop's database(database 2). Whenever there is a change in a product price or a new product has been manufactured, the manufacturer just updates this local database, database 1, and the change is propagated to the retail shop's database, database 2. The dml handler present on the apply process at the retail shops database(database 2) applies the changes in the database. At the same time it even re-enqueues the changes propagated from the manufacturers database into the same queue. These re-enqueued messages are used by the administrator.

The administrator of the retail shop has the privilege to view the details of the products changed in the database. The updated product information can be retrieved by dequeuing the details from the queue using JMS. Retention is provided on the queue so that the details are not lost once the administrator views it. The details of the product will be present in the queue until the Administrator deletes them.

Graphical interface is provided for the application so that the manufacturer can change the details of the product from the GUI page. The administrator of the Retail Shop can also view the updated product details online. The data present in the XML LCR is retrieved and shown in simple text format. When one of the product is selected the complete XML LCR retrieved is shown.The administrator can delete all the updated product information when it is not required. Until then the details of the updated products are stored in the queue.

A separate page is provided where the Retail Shop customers can view all the products available in the shop.

The flow of the application is explained using two Use Case Diagrams.

Fig. 1

Fig. 1 explains the complete flow of Streams Messaging Sample Application from the time changes are made in Manufacturers database.
1. When the details of the products are either inserted or updated or deleted in manufacturers database, it is captured, propagated to the Retail Shop's database.
2. The dml handler on the apply process of retail shop's database reenqueues the changes retrieved from the manufacturers database before applying it on the retail shops database.
3. This enqueued information is used by the administrator to find out the changes made in the retail shops database.
4. The administrator can delete all the messages in the queue when they are not required.

Now look at the Database Flow diagram:

 
Fig. 2

Fig.2 explains the flow of the application within the database. The steps carried out here are:

1. When the changes are made by the Manufacturer in the Product_Master table the changes are captured by the Streams_queue.
2. These changes are propagated from the Streams_queue in the Manufacturers database to the Streams_queue in the Retail Shops Database.
3. The DML Handler present on the Streams_queue here, applies the changes on the Product_Master table. At the same time it re-enqueues the changes to the Streams_queue once again.
4. When the Administrator logs in, the application displays the latest changes in the database by dequeuing the messages in the Streams_queue.
5. The changes applied on the Product_Master table in Retail Shops database are viewed by the Customer.

Refer to Installing the sample for step-by-step instructions on extracting files, installing and configuring the systems to successfully run this application.

The directory structure of the StreamsMessagingSample is as shown below :

Please enter your comments about this sample in the OTN Sample Code Discussion Forum.