Chapter 3   Using Administered Objects

Administered objects encapsulate provider-specific implementation and configuration information in objects that are used by JMS clients.

Sun™ ONE Message Queue (MQ) provides two types of JMS administered objects—connection factory and destination—as well as a JAXM administered object. While all encapsulate provider-specific information, they have very different uses.

ConnectionFactory and XAConnectionFactory (distributed transaction) objects are used to create connections to the MQ message server. Destination objects (which represent physical destinations) are used to create JMS message consumers and producers (see "Developing a Simple Client Application"). The JAXM endpoint administered object is used to send SOAP messages (see Chapter 5 "Working With SOAP Messages").

There are two approaches to the use of administered objects:

• They can be created and configured by an administrator, stored in an object store, accessed by clients through standard JNDI lookup code, and then used in a provider-independent manner.




---

Note	In the case where JMS clients are J2EE components, JNDI resources are provided by the J2EE container, and JNDI lookup code might differ from that shown in this chapter. Please consult your J2EE provider documentation for such details.

---



• They can be instantiated and configured by a developer when writing application code. In this case, they are used in a provider-specific manner.

The approach you take in using administered objects depends on the environment in which your application will be run and how much control you want your client to have over MQ-specific configuration details. This chapter describes these two approaches and explains how to code your JMS client for each.

JNDI Lookup of Administered Objects

---

If you wish an application to be run under controlled conditions in a centrally administered messaging environment, then MQ administered objects should be created and configured by an administrator. This makes it possible for the administrator to do the following:

• control the behavior of connections by requiring clients to access pre-configured ConnectionFactory (and XAConnectionFactory) objects through a JNDI lookup.
• control the proliferation of physical destinations by requiring clients to access only Destination objects that correspond to existing physical destinations.

This approach gives the administrator control over message server and client runtime configuration details, and at the same time allows clients to be JMS provider-independent: they do not have to know about provider-specific syntax and object naming conventions or provider-specific configuration properties.

An administrator creates administered objects in an object store using MQ administration tools, as described in the MQ Administrator's Guide. When creating an administered object, the administrator can specify that it be read only—that is, clients cannot change MQ-specific configuration values specified when the object was created. In other words, application code cannot set attribute values on read-only administered objects, nor can they be overridden using client startup options, as described in "Starting Client Applications With Overrides".

While it is possible for clients to instantiate ConnectionFactory (and XAConnectionFactory) and destination administered objects on their own, this practice undermines the basic purpose of an administered object—to allow an administrator to control the broker resources required by an application and to tune application performance. Instantiating administered objects also makes a client provider specific.

Looking Up ConnectionFactory Objects

To perform a JNDI lookup of a ConnectionFactory object

1. Create an initial context for the JNDI lookup.

The details of how you create this context depend on whether you are using a file-system object store or an LDAP serverO for your MQ administered objects. The code below assumes a file-system store. For information about the corresponding LDAP object store attributes, see the MQ Administrator's Guide.

Hashtable env = new Hashtable();
env.put (Context.INITIAL_CONTEXT_FACTORY,
   "com.sun.jndi.fscontext.RefFSContextFactory");
env.put (Context.PROVIDER_URL,
   "file:///c:/imq_admin_objects");
Context ctx = new InitialContext(env);

You can also set an environment by specifying system properties on the command line, rather than programmatically, as shown above. For instructions, see the README file in the jms subdirectory of the example applications directory:

IMQ_HOME/demo/jms (/usr/demo/imq/jms on Solaris)

If you use system properties to set the environment, then you initialize the context without providing the env parameter:

Context ctx = new InitialContext();

2. Perform a JNDI lookup on the "lookup" name under which the ConnectionFactory or XAConnectionFactory object was stored in the JNDI object store.

QueueConnectionFactory myQConnFactory = (QueueConnectionFactory)
   ctx.lookup("cn=MyQueueConnectionFactory");

It is recommended that you use this connection factory as originally configured. For a discussion of ConnectionFactory and XAConnectionFactory object configuration properties, see "MQ Client Runtime Configurable Properties" and for a complete list of properties, see "ConnectionFactory Administered Object".

3. Use the ConnectionFactory to create a connection object.

QueueConnection myQConn =
   myQConnFactory.createQueueConnection();

The code in the previous steps is shown in Code Example 3-1.

---

Code Example 3-1    Looking Up a ConnectionFactory Object

Hashtable env = new Hashtable();

env.put (Context.INITIAL_CONTEXT_FACTORY,    "com.sun.jndi.fscontext.RefFSContextFactory");

env.put (Context.PROVIDER_URL,    "file:///c:/imq_admin_objects");

Context ctx = new InitialContext(env);

QueueConnectionFactory myQConnFactory = (QueueConnectionFactory)     ctx.lookup("cn=MyQueueConnectionFactory");

QueueConnection myQConn =     myQConnFactory.createQueueConnection();

---

Looking Up Destination Objects

To perform a JNDI lookup of a Destination object

