2010-04-14 - Jakarta Taglibs has been retired.

For more information, please explore the Attic.

Jakarta Project: JMS Tag library: Tags for working with JMS

Version: 1.0

Table of Contents

Overview

The JMS custom tag library contains tags which can be used to perform a variety of JMS related operations such as sending and receiving messages from inside JSP.

Please refer to the detailed overview for more details.

Requirements

This taglib is currently built on top of the Messenger component from Jakarta Commons. In addition a JMS implementation is required along with a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher.

Configuration

Follow these steps to configure your web application with this tag library:

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="http://jakarta.apache.org/taglibs/jms-1.0" prefix="jms" %>

where "jms" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Tag Summary

JMS Tags
connection Defines a JMS connection facade (Messenger instance) to be used by other JMS tags.
send Sends a JMS message to some destination. The message and destination can be specified via attributes or via child tags as shown in the examples below.
receive Receives a JMS message from a given destination blocking either forever or for a given timeout value until a message is received. The destination can be specified via an attribute or via a nested <jms:destination> tag as shown in the examples below.
destination Defines a JMS Destination to be used by other tags. The name of the destination can either be specified using the 'name' attribute or the body content will be taken as being the destination name.
message Creates a JMS Message.
mapMessage Creates a JMS MapMessage. This tag may contain other <jms:mapEntry> tags or the body may be specified via the 'map' attribute.
objectMessage Creates a JMS ObjectMessage.
textMessage Creates a JMS TextMessage. The text body of the message can be specified via the 'body' attribute or via the content of this tag.
property Defines a JMS header property which is added to the outer <jms:message> tag. The value of the header can be specified via the value attribute otherwise the tags body is used as the value.
mapEntry Defines an entry in a JMS MapMessage.
 

Tag Reference

connection Availability: 

Defines a JMS connection facade (Messenger instance) to be used by other JMS tags.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 name  Yes   Yes  
 

The name of the Messenger connection to use

 var  No   Yes  
 

The JSP attribute variable that the JMS connection will be output as

VariablesNone
 
 


<jms:connection name="OrderBus" var="myConn"/>
<jms:send connection="$myConn">
  <jms:destination name="INCOMING.ORDERS"/>
  <jms:message type="NewOrder"/>
</jms:send>

<jms:connection name="OrderBus">
  <jms:send>
    <jms:destination name="INCOMING.ORDERS"/>
    <jms:message type="NewOrder"/>
  </jms:send>
</jms:connection>

send Availability: 

Sends a JMS message to some destination. The message and destination can be specified via attributes or via child tags as shown in the examples below.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 connection  No   Yes  
 

The JMS connection facade (Messenger instance).

 destination  No   Yes  
 

The JMS Destination to send the message to

 message  No   Yes  
 

The JMS Message to send

VariablesNone
 
 


<jms:send connection="$myConnection" destination="$myDest" message="$myMessage"/>

<jms:connection name="OrderBus">
  <jms:send>
    <jms:destination name="INCOMING.ORDERS"/>
    <jms:message type="NewOrder"/>
  </jms:send>
</jms:connection>

receive Availability: 

Receives a JMS message from a given destination blocking either forever or for a given timeout value until a message is received. The destination can be specified via an attribute or via a nested <jms:destination> tag as shown in the examples below.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 var  Yes   Yes  
 

The name of the JSP scope attribute variable which gets defined for the received message

 connection  No   Yes  
 

The JMS connection facade (Messenger instance).

 destination  No   Yes  
 

Defines the JMS Destination to use

 timeout  No   Yes  
 

An optional timeout value in milliseconds for which this tag will wait for a message. This timeout value should be greater than or equal to zero. If no timeout value is specified then the tag to wait indefinitely until a message arrives. If a timeout value is specified and no message arrives before the timeout period expires then a null message is returned. A value of 0 will cause the tag to return immedately (it is equivalent to the receiveNoWait() method in JMS and Messenger).

VariablesNone
 
 


<jms:receive var="msg" connection="$myConnection" destination="$myDest" timeout="1000"/>

<jms:connection name="OrderBus">
  <jms:receive var="msg">
    <jms:destination name="INCOMING.ORDERS"/>
  </jms:receive>
  <jx:expr value="$msg.text"/>
</jms:connection>

destination Availability: 

Defines a JMS Destination to be used by other tags. The name of the destination can either be specified using the 'name' attribute or the body content will be taken as being the destination name.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 name  No   Yes  
 

The name of the Destination connection to use, otherwise the body content of this tag will be used.

 var  No   Yes  
 

The JSP attribute variable that the JMS Destination will be output as

VariablesNone
 
 


<jms:destination var="myDest" connection="$myConn" name="SOME.WHERE"/>

<jms:connection name="Prices">
  <jms:destination var="myDest2" name="FOO.BAR.PRICES"/>
</jms:connection>

<jms:connection name="OrderBus">
  <jms:send>
    <jms:destination name="INCOMING.ORDERS"/>
    <jms:message type="NewOrder"/>
  </jms:send>
</jms:connection>

<jms:connection name="OrderBus">
  <jms:send>
    <jms:destination>INCOMING.ORDERS</jms:destination>
    <jms:message type="NewOrder"/>
  </jms:send>
</jms:connection>

message Availability: 

Creates a JMS Message.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 var  No   Yes  
 

