public class

JmsInvokerClientInterceptor

extends Object
implements InitializingBean
java.lang.Object
   ↳ org.springframework.jms.remoting.JmsInvokerClientInterceptor
Known Direct Subclasses

Class Overview

org.aopalliance.intercept.MethodInterceptor for accessing a JMS-based remote service.

Serializes remote invocation objects and deserializes remote invocation result objects. Uses Java serialization just like RMI, but with the JMS provider as communication infrastructure.

To be configured with a javax.jms.QueueConnectionFactory and a target queue (either as javax.jms.Queue reference or as queue name).

Thanks to James Strachan for the original prototype that this JMS invoker mechanism was inspired by!

Summary

Public Constructors
JmsInvokerClientInterceptor()
Public Methods
void afterPropertiesSet()
Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
Object invoke(MethodInvocation methodInvocation)
void setConnectionFactory(ConnectionFactory connectionFactory)
Set the QueueConnectionFactory to use for obtaining JMS QueueConnections.
void setDestinationResolver(DestinationResolver destinationResolver)
Set the DestinationResolver that is to be used to resolve Queue references for this accessor.
void setMessageConverter(MessageConverter messageConverter)
Specify the MessageConverter to use for turning RemoteInvocation objects into request messages, as well as response messages into RemoteInvocationResult objects.
void setQueue(Queue queue)
Set the target Queue to send invoker requests to.
void setQueueName(String queueName)
Set the name of target queue to send invoker requests to.
void setReceiveTimeout(long receiveTimeout)
Set the timeout to use for receiving the response message for a request (in milliseconds).
void setRemoteInvocationFactory(RemoteInvocationFactory remoteInvocationFactory)
Set the RemoteInvocationFactory to use for this accessor.
Protected Methods
RemoteAccessException convertJmsInvokerAccessException(JMSException ex)
Convert the given JMS invoker access exception to an appropriate Spring RemoteAccessException.
Connection createConnection()
Create a new JMS Connection for this JMS invoker, ideally a javax.jms.QueueConnection.
RemoteInvocation createRemoteInvocation(MethodInvocation methodInvocation)
Create a new RemoteInvocation object for the given AOP method invocation.
Message createRequestMessage(Session session, RemoteInvocation invocation)
Create the invoker request message.
Session createSession(Connection con)
Create a new JMS Session for this JMS invoker, ideally a javax.jms.QueueSession.
Message doExecuteRequest(Session session, Queue queue, Message requestMessage)
Actually execute the given request, sending the invoker request message to the specified target queue and waiting for a corresponding response.
RemoteInvocationResult executeRequest(RemoteInvocation invocation)
Execute the given remote invocation, sending an invoker request message to this accessor's target queue and waiting for a corresponding response.
RemoteInvocationResult extractInvocationResult(Message responseMessage)
Extract the invocation result from the response message.
ConnectionFactory getConnectionFactory()
Return the QueueConnectionFactory to use for obtaining JMS QueueConnections.
long getReceiveTimeout()
Return the timeout to use for receiving the response message for a request (in milliseconds).
RemoteInvocationResult onInvalidResponse(Message responseMessage)
Callback that is invoked by extractInvocationResult when it encounters an invalid response message.
Object recreateRemoteInvocationResult(RemoteInvocationResult result)
Recreate the invocation result contained in the given RemoteInvocationResult object.
Queue resolveQueue(Session session)
Resolve this accessor's target queue.
Queue resolveQueueName(Session session, String queueName)
Resolve the given queue name into a JMS javax.jms.Queue, via this accessor's DestinationResolver.
[Expand]
Inherited Methods
From class java.lang.Object
From interface org.springframework.beans.factory.InitializingBean

Public Constructors

public JmsInvokerClientInterceptor ()

Public Methods

public void afterPropertiesSet ()

Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).

This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.

public Object invoke (MethodInvocation methodInvocation)

Throws
Throwable

public void setConnectionFactory (ConnectionFactory connectionFactory)

Set the QueueConnectionFactory to use for obtaining JMS QueueConnections.

public void setDestinationResolver (DestinationResolver destinationResolver)

Set the DestinationResolver that is to be used to resolve Queue references for this accessor.

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

public void setMessageConverter (MessageConverter messageConverter)

Specify the MessageConverter to use for turning RemoteInvocation objects into request messages, as well as response messages into RemoteInvocationResult objects.

Default is a SimpleMessageConverter, using a standard JMS javax.jms.ObjectMessage for each invocation / invocation result object.

Custom implementations may generally adapt Serializables into special kinds of messages, or might be specifically tailored for translating RemoteInvocation(Result)s into specific kinds of messages.

public void setQueue (Queue queue)

Set the target Queue to send invoker requests to.

public void setQueueName (String queueName)

Set the name of target queue to send invoker requests to. The specified name will be dynamically resolved via the DestinationResolver.

public void setReceiveTimeout (long receiveTimeout)

Set the timeout to use for receiving the response message for a request (in milliseconds).

The default is 0, which indicates a blocking receive without timeout.