1. Using the same initial context used in performing the ConnectionFactory lookup, Perform a JNDI lookup on the "lookup" name under which the Destination object was stored in the JNDI object store.

Queue myQ =
(Queue) ctx.lookup("cn=MyQueueDestination");

Instantiating Administered Objects

---

If you do not wish an application to be run under controlled conditions in a centrally administered environment, then you can instantiate and configure administered objects in application code.

While this approach gives you, the developer, control over message server and client runtime configuration details, it also means that your clients are not supported by other JMS providers. Typically, you might instantiate administered objects in application code in the following situations:

• You are in the early stages of development in which there is no real need to create, configure, and store administered objects. You just want to develop and debug your application without involving JNDI lookups.
• You are not concerned about your clients being supported by other JMS providers.

Instantiating administered objects in application code means you are hard-coding configuration values into your application. You give up the flexibility of having an administrator reconfigure the administered objects to achieve higher performance or throughput after an application has been deployed.

Instantiating ConnectionFactory Objects

There are two object constructors for instantiating MQ ConnectionFactory administered objects, one for each programming domain:

• Publish/subscribe (Topic) domain

new com.sun.messaging.TopicConnectionFactory();

Instantiates a TopicConnectionFactory with a default configuration (creates Topic TCP-based connections to a broker running on "localhost" at port number 7676).

• Point to point (Queue) domain

new com.sun.messaging.QueueConnectionFactory();

Instantiates a QueueConnectionFactory with a default configuration (creates Queue TCP-based connections to a broker running on "localhost" at port number 7676).

To directly instantiate and configure a ConnectionFactory object

1. Instantiate a Topic or Queue ConnectionFactory object using the appropriate constructor.

com.sun.messaging.QueueConnectionFactory myQConnFactory =
   new com.sun.messaging.QueueConnectionFactory();

2. Configure the ConnectionFactory object.

myQConnFactory.setProperty("imqBrokerHostName", "new_hostname");
myQConnFactory.setProperty("imqBrokerHostPort", "7878");

For a discussion of ConnectionFactory configuration properties, see "MQ Client Runtime Configurable Properties" and for a complete list of properties, see "ConnectionFactory Administered Object".

3. Use the ConnectionFactory to create a Connection object.

QueueConnection myQConn =
   myQConnFactory.createQueueConnection();

The code in the previous steps is shown in Code Example 3-2.

---

Code Example 3-2    Instantiating a ConnectionFactory Object

com.sun.messaging.QueueConnectionFactory myQConnFactory =     new com.sun.messaging.QueueConnectionFactory();

try {

myQConnFactory.setProperty("imqBrokerHostName", "new_host");

myQConnFactory.setProperty("imqBrokerHostPort", "7878");

} catch (JMSException je) {

}

QueueConnection myQConn =     myQConnFactory.createQueueConnection();

---

Instantiating Destination Objects

There are two object constructors for instantiating MQ Destination administered objects, one for each programming domain:

• Publish/subscribe (Topic) domain

new com.sun.messaging.Topic();

Instantiates a Topic with the default destination name of "Untitled_Destination_Object".

• Point to point (Queue) domain

new com.sun.messaging.Queue();

Instantiates a Queue with the default destination name of "Untitled_Destination_Object".

To directly instantiate and configure a Destination object

1. Instantiate a Topic or Queue Destination object using the appropriate constructor.

com.sun.messaging.Queue myQueue = new com.sun.messaging.Queue();

2. Configure the Destination object.

myQueue.setProperty("imqDestinationName", "new_queue_name");

3. After creating a session, you use the Destination object to create a MessageProducer or MessageConsumer object.

QueueSender qs = qSession.createSender((Queue)myQueue);

The code is shown in Code Example 3-3.

---

Code Example 3-3    Instantiating a Destination Object

com.sun.messaging.Queue myQueue = new com.sun.messaging.Queue();

try {

myQueue.setProperty("imqDestinationName", "new_queue_name");

} catch (JMSException je) {

}

...

QueueSender qs = qSession.createSender((Queue)myQueue);

...

---

Starting Client Applications With Overrides

---

As with any Java application, you can start messaging applications using the command-line to specify system properties. This mechanism can be used, as well, to override attribute values of MQ administered objects used in application code. You can override the configuration of MQ administered objects accessed through a JNDI lookup as well as MQ administered objects instantiated and configured using setProperty() methods in application code.

To override administered object settings, use the following command line syntax:

java [[-Dattribute=value ]...] clientAppName

where attribute corresponds to any of the ConnectionFactory administered object attributes documented in "MQ Client Runtime Configurable Properties".

For example, if you want a client to connect to a different broker than that specified in a ConnectionFactory administered object accessed in the application code, you can start up the client using command line overrides to set the imqBrokerHostName and imqBrokerHostPort of another broker.

It is also possible to set system properties within application code using the System.setProperty() method. This method will override attribute values of MQ administered objects in the same way that command line options do.

If an administered object has been set as read-only, however, the values of its attributes cannot be changed using either command-line overrides or the System.setProperty() method. Any such overrides will simply be ignored.