|
| Sun ONE Application Server 7 Administrator's Guide |
Using the JMS ServiceSun ONE 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 ONE 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 ONE Application Server uses Sun ONE Message Queue (MQ), Version 3.01, as its native JMS provider.
MQ is tightly integrated into Sun ONE Application Server, providing transparent JMS messaging support. This support (known within Sun ONE Application Server as the JMS Service) requires only minimal administration.
This module provides information needed to understand and administer the built-in JMS Service provided through Sun ONE Message Queue. It includes the following topics:
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:
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 the figure "Message Service Architecture." 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 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.
The 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. Properties are optional.
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. The figure "JMS Programming Objects" 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.
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 the figure "JMS Programming Model" 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 ONE Application Server, JMS administered objects are regarded as JMS resources, similar to other Application Server resources.
Message-driven Beans
In addition to the general JMS client programming model introduced in the figure "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).
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 the "MDB Message Consumers" figure.
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 ONE Application Server, see "About Message-driven Beans".
The Built-in JMS Service
Support for JMS messaging, in general, and for MDBs, in particular, is built into Sun ONE Application Server. This support is achieved through the tight integration of Sun ONE Message Queue with the Sun ONE Application Server, providing a native, built-in JMS Service.
This topic covers the following topics necessary to understand this built-in JMS Service:
For information on administering the built-in JMS Service, see "Administration of the Built-in JMS Service".
About Sun ONE Message Queue (MQ)
Sun ONE Message Queue (MQ) is an enterprise messaging system that implements the JMS open standard: it is a JMS provider.
The MQ product has features which go beyond the minimum requirements of the JMS specification for reliable, asynchronous messaging. Some of these features (centralized administration, tunable performance, support for multiple messaging transports. user authentication and authorization) are available in the MQ Platform Edition integrated into Sun ONE Application Server. Additional features (scalable message servers and secure messaging) are available by upgrading to the MQ Enterprise Edition.
An MQ messaging system consists of a number of parts, as illustrated in the figure "MQ System Architecture", that work together to provide for reliable message delivery.
The main parts of an MQ messaging system are the following:
These are introduced briefly in the following topics. For a more complete discussion of the MQ messaging system, see the MQ Administrator's Guide, which can be found at the following location:
MQ Message Server
The main parts of an MQ message server, as shown in the figure "MQ System Architecture", 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).
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 MQ 3.01 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 Administrator's 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.
The figure "Messaging Operations" 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.
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 ONE Application Server
MQ Platform Edition is automatically installed as part of the Sun ONE Application Server installation process. For more information, see the Sun ONE Application Server Installation Guide.
This installation provides Sun ONE Application Server with a JMS messaging system that supports any number of Sun ONE 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:
The built-in JMS Service can be administered using Sun ONE 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 the figure "Built-in MQ Messaging System"—is similar to an ordinary MQ messaging system (shown in the figure "MQ System Architecture"), except for a number of qualifications, described below.
Built-in MQ Messaging System
MQ Message Server. Each Sun ONE 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 Sun ONE Application Server instance as shown in the figure "Built-in MQ Messaging System." 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 Sun ONE 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 Sun ONE 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.
Sun ONE Application Server Administration. The Sun ONE 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 Administrator's Guide. For a comparison of MQ and Sun ONE Application Server administration capability, see the table "Comparison of Sun ONE Message Queue and Sun ONE 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 Sun ONE 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 Sun ONE 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:
- Disable the JMS service on all the server instances.
- 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 ONE Application Server.
- Configure a connection factory JMS resource in each server instance such that it points to this external MQ broker (you must set the imqBrokerHostName and imqBrokerHostPort properties appropriately).
- Use this connection factory resource when deploying JMS applications on the Sun ONE 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
- Administering the Built-in JMS Service Using the Command-Line Interface
Administration can be performed using the Sun ONE 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 ONE Message Queue and Sun ONE Application Server Administration Capability."
The following sections explain how to perform JMS Service administration tasks using the Sun ONE 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 "JMS Service Properties."
JMS Service Properties
Property
Description
Default Value
Log level
The level of logging information you want written to the Sun ONE Application Server log file. For more information, see "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 Sun 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"). If you want administrator access to a broker instance to be secure (by default, any user is provided access), you need to first make the appropriate entries in the broker's user repository (as described in the MQ 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 MQ 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:
- Open the Administration interface.
- Open a server instance in the left pane.
- Open the JMS folder.
- Select the Service link.
The JMS Service configuration screen is displayed on the right pane.
JMS Service Configuration Screen
- Modify any of the properties you wish (see the table "JMS Service Properties").
- 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 Queue or Topic Destination
To create a queue or topic destination:
- Open the Administration interface.
- Open a server instance in the left pane.
- Open the JMS folder.
- Open the Service link.
- Select the Physical Destinations link
The Physical Destinations screen is displayed in the right pane.
- Click the New button.
The Physical Destinations: New screen is displayed in the right pane.
New JMS Physical Destination Screen
- Enter the name of the physical destination.
- Select queue or topic from the Type pull down.
- 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:
- Open the Administration interface.
- Open a server instance in the left pane.
- Open the JMS folder.
- Open the Service link.
- 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:
- List the existing destinations (see "List Physical Destinations").
- Click within the Select box for each destination you wish to delete.
JMS Physical Destinations Screen
- 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 ONE Application Service 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
In the case of connection factory administered objects, the Administration interface creates, by default, a connection factory that points to the built-in JMS Service—that is, to a broker instance whose hostname is the local host and whose port number is that set when configuring the JMS Service (see the table "JMS Service Properties").
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 and port number of the appropriate broker instance.
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:
- Open the Administration interface.
- Open a server instance in the left pane.
- Open the JMS folder.
- Select the Destination Resources link.
The Destination Resources screen is displayed in the right pane.
- Click on the New button.
The Destination Resources: New screen is displayed.
New Destination Administered Object Screen
- Enter the JNDI lookup name associated with this destination administered object.
- Select the "queue" or "topic" object type from the pull down list.
- 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:
- Open the Administration interface.
- Open a server instance in the left pane.
- Open the JMS folder.
- Open the Destination Resources folder.
- Select the Destination Resource you want to edit.
The right pane displays the Destination Resource screen.
- In the right pane, click Properties.
The Edit Properties screen appears.
- In the Name field, enter imqDestinationName.
- In the Value field, enter the physical destination's name.
- 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:
- Open the Administration interface.
- Open a server instance in the left pane.
- Open the JMS folder.
- Select the Connection Factories link.
The Connection Factory Resources screen is displayed in the right pane.
- Click on the New button.
The Connection Factory Resources: New screen is displayed.
New ConnectionFactory Administered Object Screen
- Enter the JNDI lookup name associated with this connection factory administered object.
- Select the connection factory object type from the pull down list.
- 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 the imqBrokerHostName and imqBrokerHostPort properties.
To change the value of these properties:
- Open the Administration interface.
- Open a server instance in the left pane.
- Open the JMS folder.
- Open the Connection Factories folder
- Select the Connection Factory resource you want to edit.
The right pane displays the Connection Factory screen.
- In the right pane, click Properties.
The Edit Properties screen appears.
- In the Name field, enter imqBrokerHostName.
- In the Value field, enter a value for the property.
- In the Name field and imqBrokerHostPort.
- In the Value field, enter a value for the property.
- Click OK.
The right pane redisplays the Connection Factory screen.
List Administered Object Resources
To list existing administered objects:
- Open the Administration interface.
- Open a server instance in the left pane.
- Open the JMS folder.
- 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:
- List the existing administered object resources (see "List Administered Object Resources").
The right pane displays the existing administered object resources.
- Click within the Select box for each object you wish to delete.
JMS Connection Factory Screen, Refreshed
- Click the Delete button to remove each selected object.
The screen refreshes the list, showing the remaining administered object resources.
Administering the Built-in JMS Service Using the Command-Line Interface
The Sun ONE 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.
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 "Using the Command Line Interface."