1 Overview of the WebLogic JMS .NET Client

These sections provide an overview of the WebLogic JMS .NET client, illustrate how a JMS .NET client application accesses WebLogic JMS resources, and provide a brief summary of the WebLogic JMS .NET API.

It is assumed that the reader is familiar with .NET programming and JMS 1.1 concepts and features.

What is the WebLogic JMS .NET Client?

The WebLogic JMS .NET client is a fully-managed .NET runtime library and application programming interface (API). It enables programmers to create .NET C# client applications that can access WebLogic Java Message Service (JMS) applications and resources.

WebLogic JMS is an enterprise-level messaging system that fully supports the JMS 1.1 Specification (see http://java.sun.com/products/jms/docs.html) and also provides numerous "WebLogic JMS Extensions" to the standard JMS APIs. For a summary of the WebLogic Server value-added JMS features, see "WebLogic Server Value-Added JMS Features" in Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.

For complete details about all the classes and interfaces in the JMS .NET API, see the Oracle Fusion Middleware Microsoft .NET Messaging API for Oracle WebLogic Server documentation.

The WebLogic JMS .NET client, which is bundled with WebLogic Server 10g Release 3 and higher, is supported on Microsoft .NET Framework versions 2.0 through 3.5. Installation details are provided in Chapter 2, "Installing and Copying the WebLogic JMS .NET Client Libraries."

Supported JMS Features

For this release, the WebLogic JMS .NET client supports the major standard features of the JMS Version 1.1 Specification (see http://java.sun.com/products/jms/docs.html). For a list of the JMS 1.1 standard features that are not supported, see Limitations of Using the WebLogic JMS .NET Client.

In addition to the standard JMS 1.1 Specification support, the WebLogic JMS .NET client also supports several WebLogic JMS extensions. For more information about the features supported and how they can be used with the JMS .NET client, see Using WebLogic JMS Extensions.

Messaging Models

The WebLogic JMS .NET client supports the following messaging models:

  • The point-to-point (PTP) messaging model, which enables one application to send a message to exactly one recipient.

  • The publish/subscribe (pub/sub) messaging model, which enables an application to send a message to multiple recipients.

Messages can be specified as persistent or non-persistent:

  • Persistent messages are guaranteed to be delivered once-and-only-once. The message will not be lost due to JMS server failure and it will not be redelivered once it is acknowledged by an application. It is not considered sent until it has been safely written to a file or database.

  • Non-persistent messages are not stored. They are guaranteed to be delivered at-most-once. Messages may be lost when there is a JMS provider failure and will not be redelivered.

For more information, see "Understanding the Messaging Models" in Oracle Fusion Middleware Programming JMS for Oracle WebLogic Server.

Message Types

The WebLogic JMS .NET client supports the following message types, as defined in the JMS 1.1 Specification (see http://java.sun.com/products/jms/docs.html):

  • Message

  • BytesMessage

  • MapMessage

  • ObjectMessage (between producers and consumers written in the same language only)

  • StreamMessage

  • TextMessage

The XMLMessage type extension provided by WebLogic JMS is not supported in this release. Such messages are automatically converted to a TextMessage type when received by a .NET client.

For more information about using the supported message types, see Exchanging Messages Between Different Language Environments.

How the WebLogic JMS .NET Client Works

The following figure illustrates how a JMS .NET client application running in a .NET Framework CLR can access JMS resources deployed on WebLogic Server.

Figure 1-1 JMS .NET Client Architecture

Description of Figure 1-1 follows
Description of "Figure 1-1 JMS .NET Client Architecture"

Note:

All of the WebLogic components shown in Figure 1-1 are hosted on a single instance of WebLogic Server 10g Release 3 or later. In a multi-server or cluster configuration, each of the WebLogic Server components can run on a separate instance of WebLogic Server. However, the JMS .NET client host must run on WebLogic Server 10g Release 3 or later, and the connection host and the JMS server must run in the same WebLogic Server 8.1 or later cluster.

The major components depicted in the illustration consist of the following:

  • A JMS .NET client written in C#, running in a .NET Framework CLR, that either produces messages to destinations or consumes messages from destinations.

  • A JMS .NET client host running on WebLogic Server 10g Release 3 or later that provides the interface between the JMS .NET client and WebLogic JMS.

  • A standard T3 protocol listen port configured on the .NET client host.

  • One or more connection hosts (i.e., connection factories).

  • One or more JMS servers that define a set of JMS destinations.

Traffic to the JMS servers is always routed from the .NET client through the JMS .NET client host to the connection host to the JMS servers. Traffic to the JMS .NET client is always routed from the JMS servers to the connection host and through the JMS .NET client host to the .NET client.

A brief summary of the process used to exchange messages between the JMS .NET client and a JMS server, as illustrated in Figure 1-1, is summarized in the following steps:

  1. The JMS .NET client establishes an initial T3 network connection with the JMS .NET client host running on WebLogic Server 10g Release 3 or later.

  2. The JMS .NET client obtains a connection factory from the JMS .NET client host.

  3. The JMS .NET client host, in turn, obtains the connection factory from JNDI.

  4. The JMS .NET client creates a connection using the connection factory, which will establish a connection from the JMS .NET client host to one of the connection hosts where the connection factory resides.

  5. When the JMS .NET client sends (produces) a message, the JMS .NET client host sends it to the connection host, which in turn routes it to the JMS server hosting the destination. Alternatively, when the JMS .NET client receives (consumes) a message, the connection host routes it from the JMS server hosting the destination to the JMS .NET client host, which passes the message to the JMS .NET client.

Instructions and examples for creating a JMS .NET client application are provided in Chapter 3, "Developing a Basic JMS Application Using the WebLogic JMS .NET API."

Configuring WebLogic Server

The following sections describe the configuration that must occur before a JMS .NET client application can access JMS resources.

Configuring the Listen Port

The JMS .NET client requires that a listen port configured for T3 protocol is enabled on the WebLogic Server instance hosting the JMS .NET client host. When you install WebLogic Server, a default port is configured for use with T3 protocol. Because the default port configuration can be changed or disabled, the system administrator needs to ensure that the T3 protocol is enabled on the server's default port, or add a network channel that supports the T3 protocol. For configuration information, see the following topics:

Configuring JMS Resources for the JMS .NET Client

Before a JMS .NET client application can access JMS resources deployed on WebLogic Server, the WebLogic Server system administrator must configure the required JMS resources, including the connection factories, JMS servers, and destinations. For instructions for configuring JMS resources, see:

Interoperating with Previous WebLogic Server Releases

The JMS .NET client can communicate directly only with WebLogic Server 10g Release 3 and later. As shown in Figure 1-2, the JMS .NET client host must run on WebLogic Server 10g Release 3 or later, however, the connection host and the JMS server can run on WebLogic Server 8.1 or later. Both the connection host and the JMS server must be in the same cluster.

Figure 1-2 JMS .NET Client Interoperability

Description of Figure 1-2 follows
Description of "Figure 1-2 JMS .NET Client Interoperability"

To access destinations on WebLogic Server 8.1 or later that are not in the same cluster as the .NET client host running on 10g Release 3 or later, you must configure the remote instance of WebLogic Server as a Foreign Server. For more information, see Configuring Foreign Server Resources to Access Third-Party JMS Providers in Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.

Note:

Although you can also use Foreign Servers to connect to third-party JMS providers using JMS Java clients, this feature is not supported in the WebLogic JMS .NET client.

Understanding the WebLogic JMS .NET API

The following table lists the primary JMS .NET API classes and interfaces used to create a JMS .NET client application. For complete details about all the classes and interfaces in the JMS .NET API, see the documentation.

Table 1-1 WebLogic JMS .NET Classes and Interfaces

Interface/Class Description
Constants

The Constants family of classes is used to define commonly used constants/enumerations for the API.

ContextFactory

A ContextFactory is used to create contexts, which are network connections from the .NET client to the client host.

IContext

An IContext object represents a network connection from the .NET client to the client host. It is used to lookup destinations and connection factories, and to close the network connection when it is no longer needed.

IConnectionFactory

An IConnectionFactory object encapsulates JMS connection configuration information. A JMS .NET client looks up a connection factory using an IContext object, and then uses it to create an IConnection with a JMS server.

IConnection

An IConnection object is the active connection between the JMS .NET client host and the JMS connection host. Authentication optionally takes place during the creation of the connection. A connection is used to create sessions.

ISession

An ISession object is a single-threaded entity for producing and consuming messages. A session can create and service multiple message producers and consumers.

IDestination

An IDestination object identifies a queue or topic. Queue and topic destinations manage the messages delivered from the point-to-point and pub/sub messaging models, respectively.

ITopic

An ITopic object is pub/sub IDestination that encapsulates a provider-specific topic name. It is the way a client specifies the identity of a topic to JMS API methods. For those methods that use an IDestination as a parameter, an ITopic object may be used as an argument. For example, an ITopic can be used to create an IMessageConsumer and an IMessageProducer by calling:

ISession.CreateConsumer(IDestination destination)
ISession.CreateProducer(IDestination destination)
IQueue

An IQueue object is a point-to-point IDestination that encapsulates a provider-specific queue name. It is the way a client specifies the identity of a queue to JMS API methods.

Since IQueue and ITopic both inherit from IDestination, for those methods that use an IDestination as a parameter, an IQueue object can be used as the argument. For example, an IQueue can be used to create an IMessageConsumer and an IMessageProducer by calling:

ISession.CreateConsumer(IQueue queue)
ISession.CreateProducer(IQueue queue)
IMessageConsumer

A JMS .NET client uses an IMessageConsumer object to receive messages from a destination. An IMessageConsumer object is created by passing an IDestination object to a message-consumer creation method supplied by a session.

IMessageProducer

A JMS .NET client uses an IMessageProducer object to send messages to a destination. An IMessageProducer object is created by passing an IDestination object to a message-producer creation method supplied by a session.

IMessage

The IMessage interface is the root interface of all JMS messages. It defines the message header and the Acknowledge method used for all messages.

JMS messages are composed of the following parts:

Header - All messages support the same set of header fields. Header fields contain values used by both clients and providers to identify and route messages.

Properties - Each message contains a built-in facility for supporting application-defined property values. Properties provide an efficient mechanism for supporting application-defined message filtering.

Body - The JMS API defines several types of message body, which cover the majority of messaging styles currently in use.

IMapMessage

An IMapMessage object is used to send a set of name-value pairs. The names are String objects, and the values are primitive data types in the Java and C# programming languages. The names must have a value that is not null, and not an empty string. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined. IMapMessage inherits from the IMessage interface and adds a message body that contains a map.

IObjectMessage

An IObjectMessage object is used to send a message that contains a serializable object in the Java and C# programming languages. It inherits from the IMessage interface and adds a body containing a single reference to an object. C# objects cannot be read by Java programs, and vice versa. For more information, see Exchanging Messages Between Different Language Environments.

IStreamMessage

An IStreamMessage object is used to send a stream of primitive types in the Java programming language. It is filled and read sequentially. It inherits from the IMessage interface and adds a stream message body. Its methods are based largely on those found in java.io.DataInputStream and java.io.DataOutputStream.

ITextMessage

An ITextMessage object is used to send a message containing a String. It inherits from the IMessage interface and adds a text message body.

IBytesMessage

An IBytesMessage object is used to send a message containing a stream of uninterpreted bytes. It inherits from the IMessage interface and adds a bytes message body. The receiver of the message supplies the interpretation of the bytes.