Chapter 10 Using the JMS Service

Sun Java System Application Server provides support for applications that use the Java Message Service (JMS) application programming interface (API) for messaging operations. JMS is a set of programming interfaces that provide a common way for Java applications to create, send, receive, and read messages in a distributed environment.

In particular, JMS is the standards-based way that Java 2 Enterprise Edition (J2EE) applications perform asynchronous messaging. Accordingly, J2EE components—Web components or Enterprise JavaBeans (EJB) components—can use the JMS API to send messages that can be consumed asynchronously by a specialized EJB, called a message-driven bean (MDB).

Sun Java System Application Server support for JMS messaging, in general, and for MDBs, in particular, requires messaging middleware that implements the JMS specification—a JMS provider. Sun Java System Application Server uses Sun Java System Message Queue 3.5 Service Pack 1 as its native JMS provider.

MQ is tightly integrated into Sun Java System Application Server, providing transparent JMS messaging support. This support (known within Sun Java System Application Server as the JMS Service) requires only minimal administration.

This chapter provides information needed to understand and administer the built-in JMS Service provided through Sun Java System Message Queue. It includes the following sections:

About JMS

The JMS specification describes a set of programming interfaces that support distributed, enterprise messaging. An enterprise messaging systems enables independent distributed components or applications to interact through messages. These components, whether on the same system, the same network, or loosely connected through the Internet, use messaging to pass data and coordinate their respective functions.

To support enterprise-scale messaging, JMS provides for reliable, asynchronous message delivery.

Reliable delivery. Messages from one component to another must not be lost due to network or system failure. This means the system must be able to guarantee that a message is successfully delivered.

Asynchronous delivery. For large numbers of components to be able to exchange messages simultaneously, and support high density throughputs, the sending of a message cannot depend upon the readiness of the consumer to immediately receive it. If a consumer is busy or offline, the system must allow for a message to be sent and subsequently received when the consumer is ready. This is known as asynchronous message delivery, popularly known as store-and-forward messaging.

For a full description of JMS, see the JMS 1.0.2 specification, which can be found at the following location:

Basic Messaging System Concepts

A few basic concepts underlie enterprise messaging systems in general, and JMS in particular. These are discussed in this topic.

Message

A message consists of data in some format (message body) and meta-data that describes the characteristics or properties of the message (message header), such as its destination, lifetime, or other characteristics determined by the messaging system.

Message Service Architecture

The basic architecture of a messaging system is illustrated in Figure 10-1. It consists of message producers and message consumers that exchange messages by way of a common message service. In general, any number of message producers and consumers can reside in the same messaging component. A message producer sends a message to a message service. The message service, in turn, using message routing and delivery components, delivers the message to one or more message consumers that have registered an interest in the message. The message routing and delivery components are responsible for guaranteeing delivery of the message to all appropriate consumers.

Message Delivery Models

There are many relationships between producers and consumers: one to one, one to many, and many to many relationships. For example, you might have messages delivered from:

These relationships are often reduced to two message delivery models: point-to-point and publish/subscribe messaging. The focus of the point-to-point delivery model is on messages that originate from a specific producer and are received by a specific consumer. The focus of publish/subscribe delivery model is on messages that originate from any of a number of producers and are received by any number of consumers. These message delivery models can overlap.

Historically, messaging systems supported various combinations of these two delivery models. The JMS API was intended to create a common programming approach that supports both point to point and publish/subscribe delivery models.

JMS Specification

JMS specifies a message structure, a programming model, and a set of rules and semantics that govern messaging operations.

JMS Message Structure

According to the JMS specification, a message is composed of three parts: a header, properties (which can be thought of as an extension of the header), and a body.

Header. The header specifies the JMS characteristics of the message: its destination, whether is persistent or not, its time to live, and its priority. These characteristics govern how the messaging system delivers the message.

Properties. Properties are optional—they provide values that applications can use to filter messages according to various selection criteria.

Message body. The message body contains the actual data to be exchanged. JMS supports six body types.

JMS Programming Model

