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

> ## 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
> - Built-in JMS Service
> - Administration of the Built-in JMS Service

> ##

> 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.

> This topic is a brief overview of JMS concepts and terminology:

> - Basic Messaging System Concepts
> - JMS Specification
> - Message-driven Beans

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

> http://java.sun.com/products/jms/docs.html

> ### 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.

> Figure 10-1 Message Service Architecture

> #### 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:

> - one producer to one consumer
> - one producer to many consumers
> - many producers to one consumer
> - many producers to many consumers.

> 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.

> Figure 10-2 JMS Programming Objects

> 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.

> 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.

> ### Message-driven Beans

> 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).

> Figure 10-3 MDB Message Consumers

> 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
> - Integration of MQ with Sun Java System Application Server

> For information on administering the built-in JMS Service, see Administration of the 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:

> - centralized administration
> - tunable performance
> - support for multiple messaging transports
> - user authentication and authorization

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

> - support for multi-broker message services
> - HTTP/HTTPS connections
> - secure connection services
> - scalable connection capability
> - multiple queue delivery policies

> 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.

> For information on how to run the trial version of MQ Enterprise Edition see Appendix D, "Running Message Queue Broker with Trial Enterprise License." The Appendix also provides information on how to purchase the Enterprise Edition, should you wish to do so.

> ### 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.

> The main parts of an MQ messaging system are the following:

> - MQ Message Server
> - MQ Client Runtime
> - MQ Administered Objects
> - MQ Administration Tools

> 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:

> http://docs.sun.com/

> #### 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).

> Figure 10-4 MQ System Architecture

> ##### 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.

> Figure 10-5 Messaging Operations

> #### 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.

> This topic covers the following topics:

> - Architecture of the Built-in JMS Service
> - Disabling the Built-in JMS Service

> The built-in JMS Service can be administered using Sun Java System Application Server administration tools (see Administration of the Built-in JMS Service).

> #### 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.

> Figure 10-6 Built-in MQ Messaging System

> 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:

> 1. Disable the JMS service on all the server instances.
> 2. Manage the shared MQ broker independently of any server instance, which means you must start up and shut down the broker using the administration tools for managing the external service. You must also manage physical destinations independently of the Sun Java System Application Server.
> 3. Configure a connection factory JMS resource in each server instance such that it points to this external MQ broker (you must set the properties appropriately).
> 4. Use this connection factory resource when deploying JMS applications on the Sun Java System Application Server.

> 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.

> Administration of the built-in JMS Service involves the following tasks:

> - Configuring the JMS Service
> - Managing Physical Destinations
> - Managing Administered Object Resources
> - Viewing the JMS Log
> - Administering the Built-in JMS Service Using the Command-Line Interface

> Administration can be performed using the Sun Java System Application Server’s Administration interface or command line utility. A comparison of these administration tools with MQ administration tools is shown in the table Comparison of Sun Java System Message Queue and Sun Java System Application Server Administration Capability.

> 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.

> JMS Service properties are described in the Table 10-2.

> 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.

> To configure the built-in JMS Service:

> 1. Open the Administration interface.
> 2. Open a server instance in the left pane.
> 3. Open the JMS folder.
> 4. Select the Service link.
> 5. Modify any of the properties you wish (see the table JMS Service Properties).
> 6. Click the Save button.

> The JMS Service screen is refreshed.

> ### 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

> #### Create a Physical Destination

> To create a queue or topic destination:

> 1. Open the Administration interface.
> 2. Open a server instance in the left pane.
> 3. Open the JMS folder.
> 4. Open the Service link.
> 5. Select the Physical Destinations link

> The Physical Destinations screen is displayed in the right pane.

> 6. Click the New button.

> The Physical Destinations: New screen is displayed in the right pane.

> 7. Enter the name of the physical destination.
> 8. Select queue or topic from the Type pull down.
> 9. Click the OK button.

> The right pane is refreshed and displays the new queue or topic destination in the list of existing queue and topic destinations.

> #### List Physical Destinations

> To list existing queue and topic destinations:

