Guide to J2EE: Enterprise Java || Message-Driven EJBs

Chapter 16

Message-Driven EJBs

16.1 Introduction

A major feature missing from EJB 1.1 was a bean that could receive messages via an intermediate queue; sessions and entity EJBs could only be called synchronously via their business logic and life cycle interfaces. EJB 2.0 introduced the message-driven EJB to rectify this problem, an EJB that is able to communicate with other EJBs and clients in an asynchronous manner.

Message-driven EJBs simply tap into existing J2EE technologies, primarily the Java Messaging Service OMS). We discussed JMS in Chapter 7, which we assume you have read. In this chapter we explore how message-driven EJBs are developed and used, and how they integrate with JMS. From here on we refer to message-driven EJBs as MDBs (messagedriven beans).

Unlike other EJBs, MDBs only have a component class; they do not have business logic or life cycle interfaces. This is because all communication with an MDB is via a JMS queue or topic, no direct synchronous interaction is allowed. In the following sections we examine MDB life cycle states, the MDB component class and MDB deployment descriptors. We extend the bookstore application to illustrate the use of an MDB. A DebugMoni tor MDB is presented that will receive debug messages from clients (other EJBs, web clients and application clients).

16.2 Message-Driven EJB Life Cycle

The life cycle of the MDB is straightforward. Figure 16.1 shows that the MDB can be in two states, does not exist and ready pool. At the point of deployment the deployed MDB will have no instances, corresponding to the does not exist state. The container will at some time after deployment, create one or more instances of the MDB component class, these instances thereby entering the ready pool state. The size of this pool of MDB instances will depend on deployment information provided in vendor-specific deployment fIles. In many applications it makes sense

291

J. Hunt et al., Guide to J2EE: Enterprise Java© Springer-Verlag London 2003

292

ejbRemoveO

\

Guide to J2EE: Ente

Does not exist

Ready pool

\ setMessageDrivenContextO

ejbCreateO

Figure 16.1 The message-driven EJB life cycle.

to have only a single instance of the MDB. This is true of our DebugMon i tor MDB, since it represents a central point of collection for debugging information. 1

During the transition from the does not exist state to the ready pool state the container will call the setMessageDri venContext and ej bCreate methods on the component object. The former provides a reference to a MessageDri venContext object that enables you to obtain information about the state of the MDB. The latter gives you the opportunity to obtain references to other EJBs or external resources. Similarly, during the transition in the opposite direction, the container will call ej bRemove. Here, you can close connections to external resources. This transition is instigated by the container if it "wishes" to reduce the size of the free pool, perhaps to optimize resource utilization within the container. It may also remove MDB instances if the queue or topic that they are attached to is made unavailable.

The onMessage method is called by the container when messages become available on the queue or topic associated with the MDB. Figure 16.2 illustrates an external client sending messages to a JMS Dest i nat i on (this could be a JMS Queue or JMS Topi c). When received, the container, with the aid of the JMS framework, will read the message from the head of the queue or topic and deliver it to one or more MDB instances, via their onMes sage methods. If the Destination is a queue then the message will be sent to an arbitrarily selected MDB instance. If it is a topic, then a duplicate of the message will be sent to all MDBs that subscribe to the topic. Unlike synchronous communication, the client will not have to wait for a method return of control. It simply sends the message to the Des tina t ion

Although you could argue for specialised debugging monitors, where each instance of the MDB listens for a particular kind of debugging information.

81ient Client ~e~d~-----messages to the JM destination

5

DB essage

Oneor more M instance onM methods are c service each message

ailed to

Destination

.' ........

,

Ready pool

"'\

0 , ,

"·0 0/ ..... .....

Container

EJB server

Figure 16.2 Interactions between a client and an MOB via a JMS destination.

293

f\

"'

and continues its execution. The diagram shows a single external client, but equally there could be any number of EJBs or client/web tier applications acting as clients.

16.3 The Component Class

We illustrate the use of MDBs with a DebugMoni tor MDB. We will illustrate this MDB working with both queues and topics. For both, a single instance of the DebugMoni tor listens for debug messages sent to either a JMS queue or a JMS topic OMS destination}. Debug messages are placed on the JMS destination by EJBs in the bookstore application that we wish to debug. In this case, the Cart EJB has been updated to send messages to the JMS destination. The MDB implementation is identical for both versions; only the deployment descriptors and client code need to vary.

Listing 16.1 shows part of the code for the DebugMoni tor MDB. We decided to place the debug-related classes in the ut i 1 package rather than the store package, since these classes are not application-specific. An MDB must implement the j avax. ej b. MessageDri venBean interface. This defines two methods:

publ;c ;nterface MessageDrivenBean extends EnterpriseBean{ publ;c vo;d ejbRemove() throws EJBException; publ;c vo;d setMessageDrivenContext(MessageDrivenContext ctx)

throws EJBException;

The ejbRemove method was described earlier. The setMessageDri venContext method provides your MDB with a reference to the container-managed MessageDri venContext object. In a similar way to other kinds of EJB, you may wish to use this to obtain further information about the MDB. This interface defines no methods of its own, but inherits methods from EJBContext

294

(described in Chapter 13). The only methods that can be called from an MDB are setRo 11 backOn 1 y, getRo 11 backOn 1 y and getUserTransact i on. We have omitted several deprecated methods from this list. If called, the others will throw III ega 1 StateExcept ion. These transaction and security methods will be examined in Chapters 27 and 28, respectively.

The MDB must also provide the ej bCrea te method that takes no parameters. This is rather like the ej bCrea te method defined for a stateless session EJB, it is called by the container immediately after the MDB's creation. Use this method to establish connections to external resources or to obtain references to other EJBs.

Listing 16.1 Part of the DebugMoni torBean.

package uti1;

import javax.ejb.*; import javax.jms.*; import java.io.*;

1* ** This class enables the central monitoring of debugging ** information. It will either write the debug information to ** the standard output or to a specified log file. ** @author Chris Loftus ** @version 2 *1 public class DebugMonitorBean

implements MessageDrivenBean, MessageListener{

private MessageDrivenContext mContext;

private boolean done = false;

private String currentOutputFi1e; private PrintWriter out; II The following two methods are required by the EJB spec but II implementations are not required for this class

public void ejbRemove(){}

public void setMessageDrivenContext(MessageDrivenContext ctx){ mContext = ctx;

public void ejbCreate(){ }

The MDB must also implement the javax. jms. MessageL i stener interface. This defines a single method, namely the onMes sage method. Listing 16.2 shows the implementation of this

16· Message-Driven EJBs 295

method. The comments in the code describe its operation. A utility class called DebugUt i 1 defines several constants used when creating or interrogating debug messages. We will examine this class in Section 16.5. Note that your MDB can reply to a message by using the JMSRep 1 yTo header value. In this case, your MDB needs to identify whether the rep 1 y-to destination is a Queue or Top i c by using Java's ins tanceof operator. Once this has been discovered, your code can obtain and use the appropriate kind of JMS message producer, namely Topi cPubl i sher or QueueSender.

The utility method wri teOutput is called by onMessage after it has extracted the message properties and contents. If a file pathname is provided with the message then a log file is opened (with wri te append). This is only done if the current output filename is null or its pathname differs from the new pathname. The MDB will write to standard output if an empty file pathname is provided. This makes it very easy for the client to direct debug messages to specific debug log files, e.g. one for the Cart EJB, another for the Purchase EJB, or to create client-specific log files.

Listing 16.2 The onMessage method.

1** ** Receives messages sent to an associated JMS queue or topic. ** others will be ignored. The TERMINATE_MONITOR message will ** be ignored, since we rely on the container to decide when to ** terminate this object. Extracts the message properties ** CLIENT_NAME, FILE_PATHNAME, CLASS_NAME and METHOD_NAME. ** If FILE PATHNAME contains a non-empty string, this is used ** to create or append to a log file with that name. ** @param message The JMS message *1

public void onMessage(Message message) { II Check if a TextMessage if (message instanceof TextMessage){

String contents = null; String clientName = null; String filePathname = null; String className = null; String methodName = null;

try{ TextMessage msg = (TextMessage)message;

II Correct JMSType will be checked automatically using II <message-selector> descriptor II Get the message contents contents = msg.getText(); if (contents.equals(DebugUtil.TERMINATE MONITOR)) {

II Ignore this request. It is up to the container to decide II when a message driven bean should be terminated

296

}

} else{

II Get the properties clientName = msg.getStringProperty(DebugUtil .CLIENT NAME); filePathname = msg.getStringProperty(DebugUtil.FILE-PATHNAME); className = msg.getStringProperty(DebugUtil.CLASS NAME); methodName = msg.getStringProperty(DebugUti1 .METHOD_NAME);

writeOutput(clientName, filePathname, className, methodName, contents);

catch (Exception e){ II Will force rollback for container-managed transactions II where transaction attribute is Required throw new EJBException(e);

private void writeOutput(String clientName, String filePathname, String className, String methodName, String contents) throws IOException{

II If a filePathname specified then see if current name II If yes then write to the current stream II Else close old stream

if (filePathname == null I I filePathname.length() == O){ System.out.println("client:\t" + clientName); System.out.println("class:\t" + className); System.out.println("method:\t" + methodName); System.out.print(contents); System.out.println();

} else{

if (currentOutputFile == null I I (lcurrentOutputFile.equals(filePathname))){

II Close the old stream and open a new one. Append data. if (out 1= null) out.close();

}

out = new PrintWriter( new BufferedWriter( new FileWriter(filePathname, true)));

currentOutputFile = filePathname;

II Write the message

out.println("client:\t" + clientName); out.println("class:\t" + className); out.println("method:\t" + methodName); out.print(contents); out.println(); out.flush();

16.4 The Deployment Descriptor Files

297

There are both standard and vendor-specific deployment descriptors used to define MDBs and their properties. For JBoss there are two JBoss-specific files we need to consider, namely j boss. xml which defines non-standard deployment descriptors for the MDB, and j bossdesti nati ons-servi ce. xml where JMS queues and topics can be defined.2

16.4.1 Theejb-jar.xml File

Listing 16.3 shows the standard deployment descriptors for the DebugMon i tor MDB. An MDB is declared using the <message-dri ven> tag. As with other EJB declarations, this may be followed by several optional description and icon tags. These must be followed by an <ej b-name> tag, identifying the EJB. This must be followed by an <ej b-cl ass> tag. A fully qualified package name for the component class must be given. Notice that, unlike other kinds of EJB, there are no business logic or life cycle interface tags; all access being through the JMS destination queue or topic.

The <message-sel ector> tag is optional. It is used to filter messages sent to the JMS destination. In this case we only want to allow messages with the "DEBUG" JMSType property. The selector constraint language was described in Chapter 7. The advantage of using this tag is that we do not need to hard-code message selection checks in our component class. The tag makes it very easy to control the behaviour of the MDB.

The <t ransact i on-type> tag is mandatory. As with other kinds of EJB, this tag either has the value Conta i ner or Bean. The former requests that the container handles transactions (starts, commits or rolls them back). The latter requires you to code the transaction handling explicitly, as we will see in Chapter 27.

The optional <acknowl edge-mode> tag can have the values Auto-acknowl edge (the default if the descriptor is missing) or Dups -0 k - ac knowl edge. The tag only influences the container where bean-managed transactions are being used (so it will be ignored in our example). Where container-managed transactions are used, the container will always autoacknowledge the message receipt during transaction commit (which is managed by the container). For bean-managed transactions, the Auto-acknowl edge value forces the container to acknowledge the message automatically on its arrival. The Dups-okackn 1 owl edge allows for lazy acknowledgment of incoming messages, and can lead to the

2 Note that this was the name of the file used in JBoss 3.0. This could change in later versions.

298

sending of duplicate messages. However, it provides a performance enhancement avoiding the overhead otherwise required to prevent duplicates. Use it only if your application can handle duplicate messages.

The optional <message-dri ven-desti nati on> tag specifies whether the MDB is to be tied to a JMS topic or queue. Future versions of the EJB specification might well allow for other types of messaging system, not just JMS.

Two <resource-ref> tags are included for the Ca rt entity EJB. As we will see later, the CartBean component code has been modified to send debug messages to a debug queue. JMS resources (queues, topics and connection factories) are published via the JNDI directory namespace. The <resource-ref> tags enable us to decouple the actual JNDI pathnames used in an environment from the logical lookup names used in our EJBs. The Ca rt EJB obtains a QueueConnect i onFactory object using the logical name jms/factory. It also obtains the debug queue with the name jms/debugDestination. As we will see, these logical environment naming context (ENC) names are mapped onto actual JNDI names in j boss. xml. This is another use of the ENC (see Chapter 15) that provides decoupling between the actual location of resources and the logical location names used within our code. If we move the Ca rt EJB to another server where the JMS resources have different location names, we need only change the vendor-specific deployment descriptors to map to these new names; no code needs to be modified.

Finally, the <env-entry> tag (see Chapter 15) is included so that we can pass a boolean flag to the Cart EJB. As we will see in Section 16.5, this flag enables the Cart to decide whether to send debug messages to a Queue or to a Topi c.

Listing 16.3 ej b-j ar. xml file highlighting message-driven EJB-related descriptors.

<ejb-jar> <enterprise-beans>

 <entity>

<ejb-name>Cart</ejb-name>  <resource-ref>

<res-ref-name>jms/factory</res-ref-name> <res-type>javax.jms.QueueConnect;onFactory</res-type> <res-auth>Conta;ner</res-auth>

</resource-ref> <resource-ref>

<res-ref-name>jms/debugDest; nat; on</res-ref-name> <res-type>javax.jms.Queue</res-type> <res-auth>Conta;ner</res-auth>

</resource-ref> <env-entry>

<env-entry-name>debugByQueue</env-entry-name> <env-entry-type>java.l ang. Boolean</env-entry-type> <env-entry-value>true</env-entry-value>

</env-entry>

16 . Messa e-Driven EJBs

</entity>  <message-driven>

<ejb-name>DebugMonitor</ejb-name> <ejb-class>util.DebugMonitorBean</ejb-class> <message-selector>JMSType = 'DEBUG'</message-selector> <transaction-type>Container</transaction-type> <acknowl edge-mode>Auto-acknowledge</acknowl edge-mode> <message-driven-destination>

<destination-type>javax.jms.Queue</destination-type> </message-driven-destination>

</message-driven> </enterprise-beans> 

</ejb-jar>

16.4.2 Theejb-jar.xml file (forEJB 2.1)

299

The EJB 2.1 specification has changed the way MDBs are configured. Listing 16.4 provides the EJB 2.1-compliant version of Listing 16.3.

Listing 16.4 ej b-j ar. xml file highlighting tags new to EJB 2.1.


 <entity>

<ejb-name>Cart</ejb-name>  <resource-ref>

<res-ref-name>jms/factory</res-ref-name> <res-type>javax.jms.QueueConnectionFactory</res-type> <res-auth>Container</res-auth>

</resource-ref> <message-destination-ref>

<message-destination-ref-name> jms/debugDestination

</message-destination-ref-name> <message-destination-type>

javax .jms. Queue </message-destination-type> <message-destination-usage>

Produces </message-destination-usage> <message-destination-link>

DebugQueue

300

</message-destination-link> </message-destination-ref> <env-entry>

<env-entry-name>debugByQueue</env-entry-name> <env-entry-type>java.lang.Boolean</env-entry-type> <env-entry-value>true</env-entry-value>

</env-entry> </entity>  <message-driven>

<ejb-name>DebugMonitor</ejb-name> <ejb-class>util.DebugMonitorBean</ejb-class> <activation-config>

<activation-config-property> <activation-config-property-name>

messageSelector </activation-config-property-name> <activation-config-property-value>

JMSType = 'DEBUG' </activation-config-property-value>

</activation-config-property> <activation-config-property>

<activation-config-property-name> acknowledgeMode

</activation-config-property-name> <activation-config-property-value>

Auto-acknowledge </activation-config-property-value>


<activation-config-property-name> destinationType


javax.jms.Queue </activation-config-property-value>

</activation-config-property> </activation-config> <transaction-type>Container</transaction-type> <message-destination-link>

DebugQueue </message-destination-link>

</message-driven> </enterprise-beans> <application-assembly>



<message-destination> <message-destintation-name>

DebugQueue </message-desti nati on-name>

</message-destination> </application-assembly>

<jejb-jar>

301

The types of configuration and their values remain unchanged. However, EJB 2.1 provides a new way of declaring them. The <act i vat i on-confi g> tag packages up all the configuration properties. Each such property is declared using an <act i vat i on-confi gproperty> tag. The <act i vat i on-confi g-property-name> tag declares the kind of property and the <ac t i vat i on -con fi 9 -property-val ue> tag provides an appropriate value.

Another change is the way Queues and Topics are added to the environment-naming context of other EJBs. There is now a <message-desti nati on-ref> tag. Two of the subtags require further explanation.

The <mes sage-des tina t ion -u sage> tag indicates the role the EJB will play with respect to the Queue or Topic. In this case the Ca rt will act as a producer and send messages to the queue. However, it could be declared to be a consumer or both a producer and consumer.

The <message-des t i nat i on-1 ink> tag provides a way of tying the ENe name to the MDB that services the Queue or Topic. Notice that OebugMoni tor also has the same tag, and the <as semb 1 y-des c ri ptor> tag has a sub-tag called <mes sage-des tina t i on>. It is this latter tag that ties together the Cart with OebugMoni tor by referring to the same message link name.

16.4.3 TheJ8ossjboss.xml File

One role of the j bos s . xm 1 file is used to map logical JMS resource location names onto their real location names. In Listing 16.5, the Cart descriptors include <resource-ref> tags that do this mapping. The MDB is represented by the <message-dri yen> tag. This has an <ej b-name> that must correspond to the name used in the ej b-jar. xm1 file. The<confi gurati on-name> tag refers to a set of JMS-specific container configuration descriptors, in this case defined in a standard JBoss configuration file. Optionally, you can override the standard configuration using a <conta i nerconfi gurat ions> tag in the j boss. xm1 file (see the JBoss documentation). Some optional configuration information has been included underthe<message-dri yen> tag. The<contai ner-poo 1-conf> tag can be used to specify the maximum and minimum number ofMDB instances. Here, we want to ensure that one and only one instance of the OebugMoni tor MDB is created.

Listing 16.5 j bos s . xm 1 file highlighting JMS resource mappings and JMS pool configuration.

<?xm1 version=I1.0"?> <jboss>

<enterprise-beans> <entity>

<ejb-name>Cart<jejb-name> <loca1-jndi-name>ejbjcart<j1oca1-jndi-name>

302

<resource-ref> <res-ref-name>jms/factory</res-ref-name> <jndi-name>ConnectionFactory</jndi-name>


<res-ref-name>jms/debugDestination</res-ref-name> <jndi-name>queue/debugger</jndi-name>

</resource-ref> </entity>  <message-driven>

<ejb-name>DebugMonitor</ejb-name> <configuration-name>

Standard Message Driven Bean </configuration-name> <destination-jndi-name>queue/debugMonitor</destination-jndi-name> <container-pool-conf>

<MaximumSize>!</MaximumSize> <MinimumSize>!</MinimumSize>

</container-pool-conf> </message-driven>

</enterprise-beans> </jboss>

16.4.4 TheJBossjboss-destinations-service.xml file

JMS queue and topics can be defined in the standard JBoss configuration file: j bos s -des tinat i ons-servi ce. xml . In JBoss 3, this file is located in the directory j boss-3. O. O/server /defaul t/depl oy. The <mbean> entry we used for the debugger queue is:

<mbean code="org.jboss.mq.server.jmx.Queue" name="jboss.mq.destination:service=Queue,name=debugger">

<depends optional-attribute-name="DestinationManager"> jboss.mq:service=DestinationManager

</depends> </mbean>

16.4.S DebugMoni tor Connected to a JMS Topic

In this section we explore the changes we need to make to the descriptors if we decide to use a Topi c rather than a Queue. We might want to use a Topi c if we have several different MDBs each of which subscribes to and receives messages sent to the Topi c. Listings 16.6 and 16.7 show the changes made to ej b- jar. xm 1, with changes shown in bold. Clearly, we need to specify that we are now using Topi c-related classes. The debugByQueue value is set to fa 1 se, to indicate to the

303

Cart that it should send messages to a Topi c rather than a Queue. We have also specified that the Topi c must be durable, that is, if the server crashes then messages sent to the Topi c will persist. If the <subscri pti on-durabi 1 i ty> tag is omitted, then the Topi c is assumed to be non-durable. The tag can take the values Durab 1 e and NonDurab 1 e.

Listing 16.6 ej b-j ar. xml revised for topics (for EJB 2.0).


<J-- Some descriptors omitted --> <entity>

<ejb-name>Cart</ejb-name> <J-- Some descriptors omitted --> <resource-ref>

<res-ref-name>jms/factory</res-ref-name> <res-type>javax.jms.Top;cConnect;onFactory</res-type> <res-auth>Container</res-auth>


<res-ref-name>jms/debugDestination</res-ref-name> <res-type>javax.jms.Top;c</res-type> <res-auth>Container</res-auth>

</resource-ref> <env-entry>

<env-entry-name>debugByQueue</env-entry-name> <env-entry-type>java.lang.Boolean</env-entry-type> <env-entry-value>false</env-entry-value>

</env-entry> </entity> <J-- Some descriptors omitted --> <message-driven>

<ejb-name>DebugMonitor</ejb-name> <ejb-class>util.DebugMonitorBean</ejb-class> <message-selector>JMSType = 'DEBUG '</message-selector> <transaction-type>Container</transaction-type> <acknowledge-mode>Auto-acknowledge</acknowledge-mode> <message-driven-destination>

<dest;nat;on-type>javax.jms.Top;c</dest;nat;on-type> <subscr;pt;on-durab;l;ty>Durable</subscr;pt;on-durab;l;ty>

</message-driven-destination> </message-driven>

</enterprise-beans> <J-- Some descriptors omitted -->

</ejb-jar>

304 Guide to J2EE: Enterprise Java

Listing 16.7 ejb-jar.xml revised for topics (for EJB 2.1)


 <message-driven>

<ejb-name>DebugMonitor</ejb-name> <ejb-class>util.DebugMonitorBean</ejb-class> <activation-config>

<activation-config-property> <activation-config-property-name>

messageSelector </activation-config-property-name> <activation-config-property-value>

JMSType = 'DEBUG' </activation-config-property-value>


<activation-config-property-name> acknowledgeMode


Auto-acknowledge </activation-config-property-value>


<activation-config-property-name> destinationType


javax.jms. Topic </activation-config-property-value>


<activation-config-property-name> subscriptionDurability


Durable </activation-config-property-value>

</activation-config-property> </activation-config> <transaction-type>Container</transaction-type> <message-destination-link>

DebugQueue </message-destination-link>

16 . Messa e-Driven EJBs 30S

</message-driven> </enterprise-beans> 

</ejb-jar>

The j boss. xml file must also be altered to support topics. In Listing 16.8 we have included three new tags. These tags are mandatory for durable topics, but can be omitted for non-durable topics. The <mdb-user> and <mdb-passwd> tags identify the logical user security credentials to be used by the MDB when it accesses the associated Topic. We discuss J2EE security issues further in Chapter 28. The <mdb -s ubs c ri pt i on- i d> is used to tie this MDB with the durable topic defined in other JBoss configuration files. These files are j bos smq - s ta te. xml (in directory ... / server / defau It/ conf) and j bos smq-des t i -nations-service.xml (in directory ... /server/default/deploy). The former is used to specify logical security credentials and roles that are to be used with JMS resources, such as durable subscriptions to topics. The latter file is used to declare queues and topics, and access permissions granted to logical security roles.

Listing 16.8 Revised j boss. xml file.

<?xml version="l.O"?> <jboss>

<enterprise-beans>

name>

<entity> <ejb-name>Cart</ejb-name> <local-jndi-name>ejb/cart</local-jndi-name> <resource-ref>

<res-ref-name>jms/factory</res-ref-name> <jndi-name>ConnectionFactory</jndi-name>


<res-ref-name>jms/debugDestination</res-ref-name> <jndi-name>queue/debugger</jndi-name>

</resource-ref> </entity>  <message-driven>

<ejb-name>DebugMonitor</ejb-name> <configuration-name>

Standard Message Driven Bean </configuration-name> <destination-jndi-name>queue/debugMonitor</destination-jndi-

<mdb-user>Admin</mdb-user> <mdb-passwd>debug</mdb-passwd> <mdb-subscription-id>DurableDebugger</mdb-subscription-id> <container-pool-conf>

306

<MaximumSize>l</MaximumSize> <MinimumSize>l</MinimumSize>

</container-pool-conf> </message-driven>

</enterprise-beans> </jboss>

Listing 16.9 shows part of the j bossmq-state. xml file. Here we declare logical security credentials for users and roles. One of the <User> tags declares the Admi n user and associates it with the Durabl eDebugger identifier. The <Durabl eSubscri pti on> tag ties this identifier to the specific debugger Topi c. The Admi n user is assigned two roles, namely guest and Adminstrator. These roles are referenced in the jbossmq-destinationsserv ice. xml file. The gues t role is a default role assigned to clients that have not provided credentials. The container inserts further subscription information into the empty <Durab 1 eSubscri pt ions> tag at runtime; you need not provide any values.

Listing 16.9 The jbossmq-state.xml file.

<?xml version="l.O" encoding="UTF-B"?> <StateManager>

<Users> <User>

<Name>Admin</Name> <Password>debug</Password> <Id>DurableDebugger</Id> <DurableSubscription>

<Name>DurableDebugger</Name> <TopicName>debugger</TopicName>

</DurableSubscription> </User> <User>

<Name>guest</Name> <Password>guest</Password>

</User> 

</Users> <Roles>

<Role name="guest"> <UserName>guest</UserName> <UserName>Admin</UserName>

</Role> <Role name="Administrator">

<UserName>Admin</UserName> </Role> 

16· Messa e-Driven EJBs -------------------------------------</Roles> <DurableSubscriptions> </DurableSubscriptions>

</StateManager>

307

Listing 16.10 shows a fragment of the jbossmq-dest i nati ons-servi ce. xml file. We have specified the JNDI nameofthe Topi c as debugger.lnfactJBoss prefixes this with the word topi c giving the full JNDI name topi c/debugger. The Securi tyConf attribute allows us to restrict which security roles may access the topic and the privileges granted to users with those roles. Here, the Admi ni strat~r can create, write and read the topic, whereas guest users may only read and write to the topic. We have allowed guest access since the Cart EJB deployment descriptors do not restrict access to specific security roles, and by default will be granted the gues t role. As we will see in the next section, the Cart acting in this guest role will need to write debug messages to topi c/debugger.

Listing 16.10 The j bossmq-dest i nat i ons-servi ce. xml file.

<mbean code="org.jboss.mq.server.jmx.Topic" name="jboss.mq.destination:service=Topic,name=debugger">

<depends optional-attribute-name="DestinationManager"> jboss.mq:service=DestinationManager

</depends> <attribute name="SecurityConf">

<security> <role name="guest" read="true" write="true"/> <role name="Administrator" read="true" write="true" create="true"/>

</security> </attribute>

</mbean>

16.5 Accessing the EJB From Other EJBs

The MDB is not directly accessed from clients (other EJBs or application or Web clients); rather all communication is through the JMS Desti nati on, be it Topi c or Queue. Also, the MDB clients are identical to any JMS application that needs to send messages via a Des tina t i on, as discussed in Chapter 7. However, to complete the debugger example, Listings 16.11-16.13 present the client perspective.

Listing 16.11 shows parts of the modified CartBean class (modifications in bold; see Chapter 15 for the previous version). The DebugSender class is used to send debugging information via a Top i c or Queue. Three ENC references are used to access JMS-related resources and information. The DEBUG BY QUEUE REF is used by Cart Bean to obtain the byQueue environment entry. This is ~btained in-the setEnt ityContext method. This method also creates a DebugSender object, passing the factory and destination ENC values

308

and the byQueue value to its constructor. The pathname of a log file is also passed, which is ultimately passed on to the DebugMoni tor MDB.

The DebugSender class provides methods for recording the name of the class being debugged, the name of the method sending the debug message and the debug message itself.

Listing 16.11 Modified CartBean implementation class.

package store;

import util.DebugSender; II Other import statements

1** * The cart entity bean is a simplified shopping cart as used by many * online shops. * It is possible to add items to a shopping cart, remove them * determine how they cost, etc. * @author John Hunt & Chris Loftus * @version 3.0 *1

abstract public class CartBean implements EntityBean { II Other instance variables private DebugSender ds; private boolean byQueue = true; II Other ENe references II ENC references to JMS resources private static final String DEBUGGER DESTINATION REF =

"java:comp/env/jms/debugDestinatioii"; -private static final String CONNECTION FACTORY REF =

"java:comp/env/jms/factory"; - -private static final String DEBUG BY QUEUE REF =

"java:comp/env/debugByQueue"; - - -private static final String DEBUG_LOGJILE = "debug. log" ;

II Container managed fields follow (defined in ejb-jar.xml) I I Omitted

public void setEntityContext(EntityContext context){ ctx = context; II Establish the JMS connection to the DebugMontiorBean try{

InitialContext ictx = new InitialContextO ; byQueue = «Boolean)ictx.lookup(DEBUG_BY_QUEUE_REF».booleanValue() ;

} catch(Exception e){}

try{

}

ds = new DebugSender(DEBUGGER_DESTINATION_REF, CONNECTION FACTORY REF, "", DEBUG LOG FILE: byQueue);

ds.setClassName("store.CartBeai") ;ds.setMethodName("setEntityContext") ; ds.sendMessage("Completed successfully") ;

catch(Exception e){ throw new EJBException(e);

}

II Several callback methods omitted

public CartPK ejbCreate(String customerld) throws CreateException{ this.setld(customerld); this.itemHome = this.getltemHome();

ds.setMethodName("ejbCreate") ; try{

}

ds.sendMessage("customerId = " + customerId) ; ds.sendMessage("Completed successfully") ;

catch(Exception e){ throw new EJBException(e) ;

} return null;

II ejbPostCreate omitted

II Business methods

public void add(Book item) throws FinderException{ try{

ds.setMethodName("add") ; ds.sendMessage("Started. Book = " + item) ;

309

BookltemLocal bookltem = itemHome.findByPrimaryKey(item.getIsbn()); Collection items = this.getCartltems(); items.add(bookltem); ds.sendMessage("Completed successfully") ;

} catch(FinderException fell

throw fe;

310

catch(Exception e){ throw new EJBException(e);

} II Other business methods omitted

Let's take a look at the DebugSender class (Listing 16.12). The comments within the code describe its operation. However, it is worth highlighting a few points. The second constructor establishes a connection with the queue or topic using the DebugUt i 1 class. A TextMessage object is created once and then reused by the sendMessage method, rather than being repeatedly recreated. The termi nateMoni tor method sends a special DebugUt i 1 . TERMI NATE_MONITOR message. This gives a debug monitor the opportunity to terminate. In our example, the DebugMoni tor MDB ignores this message.

Listing 16.12 The DebugSender class.

package util;

import javax.jms.*; 1**

** This class provides methods that support construction ** and sending of debug messages via JMS Queues or Topics. ** Each message sent will set the JMSType header to DebugUtil.DEBUG_TYPE ** and the message properties: ** <p> ** <ul> ** <li>DebugUtil.CLIENT_NAME ** <li>DebugUtil.FILE_PATHNAME ** ** ** ** **

<li>DebugUtil.CLASS_NAME

<li>DebugUtil.METHOD_NAME

** </ul> ** @author Chris Loftus ** @versi on 1. 0 *1

public class DebugSender{

private String destinationName; private String factoryName; private String clientName; private String filePathname; private String className; private String methodName;

<t> A name to help distinguish messages <t> The name that can be used for a log

file <t> The name of the class sending the

message <t> The name of the method sending the

message

16· Message-Drive~n~EJ==Bs:....-________ ~ ____ =3-=-11~

private boolean byQueue;

private QueueConnection queueConnection; private QueueSender queueSender; private QueueSession queueSession; private TopicConnection topicConnection; private TopicPublisher topicPublisher; private TopicSession topicSession;

private TextMessage debugMessage;

/** ** Establishes a JMS Queue or Topic connection, session ** and sender or publisher. As part of this it obtains the ** JMS Queue or Topic via JNDI. ** @param destinationName Contains the JNDI name for the JMS Destination ** @param factoryName Contains the JNDI name for the JMS connection factory ** @param byQueue If true, DebugSender will establish a Queue connection ** else if false a Topic connection ** @exception Exception Is thrown if there's a problem interacting with ** JMS */

public DebugSender(String destinationName, String factoryName, boolean byQueue) throws Exception{

this(destinationName, factoryName, "", "", byQueue);

/** ** Establishes a JMS Queue or Topic connection, session ** and sender or publisher. As part of this it obtains the ** JMS Queue or Topic via JNDI. ** @param destinationName Contains the JNDI name for the JMS Destination ** @param factoryName Contains the JNDI name for the JMS connection factory ** @param clientName Used to record a client name for each message sent ** @param filePathname Used to record a debug log pathname for each ** message sent ** @param byQueue If true, DebugSender will establish a Queue connection ** else if false a Topic connection ** @exception Exception Is thrown if there's a problem interacting with ** JMS */

public DebugSender(String destinationName, String factoryName, String clientName, String filePathname,

312 Guide to J2EE: Ente

boolean byQueue) throws Exception{ DebugUtil dUtil = new DebugUtil(); try{

}

if (byQueue){ QueueConnectionFactory queueConnectionFactory =

(QueueConnectionFactory)dUtil.getJNDIObject(factoryName); queueConnection =

queueConnectionFactory.createQueueConnection(); queueSession =

queueConnection.createQueueSession(false, Session.AUTO ACKNOWLEDGE);

Queue queue = (Queue)dUtil.getJNDIObject(destinationName); queueSender = queueSession.createSender(queue);

II Might as well create this once and then reuse each time II we send a message debugMessage = queueSession.createTextMessage();

} else{

}

II Assume it's a topic TopicConnectionFactory topicConnectionFactory =

(TopicConnectionFactory)dUtil.getJNDIObject(factoryName); topicConnection =

topicConnectionFactory.createTopicConnection(); topicSession =

topicConnection .createTopicSession(false, Session.AUTO ACKNOWLEDGE);

Topic topic = (Topic)dUtil.getJNDIObject(destinationName); topicPublisher = topicSession.createPublisher(topic);

II Might as well create this once and then reuse each time II we send a message debugMessage = topicSession.createTextMessage();

II Set its JMSType to "DEBUG" debugMessage.setJMSType(DebugUtil.DEBUG_TYPE);

catch(Exception e){ System.err.println("Connection problem: " + e.toString()); if (byQueue) {

if (queueConnection != null){ try{

queueConnection.close(); } catch (JMSException eel {}

16· Messa e-Driven EJBs

}

} else{

if (topicConnection != null){ try{

topicConnection.close();

}

catch (JMSException eel {} }

II Really ought to throw application-specific exception II that is more user-friendly throw e;

II Set the instance variables this.destinationName = destinationName; this.factoryName = factoryName; this.byQueue = byQueue; this.clientName = clientName; this.filePathname = filePathname;

1** ** Obtains the Destination JNDI name ** @return The Destination JNDI name *1

public String getDestinationName(){ return destinationName;

} 1**

** Obtains the Factory JNDI name ** @return The Factory JNDI name *1

public String getFactoryName(){ return factoryName;

} 1**

** Are we supporting queues or topics? ** @return true if queues, else false *1

public boolean isByQueue(){ return byQueue;

}

/** ** Resets the client name ** @param clientName The new client name *1

313

314 Guide to J2EE: Ente

public void setClientName(String clientName){ this.clientName = clientName;

} /**

** Obtains the client name ** @return The client name */

public String getClientName(){ return clientName;

/** ** Resets the log file pathname ** @param filePathname The new pathname */

public void setFilePathname(String filePathname){ this.filePathname = filePathname;

/** ** Obtains the log file pathname ** @return The debug log file pathname */

public String getFilePathname(){ return filePathname;

} /**

** Resets the class name ** @param className The new class name */

public void setClassName(String className){ this.className = className;

} /** ** Obtains the class name ** @return The class name */

public String getClassName(){ return className;

} /** ** Resets the method name ** @param methodName The new method name */

public void setMethodName(String methodName){ this.methodName = methodName;

}

/**

** Obtains the method name ** @return The method name */

public String getMethodName(){ return methodName;

/** ** Populates the message with data and sends/publishes it ** @param message The debug message ** @exception Thrown if the message cannot be sent/published */

public void sendMessage(String message) throws Exception{

315

debugMessage.setStringProperty(DebugUtil.CLIENT NAME, this.clientName);

debugMessage.setStringProperty(DebugUtil .FILE PATHNAME, this.filePathname);

debugMessage.setStringProperty(DebugUtil.CLASS NAME, this.className); debugMessage.setStringProperty(DebugUtil .METHOD NAME,

this.methodName); debugMessage.setText(message); if (byQueue){

queueSender.send(debugMessage); } else{

topicPublisher.publish(debugMessage);

/** ** Closes the JMS connection */

public void close(){ try{

}

if (byQueue){ queueConnection.close();

} else{

topicConnection.close();

catch(Exception e){}

protected void finalize() throws Throwable{ super.finalize(); this.close();

316

private void terminateMonitor() throws Exception{ debugMessage . setText(DebugUtil.TERMINATE MONITOR); if (byQueue){ -

queueSender.send(debugMessage); } else{

topicPublisher.publish(debugMessage);

The final piece of the puzzle is shown in Listing 16.13. This provides some useful constants and the getJNDIObject method used by DebugSender. Again you are encouraged to scan the comments for an explanation of its purpose.

Listing 16.13 The DebugUt i 1 class.

package util;

import java.util .Properties; import javax.naming.*; /**

** A set of constants and a method to assist with the use of ** JMS as a means of sending debug messages */

public class DebugUtil{ /** Intended to be used as a JMSType value */ public static final String DEBUG TYPE = "DEBUG"; j** Intended to be used as part of a special terminate message *j public static final String TERMINATE MONITOR = "TERMINATE"; /** Property names */ -/** Used if you need to distinguish between messages sent by

** different clients */

public static final String CLIENT NAME = "clientName"; /** The property that will hold the optional log file pathname */ public static final String FILE PATHNAME = "filePathname"; /** The property that will hold-the class name */ public static final String CLASS NAME = "className"; /** The property that will hold the method name */ public static final String METHOD_NAME = "methodName";

private InitialContext jndiContext;

/** ** Uses InitialContext and lookup to obtain a JNDI object ** @param jndiName The JNDI lookup name ** @return The object retrieved from the JNDI directory space

317 I

** @exception Exception Thrown if a problem is encountered using JNDI */

public Object getJNDIObject(String jndiName) throws Exception{ if (jndiContext == null){

jndiContext = new InitialContext(); } return jndiContext.lookup(jndiName);

Documents

Guide to J2EE: Enterprise Java || Message-Driven EJBs