In the JMS programming model, JMS clients (components or applications) exchange messages by way of a JMS message service. Message producers send messages to the message service, from which message consumers receive them. These messaging operations are performed using a set of objects (furnished by a JMS provider) that implement the JMS API. Figure 10-2 shows the JMS objects used to program the delivery of messages.

In the JMS programming model, a JMS client uses a ConnectionFactory object to create a connection over which messages are sent to and received from the JMS message service. A Connection is a JMS client’s active connection to the message service. Both allocation of communication resources and authentication of the client take place when a connection is created.

The connection is used to create sessions. A Session is a single-threaded context for producing and consuming messages. It is used to create the message producers and consumers that send and receive messages. A session supports reliable delivery through a number of acknowledgement options or through transactions (which can be managed by a distributed transaction manager).

A JMS client uses a MessageProducer to send messages to a specified physical destination, represented in the API as a destination object. The message producer can specify a default delivery mode (persistent vs. non-persistent messages), priority, and time-to-live that govern all messages sent by the producer to the physical destination.

Similarly, a JMS client uses a MessageConsumer to receive messages from a specified physical destination, represented in the API as a destination object. A message consumer can support either synchronous or asynchronous consumption of messages. Asynchronous consumption is achieved by registering a MessageListener with the consumer. The client consumes a message when a session thread invokes the onMessage() method of the MessageListener object.

Administered Objects: Provider Independence

Two of the objects described in Figure 10-2 depend on the details of how a JMS provider implements a JMS message service. The connection factory object depends on the underlying protocols and mechanisms used by the provider to deliver messages, and the destination object depends on the specific naming conventions and capabilities of the physical destinations used by the provider.

Normally these provider-specific characteristics would make JMS client code dependent on the details of a JMS API implementation. To make JMS client code provider-independent, however, the JMS specification requires that provider-specific objects—called administered objects—be accessed in a standardized way, rather than directly instantiated in client code.

Administered objects encapsulate provider-specific implementation and configuration information. They are created and configured by an administrator, stored in a name service, and accessed by client applications through standard JNDI lookup code. Using administered objects in this way makes JMS client code provider-independent.

JMS provides for two general types of administered objects: connection factories and destinations. Both encapsulate provider-specific information, but they have very different uses within a JMS client. A connection factory is used to create connections to a message server, while destination objects are used to identify physical destinations used by the JMS message service.

Message-driven Beans


Note	In the context of the Sun Java System Application Server, JMS administered objects are regarded as JMS resources, similar to other Sun Java System Application Server resources.

