org.springframework.jms.core
Class JmsTemplate

Direct Known Subclasses:
JmsTemplate102

public class JmsTemplate
implements InitializingBean, JmsOperations

Helper class that simplifies JMS access code. This class requires a JMS >= 1.1 provider, because it builds on the domain-independent API. Use the JmsTemplate102 subclass for JMS 1.0.2 providers.

If you want to use dynamic destination creation, you must specify the type of JMS destination to create, using the "pubSubDomain" property. For other operations, this is not necessary, in contrast to when working with JmsTemplate102. Point-to-Point (Queues) is the default domain.

Default settings for JMS sessions are not transacted and auto-acknowledge. As defined by the J2EE specification, the transaction and acknowledgement parameters are ignored when a JMS Session is created inside an active transaction, no matter if a JTA transaction or a Spring-managed transaction.

This template uses a DynamicDestinationResolver and a SimpleMessageConverter as default strategies for resolving a destination name respectively converting a message.

Author:
Mark Pollack, Juergen Hoeller
Since: 1.1
See Also: setConnectionFactory(ConnectionFactory), setPubSubDomain(boolean), JmsTemplate102, setDestinationResolver(org.springframework.jms.support.destination.DestinationResolver), setMessageConverter(org.springframework.jms.support.converter.MessageConverter), DynamicDestinationResolver, SimpleMessageConverter, javax.jms.Destination, javax.jms.Session, javax.jms.MessageProducer, javax.jms.MessageConsumer

Field Summary
 final static longDEFAULT_RECEIVE_TIMEOUT
          Default timeout for receive operations: -1 indicates a blocking receive without timeout.

Constructor Summary
JmsTemplate()
          Create a new JmsTemplate for bean-style usage.
JmsTemplate(ConnectionFactory connectionFactory)
          Create a new JmsTemplate, given a ConnectionFactory.

Method Summary
 voidafterPropertiesSet()
           
 voidconvertAndSend(Object message)
           
 voidconvertAndSend(Destination destination, Object message)
           
 voidconvertAndSend(String destinationName, Object message)
           
 voidconvertAndSend(Object message, MessagePostProcessor postProcessor)
           
 voidconvertAndSend(Destination destination, Object message, MessagePostProcessor postProcessor)
           
 voidconvertAndSend(String destinationName, Object message, MessagePostProcessor postProcessor)
           
 Objectexecute(SessionCallback action, boolean startConnection)
          Execute the action specified by the given action object within a JMS Session.
 Objectexecute(SessionCallback action)
           
 Objectexecute(ProducerCallback action)
           
 ConnectionFactorygetConnectionFactory()
          Return the connection factory used for obtaining JMS connections.
 DestinationgetDefaultDestination()
          Return the destination to be used on send operations that do not have a destination parameter.
 intgetDeliveryMode()
          Return the delivery mode to use when sending a message.
 DestinationResolvergetDestinationResolver()
          Get the destination resolver for this template.
 MessageConvertergetMessageConverter()
          Return the message converter for this template.
 intgetPriority()
          Return the priority of a message when sending.
 longgetReceiveTimeout()
          Return the timeout to use for receive calls.
 intgetSessionAcknowledgeMode()
          Return the acknowledgement mode for JMS sessions.
 longgetTimeToLive()
          Return the time-to-live of the message when sending.
 booleanisExplicitQosEnabled()
          If true, then the values of deliveryMode, priority, and timeToLive will be used when sending a message.
 booleanisMessageIdEnabled()
          Return whether message IDs are enabled.
 booleanisMessageTimestampEnabled()
          Return whether message timestamps are enabled.
 booleanisPubSubDomain()
          Return whether the Publish/Subscribe domain (Topics) is used.
 booleanisPubSubNoLocal()
          Return whether to inhibit the delivery of messages published by its own connection.
 booleanisSessionTransacted()
          Return whether the JMS sessions used for sending a message are transacted.
 Messagereceive()
           
 Messagereceive(Destination destination)
           
 Messagereceive(String destinationName)
           
 ObjectreceiveAndConvert()
           
 ObjectreceiveAndConvert(Destination destination)
           
 ObjectreceiveAndConvert(String destinationName)
           
 MessagereceiveSelected(String messageSelector)
           
 MessagereceiveSelected(Destination destination, String messageSelector)
           
 MessagereceiveSelected(String destinationName, String messageSelector)
           
 ObjectreceiveSelectedAndConvert(String messageSelector)
           
 ObjectreceiveSelectedAndConvert(Destination destination, String messageSelector)
           
 ObjectreceiveSelectedAndConvert(String destinationName, String messageSelector)
           
 voidsend(MessageCreator messageCreator)
           
 voidsend(Destination destination, MessageCreator messageCreator)
           
 voidsend(String destinationName, MessageCreator messageCreator)
           
 voidsetConnectionFactory(ConnectionFactory connectionFactory)
          Set the connection factory used for obtaining JMS connections.
 voidsetDefaultDestination(Destination destination)
          Set the destination to be used on send operations that do not have a destination parameter.
 voidsetDeliveryMode(int deliveryMode)
          Set the delivery mode to use when sending a message.
 voidsetDestinationResolver(DestinationResolver destinationResolver)
          Set the destination resolver for this template.
 voidsetExplicitQosEnabled(boolean explicitQosEnabled)
          Set if the QOS values (deliveryMode, priority, timeToLive) should be used for sending a message.
 voidsetMessageConverter(MessageConverter messageConverter)
          Set the message converter for this template.
 voidsetMessageIdEnabled(boolean messageIdEnabled)
          Set whether message IDs are enabled.
 voidsetMessageTimestampEnabled(boolean messageTimestampEnabled)
          Set whether message timestamps are enabled.
 voidsetPriority(int priority)
          Set the priority of a message when sending.
 voidsetPubSubDomain(boolean pubSubDomain)
          Configure the JmsTemplate with knowledge of the JMS domain used.
 voidsetPubSubNoLocal(boolean pubSubNoLocal)
          Set whether to inhibit the delivery of messages published by its own connection.
 voidsetReceiveTimeout(long receiveTimeout)
          Set the timeout to use for receive calls.
 voidsetSessionAcknowledgeMode(int sessionAcknowledgeMode)
          Set the JMS acknowledgement mode that is used when creating a JMS session to send a message.
 voidsetSessionAcknowledgeModeName(String constantName)
          Set the JMS acknowledgement mode by the name of the corresponding constant in the JMS Session interface, e.g.
 voidsetSessionTransacted(boolean sessionTransacted)
          Set the transaction mode that is used when creating a JMS session to send a message.
 voidsetTimeToLive(long timeToLive)
          Set the time-to-live of the message when sending.

