The most common way to set up a JMS topic is to use an XML configuration file. As you learned in the installation chapter, every component in JBoss is a JMX MBean that can be hot-deployed. This part of the exercise shows you how to write a JMX MBean definition for a new JMS topic.

You can find the JMX configuration file in the ex12_1/src/resources/services directory.

<server>
  <mbean code="org.jboss.mq.server.jmx.Topic"
         name="jboss.mq.destination:service=Topic,
               name=titan-TicketTopic">
    <depends optional-attribute-name="DestinationManager"
     >jboss.mq:service=DestinationManager</depends>
  </mbean>
</server>

Each set of MBeans in a JMX configuration file must be defined within a <server> tag. An MBean itself is declared in an <mbean> tag. The only MBean declaration in this file defines the actual JMS topic you’ll use for the example code in this chapter. Each MBean is uniquely identified by its name, called an ObjectName. JMX ObjectNames can include any number of key-value parameters to describe the MBean further. In our case, the MBean class representing the JMS topic is declared first (org.jboss.mq.server.jmx.Topic), along with its JMX ObjectName (jboss.mq.destination:service=Topic, name=titan-TicketTopic). For JMS topic MBeans, a single parameter is useful: name. This is where the name of the JMS topic is defined (titan-TicketTopic).

One thing to note is that the application server must deploy the DestinationManager MBean before any queue or topic is deployed. This dependency is declared in jbossmq-titantopic-service.xml’s depends tag. JBoss will take care of satisfying this dependency and make sure the titan-TicketTopic isn’t started until the DestinationManager MBean has finished initializing and is ready to provide services to new queues and topics. Copying this file into the JBoss deploy directory will hot-deploy the JMS topic and make it ready for use.

We’ve defined a make-topic Ant target for deploying the topic bean. Run this target to copy jbossmq-titantopic-service.xml into JBoss’s deploy directory:

C:workbookex12_1>ant make-topic
Buildfile: build.xml

make-topic:
     [copy] Copying 1 file to C:jboss-4.0serverdefaultdeploy

On the server side, the following line is displayed:

[titan-TicketTopic] Bound to JNDI name: topic/titan-TicketTopic

An XML configuration file is the preferred means to deploy a JMS topic permanently, but for quick tests and such an alternative approach that uses JBoss’s JMX HTTP connector and the DestinationManager is sometimes better, because the topic lives in JBoss only until the application server is shut down. First open your browser and go to http://localhost:8080/jmx-console/, where you can browse through all deployed JBoss JMX MBeans. Scroll down to the jboss.mq section and find in it the MBean service DestinationManager (Figure 29-1).

Figure 29-1. Finding the DestinationManager

Click on the service=DestinationManager link and you get a list of the MBean’s attributes and operations. One of the operations, createTopic( ), allows you to create a new JMS topic (Figure 29-2).

Figure 29-2. Naming a new JMS topic

Type the name of the new JMS topic in the text area, and click on the Invoke button associated with the createTopic( ) operation. The Destination Manager will create the JMS topic and display a status message (Figure 29-3).

Figure 29-3. Confirming topic creation

To see your new JMS topic MBean, go back to the home page of the JMX HTTP connector and search for the jboss.mq.destination domain. You should be able to see your new topic MBean (Figure 29-4).

Figure 29-4. Finding the new topic

Note that you can use the JMX HTTP connector to see the status of your topics and queues even if you create then in an XML configuration file.

<session>
  <ejb-name>TravelAgentEJB</ejb-name>
  <home>com.titan.travelagent.TravelAgentHomeRemote</home>
  <remote>com.titan.travelagent.TravelAgentRemote</remote>
  <ejb-class>com.titan.travelagent.TravelAgentBean</ejb-class>
  <session-type>Stateful</session-type>
  <transaction-type>Container</transaction-type>
  ...
  <resource-ref>
    <res-ref-name>jdbc/titanDB</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>
  <resource-ref>
    <res-ref-name>jms/TopicFactory</res-ref-name>
    <res-type>javax.jms.TopicConnectionFactory</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>
  <resource-env-ref>
    <resource-env-ref-name>jms/TicketTopic</resource-env-ref-name>
    <resource-env-ref-type>javax.jms.Topic</resource-env-ref-type>
  </resource-env-ref>
</session>

A reference to a TopicConnectionFactory is declared in the same way as a reference to a DataSource. The definition contains the name of the resource (jms/TopicFactory), the class of the resource (javax.jms.TopicConnectionFactory), and whether the container or the bean performs the authentication.

...
<session>
  <ejb-name>TravelAgentEJB</ejb-name>
  <jndi-name>TravelAgentHomeRemote</jndi-name>
  <resource-ref>
    <res-ref-name>jdbc/titanDB</res-ref-name>
    <jndi-name>java:/DefaultDS</jndi-name>
  </resource-ref>
  <resource-ref>
    <res-ref-name>jms/TopicFactory</res-ref-name>
    <jndi-name>java:/JmsXA</jndi-name>
  </resource-ref>
  <resource-env-ref>
    <resource-env-ref-name>jms/TicketTopic</resource-env-ref-name>
    <jndi-name>topic/titan-TicketTopic</jndi-name>
  </resource-env-ref>
</session>
...

The <resource-ref> entry from ejb-jar.xml is mapped in the jboss.xml file to the JNDI name java:/JmsXA. If you take a look at the JBossMQ default configuration file in $JBOSS_HOME/server/default/deploy/jms/jms-ds.xml, you’ll see that the XA connection manager is bound to this name by default.

The last part of the TravelAgent EJB descriptor in jboss.xml maps the jms/TicketTopic name from the JNDI ENC of the bean to the topic/titan-TicketTopic JNDI name. This name corresponds to the JMS topic you just created.

...
Context jndiContext = getInitialContext( );

TopicConnectionFactory factory = (TopicConnectionFactory)
   jndiContext.lookup("ConnectionFactory");

Topic topic = (Topic) 
   jndiContext.lookup("topic/titan-TicketTopic");

The name of the JMS topic is the same as the one you created in Exercise 11.1, but the name of the TopicConnectionFactory is not the same as the one used by the TravelAgent EJB.

Remember that the java:/JmsXA connection factory used by the EJB was in the private JNDI space of the JBoss JVM (indicated by the java: prefix). Thus, the client application cannot look up this name from its JVM. For external applications, JBoss binds a set of connection factories within the public JNDI tree, each dedicated to a particular message transport protocol.

JBossMQ supports several different kinds of message invocation layers. Each layer has its own ConnectionFactory that is bound in JNDI, as shown in Table 29-1.

We strongly suggest to use the UIL2 invocation layer; it is the most robust and efficient layer currently available.

TopicConnection connect = factory.createTopicConnection( );

TopicSession session = 
   connect.createTopicSession(false, Session.AUTO_ACKNOWLEDGE); 

TopicSubscriber subscriber = session.createSubscriber(topic);

subscriber.setMessageListener(this);

System.out.println
   ("Listening for messages on topic/titan-TicketTopic...");
connect.start( );

The end of the client application code is the same as in the EJB book.