The name of the JSP attribute variable that the message will be exported as.

 connection  No   Yes  
 

The JMS connection facade (Messenger instance).

 correlationID  No   Yes  
 

The JMS Correlation ID that is to be associated with this message

 replyTo  No   Yes  
 

The JMS Destination that should be used for replies to this message

 type  No   Yes  
 

The type of the JMS message. A JMS message can be given a type name to use which maybe used by the JMS provider to implement a message type repository.

VariablesNone
 
 


<jms:message var="msg2" connection="$myConn" replyTo="$someDest"/>

<jms:connection name="PurchaseOrders">
  <jms:message var="msg">
    <jms:property name="location" value="London"/>
    <jms:property name="country">England</jms:property>
  </jms:message>
</jms:connection>

<jms:connection name="PurchaseOrders">
  <jms:message var="msg" type="NewPurchaseOrder" correlationID="1234" replyTo="$myInbox"/>
</jms:connection>

mapMessage Availability: 

Creates a JMS MapMessage. This tag may contain other <jms:mapEntry> tags or the body may be specified via the 'map' attribute.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 var  No   Yes  
 

The name of the JSP attribute variable that the message will be exported as.

 connection  No   Yes  
 

The JMS connection facade (Messenger instance).

 correlationID  No   Yes  
 

The JMS Correlation ID that is to be associated with this message

 replyTo  No   Yes  
 

The JMS Destination that should be used for replies to this message

 type  No   Yes  
 

The type of the JMS message. A JMS message can be given a type name to use which maybe used by the JMS provider to implement a message type repository.

 map  No   Yes  
 

Specifies a Map of String keys and primitive values to be used as the body of the message.

VariablesNone
 
 


<jms:mapMessage var="msg2" connection="$myConn" map="$myEntries"/>

<jms:connection name="PurchaseOrders">
  <jms:send>
    <jms:destination name="NEW.ORDERS"/>    
    <jms:mapMessage>
      <jms:mapEntry name="x" value="$foo/>
      <jms:mapEntry name="y">some text</jms:mapEntry>
    </jms:mapMessage>
  </jms:send>
</jms:connection>

objectMessage Availability: 

Creates a JMS ObjectMessage.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 var  No   Yes  
 

The name of the JSP attribute variable that the message will be exported as.

 connection  No   Yes  
 

The JMS connection facade (Messenger instance).

 correlationID  No   Yes  
 

The JMS Correlation ID that is to be associated with this message

 replyTo  No   Yes  
 

The JMS Destination that should be used for replies to this message

 type  No   Yes  
 

The type of the JMS message. A JMS message can be given a type name to use which maybe used by the JMS provider to implement a message type repository.

 body  No   Yes  
 

The Serializable object used as the body of this JMS ObjectMessage.

VariablesNone
 
 


<jms:objectMessage var="msg2" connection="$myConn" body="$foo"/>

<jms:connection name="PurchaseOrders">
  <jms:send>
    <jms:destination name="NEW.ORDERS"/>    
    <jms:objectMessage body="$foo"/>
  </jms:send>
</jms:connection>

textMessage Availability: 

Creates a JMS TextMessage. The text body of the message can be specified via the 'body' attribute or via the content of this tag.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 var  No   Yes  
 

The name of the JSP attribute variable that the message will be exported as.

 connection  No   Yes  
 

The JMS connection facade (Messenger instance).

 correlationID  No   Yes  
 

The JMS Correlation ID that is to be associated with this message

 replyTo  No   Yes  
 

The JMS Destination that should be used for replies to this message

 type  No   Yes  
 

The type of the JMS message. A JMS message can be given a type name to use which maybe used by the JMS provider to implement a message type repository.

 body  No   Yes  
 

The String used as the body of this JMS TextMessage.

VariablesNone
 
 


<jms:textMessage var="msg2" connection="$myConn" body="this is some text"/>

<jms:connection name="PurchaseOrders">
  <jms:send>
    <jms:destination name="NEW.ORDERS"/>    
    <jms:textMessage>
      this is some text
    </jms:textMessage>
  </jms:send>
</jms:connection>

property Availability: 

Defines a JMS header property which is added to the outer <jms:message> tag. The value of the header can be specified via the value attribute otherwise the tags body is used as the value.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 name  Yes   Yes  
 

Defines the name of the header to set.

 value  No   Yes  
 

Defines the value of the header. If this attribute is not specified then the body of this tag is used instead.

VariablesNone
 
 


<jms:message var="msg">
  <jms:property name="location" value="London"/>
  <jms:property name="country">England</jms:property>
</jms:message>

mapEntry Availability: 

Defines an entry in a JMS MapMessage.

Tag BodyJSP    
Restrictions

Should only be used within a <jms:mapMessage> tag

AttributesNameRequired Runtime Expression Evaluation Availability
 name  Yes   Yes  
 

Defines the name of the entry.

 value  No   Yes  
 

Defines the value of the entry. If this attribute is not specified then the body of this tag is used instead.

VariablesNone
 
 


<jms:mapMessage var="msg">
  <jms:mapEntry name="x" value="$foo"/>
  <jms:mapEntry name="y">someText</jms:mapEntry>
</jms:message>

Examples

See the example application jms-examples.war for examples of the usage of the tags from this custom tag library.

Java Docs

Java programmers can view the java class documentation for this tag library as javadocs.

Revision History

Review the complete revision history of this tag library.