1
Introduction

This chapter discusses the following topic:

• MQ Series Adapter Overview

MQ Series Adapter Overview

The Oracle Technology Adapter for IBM MQ Series enables Oracle9iAS InterConnect to send messages to and receive messages from the MQ Series queues and topics. This allows an application that uses IBM's MQ Series as its messaging technology to be integrated with other applications using Oracle9iAS InterConnect. Therefore, the MQ Series adapter is useful in all enterprise application integration scenarios involving MQ Series-based applications.

This guide explains all necessary design time and runtime concepts of the MQ Series adapter.

The following diagram describes how the MQ Series adapter interacts with an MQ Series queue manager and Oracle9iAS InterConnect.

Figure 1-1 How the MQ Series Adapter Interacts with an MQ Series Queue Manager and Oracle9iAS InterConnect

Text description of the illustration picture1.gif

The MQ Series adapter uses four logical queues or destinations to support its interaction with the MQ Series messaging system:

• Three for inbound messages; from Oracle9iAS InterConnect to MQ Series.

• One for outbound messages; from MQ Series to Oracle9iAS InterConnect.

The need for three queues for inbound messages is mandated by a requirement to support the sending of messages from Oracle9iAS InterConnect to MQ Series in a transactionally safe manner:

• One queue is the actual destination for inbound messages.

• One queue is used to keep a log of already received messages within a transaction.

• One queue is used to hold and generate incrementally unique transaction IDs.

The two latter logical queues, for the logs and transaction IDs, can be combined into one physical queue.

See Also: "Inbound"

Hardware Requirements

Table 1-1 lists the hardware requirements for the computer on which the Oracle MQ Series adapter is installed.

Table 1-1 Hardware Requirements

Hardware	Windows NT/2000	UNIX
Memory	128 MB	128 MB
Disk Space	500 MB	500 MB

Software Requirements

The following sections list software requirements for the MQ Series adapter:

• Operating System Requirements

• JRE Requirements

• MQ Series Requirements

Operating System Requirements

Table 1-2 lists operating system requirements for the computer on which the MQ Series adapter is installed.

Table 1-2 Operating System Requirements

Operating System	Version
Windows NT/2000	version that supports at least 400 MHz
IBM AIX-Based Systems	version 4.3.3
Compaq Tru64 UNIX	version 5.0a or 5.1
HP 9000 Series HP-UX	version 11.0
SUSE LINUX SLES7	version 7.2, Kernel 2.4.7, GlibC 2.2.2-55
Sun SPARC Solaris	version 2.6 through 2.8

JRE Requirements

Oracle9iAS InterConnect uses JRE 1.3, which is installed with its components.

MQ Series Requirements

The following table lists the minimum software requirements for installing the MQ Series adapter.

Software	Supported Versions
MQ Series Server	Version 5.1 or 5.2
MQ Series ClientFoot 1	Version 5.1 or 5.2
MQ Series classes for Java and MQ Series classes for Java Message Service (JMS)	Version 1.1.3 or latest supporting MQ Series 5.1 or 5.2 Downloadable from http://www-4.ibm.com/software/ts/mqseries/txppacs/ma88.html
MQ Series - Publish/SubscribeFoot 2	Version 1.0.6 or latest supporting MQ Series 5.1 or 5.2 Downloadable from http://www-4.ibm.com/software/ts/mqseries/txppacs/ma0c.html

1 Only needed if using remote or non-local MQ Series queue manager. 2 Only needed if topic (publish/subscribe) support in MQ Series is required.

Knowledge Requirements

The installation of the MQ Series adapter software components mentioned in "MQ Series Requirements" should be performed by a MQ Series system administrator.

Configuring and using the MQ Series adapter requires the following:

• Basic MQ Series administration skills, such as starting the listener and creating queues.

• Basic knowledge of MQ Series connectivity, for example channel and client concepts.

• Basic knowledge of MQ Series Java and JMS, for example, MQ Series JMS queue and topic URI syntax.

The MQ Series queues and topics referred to in this guide must be created and started by the user before starting the MQ Series adapter.

MQ Series Adapter: Typical Use

The MQ Series adapter is primarily used to provide messaging capabilities between Oracle9iAS InterConnect and the MQ Series queueing systems, such as supporting the publish and subscribe paradigm for message exchanges, for example, sending or receiving orders, invoices, and product updates.

