Developing a Basic JMS Application Using the WebLogic JMS .NET API 3-5
producer.SendsendMessage;
3.2.2.8 Step 8
Create a message consumer and receive a message. Note that the message is automatically deleted from the server because the session was created in AUTO_
ACKNOWLEDGE mode, as shown in Step 6
. IMessageConsumer consumer = session.CreateConsumerqueue;
IMessage recvMessage = consumer.Receive500;
3.2.2.9 Step 9
Close the connection. Note that closing a connection also closes its child sessions, consumers, and producers.
connection.Close;
3.2.2.10 Step 10
Close the context. context.CloseAll;
3.3 Using Advanced Concepts in JMS .NET Client Applications
Appendix A, JMS .NET Client Sample Application, provides a complete example of a
JMS .NET client application, written in C, that demonstrates some of the following advanced concepts:
■
The use of local transactions instead of acknowledge modes.
■
Message persistence. For more information, see Persistent vs. Non-Persistent Messages in Programming JMS for Oracle WebLogic Server.
■
Acknowledge modes. For more information, see Non-Transacted Session in Programming JMS for Oracle WebLogic Server.
■
Exception listeners. For more information, see Section 4.9, Best Practices.
■
Durable Subscriptions. For more information, see Setting Up Durable Subscriptions in Programming JMS for Oracle WebLogic Server.
For guidelines in the use of other advanced concepts in the JMS .NET client such as interoperability, security, and best practices, see
Chapter 4, Programming Considerations.
Note:
context.Close does not terminate the network connection until all the IConnections have been closed. context.CloseAll closes the
network connection and all open IConnections.
3-6 Using the WebLogic JMS Client for Microsoft .NET for Oracle WebLogic Server
4
Programming Considerations 4-1
4
Programming Considerations
These sections provide programming considerations and best practices to use when creating a JMS .NET client application:
■
Section 4.1, Using WebLogic JMS Extensions
■
Section 4.2, Limitations of Using the WebLogic JMS .NET Client
■
Section 4.3, Exchanging Messages Between Different Language Environments
■
Section 4.4, Specifying the URL Format
■
Section 4.5, Implementing Security With the JMS .NET Client
■
Section 4.6, Configuring Logging and Debugging
■
Section 4.7, Understanding Socket and Threading Behavior
■
Section 4.8, Data Conversion Between Java and .NET
■
Section 4.9, Best Practices
4.1 Using WebLogic JMS Extensions
Table 4–1 lists the WebLogic JMS extensions that are supported in this release of the
JMS .NET client. There are several ways that messaging can be configured:
■
On the connection factory—This method often defines default configuration settings.
■
Programmatically in the application using the API—Certain programming constructs may override the connection factory configuration.
■
On the server—Certain settings may override both the connection factory and programmatic constructs.
In some cases, there are differences in the way that an extension is configured, or in the behavior, between a JMS .NET client and a Java client. For example, some
extensions cannot be enabled programmatically using the JMS .NET API, and can only be enabled via configuration. The following table summarizes the differences.
Additional details, if required, are provided in the subsequent sections.
4-2 Using the WebLogic JMS Client for Microsoft .NET for Oracle WebLogic Server
Table 4–1 WebLogic JMS Extensions Supported in the JMS .NET Client
Feature Configurable
on Connection
Factory
Configurable on the
Server
Java API
JMS .NET
API Comments
Distributed Destinations Uniform and Weighted
For more information, see:
■
Using Distributed Destinations in Programming JMS for Oracle WebLogic
Server
■
Configuring Distributed Destination Resources in Configuring and Managing
JMS for Oracle WebLogic Server Yes
Yes No
No
Flow Control Producers For more information, see: Controlling the
Flow of Messages on JMS Servers and Destinations in Performance and Tuning for
Oracle WebLogic Server Yes
Yes No
No
Blocking producers during quota conditions For more information, see Defining a Send
Timeout on Connection Factories in Performance and Tuning for Oracle WebLogic
Server Yes
Yes No
No
Foreign destinations for remote instances of WebLogic Server
For more information, see Configuring Foreign Server Resources to Access Third-Party JMS
Providers in Configuring and Managing JMS for Oracle WebLogic Server
No Yes
No No
See Section 1.4,
Interoperati ng with
Previous WebLogic
Server Releases.
Imported store-and-forward SAF destinations For more information, see Imported SAF
Destinations in Configuring and Managing Store-and-Forward for Oracle WebLogic Server
No Yes
No No
Redelivery limit For more information, see Setting a Redelivery
Limit for Messages in Programming JMS for Oracle WebLogic Server
No Yes
Yes No
Redelivery delay For more information, see Setting a Redelivery
Delay for Messages in Programming JMS for Oracle WebLogic Server
Yes No
Yes No
Error destinations For more information, see Configuring an
Error Destination for Undelivered Messages in Programming JMS for Oracle WebLogic Server
No Yes
No No
WLDestination.getCreateDestinationArgumen t
No No
Yes Yes
Programming Considerations 4-3
No Acknowledge Mode For more information, see Using NO_
ACKNOWLEDGE in Programming JMS for Oracle WebLogic Server
No No
Yes Yes
Unit-of-Order For more information, see:
■
Using Message Unit-of-Order in Programming JMS for Oracle WebLogic
Server
■
Tuning Applicatinos Using Unit-of-Order in Tuning WebLogic JMS in Performance
and Tuning for Oracle WebLogic Server Yes
Yes Yes
Yes See
Section 4.1.2, Unit-of-Ord
er.
Scheduled message delivery For more information, see Setting Message
Delivery Times in Programming JMS for Oracle WebLogic Server
Yes Yes
Yes Yes
See Section 4.1.3,
Message Delivery
Time.
Asynchronous consumer messages maximum pipeline
■
For more information, see: Asynchronous Message Pipeline in Programming JMS for
Oracle WebLogic Server
■
Tuning MessageMaximum in Performance and Tuning for Oracle WebLogic Server
Yes No
Yes No
Message Compression For more information, see Message
Compression in Programming JMS for Oracle WebLogic Server
Yes No
Yes No
See Section 4.1.1,
Message Compression
.
Quotas For more information, see Defining Quota in
Performance and Tuning for Oracle WebLogic Server
No Yes
No No
One-way message sends For more information, see Using One-Way
Message Sends For Improved Non-Persistent Messaging Performance in Performance and
Tuning for Oracle WebLogic Server Yes
No No
No See
Section 4.1.4, One-Way
Message Sends.
Table 4–1 Cont. WebLogic JMS Extensions Supported in the JMS .NET Client
Feature Configurable
on Connection
Factory
Configurable on the
Server
Java API
JMS .NET
API Comments
4-4 Using the WebLogic JMS Client for Microsoft .NET for Oracle WebLogic Server
4.1.1 Message Compression
In this release, automatic message compression is not supported for client sends between the JMS .NET client and the JMS .NET client host running on WebLogic
Server. However, if the compression settings are set on the connection factory, message compression behavior between the .NET client host and the destination is the
same as that of the Java client. The behavior is as follows:
■
If the client host and destination run on different instances of WebLogic Server, then a sent message is automatically compressed on the client host.
■
If the client host and destination run on the same instance of WebLogic Server, then no sent message compression will occur.
Compressed messages are decompressed by the JMS .NET client host on the server side when they are received by the .NET client.
For more information, see Message Compression in Programming JMS for Oracle WebLogic Server
4.1.2 Unit-of-Order
The method used to specify Unit-of-Order UOO in the JMS .NET API differs from the Java API. To set Unit-of-Order in the JMS .NET API, add a string property named
Constants.MessagePropertyNames.UNIT_OF_ORDER_PROPERTY_NAME to the message with the desired UOO.
For more information, see Using Message Unit-of-Order in Programming JMS for Oracle WebLogic Server
4.1.3 Message Delivery Time
The method used to specify message delivery times in the JMS .NET API differs from the Java API. To set message delivery times in the JMS .NET API, add a property of
type long named Constants.MessagePropertyNames.DELIVERY_TIME_ PROPERTY_NAME to the message, where the value is the number of milliseconds in the
future in which the message will be delivered. Acknowledge policy
For more information, see JMS Connection Factory: Configuration: Client in the Oracle
WebLogic Server Administration Console Help Yes
No No
No
Automatically include user-id as message property JMSXUserID
Yes Yes
No No
See Section 4.1.5,
Include user-id as
JMSXUserId.
Get number of delivery attempts as message property JMSXDeliveryCount
No No
No No
See Section 4.1.6,
Message Delivery
Attempts.
Table 4–1 Cont. WebLogic JMS Extensions Supported in the JMS .NET Client
Feature Configurable
on Connection
Factory
Configurable on the
Server
Java API
JMS .NET
API Comments
Programming Considerations 4-5
4.1.4 One-Way Message Sends
Although you can configure one-way message sends on the connection factory, this behavior is not fully supported in the JMS .NET client. Messages sent as one-way
sends will actually be two- way sends between the .NET client and the .NET client host, and one-way sends between the .NET client host and the JMS connection host.
4.1.5 Include user-id as JMSXUserId
The optional JMSXUserId system-generated message property on received messages specifies the credential of the original sender. To enable this property, configure the
Attach Sender Credential attribute on destinations, distributed destinations, or templates, and configure the Attach JMSXUserId attribute on connection factories. To
retrieve, call msg.GetStringPropertyConstants.MessagePropertyNames.USER_ID_
PROPERTY_NAME.
4.1.6 Message Delivery Attempts
The JMSXDeliveryCount system-generated message property on received messages specifies the number of message delivery attempts. The first attempt is 1. To retrieve
the value, call msg.GetIntPropertyConstants.MessagePropertyNames.DELIVERY_
COUNT_PROPERTY_NAME.
4.2 Limitations of Using the WebLogic JMS .NET Client
The following sections describe the JMS features that are not supported in the JMS .NET client.
4.2.1 Unsupported JMS 1.1 Standard Features
In this release, the following JMS 1.1 standard features are not supported:
■
Creating and closing temporary destinations javax.jms.TemporaryQueue and javax.jms.TemporaryTopic. The JMS .NET client can still produce
messages to temporary destinations created by a Java client if the destination objects are obtained from the JMSReplyTo header of received messages.
■
javax.jms.QueueRequester and javax.jms.TopicRequester. These helper classes are related to temporary destinations.
■
Queue browsers: javax.jms.QueueBrowser.
■
Queue and Topic interfaces QueueConnectionFactory, TopicConnectionFactory, QueueConnection, TopicConnection,
QueueSession, TopicSession. These queue and topic interfaces are legacy JMS 1.0.2 interfaces that have been superseded by the JMS 1.1 common interfaces.
4.2.2 Unsupported JMS 1.1 Optional Features
In this release, the following JMS 1.1 optional features are not supported:
■
XA interfaces XAConnectionFactory, XAConnection, and XASession.
■
Participation in global XA transactions See Section 4.2.4, Transactions
.
■
Connection Consumer and Server session pools javax.jms.ConnectionConsumer, ServerSessionPool, and
4-6 Using the WebLogic JMS Client for Microsoft .NET for Oracle WebLogic Server
ServerSession. These are optional capabilities that have been superseded by Java EE MDBs, and are not supported by the WebLogic Java JMS client.
■
MessageProducer.setDisableMessageTimestamp method. Note that the WebLogic JMS Java client ignores this method.
4.2.3 Unsupported WebLogic JMS Extensions
In this release, the following WebLogic JMS extensions are not supported:
■
SSL
■
HTTP tunneling
■
SAF Client—See Reliably Sending Messages Using the JMS SAF Client in Programming Stand-alone Clients for Oracle WebLogic Server
■
Multicast Subscribers—See Using Multicasting with WebLogic JMS in Programming WebLogic JMS
■
Automatic Reconnect—See Automatic JMS Client Failoverin Programming JMS for Oracle WebLogic Server
■
Unit-of-Work—If a .NET client attempts to set a UOW property on a message, a Weblogic.Messaging.MessageException is generated. In addition, a .NET
consumer cannot receive UOW messages with deserializable content that are sent by a Java client. In this case, the consumer gets a MessageFormatException if it
calls the ObjectMessage.getObject method on the ObjectMessage. Note that while Unit-of-Work is not supported, the more commonly used Unit-of-Order
extension is fully supported. For more information about Unit-of-Order, see
Section 4.1.2, Unit-of-Order.
4.2.4 Transactions
In this release, the JMS .NET client supports transacted sessions as defined in the JMS Specification only. Transacted sessions provide a standard local transaction capability.
As with the Java client, one or more WebLogic JMS destinations from within the same cluster may participate in a transacted session local transaction, but no other resources
may participate such as JMS servers in other clusters, databases, or foreign JMS providers.
Global XA transactions are not supported, therefore JMS cannot participate in a .NET transaction. The XA setting of the connection factory is ignored by the .NET client. The
JMS NET client operations cannot participant in any .NET transactions.
4.3 Exchanging Messages Between Different Language Environments
The following Java JMS message types can be exchanged between a .NET producer and a Java or C consumer, and vice versa:
■
Message
Note: The JMS .NET API does not provide extensions for programmatically
configuring JMS resources for example, topics and queues. In Java, programmatic configuration is accomplished using JMX MBeans or the
weblogic.jms.extensions.JMSModuleHelper helper class. Alternative ways to configure JMS include WLST scripting and the WebLogic
Administration Console.
Programming Considerations 4-7
■
BytesMessage
■
StreamMessage
■
MapMessage
■
TextMessage An ObjectMessage type, however, can be sent from one language and received by
another, but the message cannot be interpreted unless it is written in the same language. The producer and consumer of an OBJECTMESSAGE type must be written in
the same language, either C or Java. If a mismatch occurs; that is, if a .NET ObjectMessage is received by a Java consumer, or a Java ObjectMessage is
received by a .NET consumer, then message.getObject throws a MessageFormatException.
4.4 Specifying the URL Format