1 Overview of the WebLogic JMS .NET Client
It is assumed that the reader is familiar with .NET programming and JMS 1.1 concepts and features.
This chapter includes the following sections:
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 client applications using .NET C# or any other supported .NET programming languages to access WebLogic Java Message Service (JMS) applications and resources.
WebLogic JMS is an enterprise-level messaging system that fully supports the JMS 2.0 Specification (see http://www.oracle.com/technetwork/java/jms/index.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 Administering JMS Resources for Oracle WebLogic Server.
For complete details about all the classes and interfaces in the JMS .NET API, see the Microsoft .NET Messaging API for Oracle WebLogic Server documentation.
The WebLogic JMS .NET client, which is bundled with WebLogic Server, is supported on Microsoft .NET Framework. Installation details are provided in 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 2.0 Specification (see http://www.oracle.com/technetwork/java/jms/index.html
). For a list of the JMS 2.0 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 Developing JMS Applications for Oracle WebLogic Server.
Message Types
The WebLogic JMS .NET client supports the following message types, as defined in the JMS Specification (see http://www.oracle.com/technetwork/java/jms/index.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.
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 9.x or later cluster.
The major components depicted in the illustration consist of the following:
-
A JMS .NET client written in C# or any supported .NET programming language, 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:
- 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.
- The JMS .NET client obtains a connection factory from the JMS .NET client host.
- The JMS .NET client host, in turn, obtains the connection factory from JNDI.
- 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.
- 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 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:
-
Configure default network connections in the Oracle WebLogic Server Administration Console Online Help
-
Understanding Network Channels in Administering Server Environments for Oracle WebLogic Server
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:
-
Configure Messaging in the Oracle WebLogic Server Administration Console Online Help
Interoperating with Pre-12.1.3 JMS .NET Clients
To enable JMS .NET clients developed prior to WebLogic Server 12.1.3 to interoperate with WebLogic Server 12.1.3 and later, set the following system property on your WebLogic Server 12.1.3 and later instances:
-Dweblogic.protocol.t3.login.replyWithRel10Content=true
The default value is false
for interoperability with existing JMS .NET clients developed prior to WebLogic Server 12.1.3.
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 9.x 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 follows](img/dotnetclient_cluster_9x.png)
Description of "Figure 1-2 JMS .NET Client Interoperability"
To access destinations on WebLogic Server 9.x 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 Administering JMS Resources 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 Microsoft .NET Messaging API for Oracle WebLogic Serverdocumentation.
Table 1-1 WebLogic JMS .NET Classes and Interfaces
Interface/Class | Description |
---|---|
|
The |
|
A |
|
An |
|
An |
|
An |
|
An |
|
An |
|
An ISession.CreateConsumer(IDestination destination)
ISession.CreateProducer(IDestination destination) |
|
An Since
ISession.CreateConsumer(IQueue queue)
ISession.CreateProducer(IQueue queue) |
|
A JMS .NET client uses an |
|
A JMS .NET client uses an |
|
The 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. |
|
An |
|
An |
|
An |
|
An |
|
An |