org.springframework.jms.remoting

## Class JmsInvokerClientInterceptor

- java.lang.Object
- - org.springframework.jms.remoting.JmsInvokerClientInterceptor

All Implemented Interfaces:
  org.aopalliance.aop.Advice, org.aopalliance.intercept.Interceptor, org.aopalliance.intercept.MethodInterceptor, org.springframework.beans.factory.InitializingBean

Direct Known Subclasses:
  JmsInvokerProxyFactoryBean

    public class JmsInvokerClientInterceptor
    extends Object
    implements org.aopalliance.intercept.MethodInterceptor, org.springframework.beans.factory.InitializingBean

`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 `QueueConnectionFactory` and a target queue (either as `Queue` reference or as queue name).

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

Since:
  2.0
Author:
  Juergen Hoeller, James Strachan, Stephane Nicoll
See Also:
  `setConnectionFactory(javax.jms.ConnectionFactory)`, `setQueue(javax.jms.Queue)`, `setQueueName(java.lang.String)`, `JmsInvokerServiceExporter`, `JmsInvokerProxyFactoryBean`

### Constructor Summary

Constructors
Constructor and Description
`JmsInvokerClientInterceptor()`

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `afterPropertiesSet()`
`protected org.springframework.remoting.RemoteAccessException` `convertJmsInvokerAccessException(JMSException ex)` Convert the given JMS invoker access exception to an appropriate Spring `RemoteAccessException`.
`protected Connection` `createConnection()` Create a new JMS Connection for this JMS invoker.
`protected org.springframework.remoting.support.RemoteInvocation` `createRemoteInvocation(org.aopalliance.intercept.MethodInvocation methodInvocation)` Create a new `RemoteInvocation` object for the given AOP method invocation.
`protected Message` `createRequestMessage(Session session, org.springframework.remoting.support.RemoteInvocation invocation)` Create the invoker request message.
`protected Session` `createSession(Connection con)` Create a new JMS Session for this JMS invoker.
`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.
`protected org.springframework.remoting.support.RemoteInvocationResult` `executeRequest(org.springframework.remoting.support.RemoteInvocation invocation)` Execute the given remote invocation, sending an invoker request message to this accessor's target queue and waiting for a corresponding response.
`protected org.springframework.remoting.support.RemoteInvocationResult` `extractInvocationResult(Message responseMessage)` Extract the invocation result from the response message.
`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).
`Object` `invoke(org.aopalliance.intercept.MethodInvocation methodInvocation)`
`protected org.springframework.remoting.support.RemoteInvocationResult` `onInvalidResponse(Message responseMessage)` Callback that is invoked by `extractInvocationResult(javax.jms.Message)` when it encounters an invalid response message.
`protected org.springframework.remoting.support.RemoteInvocationResult` `onReceiveTimeout(org.springframework.remoting.support.RemoteInvocation invocation)` Callback that is invoked by `executeRequest(org.springframework.remoting.support.RemoteInvocation)` when the receive timeout has expired for the specified `RemoteInvocation`.
`protected Object` `recreateRemoteInvocationResult(org.springframework.remoting.support.RemoteInvocationResult result)` Recreate the invocation result contained in the given `RemoteInvocationResult` object.
`protected Queue` `resolveQueue(Session session)` Resolve this accessor's target queue.
`protected Queue` `resolveQueueName(Session session, String queueName)` Resolve the given queue name into a JMS `Queue`, via this accessor's `DestinationResolver`.
`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(org.springframework.remoting.support.RemoteInvocationFactory remoteInvocationFactory)` Set the `RemoteInvocationFactory` to use for this accessor.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### JmsInvokerClientInterceptor

    public JmsInvokerClientInterceptor()

### Method Detail

#### setConnectionFactory

    public void setConnectionFactory(@Nullable
                                     ConnectionFactory connectionFactory)

Set the QueueConnectionFactory to use for obtaining JMS QueueConnections.

#### getConnectionFactory

    @Nullable
    protected ConnectionFactory getConnectionFactory()

Return the QueueConnectionFactory to use for obtaining JMS QueueConnections.

#### setQueue

    public void setQueue(Queue queue)

Set the target Queue to send invoker requests to.

#### setQueueName

    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`.

