Skip Headers

Oracle9i Application Developer's Guide - Advanced Queuing
Release 2 (9.2)

Part Number A96587-01
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index


Go to previous page Go to next page

Messaging Gateway

Messaging Gateway, an Oracle9i Advanced Queuing feature, enables communication between applications based on non-Oracle messaging systems and Oracle's Advanced Queuing (AQ) feature. Advanced Queuing provides the propagation between two AQ queues to enable e-business (HTTP via IDAP). Messaging Gateway extends that propagation to legacy applications based on non-Oracle messaging systems.

Because Messaging Gateway is integrated with Advanced Queuing and Oracle9i, it offers fully transactional and secure message delivery. Messaging Gateway guarantees that messages are delivered once and only once between AQ and non-Oracle messaging systems that support persistence. The AQ-like PL/SQL interface provides an easy-to-learn administrative API, especially for developers already proficient in using AQ.

This release of Messaging Gateway supports the integration of Oracle9i Advanced Queuing with IBM MQSeries 5.1- and MQSeries 5.2-based applications.

This chapter discusses the following topics:

Messaging Gateway Functionality

Messaging Gateway provides the following functionality:

For Oracle database administrators to control access to the tables, views, and procedures created by the gateway, Messaging Gateway defines two roles, MGW_ADMINISTRATOR_ROLE and MGW_AGENT_ROLE, for gateway administration and propagation processing. Refer to "Loading Database Objects into the Database", "Creating a Messaging Gateway Administration User", and "Creating a Messaging Gateway Agent User".

Messaging Gateway Architecture

Messaging Gateway has the following main components: an administration package named DBMS_MGWADM for gateway configuration and management, and a gateway agent that processes propagation, as shown in Figure 18-1. The gateway agent consists of a propagation engine and a set of drivers that communicate with non-Oracle messaging systems.

Figure 18-1 Messaging Gateway Architecture

Text description of adqmg002.gif follows
Text description of the illustration adqmg002.gif

Administration Package

The Messaging Gateway administration package, DBMS_MGWADM, provides an interface for gateway administrators to manage the gateway agent, set up propagation, and monitor propagation processing.

Through the administration package, you configure the gateway agent with the proper user name, password, and database connect string of the Oracle database in order for the agent to create connections to the database. You can also call procedures in the package to assign the maximum number of database connections and the size of the memory heap to the agent.

For the gateway agent to propagate messages to and from a non-Oracle messaging system, a messaging system link, which represents a communication channel between the agent and the non-Oracle messaging system, must be created using the administration package. Multiple messaging system links can be configured in the agent.

All non-Oracle queues that are involved in propagation must be registered using the administration package. Registering a non-Oracle queue in the gateway configuration does not create the physical queue in the non-Oracle messaging system, but only records information about the queue, such as the messaging system link to access it, its native name, and its domain (queue or topic). The physical queue must be created through the administration interfaces of the non-Oracle messaging system.

With messaging system links and non-Oracle queues configured, you can create propagation jobs to set up message propagation. A propagation job in Messaging Gateway consists of a propagation subscriber and a propagation schedule. A propagation subscriber is created to define the source queue and the destination queue of a propagation job. You manipulate the propagation schedule associated with the propagation job to control when the propagation job is processed.

Messaging Gateway provides database views for gateway administrators to query and check the current configuration information, the gateway agent running status, and the propagation job status and statistics.

Gateway configuration can be changed independent of whether the gateway agent is running or shut down. If the agent is running, the administration procedures send notifications to the agent for configuration changes. The agent will dynamically alter its configuration for most configuration changes, although some require that the agent be shut down and restarted before they take effect. All the procedures in the administration package are serialized to guarantee that the gateway agent receives notifications for the configuration changes in the same order they are made.

See Also:

Oracle9i Supplied PL/SQL Packages and Types Reference for more information on DBMS_MGWADM

Gateway Agent

The gateway agent schedules and processes propagation jobs. The agent executes in an external process of the Oracle database server. The agent is started and terminated by calling the STARTUP and SHUTDOWN procedures in the administration package. Like all external processes of Oracle database server, the agent runs only when the database server that it resides in is up and running.

