Appendix A
Using the Java Message Service
This appendix describes how to use the Java Message Service (JMS) API. iAS 6.0 allows the integration of third party JMS providers into its Java environment, and provides two added value features: Connection Pooling and User identity mapping.The following topics are included in this chapter:
About the JMS API
The Java Message Service is a Java2 Enterprise Edition API. JMS provides a set of standard Java language interfaces to Enterprise Messaging Systems, often referred to as "message oriented middleware." These interfaces are implemented by JMS providers. iAS supports the JMS provider for IBM MQ Series.
The JMS web page at java.sun.com describes the purpose of JMS 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.
iAS 6.0 also includes JMS Connection Pooling and User Identity Mapping. These are provided through an adminstrative framework and iAS 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 Connection Factories.
In order maximize portability of applications between JMS providers, provider specific aspects of messaging 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 instances of the administered object classes, and to configure them to the requirements of the deployment. Administrators use the tools to set provider specific parameters.
This programming model allows JMS programs to be written that are completely independent of the provider. Applications look up the administered objects by name using the Java Naming and Directory Interface (JNDI).
The following sample program 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 this application did not hard code the names of the resources, 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 iAS deployment manager does not support iAS JMS beta JMS resource references.
Enabling JMS and Integrating Providers
IAS6.0 includes the software required to integrate JMS providers, but it must be enabled. This section describes how to integrate a JMS provider with iAS, and to enable the JMS connection pooling and user identity mapping features.
Running the program jms/bin/jms_setup during iAS installation enables JMS. This program prompts the user for information about the JMS provider, and performs the appropriate setup including:
Set up the system Java class path and dynamic library paths
Enable the object pooling infrastructure in the iAS runtime
Adapt the JMS administration programs to the iAS installation location
The JMS provider software should have been installed previously. 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 the Sun JMQ:
#./jms_setup
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
The support for JMS included with iAS 6.0 is based entirely on the standard J2EE APIs. Application components using the added value features will be portable with other J2EE environments. This section discusses some issues that programmers should consider when using JMS in applications deployed on iAS 6.0.
JNDI and Application Component Deployment
JMS objects are stored by administration tools in the jms subcontext of the iAS root JNDI namespace. 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 names beginning with jms/. Greater flexibility can be achieved by using J2EE resource references. This was demonstrated in the sample code shown on page 2, where the name looked up for the factory was java:comp/env/jms/theFactory. In the iAS JMS beta, JMS resource references are not supported. JMS objects should be referenced directly.
Connection Factory Proxy
iAS 6.0 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 the proxies, which may be used transparently to application code.
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 can be 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 will re-use the connection.
User Identity Mapping
The Connection Factory Proxy also provides user identity mapping. JMS providers do not use the same security infrastructure as the application server and thus have different user namespaces. User identity mapping provides administrators flexibility in designing their security infrastructure.
Two forms of mapping 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 iAS 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 user name and password for the proxy. 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 iAS implementation of the proxy 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 a list of entries, each referenced by a unique user id key and containing two values:
The administrator creates the map using a provided tool called jmsuadm. The values in the entry are used when creating connections.
For example, when an application creates a connection using the proxy with:
connection = proxy.createQueueConnection(userString,
passWordString);
the iAS proxy implementation looks up an entry for the given userString in the map. If it finds an entry, the proxy passes jmsUserName and jmsPassWord values from that 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 providerFactory.
ConnectionFactoryProxies and Application Created Threads
A servlet can create Java threads, but it is not recommended. User created threads will not be 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 will result 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 will crash KJS.
JMS Features Not Supported
iAS 6.0 does not support the JMS XAConnection and server session pools features described in Chapter 8 of the JMS specification. These features will be supported in a subsequent iAS release.
JMS Administration
The JMS API depends on administered objects for portability. Provider specific aspects of a deployment are encapsulated in Administered objects allowing application code to be portable.
In the iAS environment JMS administration consists of four tasks
Creating JMS provider factories and destinations
Creating user id maps
Creating ConnectionFactoryProxies
Modifying the connection pooling parameters in the iAS registry.
JMS Object Administration Tools
Each JMS product should include an administration program. This tool creates objects and binds them to names in the iAS JNDI. This section describes the Java properties and system paths required to configure a tool for working with the JMS JNDI Context. Consult your provider's documentation for descriptions of how specific tools are configured. (A script for launching the administration tool for IBM MQ JMS for iAS is described in the next section. )
To access the JMS context, create the InitialContext using the following property values:
|
Java Property Name
|
Property value
|
|
Java.naming.factory.initial
|
com.netscape.server.jndi.ExternalContextFactory
|
|
Java.naming.provider.url
|
/jms
|
Java Property Names and Values">
Table A-1
|
Java Property Name
|
Property value
|
|
Java.naming.factory.initial
|
com.netscape.server.jndi.ExternalContextFactory
|
|
Java.naming.provider.url
|
/jms
|
Java Property Names and Values
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 location of the iAS installation. 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 that launches the IBM MQ JMS administration program is included in iAS. It is located in GX_ROOTDIR/jms/bin. The administration program is a Java class. mqjmsadm is an interactive command line program that accepts input from the administrator, or from an input file.
Operation is described in the MQSeries documentation for JMSAdmin. 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
Response:
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 sub-contexts will generate error messages.
Connection Factory Proxy Administration
Connection Factory Proxies are created with the command jmspadm (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 , that 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 control the operation of the proxy 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 command jmsuadm. 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 names of maps.
For security purposes, the contents of the map cannot be listed. Administrators should protect the input files carefully.
The input file format is XML. The public name for the data type description (DTD) is:
-//Sun Microsystems, Inc.//DTD iAS JMS User Identity Map 1.0//EN
The following example input file contains the mappings for two JMS users:
<?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 each of the three elements noted above:
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 iAS registry. If desired, these may be adjusted using the kregedit program in the iAS bin directory.
The parameters are stored in the key:
SOFTWARE\iPlanet\ApplicationServer\6.0\CCS0\POOLS\JMSConnectionPool
Following are the parameter names and default values:
|
Parameter
|
Default Value
|
Description
|
|
MaxPoolSize
|
20
|
maximum # of pooled JMS connections
|
|
SteadyPoolSize
|
10
|
# of steady state connections
|
|
MaxWait
|
32 seconds
|
time client will wait for 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
|
Parameter Names and Default Values for Connection Pooling">
Table A-2
|
Parameter
|
Default Value
|
Description
|
|
MaxPoolSize
|
20
|
maximum # of pooled JMS connections
|
|
SteadyPoolSize
|
10
|
# of steady state connections
|
|
MaxWait
|
32 seconds
|
time client will wait for 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
|
Parameter Names and Default Values for Connection Pooling
Connections are deleted when they are 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
See the README files in for more information
Future of JMS in iAS
Default JMS Provider
A future release of the J2EE standard will require that the environment include a JMS provider.
Message Driven Enterprise Java Beans
J2EE and iAS 6.0 do not currently support application components that receive scalable messages. A future release of J2EE will include support for "Message Driven Enterprise Java Beans," which are activated in response to the receipt of JMS messages. The application framework allows for scalable message receipt.
Using JMS in distributed transactions
A future release of iAS will support JMS resources in global transactions.
(javax.jms.XAConnection)