#### setDestinationResolver

    public void setDestinationResolver(@Nullable
                                       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.

See Also:
  `DynamicDestinationResolver`, `JndiDestinationResolver`

#### setRemoteInvocationFactory

    public void setRemoteInvocationFactory(@Nullable
                                           org.springframework.remoting.support.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.

#### setMessageConverter

    public void setMessageConverter(@Nullable
                                    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 `ObjectMessage` for each invocation / invocation result object.

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

#### setReceiveTimeout

    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:
  `MessageConsumer.receive(long)`, `MessageConsumer.receive()`

#### getReceiveTimeout

    protected long getReceiveTimeout()

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

#### afterPropertiesSet

    public void afterPropertiesSet()

Specified by:
  `afterPropertiesSet` in interface `org.springframework.beans.factory.InitializingBean`

#### invoke

    @Nullable
    public Object invoke(org.aopalliance.intercept.MethodInvocation methodInvocation)
                            throws Throwable

Specified by:
  `invoke` in interface `org.aopalliance.intercept.MethodInterceptor`
Throws:
  `Throwable`

#### createRemoteInvocation

    protected org.springframework.remoting.support.RemoteInvocation createRemoteInvocation(org.aopalliance.intercept.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
See Also:
  `RemoteInvocationFactory.createRemoteInvocation(org.aopalliance.intercept.MethodInvocation)`

#### executeRequest

    protected org.springframework.remoting.support.RemoteInvocationResult executeRequest(org.springframework.remoting.support.RemoteInvocation invocation)
                                                                                  throws JMSException

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:
  `JMSException` - in case of JMS failure
See Also:
  `doExecuteRequest(javax.jms.Session, javax.jms.Queue, javax.jms.Message)`

#### createConnection

    protected Connection createConnection()
                                   throws JMSException

Create a new JMS Connection for this JMS invoker.

Throws:
  `JMSException`

#### createSession

    protected Session createSession(Connection con)
                             throws JMSException

Create a new JMS Session for this JMS invoker.

Throws:
  `JMSException`

#### resolveQueue

    protected Queue resolveQueue(Session session)
                          throws JMSException

Resolve this accessor's target queue.

Parameters:
  `session` - the current JMS Session
Returns:
  the resolved target Queue
Throws:
  `JMSException` - if resolution failed

#### resolveQueueName

    protected Queue resolveQueueName(Session session,
                                     String queueName)
                              throws JMSException

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

Parameters:
  `session` - the current JMS Session
  `queueName` - the name of the queue
Returns:
  the located Queue
Throws:
  `JMSException` - if resolution failed
See Also:
  `setDestinationResolver(org.springframework.jms.support.destination.DestinationResolver)`

#### createRequestMessage

    protected Message createRequestMessage(Session session,
                                           org.springframework.remoting.support.RemoteInvocation invocation)
                                    throws JMSException

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:
  `JMSException` - if the message could not be created

#### doExecuteRequest

    @Nullable
    protected Message doExecuteRequest(Session session,
                                                 Queue queue,
                                                 Message requestMessage)
                                          throws JMSException

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 `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:
  `JMSException` - in case of JMS failure

#### extractInvocationResult

    protected org.springframework.remoting.support.RemoteInvocationResult extractInvocationResult(Message responseMessage)
                                                                                           throws JMSException

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:
  `JMSException` - is thrown if a JMS exception occurs
See Also:
  `onInvalidResponse(javax.jms.Message)`

#### onReceiveTimeout

    protected org.springframework.remoting.support.RemoteInvocationResult onReceiveTimeout(org.springframework.remoting.support.RemoteInvocation invocation)

Callback that is invoked by `executeRequest(org.springframework.remoting.support.RemoteInvocation)` when the receive timeout has expired for the specified `RemoteInvocation`.

By default, an `RemoteTimeoutException` is thrown. Sub-classes can choose to either throw a more dedicated exception or even return a default `RemoteInvocationResult` as a fallback.

Parameters:
  `invocation` - the invocation
Returns:
  a default result when the receive timeout has expired

#### onInvalidResponse

    protected org.springframework.remoting.support.RemoteInvocationResult onInvalidResponse(Message responseMessage)
                                                                                     throws JMSException

Callback that is invoked by `extractInvocationResult(javax.jms.Message)` 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:
  `JMSException` - if the invalid response should lead to an infrastructure exception propagated to the caller
See Also:
  `extractInvocationResult(javax.jms.Message)`

#### recreateRemoteInvocationResult

    @Nullable
    protected Object recreateRemoteInvocationResult(org.springframework.remoting.support.RemoteInvocationResult result)
                                                       throws Throwable

Recreate the invocation result contained in the given `RemoteInvocationResult` object.

The default implementation calls the default `recreate()` method.

Can be overridden in subclasses 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:
  `RemoteInvocationResult.recreate()`

#### convertJmsInvokerAccessException

    protected org.springframework.remoting.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