In addition to the general JMS client programming model introduced in JMS Programming Model, there is a more specialized adaptation of the JMS API used in the context of J2EE applications. This specialized JMS client is called a message-driven bean and is one of a family of EJB components specified in the EJB 2.0 Specification (http://java.sun.com/products/ejb/docs.html).

The need for message-driven beans arises out of the fact that other EJB components (session beans and entity beans) can only be called synchronously. Hence, when you invoke a method of these beans, resources are blocked until the methods have completed. These EJB components have no mechanism for receiving messages asynchronously, since they are only accessed through standard EJB interfaces.

However, asynchronous messaging is a requirement of many enterprise applications. Hence, the need for an EJB component that can receive messages and consume them without being tightly coupled to the producer of the message.

The MDB is a specialized EJB component supported by a specialized EJB container (a software environment that provides distributed services for the components it supports).

Message-driven Bean. The MDB is a JMS message consumer that implement the JMS MessageListener interface. Its onMessage method (written by the MDB developer) is invoked when a message is received by the MDB container. The onMessage method consumes the message, just as the onMessage method of any JMS MessageListener object would. The MDB can consume messages from a single destination. The messages can be produced by standalone JMS client applications, Web components, or other EJB components, as shown in Figure 10-3.

MDB Container. The MDB is supported by a specialized EJB container, responsible for creating instances of the MDB and setting them up for asynchronous consumption of messages. This involves setting up a connection with the message service (including authentication), creating a pool of sessions associated with a given destination, and managing the distribution of messages as they are received among the pool of sessions and associated MDB instances. Since the container controls the life-cycle of MDB instances, it manages the pool of MDB instances so as to accommodate incoming message loads.

Associated with an MDB is a deployment descriptor that specifies the JNDI lookup names for the administered objects used by the container in setting up message consumption: a connection factory and a destination. The deployment descriptor might also include other information that can be used by deployment tools to configure the container. Each such container supports instances of only a single MDB.

For information on configuring an EJB container’s MDB settings for the Sun Java System Application Server, see About Message-driven Beans.

Built-in JMS Service

Support for JMS messaging, in general, and for MDBs, in particular, is built into Sun Java System Application Server. This support is achieved through the tight integration of Sun Java System Message Queue with the Sun Java System Application Server, providing a native, built-in JMS Service.

This topic covers the following topics necessary to understand this built-in JMS Service:

About Sun Java System Message Queue

Sun Java System Message Queue (MQ) is an enterprise messaging system that implements the JMS open standard: it is a JMS provider.

The MQ product has features that go beyond the minimum requirements of the JMS specification for reliable, asynchronous messaging. Some of these features such as the following are available in the MQ Platform Edition integrated into Sun Java System Application Server:

The following additional features are available by upgrading to the MQ Enterprise Edition:

You can, however, run the MQ broker with a trial license of the Enterprise Edition of MQ. The trial license has a limited 90-day duration enforced by the software, making it suitable for evaluating the enterprise features available in the Enterprise Edition of MQ.

Components of an MQ Messaging System

An MQ messaging system consists of a number of parts, as illustrated in Figure 10-4, that work together to provide for reliable message delivery.

These are introduced briefly in the following topics. For a more complete discussion of the MQ messaging system, see the Sun Java System Message Queue Administration Guide, which can be found at the following location:

MQ Message Server

The main parts of an MQ message server, as shown in Figure 10-4, are brokers and physical destinations.

Brokers. A broker provides delivery services for an MQ messaging system. Message delivery relies upon a number of supporting components that handle connection services, message routing and delivery, persistence, security, and logging. A message server can employ one or more brokers to achieve scalability.

Physical Destinations. Delivery of a message is a two-phase process—delivery from a producing client to a physical destination maintained by a broker, followed by delivery from the destination to one or more consuming clients. Physical destinations represent locations in a broker’s physical memory and/or persistent storage (see Physical Destinations for more information).

Brokers

Message delivery in an MQ messaging system—from producing clients to destinations, and then from destinations to one or more consuming clients—is performed by a broker (or, in the Enterprise Edition, a cluster of brokers working in tandem). To perform message delivery, a broker must set up communication channels with clients, perform authentication and authorization, route messages appropriately, guarantee reliable delivery, and provide data for monitoring system performance.

To perform this complex set of functions, a broker uses a number of different components, each with a specific role in the delivery process. You can configure these internal components to optimize the performance of the broker, depending on load conditions, application complexity, and so on. See the MQ Administration Guide for more information.

Physical Destinations

MQ messaging is premised on a two-phase delivery of messages: first, delivery of a message from a producer client to a destination on the broker, and second, delivery of the message from the destination on the broker to one or more consumer clients. There are two types of destinations: queues (point to point delivery model) and topics (publish/subscribe delivery model). These destinations represent locations in a broker’s physical memory where incoming messages are marshaled before being routed to consumer clients.

You generally create physical destinations using administration tools, however destinations can also be automatically created by the broker upon receipt of a message.

Queue Destinations. Queue destinations are used in point to point messaging, where a message is meant for ultimate delivery to only one of a number of consumers that has registered an interest in the destination. As messages arrive from producer clients, they are queued and delivered to a consumer client.

Topic Destinations. Topic destinations are used in publish/subscribe messaging, where a message is meant for ultimate delivery to all of the consumers that have registered an interest in the destination. As messages arrive from producers, they are routed to all consumers subscribed to the topic. If consumers have registered a durable subscription to the topic, they do not have to be active at the time the message is delivered to the topic—the broker will store the message until the consumer is once again active, and then deliver the message.

MQ Client Runtime

The MQ client runtime provides JMS clients (stand-alone applications, Web components or EJB components) with an interface to the MQ message server—it supplies JMS clients with implementations of all the programming interfaces needed for clients to send messages to destinations and to receive messages from such destinations.

Figure 10-5 illustrates how message production and consumption involve an interaction between JMS clients and the MQ client runtime, while message delivery involves an interaction between the MQ client runtime and the MQ message server.

MQ Administered Objects

MQ administered objects allow JMS client code to be provider-independent (see Administered Objects: Provider Independence). They do this by encapsulating provider-specific implementation and configuration information in objects that can then be used by client applications in a provider-independent way. MQ administered objects are created and configured by an administrator, stored in a name service, and accessed by JMS clients through standard JNDI lookup code.

Connection Factory Administered Objects. A connection factory object is used to create physical connections between a JMS client (stand-alone applications, Web components or EJB components) and an MQ message server. A connection factory object has no physical representation in a broker—it is used simply to enable a JMS client to establish connections with a broker. It is also used to specify behaviors of the connection and of the client runtime that uses the connection to access a broker: an MQ connection factory therefore has a significant number of configurable attributes that allow you to tune the performance of an MQ system.

Destination Administered Objects. A destination administered object (a queue or a topic) represents a physical destination (a physical queue or a physical topic) in a broker to which the publicly-named destination administered object corresponds. By creating a destination administered object, you allow JMS clients (message consumers and/or message producers) to access the corresponding physical destination.

MQ Administration Tools

MQ administration tools fall into two categories: command line utilities and a graphical user interface (GUI) Administration Console.

The Administration Console. You can use the administration console to connect to a broker and manage it, create physical destinations on the broker, connect to an object store and add, update, or delete administered objects from the object store. There are some tasks that you cannot use the Administration Console to perform; chief among these are starting up a broker, creating broker clusters, configuring more specialized properties of a broker, and managing a user database.

Command Line Utilities. You use the MQ utilities to perform all the tasks you can perform using the administration console, and in addition, to start up and manage a broker, configure more specialized properties of a broker, and manage a MQ user database.

Integration of MQ with Sun Java System Application Server

MQ Platform Edition is automatically installed as part of the Sun Java System Application Server installation process. For more information, see the Sun Java System Application Server Installation Guide.

This installation provides Sun Java System Application Server with a JMS messaging system that supports any number of application server instances. Each server instance, by default, has an associated built-in JMS Service that supports all JMS clients running in the instance.

Architecture of the Built-in JMS Service

The built-in JMS Service—illustrated in Figure 10-6—is similar to an ordinary MQ messaging system (shown in the figure MQ System Architecture), except for a number of qualifications, described below.

MQ Message Server. Each application server instance is associated with its own built-in JMS Service. The built-in JMS Service makes use of a single-broker message server. The broker runs in a separate process outside of the application server instance as shown in Figure 10-6. By default, the broker instance (the built-in JMS Service) starts up when its associated server instance is started up and shuts down when the server instance is shut down. Configuration information for a server instance’s built-in JMS Service is recorded in the application server configuration store (the server.xml file) and can be modified as described in Configuring the JMS Service.

MQ Client Runtime. The client runtime part of the JMS Service is a set of libraries that support the JMS API. Any JMS clients (JMS client components, including MDBs) that run in a server instance have access to these libraries.

MQ Administered Objects. The built-in JMS Service uses an object store provided by application server. Each server instance has its own object store. The JMS Service stores administered objects (connection factory and destination resources) in this object store. You create these administered object resources as described in Managing Administered Object Resources, and they are accessed by JMS clients using JNDI lookup code.

Application Server Administration. The Sun Java System Application Server Administration interface and command line utilities implement a limited subset of MQ administration capability. The Administration interface and command line let you configure the built-in JMS Service, create and delete physical destinations, and create and delete administered object resources needed by JMS clients to perform JMS messaging operations. These administration tools, however, do not allow (or do not facilitate) performing more sophisticated administration tasks, such as setting broker properties, tuning the MQ client runtime, modifying the MQ user repository, managing MQ security, and so forth. If you wish to perform these administration tasks for the built-in JMS Service, you have to use the administration tools installed with MQ and described in the MQ Administration Guide. For a comparison of MQ and Sun Java System Application Server administration capability, see the table Comparison of Sun Java System Message Queue and Sun Java System Application Server Administration Capability.

Disabling the Built-in JMS Service

By default, the built-in JMS Service is started up (that is, the MQ broker is started up) when the associated application server instance is started up. However, you might want to disable the automatic startup of the JMS Service when you start up a server instance, either because the server instance does not need to support JMS messaging or because the server instance uses an external JMS Service. (To disable the built-in JMS Service, see Configuring the JMS Service.)

An external JMS Service is a messaging system that is not controlled from within application server. In the case of MQ—the native JMS provider—this means that you simply start up and manage your MQ message server independently, using MQ administration tools. JMS clients running in various server instances can still use MQ administered objects to access the MQ message server. These administered objects can either be stored in the object store associated with each application server instance, or in a separate, independent object store managed by the MQ administration tools (where the store can be shared by multiple server instances if necessary).

There are a number of scenarios in which a server instance might use an external JMS Service. The most likely is when JMS clients in different server instances need to access the same physical destinations. In that case, the server instances must all access the same message server. To achieve this, you disable the built-in JMS Service for all server instances and configure all JMS clients to perform the appropriate JNDI lookups to access the external JMS Service. In addition, you independently administer the external JMS Service (managing the message server, creating physical destinations, and creating all needed administered objects) using the external JMS Service provider’s administration tools.

To configure multiple application server instances to share a single MQ broker instance:

It is possible to have both an external and built-in JMS Service running at the same time. JMS clients in a server instance can access whichever JMS Service they need.

One possibility that is not recommended is to have a number of server instances share the same built-in JMS Service (one is enabled, the rest are disabled). This is not recommended because the enabled JMS Service only runs when its associated server instance runs, making it very difficult to manage the situation.

When you disable a built-in JMS Service, you also disable your ability to perform administrative tasks associated with that built-in JMS Service. All administrative tasks needed to support an external JMS Service must be performed using the administration tools for managing that external service.

Administration of the Built-in JMS Service

This topic focuses on administration of the built-in JMS Service. Administration is performed on a server instance-by-server instance basis.

Table 10-1 Comparison of Sun Java System Message Queue and Sun Java System Application Server Administration Capability
Function	Sun Java System MQ Administration Tools	Sun Java System Application Server Administration interface	Sun Java System Application Server Administration Command Line
Manage MQ broker state	yes	start/stop	start/stop
Configure MQ broker	yes	no	no
Manage MQ broker user repository	yes	no	no
Multi-broker clusters	yes	no	no
Manage security	yes	no	no
Manage physical destinations	yes	create/delete	create/delete
Manage durable subscriptions and transactions	yes	no	no
Manage administered object resources	yes	create/delete/ configure	yes

The following sections explain how to perform JMS Service administration tasks using the Sun Java System Application Server Administration interface.

Configuring the JMS Service

At installation time a number of JMS Service properties are set for the built-in JMS Service. You can change the default values of these properties by configuring the JMS Service.

Table 10-2 JMS Service Properties
Property	Description	Default Value
Log level	The level of logging information you want written to the Sun Java System Application Server log file. For more information, see Chapter 5, "Using Logging."	DEBUG_HIGH
Port	The primary port number of the broker instance providing built-in JMS Service. By default, the built-in JMS Service uses the default primary port number. However, if that port conflicts with other software, or if you are starting up more than one Application Server instance, you need to specify a unique primary port number for each. Note that it is possible to have a port conflict if the port number assigned to the JMS Service at installation time later is used by another service. In this case, you have to give the JMS Service a different port number.	7676
Administrator’s username/password	The username/password needed to perform broker administration tasks, such as managing physical destinations (see Managing Physical Destinations). It is recommended that you modify the administrator username and password to be something other than the default. To do this, you need to first make the appropriate entries in the broker's user repository (as described in the Sun Java System Message Queue Administrator’s Guide) and then enter the corresponding values here for the administrator's username and password.	admin/admin
Start Timeout	Specifies the time in seconds that the server instance waits for the JMS Service to start up. If this timeout is exceeded, the server instance startup is aborted.	60
Start Arguments	Specifies any arguments that will be used in starting up the JMS Service. The startup arguments for the imqbroker command, and how to specify them, can be found in the Sun Java System Message Queue Administrator’s Guide. (The -name and -port arguments, if supplied, are ignored.)
Startup Enabled	Specifies whether the built-in JMS Service is started up when the server instance starts up. If you are not supporting JMS messaging or are using an external JMS message service, set this property to FALSE.	TRUE

The built-in JMS Service can be configured before starting up its corresponding server instance. If the server instance is already running, however, configuration changes take effect only after the server instance is stopped and subsequently restarted.

Managing Physical Destinations

In JMS messaging, a JMS producer sends messages to a physical destination on a message service from which they are dispatched to a JMS consumer.

For the built-in JMS Service, you can create these physical destinations explicitly or they can be created automatically by the JMS Service (MQ broker) upon receipt of a message. In general, you have more control over the messaging system and its resources by explicitly creating the physical destinations needed by messaging applications. When these destinations are no longer needed, you can delete them.

In order to create or delete physical destinations for a built-in JMS Service, the JMS Service must be running and the administrator username and password (specified when you configure the built-in JMS Service) must correspond to valid entries in the broker’s user repository (see the table JMS Service Properties).

Using the Administration interface, you can perform the following management tasks for physical destinations on a built-in JMS Service:

Create a Physical Destination

List Physical Destinations

Delete a Physical Destination

Managing Administered Object Resources

MQ administered objects, regarded by Sun Java System Application Server as JMS Resources, are used by JMS clients to access a JMS Service (either built-in or external).

Two administered object resources—connection factories and destinations—are used by J2EE components to obtain connections to a JMS Service, and then to deliver messages to and from physical destinations on the Service (see MQ Administered Objects).

Because the creation of administered object resources does not involve the JMS Service directly, you do not need to enable the JMS Service, and you do not need a valid username and password (see the table JMS Service Properties), to create administered object resources for a server instance.

Administered Object Attributes

To support JMS messaging, you must create the administered object resources required by all JMS clients running in a server instance. At a minimum, you need to specify a JNDI lookup name for each administered object resource, its type (connection factory, queue, or topic), a description (optional) and whether or not the resource is enabled. Other attributes are discussed in the following sections.

Destination (queue or topic)

In the case of queue or topic administered objects, you also need to specify the name of the corresponding physical destination.

Connection Factory

Connection factory administered objects have attributes as listed in Table 10-3. The attribute you are primarily concerned with is imqAddressList, which is used to specify the broker to which the client will establish a connection. The section, Create a ConnectionFactory Administered Object explains how you specify a attributes when you add a connection factory administered object to your object store.

Table 10-3 Connection Factory Administered Object Attributes
Attribute/property name	Type	Default Value
imqAckOnAcknowledge	String	No value
imqAckOnProduce	String	No value
imqAckTimeout	String	0 millisecs
imqAddressList	String	No value
imqAddressListIterations	Integer	1
imqAddressListBehavior	String	PRIORITY
imqBrokerHostName (MQ 3.0)	String	localhost
imqBrokerHostPort (MQ 3.0)	Integer	7676
imqBrokerServicePort (MQ 3.0)	Integer	0
imqConfiguredClientID	String	No value
imqConnectionFlowCount	Integer	100
imqConnectionFlowLimit	Integer	1000
imqConnectionFlowLimitEnabled	Boolean	false
imqConnectionType (MQ 3.0)	String	TCP
imqConnectionURL (MQ 3.0)	String	http://localhost/imq/tunnel
imqConsumerFlowLimit	Integer	1000
imqConsumerFlowThreshold	Integer	50
imqDefaultPassword	String	guest
imqDefaultUsername	String	guest
imqDisableSetClientID	Boolean	false
imqJMSDeliveryMode	Integer	2 (persistent)
imqJMSExpiration	Long	0 (does not expire)
imqJMSPriority	Integer	4 (normal)
imqLoadMaxToServerSession	Boolean	true
imqOverrideJMSDeliveryMode	Boolean	false
imqOverrideJMSExpiration	Boolean	false
imqOverrideJMSHeadersToTemporaryDestinations	Boolean	false
imqOverrideJMSPriority	Boolean	false
imqQueueBrowserMaxMessagesPerRetrieve	Integer	1000
imqQueueBrowserRetrieveTimeout	Long	60,000 (milliseconds)
imqReconnectAttempts	Integer	0
imqReconnectEnabled	Boolean	false
imqReconnectInterval	Long	3000 (milliseconds)
imqSetJMSXAppID	Boolean	false
imqSetJMSXConsumerTXID	Boolean	false
imqSetJMSXProducerTXID	Boolean	false
imqSetJMSXRcvTimestamp	Boolean	false
imqSetJMSXUserID	Boolean	false
imqSSLIsHostTrusted (MQ 3.0)	Boolean	true

For more descriptions of connection factory attributes and information on how they are used, see the Sun Java System Message Queue 3.5 Administration Guide and the JavaDoc API documentation for the following MQ class: com.sun.messaging.ConnectionConfiguration.

However, if you disable the JMS Service for a particular server instance, then any JMS clients supported by that server instance must use an external JMS Service. When you create a connection factory to be used to create connections to that external JMS Service, you need to set attributes that specify the hostname, port number of the appropriate broker instance, address list and so on.

Connection factory administered objects have additional attributes used to tune the server instance’s MQ client runtime. These are documented in the MQ Developer’s Guide.

Connection factory administered objects created using the Administration interface support distributed transaction managers.

Administered Object Resource Management Tasks

From the Administration interface, you can perform the following management tasks for administered object resources:

Create a Queue or Topic Administered Object (Destination Resource)

In addition, you must specify the destination name for the object by specifying the imqDestinationName property. The value of this property should match the physical destination’s name.

Create a ConnectionFactory Administered Object

To create a queue connection factory or topic connection factory administered object:

If this connection factory creates connections to a broker other than that of the built-in JMS Service, you must set values for other properties.

List Administered Object Resources

Delete an Administered Object Resource

Viewing the JMS Log

To troubleshoot your JMS Service, in addition to the Sun Java System Application Server log files, you can also use the JMS log file. All the messages from the MQ broker are logged to the broker log files, while the Sun Java System Application Server log files contain the messages which the MDB or the MDB container sends.

For more information on using the JMS log files, see the Sun Java System Message Queue Administration Guide.

Administering the Built-in JMS Service Using the Command-Line Interface

The Sun Java System Application Server has a command-line utility, asadmin, which you can use to perform all the same tasks as you can perform with the Administration interface.

Use the following asadmin commands to configure and administer the built-in JMS Service.

Table 10-4 asadmin Commands for Administering the Built-in JMS Service
Command	Use
add-resources	Adds one or more resources of type jdbc, jms, or javamail.
create-jmsdest	Creates a JMS physical destination.
create-jms-resource	Creates a JMS resource.
delete-jmsdest	Deletes a JMS physical destination.
delete-jms-resource	Deletes a JMS resource.
jms-ping	Pings the JMS provider to see if it is running.
list-jmsdest	Lists JMS physical destinations for a server instance.
list-jms-resources	Lists JMS resources for a server instance.
get and set jms-service	Gets and sets attributes for the JMS service.
get and set jms-resource	Gets and sets attributes for a JMS resource.

For information on the syntax of these commands, see the online help for asadmin. For more information on asadmin, as well as a list of attributes for jms-service and jms-resource, see Appendix A, "Using the Command Line Interface."

Previous Contents Index Next
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Update 3 Administration Guide