In addition to basic publish and subscribe messaging, the MQ Series adapter also supports the Oracle9iAS InterConnect request and reply paradigm which maps directly onto MQ Series' own generic support for request and reply messages. This capability is based on the support for message correlation for Oracle9iAS InterConnect as well as in MQ Series. Examples include inventory lookups, price calculations, and status requests.

Supported MQ Series Adapter Interfaces

The following sections describe the MQ Series adapter interfaces.

General

The MQ Series adapter uses the MQ Series JMS URI syntax for specifying which queues and topics constitute the endpoints for inbound and outbound messages.

This format is derived from uniform resource identifiers and allows the specification of remote queues (queues on a queue manager other than the one to which you have connected) as well as the setting of the other queue connection properties.

The URI for a queue starts with the sequence queue://, followed by the name of the queue manager on which the queue resides, a further /, then the name of the queue, and optionally, a list of name-value pairs to set the remaining queue properties as follows:

queue://[queue-manager]/queue[?property=value [&property=value ]*] 

Queue URI Example:

queue:///SYSTEM.DEFAULT.LOCAL.QUEUE

Note: The name of the queue manager is omitted. This is interpreted to mean use the default queue manager as specified in the adapter.ini file.

The URI for a topic starts with the sequence topic:// followed by the name of the topic, and optionally, a list of name-value pairs to set the remaining topic properties as follows:

topic://TopicName[?property=value [&property=value ]*] 

Topic URI example:

topic://SAP/Events/HR/newCustomer?priority=1

Note: The topic URI syntax does not allow the specification of the queue manager. It must be specified in the mq.default.queue_manager property in the adapter.ini file.

Inbound

Inbound interfaces consist of MQ Series queues to which the MQ Series adapter sends messages. The MQ Series adapter only supports MQ Series queues, not topics, for inbound interfaces. The reason for this stems from the following combination of constraints:

• The MQ Series adapter must send messages to MQ Series in a transactionally safe manner as it implements the Oracle9iAS InterConnect SDK TransactionalMessageReceiver interface.

• This requires the use of a queue for keeping log records.

• The destination queue or topic and log queue must be updated within the same JMS transaction, that is, the same JMS session.

• The MQ Series JMS implementation does not support the concept of Universal JMS sessions, which would allow queues and topics to be updated within the same transaction.

• Storing temporary log records in a topic is not practical.

Outbound

Outbound interfaces can consist of both queues and topics from which the MQ Series adapter will receive messages. Additional configuration parameters in the adapter.ini file allow for defining a JMS selector expression, which can be used to filter which messages should be received by MQ Series adapter. Another parameter controls whether the message consumption should be performed within a transactional or non-transactional JMS session.

Connection Types

MQ Series supports two connection types:

• Local (bind)

• Remote (client)

Local Connections

Local connections imply that the MQ Series queue manager is running on the same host as the MQ Series adapter. In this case, the MQ Series adapter only needs to know the name of the queue manager and queue name itself in order to establish a queue connection.

Remote Connections

For remote connections, the MQ Series queue manager can run on a different host. In this case, the MQ Series adapter needs access to MQ Series client libraries, which must be installed, in order to establish a queue connection. The MQ Series adapter also needs additional configuration information such as the name of the remote host, the port number where the MQ Series listener is listening, and the channel name (MQ Series concept).

Figure 1-2 displays a client connection:

Figure 1-2 Client Connection

Text description of the illustration picture2.gif

MQ Series Adapter Limitations

The MQ Series adapter has the following limitations:

• All messages received are assumed to be unencrypted, as the MQ Bridge is not expected to do any decryption before handing messages to the D3L engine.

• All but the ObjectMessage JMS message types are supported: TextMessage, BytesMessage, MapMessage and StreamMessage.

• All MQ Series Report messages are used only to the extent MQ Series expects it but otherwise they are not utilized.

• MQ Series message grouping and segmentation are not supported.

• JMS Message properties of received messages from MQ Series are not passed on to Oracle9iAS InterConnect. To some extent they can be used in selecting a relevant D3L transformation.

• MQ Series transactions are used to support the Oracle9iAS InterConnect TransactionalMessageReceiver interface. The mq.default.trans_id_expiry configuration parameter determines how long a transaction started by the Oracle9iAS InterConnect Agent, can stay idle before it expires. MQ Series does not expose the concept of a persistent transaction identifier, therefore, the transaction identifier is only valid for the lifespan of the MQ Series adapter instance and the underlying transactional JMS session. Consequently, a given transaction ID is rendered invalid immediately when the adapter process dies.

• An MQ Series adapter instance only supports one outgoing (sending) endpoint. For example, it can only communicate with one queue manager.