Oracle JCA Adapter for Microsoft Message Queueing

Hello,

In Oracle SOA 12C, Oracle added few new adapters which can be used across with BPM/BPEL/OSB components. One of them is "Microsoft Message Queueing". 

Microsoft Message Queuing is similar to weblogic JMS queues, difference is it's a Microsoft technologies.

Microsoft Message Queuing provide most of the all functionalities and use case implementation which are provide by JMS queues.

During the design of SOA applications it is inevitable that from time to time you will need to interface with Microsoft-based applications. While technologies like SOAP and REST do a great job when request-reply communication is needed, most people struggle when a messaging-based communication is required. This blog will present two approaches to get messaging working between Microsoft and SOA Suite 12c.

Before going to implementation part, let c what is it and why we should use it.

What is MSMQ:

Microsoft Message Queueing (MSMQ) is a message infrastructure and a development platform for creating distributed, loosely-coupled messaging applications for the Microsoft Windows operating system.

Message queuing applications use message queuing to communicate across heterogeneous networks with computers that might be offline. Microsoft message queuing provides guaranteed message delivery, routing, security, transaction support and priority based routing.

Message Queues are logical containers that MSMQ uses to store and later forward those messages, thus providing the basis for loosely-coupled aspects of Message Queuing. Queuing applications send messages to the queue without needing to know when the messages are processed and which receiving application actually processes the message.

Before going in depth of MSMQ, let see what all are the terms used in MSMQ and it's very necessary to understand them before implementation.

• Public Queues – A queue registered in the directory service that can be located by any Message Queuing application. This enables the MSMQ application to locate and open a queue anywhere within its domain. Public queues enable multi-hop scenarios, where messages are replicated throughout the Active Directory Service.
• Private Queues–A queue registered on the local computer (and not in the directory service) that typically cannot be located by other applications.
• MSMQ queue – A temporary storage location from where messages can be sent and received reliably, as and when conditions permit.
• MSMQ user message queues – Queues that are either private or public.
• Remote Queue – A queue manager is a Message Queuing service that delivers, receives, authenticates, and routes messages, and maintains information in the directory service. For an application, a remote queue is a queue that is hosted by a queue manager other than the one with which the application communicates.
• Distribution Lists – Distribution lists are public lists of destinations that are stored in Active Directory Domain Services (ADDS).
• ADDS – Active Directory Domain Services is a directory service implemented by Microsoft for Windows domain networks. It is included in most Windows Server operating systems.
• Transactional Queues – A queue that contains transactional messages. Transactional queues can only contain transactional messages, which are messages sent within a transaction. You can use transactional messages to pair the sending or receiving of any message with an action in another operation. Using transactional messages ensures that the unit of work is carried out as an atomic operation.
• NonTransactional Queues – A queue that contains only non-transactional messages. Message Queuing does not allow transactional messages in non-transactional queues.
• Foreign Queue – A queue that resides on a computer that does not run Message Queuing (a foreign computer).

Features of MSMQ:

• Sending Messages to MSMQ Private Queues:
• The MSMQ Adapter enables sending a message to a local private queue. When using the MSMQ Adapter Configuration Wizard to model an MSMQ Adapter reference, you can model an enqueue operation that is used to send (or Put) a message to an MSMQ queue.
• The MSMQ Adapter enables sending a message to a local transactional private queue. When using the MSMQ Adapter Configuration Wizard to model an MSMQ Adapter reference, you can model an enqueue operation that is used to send a message to a local transactional MSMQ queue.
• Sending messages to MSMQ Public Queues:
  • The MSMQ Adapter enables sending a message to a local public queue. When using the MSMQ Adapter Configuration Wizard to model an MSMQ Adapter reference, you can model an enqueue operation. You can use this enqueue operation to send a message to a public MSMQ queue.
  • The MSMQ Adapter enables you to send a message to a local transactional public queue. When using the MSMQ Adapter Configuration Wizard to model an MSMQ Adapter reference, you can model an enqueue operation. You can use this enqueue operation to send a message to a MSMQ queue.
• Sending Messages to MSMQ Distribution Lists
  • The MSMQ Adapter enables you to send a message to a Distribution List. When using the MSMQ Adapter Configuration Wizard to model an MSMQ Adapter reference, you can configure an enqueue operation to send a message to a MSMQ distribution list.