See Also
  • javax.jms.MessageConsumer#receive(long)
  • javax.jms.MessageConsumer#receive()

public void setRemoteInvocationFactory (RemoteInvocationFactory remoteInvocationFactory)

Set the RemoteInvocationFactory to use for this accessor. Default is a DefaultRemoteInvocationFactory.

A custom invocation factory can add further context information to the invocation, for example user credentials.

Protected Methods

protected RemoteAccessException convertJmsInvokerAccessException (JMSException ex)

Convert the given JMS invoker access exception to an appropriate Spring RemoteAccessException.

Parameters
ex the exception to convert
Returns
  • the RemoteAccessException to throw

protected Connection createConnection ()

Create a new JMS Connection for this JMS invoker, ideally a javax.jms.QueueConnection.

The default implementation uses the javax.jms.QueueConnectionFactory API if available, falling back to a standard JMS 1.1 ConnectionFactory otherwise. This is necessary for working with generic JMS 1.1 connection pools (such as ActiveMQ's org.apache.activemq.pool.PooledConnectionFactory).

Throws
JMSException

protected RemoteInvocation createRemoteInvocation (MethodInvocation methodInvocation)

Create a new RemoteInvocation object for the given AOP method invocation. The default implementation delegates to the RemoteInvocationFactory.

Can be overridden in subclasses to provide custom RemoteInvocation subclasses, containing additional invocation parameters like user credentials. Note that it is preferable to use a custom RemoteInvocationFactory which is a reusable strategy.

Parameters
methodInvocation the current AOP method invocation
Returns
  • the RemoteInvocation object

protected Message createRequestMessage (Session session, RemoteInvocation invocation)

Create the invoker request message.

The default implementation creates a JMS ObjectMessage for the given RemoteInvocation object.

Parameters
session the current JMS Session
invocation the remote invocation to send
Returns
  • the JMS Message to send
Throws
if the message could not be created
JMSException

protected Session createSession (Connection con)

Create a new JMS Session for this JMS invoker, ideally a javax.jms.QueueSession.

The default implementation uses the javax.jms.QueueConnection API if available, falling back to a standard JMS 1.1 Connection otherwise. This is necessary for working with generic JMS 1.1 connection pools (such as ActiveMQ's org.apache.activemq.pool.PooledConnectionFactory).

Throws
JMSException

protected Message doExecuteRequest (Session session, Queue queue, Message requestMessage)

Actually execute the given request, sending the invoker request message to the specified target queue and waiting for a corresponding response.

The default implementation is based on standard JMS send/receive, using a javax.jms.TemporaryQueue for receiving the response.

Parameters
session the JMS Session to use
queue the resolved target Queue to send to
requestMessage the JMS Message to send
Returns
  • the RemoteInvocationResult object
Throws
in case of JMS failure
JMSException

protected RemoteInvocationResult executeRequest (RemoteInvocation invocation)

Execute the given remote invocation, sending an invoker request message to this accessor's target queue and waiting for a corresponding response.

Parameters
invocation the RemoteInvocation to execute
Returns
  • the RemoteInvocationResult object
Throws
in case of JMS failure
JMSException

protected RemoteInvocationResult extractInvocationResult (Message responseMessage)

Extract the invocation result from the response message.

The default implementation expects a JMS ObjectMessage carrying a RemoteInvocationResult object. If an invalid response message is encountered, the onInvalidResponse callback gets invoked.

Parameters
responseMessage the response message
Returns
  • the invocation result
Throws
is thrown if a JMS exception occurs
JMSException

protected ConnectionFactory getConnectionFactory ()

Return the QueueConnectionFactory to use for obtaining JMS QueueConnections.

protected long getReceiveTimeout ()

Return the timeout to use for receiving the response message for a request (in milliseconds).

protected RemoteInvocationResult onInvalidResponse (Message responseMessage)

Callback that is invoked by extractInvocationResult when it encounters an invalid response message.

The default implementation throws a MessageFormatException.

Parameters
responseMessage the invalid response message
Returns
  • an alternative invocation result that should be returned to the caller (if desired)
Throws
if the invalid response should lead to an infrastructure exception propagated to the caller
JMSException

protected Object recreateRemoteInvocationResult (RemoteInvocationResult result)

Recreate the invocation result contained in the given RemoteInvocationResult object. The default implementation calls the default recreate method.

Can be overridden in subclass to provide custom recreation, potentially processing the returned result object.

Parameters
result the RemoteInvocationResult to recreate
Returns
  • a return value if the invocation result is a successful return
Throws
Throwable if the invocation result is an exception
See Also

protected Queue resolveQueue (Session session)

Resolve this accessor's target queue.

Parameters
session the current JMS Session
Returns
  • the resolved target Queue
Throws
if resolution failed
JMSException

protected Queue resolveQueueName (Session session, String queueName)

Resolve the given queue name into a JMS javax.jms.Queue, via this accessor's DestinationResolver.

Parameters
session the current JMS Session
queueName the name of the queue
Returns
  • the located Queue
Throws
if resolution failed
JMSException