The agent contains a propagation engine and a set of drivers for the non-Oracle messaging systems. The multithreaded propagation engine fairly schedules propagation jobs and provides parallel interjob and intrajob propagation processing. A polling thread in the agent periodically polls the source queues of enabled propagation jobs and wakes up worker threads to process propagation jobs if messages are available. The drivers in the gateway agent are instantiated when messaging links are created. The drivers run as clients of messaging systems for all messaging operations.

The agent writes log messages into its log files, which contain information about agent configuration, agent status, actions taken by the agent upon receiving dynamic notifications, status of propagation jobs, and all error messages.

Propagation Processing Overview

You create propagation jobs to set up message propagation. A propagation job conceptually consists of a propagation subscriber and a propagation schedule.

After a propagation subscriber is created, the gateway creates a subscription on the propagation source if the source is a topic (publish-subscribe). The gateway moves all messages that are published to the topic after the subscriber is created. If the propagation source is a point-to-point queue, the gateway moves all messages in the queue to the destination.

A propagation job is not processed until an associated propagation schedule is created. The gateway agent processes enabled propagation jobs. Disabling a propagation job stops the transfer of messages from the source queue to the destination queue, but does not stop subscription.

When a propagation job is processed, messages are dequeued in priority order from the source queue and enqueued to the destination queue. If a message fails to be converted from the source format to the destination format, the message is moved to the exception queue. Messages that have expired in a propagation source queue are not propagated to the destination queue.

Using Messaging Gateway, you can specify a propagation message selector for a propagation job if the source messaging system of the propagation job supports message selectors. Only messages satisfying the message selector are propagated.

If a propagation job runs into failures during processing, the agent retries up to 16 times in an exponential backoff scheme before disabling the job.

When a message is propagated, it is converted from its native format in the source messaging system to its native format in the destination messaging system. The gateway provides automatic message conversions between simple and commonly used message formats. You can provide your own message transformation functions for customized message conversions.

See Also:

Oracle9i Supplied PL/SQL Packages and Types Reference for information on DBMS_TRANSFORM

Setting Up Messaging Gateway

This section describes the steps for loading and setting up Messaging Gateway.

Oracle9i Database Prerequisites

In the init<sid>.ora file, where <sid> is the Oracle system ID of the database instance used for Messaging Gateway, the following parameters must be specified:

Non-Oracle Messaging System Prerequisites

Install the non-Oracle messaging system before loading and setting up Messaging Gateway. Messaging Gateway uses the shared libraries and Java class files of the non-Oracle system.

Loading and Setup Tasks

You must do the following procedures before Messaging Gateway can run. These tasks apply to both Unix and Windows NT, except where "Windows NT Only" or "Unix Only" is indicated.

  1. Loading Database Objects into the Database
  2. Modifying listener.ora for the External Procedure
  3. Modifying tnsnames.ora for the External Procedure
  4. Modifying the mgw.ora Initialization File
  5. Creating a Messaging Gateway Administration User
  6. Creating a Messaging Gateway Agent User
  7. Configuring Messaging Gateway Connection Information

Loading Database Objects into the Database

Using SQL*Plus, run catmgw.sql, located in the $ORACLE_HOME/mgw/admin directory. Run as user: SYS as SYSDBA.

The SQL script catmgw.sql loads the necessary database objects for Messaging Gateway, including roles, tables, views, object types, and the PL/SQL packages. It creates public synonyms for Messaging Gateway PL/SQL packages and types. It creates two roles, MGW_ADMINISTRATOR_ROLE and MGW_AGENT_ROLE, with certain privileges granted. It also creates a library alias for the agent's external procedure. All objects are owned by SYS.

Modifying listener.ora for the External Procedure

Windows NT Only: You can ignore this step. Static service information for the listener is not necessary on Windows NT.

You must modify listener.ora so that the Messaging Gateway PL/SQL package can call the external procedure.

  1. In listener.ora, verify that the default IPC protocol address for the external procedures is set.
Protocol Address for the External Procedure: Example

Go to previous page Go to next page
Copyright © 1996, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index