Previous Contents Index Next |
iPlanet Application Server Developer's Guide |
Appendix A Using the Java Message Service
This appendix describes how to use the Java Message Service (JMS) API. The iPlanet Application Server allows third party JMS provider integration into its Java environment, and provides two value-added features: connection pooling and user identity mapping.This appendix contains the following sections:
About the JMS API
About the JMS API
JMS is a J2EE API which provides a standard set of Java language interfaces to an Enterprise Messaging System, often referred to as message oriented middleware. These interfaces are implemented by the JMS provider. The iPlanet Application Server supports the iPlanet Message Queue and the JMS provider for IBM MQ Series. For more information about the iPlanet Message Queue, refer to the following documentation:http://docs.iplanet.com/docs/manuals/javamq.html
The JMS web page at http://java.sun.com/products/jms/index.html describes JMS's purpose as follows:
The iPlanet Application Server also includes JMS Connection Pooling and User Identity Mapping. These are provided through an administrative framework and the iPlanet Application Server specific code is not required. Applications can use these features transparently, maintaining component portability.
- Enterprise messaging provides a reliable, flexible service for the asynchronous exchange of critical business data and events throughout an enterprise. The JMS API adds to this a common API and provider framework that enables the development of portable, message based applications in the Java programming language.
JMS Messaging Styles
JMS supports two messaging styles:
Point-to-point: allows two programs to communicate by sending and receiving messages through a Destination called a Queue.
Regardless of messaging style, the link between applications and the JMS provider is the connection object. Applications get their connection objects from the Connection Factories.Publish/subscribe: allows several messaging programs to communicate through a Destination called a Topic. Messages are sent by publishing to a Topic. Messages are received by subscribers.
In order to maximize portability of an application between JMS providers, provider specific messaging aspects are encapsulated in administered objects. JMS administered objects implement one of the following four JMS interfaces, two for each messaging style:
JMS providers supply classes that implement these interfaces. Administration tools are used to create and configure administered object class instances, and to configure them to the deployment requirements. Administrators use the tools to set provider specific parameters.
This programming model allows JMS programs to be written that are completely provider independent. Applications look up the administered objects by name using JNDI.
The following sample looks up its connection factory and destination, and sends a simple text message to a queue (exception handling has been omitted for clarity):
// Use JNDI to find the connection factory and the destination Context ctx = new InitialContext();
QueueConnectionFactory factory;
factory = (QueueConnectionFactory) ctx.lookup ("java:comp/env/jms/theFactory");Queue queue = (Queue) ctx.lookup("java:comp/env/jms/theQueue");
// create a connection, session, sender and the message QueueConnection conn;
conn = factory.createQueueConnection("myUserName", "myPassword");
QueueSession session = connection.createQueueSession (false, Session.AUTO_ACKNOWLEDGE);
QueueSender sender = session.createSender(queue);
TextMessage msg = session.createTextMessage();
msg.setText("Hello from a simple Java Message Service Application");
// start up the connection, send the message
connection.start();
sender.send(msg);
connection.stop();
// now close all resources to insure that native resources are released
sender.close();
session.close();
connection.close();Note that the application did not hardcode the resource names, but instead used J2EE resource references, as described in the section on application deployment. Applications should reference objects in the JMS subcontext directly, since the iPlanet Application Server deployment manager does not support JMS resource references.
Enabling JMS and Integrating Providers
The iPlanet Application Server includes the software to integrate JMS providers, but it must be enabled. For information about how to integrate a JMS provider with the iPlanet Application Server, see the following documentation:install_dir/ias/ias-samples/jms/docs/index.html
Using JMS in Applications
JMS support for the iPlanet Application Server is based entirely on standard J2EE APIs. Application components using the value-added features are portable with other J2EE environments. This section discusses some issues that you should consider when using JMS in applications deployed on the iPlanet Application Server.
JNDI and Application Component Deployment
JMS objects are stored by the administration tools in the JMS subcontext of the iPlanet Application Server root JNDI name space. The JMS subcontext does not support creation of subcontexts of itself. Links to the components application context are established at application deployment time.When an InitialContext is created with the default parameters, JMS objects may be referenced by name beginning with jms/. Greater flexibility can be achieved by using J2EE resource references. This was demonstrated in the sample shown on page 381, where the name looked up for the factory was java:comp/env/jms/theFactory. In the iPlanet Application Server JMS, JMS resource references are not supported. JMS objects should be referenced directly.
Connection Factory Proxy
The iPlanet Application Server supports the JMS connection pooling and user identity maps. The ConnectionFactoryProxy class functions by interposing between the application and the JMS provider's connection factory. There are two proxy classes, one for each messaging style:The APIs presented by the proxy classes are the standard JMS APIs: QueueConnectionFactory and TopicConnectionFactory. Only administrators need be concerned with proxies, which are used transparently to the application.
A simple administration program configures ConnectionFactoryProxies. The proxies handle connection pooling and user ID mapping. JMS operations are forwarded to a connection obtained by the proxy from a provider factory specified by the administrator.
Connection Pooling
Setting up a JMS connection is network intensive and therefore expensive. Connection pooling facilitates the re-use of JMS connections. When pooling is enabled and an application closes a connection, the proxy returns the connection to the pool instead of closing the provider connection. When a subsequent application attempts to create a connection using the same username and password, the proxy re-uses the connection.
User Identity Mapping
The ConnectionFactoryProxy also provides user identity mapping. JMS providers do not use the same security infrastructure as the application server and thus have different user name spaces. User identity mapping provides administrators flexibility in designing their security infrastructure.Two mapping forms are provided by the connection factory proxy classes:
As with connection pooling, this functionality is implemented by the proxy classes within the standard JMS API. When using this user identity mapping, the deployment depends on the iPlanet Application Server user security mechanisms to control access to the messaging system.
About Default Username
Default username and password enable multiple application users to share a single messaging system provider user ID and password.When a proxy is created, the administrator may define a default proxy user name and password. Applications invoking the no argument create connection method pass these values to the provider factory when creating a connection. For example, when the application calls:
connection = proxy.createQueueConnection();
If a default user name has been configured, the iPlanet Application Server proxy implementation obtains its JMS Connection with:
connection = providerFactory.createQueueConnection (defaultUserName, defaultPassword);
About Explicit User ID Map
An explicit user ID map may also be used. The map contains an entries list, each referenced by a unique user ID key and containing two values:The administrator creates the map using the jmsuadm tool. The entry values are used when creating a connection. For example, when an application creates a connection using the proxy with:
connection = proxy.createQueueConnection(userString, passWordString);
The iPlanet Application Server proxy looks up the given userString entry in the map. If it finds an entry, the proxy passes jmsUserName and jmsPassWord values from the entry to the JMS provider factory, ignoring the application provided password. That is, the proxy effectively executes:
connection = providerFactory.createConnection (entry.jmsUserName, entry.jmsPassWord);
If no entry matching userString is found in the user identity map, the application provided values are passed through to the JMS provider factory (providerFactory).
ConnectionFactoryProxies and Application Created Threads
A servlet can create Java threads, but it is not recommended. User created threads are not known to the JMS connection pooling infrastructure. Applications must not invoke the create connection or connection close methods from user created threads. Attempting to do so results in:javax.jms.IllegalStateException
This is not implemented in JMS beta. In beta, applications that attempt to create or close connections from application created threads crash KJS.
JMS Features Not Supported
The iPlanet Application Server does not support the JMS XAConnection and server session pools features described in the JMS specification.
JMS Administration
The JMS API depends on administered objects for portability. Provider specific deployment aspects are encapsulated in administered objects which allow portable application code. In the iPlanet Application Server environment JMS administration consists of four tasks:
Creating JMS provider factories and destinations
Creating ConnectionFactoryProxies
Modifying the iPlanet Application Server registry connection pooling parameters
JMS Object Administration Tools
Each JMS product should include an administration program. This tool creates objects and binds them to names in the iPlanet Application Server JNDI. This section describes the Java properties and system paths required to configure a tool to work with the JMS JNDI context. Consult your provider documentation for how specific tools are configured. (A script for launching the administration tool for IBM MQ JMS for the iPlanet Application Server is described in the next section.)Table A-1 shows the property values used to access the JMS context when creating the InitialContext.
Table A-1    Java Property Names and Values
Java Property Name
Property Value
JNDI Properties for JMS Administration Tools
For the Java classes required to access the JMSContext, include the following three .jar files in the Java runtime classpath:where GX_ROOTDIR is the iPlanet Application Server installation location, for example:
On Solaris, the following directory must be included in the LD_LIBRARY_PATH:
JMS Object Administration for IBM MQ
The mqjmsadm script launches the IBM MQ JMS administration program is included in the iPlanet Application Server. It is located in GX_ROOTDIR/jms/bin. The administration program is a Java class. mqjmsadm is an interactive command line program that accepts administrator input or from an input file.The operation is described in the MQSeries documentation for JMS Administration. mqjmsadm handles the JNDI configuration automatically, so it is not necessary to use the -cfg option. For example, a connection factory and queue could be created with the following mqjmsadm session:
5648-C60 (c) Copyright IBM Corp. 1999. All Rights Reserved.
Starting MQSeries Classes for Java(tm) Message Service Administration
Connected to LDAP server on localhost port 389
InitCtx> define q(theQueue) queue(SYSTEM.DEFAULT.LOCAL.QUEUE)
InitCtx> define qcf(theFactory)
InitCtx> display ctxContents of InitCtx
a aQueue com.ibm.mq.jms.MQQueue
a theProviderFactory com.ibm.mq.jms.MQQueueConnectionFactory
2 Object(s)
0 Context(s)
2 Binding(s), 2 Administered
InitCtx> endThe JMS context does not support subcontexts, so using JMSAdmin commands to manipulate subcontexts generate error messages.
Connection Factory Proxy Administration
Connection factory proxies are created with the jmspadm command (JMS proxy administrator). This command (shell script for Unix or BAT file for NT) launches a Java program that creates connection factory proxies with given parameters and binds them in JNDI. The proxy parameters are set by command line arguments.The command performs three operations on proxies:
Creating a Proxy
To create a proxy enter:jmspadm proxyName factoryName <-p or +p> <-u user password> <-m userMapNam>
The first two arguments are required:
Since JMS objects may only be found in the JMS subcontext, if the supplied names do not begin with jms, string is prepended. For example, the following two commands have the same result:
Using the provider specific tool, create the factory before running jmspadm, to make the factory class available. The remaining arguments are optional. They are used for proxy operation control at runtime. The default settings are:
Connection pooling is on. Disable connection pooling by using -p.
No default userid and password. Set them by using -u.
No identity map. Setting the JNDI name of a user ID map to be used by the proxy is discussed below.
Deleting a Proxy
The syntax to delete a proxy is:
Listing Proxy Parameters
To list all proxies stored in JNDI use the command: jmspadm -l.
User ID Map Administration
To create a user identity map the administrator must prepare an XML file. Once this file is ready, use the jmsuadm command. Again there are three variations to the command:
jmsuadm mapName mapFileName reads the given file and creates a user ID map.
For security purposes, the map contents cannot be listed. Administrators should protect the input files carefully.The input file format is XML. The public name for the DTD is:
-//Sun Microsystems, Inc.//DTD iAS JMS User Identity Map 1.0//EN
The following example input file contains the two JMS users mappings:
<?xml version="1.0" encoding="iso8859-1"?>
<!DOCTYPE jms-user-id-map PUBLIC "-//Sun Microsystems, Inc.//DTD iAS JMS User Identity Map 1.0//EN" "TODO: fill this in" >
<jms-user-id-map>
<user>
<name>bob</name>
<jms-name>jmsuser</jms-name>
<jms-password>secret</jms-password>
</user>
<user>
<name>nancy</name>
<jms-name>jmsuser2</jms-name>
<jms-password>private</jms-password>
</user>
</jms-user-id-map>Each user element must contain all of the following three elements as noted in the above example:
although empty values are allowed:
Connection Pooling Configuration
Certain parameters for the JMS connection pool are stored in the iPlanet Application Server registry. If desired, these may be adjusted using the kregedit program in the iPlanet Application Server bin directory.The parameters are stored for each registered datasource in the registry path:
SOFTWARE\iPlanet\ApplicationServer\6.5\CCS0\Datasource\
For more information on connection pooling parameters, see chapter eight, "Administering Database Connectivity", in iPlanet Application Server Administrator's Guide.
Sample Applications
JMS sample applications can be found in the directory:install_dir/ias/ias-samples/jms
Default JMS Provider
iPlanet Message Queue (iMQ) for Java 2.0 SP1, is the default messaging middleware for iPlanet Application Server. iMQ for Java 2.0 SP1 is available on the iPlanet Application Server product CD.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated March 06, 2002