| |
Integrating JMQ with iPlanet Application Server
By Kevin Boone
Last updated September 2001.
Disclaimer
The author is a certified iPlanet instructor, but not a member
of the iPlanet organization. I am no more privy to internal
information about the iAS product than anyone else.
Nothing in this document should be taken to
constitute official policy of Sun Microsystems.
Scope
This document describes how to use the Sun/iPlanet messaging product
JMQ with the iPlanet Application Server. It assumes that JMQ is already
installed. For illustration we will use the JMS servlet example
simplequeue, which is provided in the iAS code samples package.
This example consists of a single servlet which puts a message in a queue and
retrieves it itself.
This article assumes that the reader is already basically familiar with JMS, messaging
and the iPlanet Application Server.
Background
At present, a J2EE-compliant application server is required to
provide an interface to a messaging service provider that can be
used by applications. It is not required to provide the messaging
infrastructure itself. Most products have procedures by which a commercial
messaging product -- e.g., IBM MQ Series -- can be integrated
into the application server.
What form does this `integration' take? Well, the developer expects
to be able to enter lines of code like this
(from the simplequeue example):
QueueConnectionFactory qcf =
(QueueConnectionFactory) initialContext.lookup
("java:comp/env/jms/SampleFactory");
Queue queue =
(Queue) initialContext.lookup
("java:comp/env/jms/SampleQueue");
This leaves the application server with three problems:
- 1. Translation of the `local' names
java:comp/env/...
into the `real' JNDI names of the queue and connection factory
- 2. Supporting JNDI name lookups for JMS objects; that is,
the
lookup method should return an object that implements the
appropriate part of the JMS API, and against which the developer can
write code exactly the same as outside the application server
environment
- 3. Ideally the application server should be able to pool connections
to the messaging provider; clients connecting with the same
security credentials should be able to share physical connections.
Problem (1) is straightforward for an application server, as it will
already have techniques for doing this for JDBC database connections,
for example. Problem (2) is solved by storing references to the service provider's
objects in the application server's directory, and making it available by JNDI. Problem (3)
requires the use of proxies; that
is, the object retrieved by the JNDI lookup is not simply a reference
to something provided by the messaging service, but a proxy provided
by the application server.
In what follows we will look at the specific techniques used by
the iPlanet Application Server, version 6.0SP2. We will use the
Sun/iPlanet JMQ messaging product as the service provider.
Initial setup
iAS is not supplied with a messaging provider. In what follows we will describe
how to define JMQ queues and connection factories and register them with iAS,
but first the application server must be provided with some basic information
about the messaging provider. Specifically the kjs CLASSPATH must be
extended so that it can find the classes that will be returned as a result
of JNDI lookup operations. For JMQ, the required classes are in the two
JAR files jmq.jar and jmqadmin.jar. If you did a
default installation of JMQ, these classes will be in /opt/SUNWjmq/lib.
You could make the CLASSPATH changes manually, but iAS is provided
with a script that does it:
[iasroot]/ias/jms/bin/jmssetup
This script prompts the operator for additions to the CLASSPATH. It also
asks for additions to the LD_LIBRARY_PATH environment variable, so
that it can find native-code libraries; JMQ does not require any, so this section
can be ignored.
You will need to restart iAS after making these changes.
JMQ uses Java security policies files to dictate who can do what on the messaging
system; for ordinary operations (posting and retrieving messages) these policies
should not need to be changed. However, to add queues and topics
using command-line tools, you may need to modify /opt/SUNWjmq/security/jmqadmin.policy.
Adding this line will work:
grant { permission java.security.AllPermission; };
Name mapping
This section describes how iAS maps the `java:comp/env' name onto
a real JNDI name. This should be familiar to developers who have
used similar techniques for JDBC.
As we have seen, the Java code in the servlet contains these instructions:
QueueConnectionFactory qcf =
(QueueConnectionFactory) initialContext.lookup
("java:comp/env/jms/SampleFactory");
Queue queue =
(Queue) initialContext.lookup
("java:comp/env/jms/SampleQueue");
These lookups do not correspond to real JNDI names, but to names local to the
servlet (strictly, to the WAR module). `java:comp/env' is not part of the name,
but an indication to the JNDI subsystem to make a local name lookup. The part
of the string after `java:comp/env' is referred to as the coded name. When
we create the deployment descriptor web.xml for the servlet we
indicate the coded name and the type of resource to which it provides access.
So we have:
<resource-ref>
<res-ref-name>jms/SampleQueue</res-ref-name>
<res-type>javax.jms.Queue</res-type>
<res-auth>Container</res-auth>
</resource-ref>
<resource-ref>
<res-ref-name>jms/SampleFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
<res-auth>Container</res-auth>
</resource-ref>
This XML indicates the coded name of the resource, the type of the resource, and
who is to provide authentication information (container). It does not indicate
the real name of the resource, nor the security credentials themselves. So,
where does this information go? This is vendor-specific. With iAS, it goes into the
iAS-specific deployment descriptor which, for a WAR file, is ias-web.xml.
In that file we see the rest of the information:
<resource-ref>
<res-ref-name>jms/SampleFactory</res-ref-name>
<jndi-name>jms/theFactory</jndi-name>
</resource-ref>
<resource-ref>
<res-ref-name>jms/SampleQueue</res-ref-name>
<jndi-name>jms/theQueue</jndi-name>
</resource-ref>
That is, the local name java:comp/env/jms/SampleFactory maps onto the JNDI
name jms/theFactory, while java:comp/env/jms/SampleQueue maps
onto the JNDI name jms/theQueue.
Although it isn't strictly necessary to know this, it can be helpful for debugging to
understand that the JMS information from both web.xml and ias-web.xml
end up in the same place in the iAS registry, under the J2EE-Module branch:
J2EE-Module
jms-simplequeue
resource-ref
jms/SampleFactory
jndi-name=jms/theFactory
res-auth=container
res-type=javax.jms.QueueConnectionFactory
jms/SampleQueue
jndi-name=jms/theQueue
res-auth=container
res-type=javax.jms.Queue
This is all very well, but all we have done is translate one unknown name into another
unknown name. What exactly are jms/theFactory and jms/theQueue?
The answer is that theQueue is the JNDI name of a queue that will be registered with iAS,
while theFactory is the JNDI name for a proxy that will stand for the real
queue connection
factory. This proxy will be created using an iAS utility called jmspadm, as
described later; first we must create and register the queue and connection factory.
Creating the queue
In JMS a Queue object is really something that describes the logical
properties of a message queue; it does not represent a connection to anything.
Therefore there is no need to pool Queue objects or to provide
proxies for them. What we must do, however, is create the queue definition within
the messaging service itself, and assign it a JNDI name with iAS. We must do the
same with the connection factory, although its JNDI name won't be used by
applications (they will use its proxy).
Creating the Queue is an operation on the messaging service provider; however,
it is the application server that will need access to the created object. With
Sun JMQ the approach taken is to ask the service provider to create the queue,
and provide a JNDI context to which the service provider can add its
own reference. JMQ provides a utility called jmqconfig for this;
if you wanted to run this command at the prompt to create the queue for the
SimpleQueue servlet, you would need to do something like this
(but don't; there is a better way: see below):
/opt/SUNWjmq/bin/jmqconfig \
-a \
-t q \
-n theQueue \
-o name=SampleQueue \
-i com.netscape.server.jms.RefFSContextFactory \
-u /jms
In this example, `-a' means `add the object'. `-t q' indicates that the object
required is a Queue. `-n theQueue' indicates the JNDI name by which the
queue will be referenced. `-o name=SampleQueue' sets the internal name of the queue
(this is not a JNDI name, and won't be used by applications). `-i'
indicates a JNDI naming context class. This is not provided by JMQ, but by iAS. JMQ
will use this class to do a JNDI bind() operation to map the JNDI name
onto the queue reference. This is how JMQ can add queues and other objects to the
namespace of any application server, even one that it knows nothing about; the real
work in this case is done by the RefFSContextFactory class, which
is part of iAS. Finally, `-u /jms' sets the system property
java.naming.provider.url before carrying out the JNDI bind().
This is so that the RefFSContextFactory class, which may not be specific
to JMS lookups, knows where in the directory to insert the new name.
The problem with running the jmqconfig command manually is that it
requires an immense CLASSPATH, which would have to be set beforehand. Happily,
iAS provides a script to run it with the correct classpath. This script is
[iasroot]/ias/ias-samples/jms/docs/jmsjmqadm.sh. You may need to
tweak this script before running it, as its references to the iAS installation
directory won't be correct unless you installed the product with defaults.
If you do this, then the same effect as the jmqconfig command
above can be gained by doing:
jmsjmqadm.sh q theQueue SampleQueue
Please note that SampleQueue is the internal name of the queue, and
need not be the same as the name used in the Java code, or as the JNDI name.
However, theQueue is a name that will be used by the application;
it corresponds to the resource reference that we put in ias-web.xml.
Although not strictly necessary, it may be helpful to see how the queue creation
operation is reflected in the iAS registry:
Application Server
6.0
JMSObjects
theQueue
ClassName=com.sun.messaging.Queue
...
RA1=S#destName#SampleQueue
Note the `RA1' entry that provides the link to the internal (JMQ) name of the queue.
Creating the factory
The application will not use the connection factory directly, but it still has
to exist. If you followed the discussion of creating a queue above, then creating
the connection factory should present no additional problems:
jmsjmqadm.sh qf providerFactory SampleFactory
SampleFactory is the internal name of the object, and doesn't have
to correspond to any name used in the application. providerFactory
is a JNDI name, but this won't be used by applications either: they will use
the proxy. After running this command, you will be able to see a new branch
in the iAS registry in the same branch as the queue object created earlier. This
new branch will be called providerFactory.
Proxy generation
iAS uses proxies for database connections as well as for messaging services, but
the difference for the developer and administrator is that, for JMS, the proxy
generation process is exposed. For JDBC, it is handled internally. In the
previous step we created the connection factory, with JNDI name jms/providerFactory
and JMQ interal name SampleFactory. Now we must create the iAS proxy for
this object.
To do this, we use the script jmspadm, which is provided in the
directory [iasroot]/ias/jms/bin. The script requires the JNDI name of the
factory, and the (new) JNDI name of the proxy. The name of the proxy must match
the name of the reference in ias-web.xml, as this is what will get
looked up when the servlet runs. So we need:
jmspadm theFactory providerFactory
This creates the following entries in the registry:
Application Server
6.0
JMSObjects
theFactory
ClassName=com.netscape.server.jms.QueueConnectionFactoryProxy
...
RA0=S#connFactoryName#jms/providerFactory
...
Note that the class name is com.netscape..., not com.sun.messaging...;
that is, the servlet will get a reference to a proxy provided by the application
server, not a class that is part of Sun JMQ. Note also the reference to the
real JNDI name of the JMQ object jms/providerFactory.
Summary
A large number of name mapping steps are involved between the servlet's
JNDI lookup and the JMQ object itself. The diagram below summarizes these
steps for the connection factory.
Servlet java:comp/env/jms/SampleFactory (servlet's name for factory)
iAS jms/theFactory (JNDI name of proxy for factory)
iAS jms/providerFactory (JNDI name of factory)
JMQ SampleFactory (internal name of factory in JMQ)
The steps to instantiating, registering and creating proxies for a publish-subscribe
messaging system (Topic and TopicConnectionFactory) are
almost exactly the same as for queues.
|