Field Detail

DEFAULT_RECEIVE_TIMEOUT

public final static long DEFAULT_RECEIVE_TIMEOUT
Default timeout for receive operations: -1 indicates a blocking receive without timeout.
Constructor Detail

JmsTemplate

public JmsTemplate()
Create a new JmsTemplate for bean-style usage.

Note: The ConnectionFactory has to be set before using the instance. This constructor can be used to prepare a JmsTemplate via a BeanFactory, typically setting the ConnectionFactory via setConnectionFactory.

See Also:
setConnectionFactory(ConnectionFactory)

JmsTemplate

public JmsTemplate(ConnectionFactory connectionFactory)
Create a new JmsTemplate, given a ConnectionFactory.
Parameters:
connectionFactory - the ConnectionFactory to obtain connections from
Method Detail

afterPropertiesSet

public void afterPropertiesSet()

convertAndSend

public void convertAndSend(Object message)
throws org.springframework.jms.JmsException

convertAndSend

public void convertAndSend(Destination destination, Object message)
throws org.springframework.jms.JmsException

convertAndSend

public void convertAndSend(String destinationName, Object message)
throws org.springframework.jms.JmsException

convertAndSend

public void convertAndSend(Object message, MessagePostProcessor postProcessor)
throws org.springframework.jms.JmsException

convertAndSend

public void convertAndSend(Destination destination, Object message, MessagePostProcessor postProcessor)
throws org.springframework.jms.JmsException

convertAndSend

public void convertAndSend(String destinationName, Object message, MessagePostProcessor postProcessor)
throws org.springframework.jms.JmsException

execute

public Object execute(SessionCallback action, boolean startConnection)
throws org.springframework.jms.JmsException
Execute the action specified by the given action object within a JMS Session. Generalized version of execute(SessionCallback), allowing to start the JMS Connection on the fly.

Use execute(SessionCallback) for the general case. Starting the JMS Connection is just necessary for receiving messages, which is preferably achieve through the receive methods.

Parameters:
action - callback object that exposes the session
Returns: the result object from working with the session
Throws:
JmsException - if there is any problem
See Also:
execute(org.springframework.jms.core.SessionCallback), receive()

execute

public Object execute(SessionCallback action)
throws org.springframework.jms.JmsException

execute

public Object execute(ProducerCallback action)
throws org.springframework.jms.JmsException

getConnectionFactory

public ConnectionFactory getConnectionFactory()
Return the connection factory used for obtaining JMS connections.

getDefaultDestination

public Destination getDefaultDestination()
Return the destination to be used on send operations that do not have a destination parameter.

getDeliveryMode

public int getDeliveryMode()
Return the delivery mode to use when sending a message.

getDestinationResolver

public DestinationResolver getDestinationResolver()
Get the destination resolver for this template.

getMessageConverter

public MessageConverter getMessageConverter()
Return the message converter for this template.

getPriority

public int getPriority()
Return the priority of a message when sending.