> 1. Open the Administration interface.
> 2. Open a server instance in the left pane.
> 3. Open the JMS folder.
> 4. Open the Service link.
> 5. Select the Physical Destinations link

> The right pane displays the current physical destinations.

> #### Delete a Physical Destination

> You can delete queue or topic destinations as needed.

> To delete a physical destination:

> 1. List the existing destinations (see List Physical Destinations).
> 2. Click within the Select box for each destination you wish to delete.
> 3. Click the Delete button to remove the selected destinations.

> The list refreshes, showing the remaining destinations.

> ### 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)
> - Create a ConnectionFactory Administered Object
> - List Administered Object Resources
> - Delete an Administered Object Resource

> ##### Create a Queue or Topic Administered Object (Destination Resource)

> To create a queue or topic administered object:

> 1. Open the Administration interface.
> 2. Open a server instance in the left pane.
> 3. Open the JMS folder.
> 4. Select the Destination Resources link.

> The Destination Resources screen is displayed in the right pane.

> 5. Click on the New button.

> The Destination Resources: New screen is displayed.

> 6. Enter the JNDI lookup name associated with this destination administered object.
> 7. Select the “queue” or “topic” object type from the pull down list.
> 8. Click the OK button.

> The right pane re-displays the Destination Resource: New screen.

> 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.

> To change the value of this property:

> 1. Open the Administration interface.
> 2. Open a server instance in the left pane.
> 3. Open the JMS folder.
> 4. Open the Destination Resources folder.
> 5. Select the Destination Resource you want to edit.

> The right pane displays the Destination Resource screen.

> 6. In the right pane, click Properties.

> The Edit Properties screen appears.

> 7. In the Name field, enter imqDestinationName.
> 8. In the Value field, enter the physical destination’s name.
> 9. Click OK.

> The right pane redisplays the Destination Resources screen.

> ##### Create a ConnectionFactory Administered Object

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

> 1. Open the Administration interface.
> 2. Open a server instance in the left pane.
> 3. Open the JMS folder.
> 4. Select the Connection Factories link.

> The Connection Factory Resources screen is displayed in the right pane.

> 5. Click on the New button.

> The Connection Factory Resources: New screen is displayed.

> 6. Enter the JNDI lookup name associated with this connection factory administered object.
> 7. Select the connection factory object type from the pull down list.
> 8. Click the OK button.

> The right pane re-displays the Connection Factory Resources screen with the newly created connection factory object in the list.

> 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.

> To change the value of these properties:

> 1. Open the Administration interface.
> 2. Open a server instance in the left pane.
> 3. Open the JMS folder.
> 4. Open the Connection Factories folder
> 5. Select the Connection Factory resource you want to edit.

> The right pane displays the Connection Factory screen.

> 6. In the right pane, click Properties.

> The Edit Properties screen appears.

> 7. In the Name field, enter a property.
> 8. In the Value field, enter a value for the property.
> 9. Enter other property and the respective values.
> 10. Click OK.

> The right pane redisplays the Connection Factory screen.

> ##### List Administered Object Resources

> To list existing administered objects:

> 1. Open the Administration interface.
> 2. Open a server instance in the left pane.
> 3. Open the JMS folder.
> 4. Select the Destination Resources or Connection Factory Resources link

> The right pane displays the current destination or connection factory administered objects.

> ##### Delete an Administered Object Resource

> To delete an administered object resource:

> 1. List the existing administered object resources (see List Administered Object Resources).

> The right pane displays the existing administered object resources.

> 2. Click within the Select box for each object you wish to delete.
> 3. Click the Delete button to remove each selected object.

> The screen refreshes the list, showing the remaining administered object resources.

> ### 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.

> The location of the JMS log file varies by platform and installation type.

> For the file-based installation, the log file default location is:

> install_root/imq/instances/instance/log/log.txt

> For Solaris package-based installations, the log file default location is:

> /var/imq/instances/instance/log/log.txt

> For Linux packaged-based installations, the log file default location is:

> /opt/imq/var/instances/instance/log/log.txt

> For Windows installations, the log file default location is:

> install_root/imq/instances/instance/log/log.txt

> 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

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.