1
Introduction

This chapter provides an overview of the Oracle Application Server InterConnect Adapter for MQ Series (MQ Series adapter).

MQ Series Adapter Overview

The MQ Series adapter enables Oracle Application Server InterConnect (OracleAS 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 OracleAS 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 OracleAS InterConnect.

Figure 1-1 How the MQ Series Adapter Interacts with an MQ Series Queue Manager and OracleAS 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 OracleAS InterConnect to MQ Series.

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

The need for three queues for inbound messages is mandated by a requirement to support the sending of messages from OracleAS 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	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	4.0 with service pack 6 or above
Windows 2000	with service pack 1 or above
IBM AIX 5L	5.1 and 5.2 (64 bit)
HP Tru64	5.1a and 5.1b (64 bit)
HP-UX	11.0 and 11.11 (64 bit)
RedHat Linux	Advanced Server 2.1
Sun SPARC Solaris	8 and 9 (32 bit)

JRE Requirements

OracleAS InterConnect uses JRE 1.4.1, which is installed with its components.

MQ Series Requirements

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

Table 1-3 MQ Series Requirements

Software	Supported Versions
MQ Series Server	Version 5.2 or 5.3
MQ Series Client	Version 5.2 or 5.3
MQ Series classes for Java and MQ Series classes for Java Message Service (JMS)	Only required with MQ Series Version 5.2.x. Downloadable from http://www-4.ibm.com/software/ts/mqseries/txppacs/ma88.html MQ Series Version 5.3 Client includes Java/JMS.
MQ Series - Publish/Subscribe	Version 1.1 or latest supporting MQ Series 5.2 or 5.3 Downloadable from http://www-4.ibm.com/software/ts/mqseries/txppacs/ma0c.html

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.

Typical Use

The MQ Series adapter is primarily used to provide messaging capabilities between OracleAS 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 OracleAS 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 OracleAS 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.

Note: If the external application which is accessing the queue or topic URI is not a JMS application, the URI property targetClient can be used to prevent the JMS interface used by the MQ adapter from adding the standard JMS header. For example:    queue:///LEGACY.REMOTE.QUEUE?targetClient=1 The property setting targetClient=0 means "queue is JMS compliant", whereas targetClient=1 means "queue is MQ (not JMS) compliant". If the adapter.ini parameter mq.default.sender.mqfmt is defined, it will override the targetClient setting.

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 OracleAS 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 OracleAS InterConnect. To some extent they can be used in selecting a relevant D3L transformation.

• MQ Series transactions are used to support the OracleAS InterConnect TransactionalMessageReceiver interface. The mq.default.trans_id_expiry configuration parameter determines how long a transaction started by the OracleAS 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.