Administering JMS

As mentioned earlier, before developers can do anything with JMS on your system, you must first do some configuration. The following tasks must be performed in order before any JMS connections can be made on the server.

1. Create a connection factory.

2. Create a JMS server.

3. Create a message queue or topic.

Creating a Connection Factory

As with most things WebLogic, the connection factory is created from the Administration console pane. Expand the Services folder, click JMS, and then click on Connection Factories. There are 12 fields to fill out:

Name	A Java identifier for the connection factory. Possibly but not necessarily the same as the JNDI name.
JNDIName	The JNDI identifier as it is known within the JNDI namespace.
ClientID	This field is optional. If you fill it in, you are telling WebLogic to deliver all messages on a particular topic to the specified subscriber, regardless of whether or not that subscriber is listening when the message is posted. Such a client is called a durable subscriber. Note that true "durable subscriber"-ness also requires the configuration of a message store.
Default Priority	The numeric priority that will be assigned to a message by default. Values range from 0 (low priority) to 9 (highest priority). The default value for the default priority is 4.
Default Time to Live	If specified, this value sets the upper limit on a message's existence in the system in milliseconds .
Default Time to Deliver	You can use this value to build in a delay between the time the message is passed to the server and the time it is delivered to the intended recipient. Values are given in milliseconds; the default is 0.
Default Delivery Mode	Either "Persistent," which guarantees message delivery at a slight cost to performance, or "Nonpersistent," which is slightly faster but doesn't guarantee delivery. Persistent requires the existence of a message store.
Default Redelivery Delay	You can use this value to build in a delay between the time messages are rolled back and the time they are redelivered.
Messages Maximum	Use this to place an upper limit on the number of messages in an asynchronous session that have not been passed to a message listener. A value of -1 lets the messages expand to the limits of virtual memory.
Overrun Policy	What to do if Messages Maximum is exceeded. Either "Keep Old," in which the newest messages are discarded, or "Keep New," in which the oldest messages are discarded.
Allow Close on Message	When checked, a close( ) method call executed within an onMessage( ) method call will be permitted to succeed. If unchecked, such a call will hang forever.
Acknowledge Policy	Either "Previous," which tells the server to treat the acknowledgement of a message by a session as the acknowledgement of all messages up to and including that message, or "All," which tells the server to treat the acknowledgement of a particular message as the acknowledgement of all messages received by that session. Ask your developers if you need to set it to something other than the default value of "All."

When you have finished filling out the fields in this form, click Create.

Creating a Message Store

Creating a message store is not always required. However, if you are using a delivery mode of type "Persistent," you must have a message store attached to the queue or topic. A message store is a chunk of disk space (that is, a directory or folder) that has been set aside to hold messages. In the event that the server crashes while messages are in queue, messages in a message store will be recovered, while messages in volatile memory will be lost.

Message stores are associated with at most one JMS server. They have two properties:

Name	The name of the store, as referenced by any queue or topic using it.
Directory	The location in the directory tree in which messages are stored.

When you have filled out these properties, click create to create the store.

Creating a JMS Server

The JMS server is created under the JMS tab in the Servers folder. It has three properties:

Name	The name for the JMS server.
Store	The optional persistent message store, as discussed previously in "Creating a Message Store."
Temporary Template	The optional name of the JMS template to be applied to all temporary destinations created on this server.

When you have finished filling out the fields in this form, click Create.

Create a Message Queue or Topic

Message queues or topics are the destination to which messages are sent. See the Introduction in this chapter for discussion of the differences between them. Queues and topics are always associated with a particular JMS server. To emphasize this point, they can be created only by clicking on the server with which they are associated. (See "Creating a JMS Server," above.) Under the server with which the queue or topic will be associated, click Destinations.

The distinction between queues and topics is made when they are created. They have the same properties:

Name	The internal name for the queue or topic, possibly distinct from the JNDI name.
JNDIName	The name by which this resource is known to JNDI. This value must be unique within the JNDI namespace.
Enable Store	Whether or not the queue or topic will write messages to nonvolatile memory. If true, the store must be defined as discussed in "Creating a Message Store," above.
Template	A JMS template used to determine the destination of a message. (See "Creating a Message Template," below, for further discussion.)
Destination Keys	JMS destination keys are values used to sort the messages for delivery. They order messages for delivery according to key=value pairs specified in the message header. In order for this to work, your developers should be putting keys in the messages. Multiple keys may be specified, in order from most to least significant.

Creating a Message Template

The JMS message specification provides for the creation of destination keys that can be used by the server to order the delivery of messages. (These are the key=value pairs discussed in the section on message properties.)

In order to create a message template, you must first define one or more destination keys. They have four properties:

Name	The name for the destination key. This is an arbitrary value, but it's best to choose something meaningful.
Property	The property of the message that you will be keying off. Note that in order for this to work, your application developers must be including this property in their message.
Key Type	The type of the key you will be sorting on. One of: Boolean, Byte, Int, Short, Long, Float, Double, String.
Direction	Whether the sort will be ascending or descending.

Once the destination keys are created, you can create the template under JMS Templates. There are only two properties:

Name	An arbitrary name for the template.
Destination Keys	This field will be empty until you click the Create button, at which time a list of the applicable destination keys will be generated.

Configuring a Virtual Destination

Virtual destinations are new to WebLogic 7.0. They allow you to distribute queues or topics across two or more servers. They are defined by three properties:

Name	The name of the virtual destination.
JNDI Name	The name used to access the virtual destination in JNDI.
Load Balancing	The method that will be used to distribute the messages among the consumers.

Next, you will need to specify two or more members as targets of the virtual destination.