Using Advanced Concepts in JMS .NET Client Applications Exchanging Messages Between Different Language Environments

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