getReceiveTimeout

public long getReceiveTimeout()
Return the timeout to use for receive calls.

getSessionAcknowledgeMode

public int getSessionAcknowledgeMode()
Return the acknowledgement mode for JMS sessions.

getTimeToLive

public long getTimeToLive()
Return the time-to-live of the message when sending.

isExplicitQosEnabled

public boolean isExplicitQosEnabled()
If true, then the values of deliveryMode, priority, and timeToLive will be used when sending a message. Otherwise, the default values, that may be set administratively, will be used.
Returns: true if overriding default values of QOS parameters (deliveryMode, priority, and timeToLive)
See Also:
setDeliveryMode(int), setPriority(int), setTimeToLive(long)

isMessageIdEnabled

public boolean isMessageIdEnabled()
Return whether message IDs are enabled.

isMessageTimestampEnabled

public boolean isMessageTimestampEnabled()
Return whether message timestamps are enabled.

isPubSubDomain

public boolean isPubSubDomain()
Return whether the Publish/Subscribe domain (Topics) is used. Otherwise, the Point-to-Point domain (Queues) is used.

isPubSubNoLocal

public boolean isPubSubNoLocal()
Return whether to inhibit the delivery of messages published by its own connection.

isSessionTransacted

public boolean isSessionTransacted()
Return whether the JMS sessions used for sending a message are transacted.

receive

public Message receive()
throws org.springframework.jms.JmsException

receive

public Message receive(Destination destination)
throws org.springframework.jms.JmsException

receive

public Message receive(String destinationName)
throws org.springframework.jms.JmsException

receiveAndConvert

public Object receiveAndConvert()
throws org.springframework.jms.JmsException

receiveAndConvert

public Object receiveAndConvert(Destination destination)
throws org.springframework.jms.JmsException

receiveAndConvert

public Object receiveAndConvert(String destinationName)
throws org.springframework.jms.JmsException

receiveSelected

public Message receiveSelected(String messageSelector)
throws org.springframework.jms.JmsException

receiveSelected

public Message receiveSelected(Destination destination, String messageSelector)
throws org.springframework.jms.JmsException

receiveSelected

public Message receiveSelected(String destinationName, String messageSelector)
throws org.springframework.jms.JmsException

receiveSelectedAndConvert

public Object receiveSelectedAndConvert(String messageSelector)
throws org.springframework.jms.JmsException

receiveSelectedAndConvert

public Object receiveSelectedAndConvert(Destination destination, String messageSelector)
throws org.springframework.jms.JmsException

receiveSelectedAndConvert

public Object receiveSelectedAndConvert(String destinationName, String messageSelector)
throws org.springframework.jms.JmsException

send

public void send(MessageCreator messageCreator)
throws org.springframework.jms.JmsException

send

public void send(Destination destination, MessageCreator messageCreator)
throws org.springframework.jms.JmsException

send

public void send(String destinationName, MessageCreator messageCreator)
throws org.springframework.jms.JmsException

setConnectionFactory

public void setConnectionFactory(ConnectionFactory connectionFactory)
Set the connection factory used for obtaining JMS connections.

setDefaultDestination

public void setDefaultDestination(Destination destination)
Set the destination to be used on send operations that do not have a destination parameter.
See Also:
send(org.springframework.jms.core.MessageCreator), convertAndSend(java.lang.Object), convertAndSend(java.lang.Object,org.springframework.jms.core.MessagePostProcessor)

setDeliveryMode

public void setDeliveryMode(int deliveryMode)
Set the delivery mode to use when sending a message.

Since a default value may be defined administratively, this is only used when isExplicitQosEnabled equals true.

Parameters:
deliveryMode - the delivery mode to use
See Also:
isExplicitQosEnabled(), javax.jms.Message#DEFAULT_DELIVERY_MODE, javax.jms.MessageProducer#send(javax.jms.Message, int, int, long)

setDestinationResolver

public void setDestinationResolver(DestinationResolver destinationResolver)
Set the destination resolver for this template. Used to resolve destination names and to support dynamic destination functionality.

The default resolver is a DynamicDestinationResolver. Specify a JndiDestinationResolver for resolving destination names as JNDI locations.

See Also:
DynamicDestinationResolver, JndiDestinationResolver

setExplicitQosEnabled

public void setExplicitQosEnabled(boolean explicitQosEnabled)
Set if the QOS values (deliveryMode, priority, timeToLive) should be used for sending a message.
See Also:
setDeliveryMode(int), setPriority(int), setTimeToLive(long)

setMessageConverter

public void setMessageConverter(MessageConverter messageConverter)
Set the message converter for this template. Used to resolve Object parameters to convertAndSend methods and Object results from receiveAndConvert methods.

The default converter is a SimpleMessageConverter, which is able to handle BytesMessages, TextMessages and ObjectMessages.