• Consuming or Receiving Messages from a Private MSMQ Queue
  • The MSMQ Adapter enables you to consume or receive of a message from a local private MSMQ queue. The default behavior is for the next available message on the queue to be available for consumption.
  • To do this, use the Configuration Wizard to create the dequeue that consumes or receives a message from a transactional MSMQ queue.
  • To do this, use the MSMQ Adapter Configuration wizard to model a Dequeue operation that enables consumption of a message from an MSMQ private queue.The MSMQ Adapter enables message consumption from a local private transactional MSMQ queue and supports an operation called dequeue.
• Receiving Messages from a Public MSMQ Queue
  • The MSMQ Adapter enables reception of a message from a public MSMQ queue. The MSMQ Adapter supports an operation called dequeue that you configure when modeling an adapter service and is used to consume or receive a message from a MSMQ queue.
  • The MSMQ Adapter enables reception of a message from a public transactional MSMQ queue. You can use the MSMQ Adapter Configuration Wizard operation called dequeue that is used to receive a message from a transactional MSMQ queue.

Technical implementation summary:

• Applications that use MSMQ create/locate a queue.
• connect to the queue.
• navigate the queue.
• send/receive messages from a queue and use the MSMQ queue properties to define the behavior of the queue where applicable and needed.
• The MSMQ Adapter is deployable in an active-active topology. As part of its implementation, the MSMQ Adapter enables each poller thread to poll the queue for the next available message. Each poller thread uses the receive API; on a successful read the message is removed from the queue. This ensures there is no message duplication when the MSMQ Adapter is deployed in an active/active topology.

Don't forget to keep in mind:

The implications for use with the MSMQ Adapter are that you can use Native Mode when the MSMQ server and the SOA server are installed on the same machine. The SOA server installed must be a Windows Platform and not another platform, such as a Linux Platform.If the MSMQ Adapter and MSMQ are installed on the same system, you can enable Native Mode at both the jCOM protocol level and at the MSMQ Adapter level. When you use Native Mode, the MSMQ Adapter can directly interact with the MSMQ server because they are on the same system, rather than your having to use DCOM protocols to communicate (which are used when the MSMQ adapter and the MSMQ server are on two different machines). Ensuring that MSMQ Adapter does not use the DCOM protocol to interact with MSMQ COM components provides you with performance benefits.

Windows level configuration over windows server 2008:

To use MSMQ on a Windows Server 2008 installation, enable the following features for a Windows Server on which MSMQ is to be installed. Consult the relevant Microsoft documentation for more setup and configuration information.

• Message Queuing Server. For more information on installation, see the Microsoft document Installing Message Queuing (MSMQ) at http://msdn.microsoft.com/en-us/library/aa967729.aspx
• Directory Service Integration (for Public Queues and Distribution Lists). The prerequisite specifically requires Active Directory Domain Services (AD_DS) configured on a Windows 2008 Server system. Active Directory Domain Services is required to access MSMQ public queues, otherwise only private queues are available for MSMQ Adapter use cases.
• Message Queuing DCOM Proxy

After successful installation, Message Queuing appears under the Features link in the Microsoft Server Manager console window.

SOA/Weblogic configuration to enable COM mode:

This adapter leverages the jCOM technology available in WebLogic to provide connectivity to the MSMQ server. The first thing to do is enable jCOM in all servers where the adapter will be deployed. You can easily do this using the WebLogic administration console. In the managed server settings page, go to the “Protocols” > “jCOM” tab. Select the “Enable COM” check box as shown in the screen shot below:

Adapter level configuration:

Due to the nature of the JCA adapter, you will also need to create an outbound connection pool. In the deployments page, search for the “MSMQAdapter” and then go to the “Configuration” > “Outbound Connection Pools” tab. Create a new javax.resource.cci.ConnectionFactory and provide it with a proper JNDI name. After that click in the newly created outbound connection pool and go to the “Properties” tab. Here is the summary of the main properties:

Property Name	Description	Possible Values
AccessMode	Identifies if the connection factory allow native access or not. If native, the SOA server should be installed on the same host as the MSMQ server. Using the SOA server co-located with MSMQ provides better performance. Use DCOM only when accessing the MSMQ server remotely.	Native | DCOM
Domain	Domain of the MSMQ host.	Any java.lang.String value
Host	IP address or machine name of the MSMQ host.	Any java.lang.String value
Password	Password for the specified user.	Any java.lang.String value
TransactionMode	Indicates if the connection participates in a transaction when sending and receiving a message. Use single only if the MSMQ queue is transactional, otherwise use none.	Single | None
User	Identifies a user.	Any java.lang.String value

Sample Values:

MSMQ_AccessMode=DCOM

