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
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 JMS provider for IBM MQ Series.
The JMS web page at http://java.sun.com describes JMS' purpose as follows:
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.
The iPlanet Application Server also includes JMS Connection Pooling and User Identity Mapping. These are provided through an adminstrative framework and the iPlanet Application Server specific code is not required. Applications can use these features transparently, maintaining component portability.
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.
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.
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.
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:
Destination
ConnectionFactory
QueueConnectionFactory
TopicConnectionFactory
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. This section describes how to integrate a JMS provider with the iPlanet Application Server, and to enable the JMS connection pooling and user identity mapping features.
Running jms/bin/jms_setup during the iPlanet Application Server installation enables JMS. This program prompts the user for JMS provider information and performs the appropriate setup, including:
Sets up the system Java class path and dynamic library paths
Enables the object pooling infrastructure in the iPlanet Application Server runtime
Adapts the JMS administration programs to the iPlanet Application Server installation location
The JMS provider software must be previously installed. See the vendor's installation instructions.
Enabling JMS Connection Pooling
To enable the JMS Connection Pooling, simply run the program jms_reg.
Enabling the IBM MQ Provider
The jms_setup is preconfigured to use the MQ Series JMS provider. For example when entering:
#./jms_setup
The response is:
Are you using the IBM MQ v5.1 as message provider [Y] : Y
Enabling the Sun JMQ Provider
To set up using Sun JMQ:
#./jms_setup
The response is:
Are you using the IBM MQ v5.1 as message provider [Y] : n
Enter message provider C library absolute path (one each time, if done, hit return only) .
Enter message provider Java .jar file absolute path (one each time, if done, hit return only):
/opt/SUNWjmq/lib/jmq.jar
/opt/SUNWjmq/lib/jmqadmin.jar
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 265, 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:
Default username
Explicit user ID map
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 of 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 depend 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 user ID maps
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
|
|
Java.naming.factory.initial
|
com.netscape.server.jndi.ExternalContextFactory
|
|
Java.naming.provider.url
|
/jms
|
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:
GX_ROOTDIR/classes/java/jms.jar
GX_ROOTDIR/classes/java/javax.jar
GX_ROOTDIR/classes/java/kfcjdk11.jar
where GX_ROOTDIR is the iPlanet Application Server installation location, for example:
/usr/iPlanet/iAS6/ias
On Solaris, the following directory must be included in the LD_LIBRARY_PATH:
$GX_ROOTDIR/gxlib
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:
# mqjmsadm
The response is:
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 ctx
Contents 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> end
The 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
Deleting a proxy
Listing proxy parameters
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:
jmspadm -d proxyName
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.
jmsuadm -d mapName deletes the map.
jmsuadm -l lists the map names.
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:
name
jms-name
jms-password
although empty values are allowed:
<jms-name></jms-name>
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 in the key:
SOFTWARE\iPlanet\ApplicationServer\6.0\CCS0\POOLS\JMSConnectionPool
Table A-2 shows the parameter names and default values:
Table A-2 Parameter Names and Default Values for Connection Pooling
|
Parameter
|
Default Value
|
Description
|
|
MaxPoolSize
|
20
|
Maximum number of pooled JMS connections
|
|
SteadyPoolSize
|
10
|
Number of steady state connections
|
|
MaxWait
|
32 seconds
|
Time client waits for a connection
|
|
UnusedMaxLife
|
300 seconds
|
Time unused connections are deleted
|
|
DebugLevel
|
1
|
0-turns off logging
1-logs callback messages
2-logs all messages
(see kjs log file)
|
|
MonitorInterval
|
60
|
Time between messages
|
Connections are deleted when closed if the number of connections in the pool is between SteadyPoolSize and MaxPoolSize. Connections are kept in the pool up to UnusedMaxLife, when the number of open connections is less than SteadyPoolSize.
Sample Applications
JMS sample applications can be found in the directory:
GX_ROOTDIR/jms/samples
JMS Future in the iPlanet Application Server
The following topics cover future JMS releases and how they apply to the iPlanet Application Server.
Default JMS Provider
A future J2EE standard will require that the environment include a JMS provider.
Message Driven Enterprise Java Beans
J2EE and the iPlanet Application Server do not currently support application components that receive scalable messages. A future release of J2EE will include support for "Message Driven Enterprise JavaBeans," which are activated in response to the receipt of JMS messages. The application framework allows for scalable message receipt.
Using JMS in distributed transactions
The iPlanet Application Server does not currently support JMS resources in global transactions.