See Also:
convertAndSend(java.lang.Object), receiveAndConvert(), SimpleMessageConverter

setMessageIdEnabled

public void setMessageIdEnabled(boolean messageIdEnabled)
Set whether message IDs are enabled. Default is true.

This is only a hint to the JMS producer. See the JMS javadocs for details.

See Also:
javax.jms.MessageProducer#setDisableMessageID

setMessageTimestampEnabled

public void setMessageTimestampEnabled(boolean messageTimestampEnabled)
Set whether message timestamps are enabled. Default is true.

This is only a hint to the JMS producer. See the JMS javadocs for details.

See Also:
javax.jms.MessageProducer#setDisableMessageTimestamp

setPriority

public void setPriority(int priority)
Set the priority of a message when sending.

Since a default value may be defined administratively, this is only used when isExplicitQosEnabled equals true.

See Also:
isExplicitQosEnabled(), javax.jms.Message#DEFAULT_PRIORITY, javax.jms.MessageProducer#send(javax.jms.Message, int, int, long)

setPubSubDomain

public void setPubSubDomain(boolean pubSubDomain)
Configure the JmsTemplate with knowledge of the JMS domain used. Default is Point-to-Point (Queues).

For JmsTemplate102, this tells the JMS provider which class hierarchy to use in the implementation of the various execute methods. For JmsTemplate itself, it does not affect execute methods. In both implementations, it tells what type of destination to create if dynamic destinations are enabled.

Parameters:
pubSubDomain - true for Publish/Subscribe domain (Topics), false for Point-to-Point domain (Queues)
See Also:
setDestinationResolver(org.springframework.jms.support.destination.DestinationResolver)

setPubSubNoLocal

public void setPubSubNoLocal(boolean pubSubNoLocal)
Set whether to inhibit the delivery of messages published by its own connection. Default is false.
See Also:
javax.jms.TopicSession#createSubscriber(javax.jms.Topic, String, boolean)

setReceiveTimeout

public void setReceiveTimeout(long receiveTimeout)
Set the timeout to use for receive calls. The default is -1, which means no timeout.
See Also:
javax.jms.MessageConsumer#receive(long), javax.jms.MessageConsumer#receive

setSessionAcknowledgeMode

public void setSessionAcknowledgeMode(int sessionAcknowledgeMode)
Set the JMS acknowledgement mode that is used when creating a JMS session to send a message. Vendor extensions to the acknowledgment mode can be set here as well.

Note that that inside an EJB the parameters to create(Queue|Topic)Session(boolean transacted, int acknowledgeMode) method are not taken into account. Depending on the transaction context in the EJB, the container makes its own decisions on these values. See section 17.3.5 of the EJB Spec.

Parameters:
sessionAcknowledgeMode - the acknowledgement mode
See Also:
javax.jms.Session#AUTO_ACKNOWLEDGE, javax.jms.Session#CLIENT_ACKNOWLEDGE, javax.jms.Session#DUPS_OK_ACKNOWLEDGE, javax.jms.Connection#createSession

setSessionAcknowledgeModeName

public void setSessionAcknowledgeModeName(String constantName)
Set the JMS acknowledgement mode by the name of the corresponding constant in the JMS Session interface, e.g. "CLIENT_ACKNOWLEDGE".
Parameters:
constantName - name of the constant
See Also:
javax.jms.Session#AUTO_ACKNOWLEDGE, javax.jms.Session#CLIENT_ACKNOWLEDGE, javax.jms.Session#DUPS_OK_ACKNOWLEDGE, javax.jms.Connection#createSession

setSessionTransacted

public void setSessionTransacted(boolean sessionTransacted)
Set the transaction mode that is used when creating a JMS session to send a message.

Note that that within a JTA transaction, the parameters to createSession(boolean transacted, int acknowledgeMode) method are not taken into account. Depending on the J2EE transaction context, the container makes its own decisions on these values. See section 17.3.5 of the EJB Spec.

Parameters:
sessionTransacted - the transaction mode
See Also:
javax.jms.Connection#createSession

setTimeToLive

public void setTimeToLive(long timeToLive)
Set the time-to-live of the message when sending.

Since a default value may be defined administratively, this is only used when isExplicitQosEnabled equals true.

Parameters:
timeToLive - the message's lifetime (in milliseconds)
See Also:
isExplicitQosEnabled(), javax.jms.Message#DEFAULT_TIME_TO_LIVE, javax.jms.MessageProducer#send(javax.jms.Message, int, int, long)

Association Links

to Class org.springframework.core.Constants

Constants instance for javax.jms.Session

to Class org.springframework.jms.support.destination.DestinationResolver

Delegate management of JNDI lookups and dynamic destination creation to a DestinationResolver implementation.

to Class org.springframework.jms.support.converter.MessageConverter

The messageConverter to use for send(object) methods.