MSMQ_Domain=adapter.test.msmq

MSMQ_Host=slc04lya.us.mydomain.com 

MSMQ_Password=Welcome12

MSMQ_TransactionMode= NONE

MSMQ_User=Administrator 

After setting these properties, you can optionally go to the “Connection Pool” tab and fine tune the connection pool, specifically the “Initial Capacity”, “Max Capacity” and “Capacity Increment” parameters. That’s it, this is the minimal configuration needed to start using the JCA adapter for MSMQ. The following section discusses some special considerations for this adapter.

Enqueue Operation:

• Drag and drop MSMQ Adapter from the Component Palette of JDeveloper BPEL Designer.
• Enter a service or reference name.

• Enter JNDI name for the MSMQ Service connection which we created earlier.

• You can either create a new MSMQ adapter WSDL file using the selected operation, or import an existing WSDL that already specifies the operation.

• MSMQ Adapter Configuration Wizard Operation type page, you can select a valid operation for the MSMQ adapter configuration. If you are updating the operation, the operation is pre-selected on this page and the operation name is pre-populated. If you have imported an existing WSDL, the operation name on this page is pre-populated.

• Create an Enqueue Operation. This page captures the configuration parameters for the Enqueue operation.

• If you had chosen the Dequeue, or Get Message, Operation, the Dequeue message appears. On this screen, you can enter the parameters to dequeue message. There is a checkbox for direct format name. Direct format names are used to reference public or private queues without accessing the directory service. Direct format names are used when sending messages directly to a computer, to computers over the Internet, sending messages to any queue while operating in domain, workgroup, or offline mode, reading messages while operating in domain, workgroup, or offline mode, or sending messages across forest boundaries.
• Enable streaming by checking the Enable streaming checkbox. When you enable this feature, the payload is streamed to a database rather than being manipulated in SOA runtime as in a memory DOM. You use this feature while handling large payloads. When you select the Enable streaming check box, a corresponding Boolean property StreamPayload is appended to the Activation Spec properties defined in the respective .jca file.

• Adapter Configuration Wizard displays the Schema Page. If you need the message payload translated using a certain schema, enter the schema details, which define the incoming notification body content. Use the Native Format builder to define the Schema for native format. If the message payload is opaque, you can choose the Schema is Opaque option.

• Click Finish.

Points to remember while designing MSMQ:

• Using the JCA adapter for MSMQ in JDeveloper is equal to any other SOA Suite technology adapter. All you need to do is drag it from the components palette to the composite designer and inform the wizard about the JNDI name of the adapter and details about the queue.
• But before start deploying applications into the SOA server, review the follow recommendations to help ensure connectivity, high availability and performance:
• If you intend to access public queues and/or distribution lists, an Active Directory Domain Services (AD_DS) must be configured on a Windows 2008 Server system. This requirement does not apply for private queues.
• When the SOA server is not co-located with the MSMQ server or is installed in an operating system different than Windows (e.g.: Linux, Solaris) you need to use DCOM as access mode. in that case you need to set the value of the property “AccessMode” to “DCOM”. In addition, you need to install the MSMQ DCOM Proxy in the machine where the MSMQ server is running.
• When the MSMQ Adapter needs to make an outbound connection to the MSMQ server, it must sign on with valid security credentials. In accordance with the J2CA 1.5 specification, the WebLogic server supports both container-managed and application-managed sign-on for outbound connections. The MSMQ adapter can leverage either of these methods to sign on to the EIS. The credentials must include a user that has proper permissions to interact with the MSMQ server otherwise you will get exceptions during deployment.
• The MSMQ adapter supports high availability through the active-active topology. It has a poller thread to poll the queue for the next available message. Each poller thread uses the MSMQ receive API and only removes the message from the queue after successful read. This ensures there is no message duplication when the MSMQ Adapter is deployed in an active-active topology.
• Use the adapter.msmq.dequeue.threads binding property to increase the number of poller threads during endpoint activation. The default value of this property is “1” which is good for simple tests but with a higher value you can achieve a better degree of parallelism. You can set this property at runtime using the Enterprise Manager FMW Control Console.

• Enabling streaming during MSMQ message consumption can significantly reduce the SOA server memory footprint when large payloads are used, specially if there is a mediator applying content-based routing rules before delivering the message for processing.

Oracle documentation ref link:

https://docs.oracle.com/middleware/1221/adapters/develop-soa-adapters/GUID-8F3D79AA-5106-4493-9D60-3FF07D5A5EF3.htm#TKADP9311