JmsInvokerClientInterceptor (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jms.remoting

## Class JmsInvokerClientInterceptor

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

- All Implemented Interfaces:
    Advice, Interceptor, MethodInterceptor, InitializingBean
  Direct Known Subclasses:
    JmsInvokerProxyFactoryBean

      public class JmsInvokerClientInterceptor
      extends Object
      implements MethodInterceptor, 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
  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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
    `protected 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 RemoteInvocation` | `createRemoteInvocation(MethodInvocation methodInvocation)` Create a new RemoteInvocation object for the given AOP method invocation.
    `protected Message` | `createRequestMessage(Session session, 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 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.
    `protected 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(MethodInvocation methodInvocation)`
    `protected RemoteInvocationResult` | `onInvalidResponse(Message responseMessage)` Callback that is invoked by `extractInvocationResult` when it encounters an invalid response message.
    `protected Object` | `recreateRemoteInvocationResult(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(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(ConnectionFactory connectionFactory)

      Set the QueueConnectionFactory to use for obtaining JMS QueueConnections.

    - #### getConnectionFactory

          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(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(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(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 Serializables 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()

      Description copied from interface: `InitializingBean`
      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.

      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`

    - #### invoke

          public Object invoke(MethodInvocation methodInvocation)
                        throws Throwable

      Specified by:
        `invoke` in interface `MethodInterceptor`
      Throws:
        `Throwable`

    - #### createRemoteInvocation

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

    - #### executeRequest

          protected RemoteInvocationResult executeRequest(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,
                                     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

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

    - #### onInvalidResponse

          protected RemoteInvocationResult onInvalidResponse(Message responseMessage)
                                                      throws JMSException

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

    - #### recreateRemoteInvocationResult

          protected Object recreateRemoteInvocationResult(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 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:
        `RemoteInvocationResult.recreate()`

    - #### convertJmsInvokerAccessException

          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