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

org.springframework.remoting.jaxrpc

## Class JaxRpcPortClientInterceptor

- java.lang.Object
- - org.springframework.remoting.jaxrpc.LocalJaxRpcServiceFactory
  - - org.springframework.remoting.jaxrpc.JaxRpcPortClientInterceptor

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

  Deprecated.
  in favor of JAX-WS support in `org.springframework.remoting.jaxws`

      @Deprecated
      public class JaxRpcPortClientInterceptor
      extends LocalJaxRpcServiceFactory
      implements MethodInterceptor, InitializingBean

  `MethodInterceptor` for accessing a specific port of a JAX-RPC service. Uses either `LocalJaxRpcServiceFactory`'s facilities underneath or takes an explicit reference to an existing JAX-RPC Service instance (e.g. obtained via a `JndiObjectFactoryBean`).

  Allows to set JAX-RPC's standard stub properties directly, via the "username", "password", "endpointAddress" and "maintainSession" properties. For typical usage, it is not necessary to specify those.

  In standard JAX-RPC style, this invoker is used with an RMI service interface. Alternatively, this invoker can also proxy a JAX-RPC service with a matching non-RMI business interface, that is, an interface that declares the service methods without RemoteExceptions. In the latter case, RemoteExceptions thrown by JAX-RPC will automatically get converted to Spring's unchecked RemoteAccessException.

  Setting "serviceInterface" is usually sufficient: The invoker will automatically use JAX-RPC "dynamic invocations" via the Call API in this case, no matter whether the specified interface is an RMI or non-RMI interface. Alternatively, a corresponding JAX-RPC port interface can be specified as "portInterface", which will turn this invoker into "static invocation" mode (operating on a standard JAX-RPC port stub).

  Since:
    15.12.2003
  Author:
    Juergen Hoeller
  See Also:
    `setPortName(java.lang.String)`, `setServiceInterface(java.lang.Class)`, `setPortInterface(java.lang.Class)`, `Service.createCall(javax.xml.namespace.QName)`, `Service.getPort(javax.xml.namespace.QName, java.lang.Class)`, `RemoteAccessException`, `JndiObjectFactoryBean`

- - ### Field Summary

    - ### Fields inherited from class org.springframework.remoting.jaxrpc.LocalJaxRpcServiceFactory

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JaxRpcPortClientInterceptor()` Deprecated.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addCustomProperty(String name, Object value)` Deprecated. Add a custom property to this JAX-RPC Stub/Call.
    `void` | `afterPropertiesSet()` Deprecated. Prepares the JAX-RPC service and port if the "lookupServiceOnStartup" is turned on (which it is by default).
    `protected boolean` | `alwaysUseJaxRpcCall()` Deprecated. Return whether to always use JAX-RPC dynamic calls.
    `protected Object` | `doInvoke(MethodInvocation invocation)` Deprecated. Perform a JAX-RPC service invocation based on the given method invocation.
    `protected Object` | `doInvoke(MethodInvocation invocation, Remote portStub)` Deprecated. Perform a JAX-RPC service invocation on the given port stub.
    `Map<String,Object>` | `getCustomPropertyMap()` Deprecated. Allow Map access to the custom properties to be set on the stub or call, with the option to add or override specific entries.
    `String` | `getEndpointAddress()` Deprecated. Return the endpoint address to specify on the stub or call.
    `Service` | `getJaxRpcService()` Deprecated. Return a reference to an existing JAX-RPC Service instance, if any.
    `String` | `getPassword()` Deprecated. Return the password to specify on the stub or call.
    `Class` | `getPortInterface()` Deprecated. Return the JAX-RPC port interface to use.
    `String` | `getPortName()` Deprecated. Return the name of the port.
    `protected QName` | `getPortQName()` Deprecated. Return the prepared QName for the port.
    `protected Remote` | `getPortStub()` Deprecated. Return the underlying JAX-RPC port stub that this interceptor delegates to for each method invocation on the proxy.
    `Class` | `getServiceInterface()` Deprecated. Return the interface of the service that this factory should create a proxy for.
    `String` | `getUsername()` Deprecated. Return the username to specify on the stub or call.
    `protected Throwable` | `handleRemoteException(Method method, RemoteException ex)` Deprecated. Handle the given RemoteException that was thrown from a JAX-RPC port stub or JAX-RPC call invocation.
    `Object` | `invoke(MethodInvocation invocation)` Deprecated. Translates the method invocation into a JAX-RPC service invocation.
    `protected boolean` | `isConnectFailure(RemoteException ex)` Deprecated. Determine whether the given RMI exception indicates a connect failure.
    `boolean` | `isMaintainSession()` Deprecated. Return the maintain session flag to specify on the stub or call.
    `protected boolean` | `isPrepared()` Deprecated. Return whether this client interceptor has already been prepared, i.e.
    `protected Object` | `performJaxRpcCall(MethodInvocation invocation, Service service)` Deprecated. Perform a JAX-RPC dynamic call for the given AOP method invocation.
    `protected void` | `postProcessJaxRpcCall(Call call, MethodInvocation invocation)` Deprecated. Post-process the given JAX-RPC call.
    `protected void` | `postProcessPortStub(Stub stub)` Deprecated. Post-process the given JAX-RPC port stub.
    `void` | `prepare()` Deprecated. Create and initialize the JAX-RPC service for the specified port.
    `protected void` | `prepareJaxRpcCall(Call call)` Deprecated. Prepare the given JAX-RPC call, applying properties to it.
    `protected void` | `preparePortStub(Stub stub)` Deprecated. Prepare the given JAX-RPC port stub, applying properties to it.
    `protected void` | `reset()` Deprecated. Reset the prepared service of this interceptor, allowing for reinitialization on next access.
    `void` | `setCustomProperties(Properties customProperties)` Deprecated. Set custom properties to be set on the stub or call.
    `void` | `setCustomPropertyMap(Map<String,Object> customProperties)` Deprecated. Set custom properties to be set on the stub or call.
    `void` | `setEndpointAddress(String endpointAddress)` Deprecated. Set the endpoint address to specify on the stub or call.
    `void` | `setJaxRpcService(Service jaxRpcService)` Deprecated. Set a reference to an existing JAX-RPC Service instance, for example obtained via `JndiObjectFactoryBean`.
    `void` | `setLookupServiceOnStartup(boolean lookupServiceOnStartup)` Deprecated. Set whether to look up the JAX-RPC service on startup.
    `void` | `setMaintainSession(boolean maintainSession)` Deprecated. Set the maintain session flag to specify on the stub or call.
    `void` | `setPassword(String password)` Deprecated. Set the password to specify on the stub or call.
    `void` | `setPortInterface(Class portInterface)` Deprecated. Set the JAX-RPC port interface to use.
    `void` | `setPortName(String portName)` Deprecated. Set the name of the port.
    `void` | `setRefreshServiceAfterConnectFailure(boolean refreshServiceAfterConnectFailure)` Deprecated. Set whether to refresh the JAX-RPC service on connect failure, that is, whenever a JAX-RPC invocation throws a RemoteException.
    `void` | `setServiceInterface(Class serviceInterface)` Deprecated. Set the interface of the service that this factory should create a proxy for.
    `void` | `setUsername(String username)` Deprecated. Set the username to specify on the stub or call.

    - ### Methods inherited from class org.springframework.remoting.jaxrpc.LocalJaxRpcServiceFactory

      `createJaxRpcService, createService, createServiceFactory, getJaxRpcServiceInterface, getJaxRpcServiceProperties, getNamespaceUri, getQName, getServiceFactory, getServiceFactoryClass, getServiceName, getServicePostProcessors, getWsdlDocumentUrl, postProcessJaxRpcService, setJaxRpcServiceInterface, setJaxRpcServiceProperties, setNamespaceUri, setServiceFactory, setServiceFactoryClass, setServiceName, setServicePostProcessors, setWsdlDocumentUrl`

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

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

- - ### Constructor Detail

    - #### JaxRpcPortClientInterceptor

          public JaxRpcPortClientInterceptor()

      Deprecated.

  - ### Method Detail

    - #### setJaxRpcService

          public void setJaxRpcService(Service jaxRpcService)

      Deprecated.
      Set a reference to an existing JAX-RPC Service instance, for example obtained via `JndiObjectFactoryBean`. If not set, `LocalJaxRpcServiceFactory`'s properties have to be specified.
      See Also:
        `LocalJaxRpcServiceFactory.setServiceFactoryClass(java.lang.Class)`, `LocalJaxRpcServiceFactory.setWsdlDocumentUrl(java.net.URL)`, `LocalJaxRpcServiceFactory.setNamespaceUri(java.lang.String)`, `LocalJaxRpcServiceFactory.setServiceName(java.lang.String)`, `JndiObjectFactoryBean`

    - #### getJaxRpcService

          public Service getJaxRpcService()

      Deprecated.
      Return a reference to an existing JAX-RPC Service instance, if any.

    - #### setPortName

          public void setPortName(String portName)

      Deprecated.
      Set the name of the port. Corresponds to the "wsdl:port" name.

    - #### getPortName

          public String getPortName()

      Deprecated.
      Return the name of the port.

    - #### setUsername

          public void setUsername(String username)

      Deprecated.
      Set the username to specify on the stub or call.
      See Also:
        `Stub.USERNAME_PROPERTY`, `Call.USERNAME_PROPERTY`

    - #### getUsername

          public String getUsername()

      Deprecated.
      Return the username to specify on the stub or call.

    - #### setPassword

          public void setPassword(String password)

      Deprecated.
      Set the password to specify on the stub or call.
      See Also:
        `Stub.PASSWORD_PROPERTY`, `Call.PASSWORD_PROPERTY`

    - #### getPassword

          public String getPassword()

      Deprecated.
      Return the password to specify on the stub or call.

    - #### setEndpointAddress

          public void setEndpointAddress(String endpointAddress)

      Deprecated.
      Set the endpoint address to specify on the stub or call.
      See Also:
        `Stub.ENDPOINT_ADDRESS_PROPERTY`, `Call.setTargetEndpointAddress(java.lang.String)`

    - #### getEndpointAddress

          public String getEndpointAddress()

      Deprecated.
      Return the endpoint address to specify on the stub or call.

    - #### setMaintainSession

          public void setMaintainSession(boolean maintainSession)

      Deprecated.
      Set the maintain session flag to specify on the stub or call.
      See Also:
        `Stub.SESSION_MAINTAIN_PROPERTY`, `Call.SESSION_MAINTAIN_PROPERTY`

    - #### isMaintainSession

          public boolean isMaintainSession()

      Deprecated.
      Return the maintain session flag to specify on the stub or call.

    - #### setCustomProperties

          public void setCustomProperties(Properties customProperties)

      Deprecated.
      Set custom properties to be set on the stub or call.

      Can be populated with a String "value" (parsed via PropertiesEditor) or a "props" element in XML bean definitions.

      See Also:
        `Stub._setProperty(java.lang.String, java.lang.Object)`, `Call.setProperty(java.lang.String, java.lang.Object)`

    - #### setCustomPropertyMap

          public void setCustomPropertyMap(Map<String,Object> customProperties)

      Deprecated.
      Set custom properties to be set on the stub or call.

      Can be populated with a "map" or "props" element in XML bean definitions.

      See Also:
        `Stub._setProperty(java.lang.String, java.lang.Object)`, `Call.setProperty(java.lang.String, java.lang.Object)`

    - #### getCustomPropertyMap

          public Map<String,Object> getCustomPropertyMap()

      Deprecated.
      Allow Map access to the custom properties to be set on the stub or call, with the option to add or override specific entries.

      Useful for specifying entries directly, for example via "customPropertyMap[myKey]". This is particularly useful for adding or overriding entries in child bean definitions.

    - #### addCustomProperty

          public void addCustomProperty(String name,
                               Object value)

      Deprecated.
      Add a custom property to this JAX-RPC Stub/Call.
      Parameters:
        `name` - the name of the attribute to expose
        `value` - the attribute value to expose
      See Also:
        `Stub._setProperty(java.lang.String, java.lang.Object)`, `Call.setProperty(java.lang.String, java.lang.Object)`

    - #### setServiceInterface

          public void setServiceInterface(Class serviceInterface)

      Deprecated.
      Set the interface of the service that this factory should create a proxy for. This will typically be a non-RMI business interface, although you can also use an RMI port interface as recommended by JAX-RPC here.

      Calls on the specified service interface will either be translated to the underlying RMI port interface (in case of a "portInterface" being specified) or to dynamic calls (using the JAX-RPC Dynamic Invocation Interface).

      The dynamic call mechanism has the advantage that you don't need to maintain an RMI port interface in addition to an existing non-RMI business interface. In terms of configuration, specifying the business interface as "serviceInterface" will be enough; this interceptor will automatically use dynamic calls in such a scenario.

      See Also:
        `Service.createCall(javax.xml.namespace.QName)`, `setPortInterface(java.lang.Class)`

    - #### getServiceInterface

          public Class getServiceInterface()

      Deprecated.
      Return the interface of the service that this factory should create a proxy for.

    - #### setPortInterface

          public void setPortInterface(Class portInterface)

      Deprecated.
      Set the JAX-RPC port interface to use. Only needs to be set if a JAX-RPC port stub should be used instead of the dynamic call mechanism. See the javadoc of the "serviceInterface" property for more details.

      The interface must be suitable for a JAX-RPC port, that is, it must be an RMI service interface (that extends `java.rmi.Remote`).

      NOTE: Check whether your JAX-RPC provider returns thread-safe port stubs. If not, use the dynamic call mechanism instead, which will always be thread-safe. In particular, do not use JAX-RPC port stubs with Apache Axis, whose port stubs are known to be non-thread-safe.

      See Also:
        `Service.getPort(javax.xml.namespace.QName, java.lang.Class)`, `Remote`, `setServiceInterface(java.lang.Class)`

    - #### getPortInterface

          public Class getPortInterface()

      Deprecated.
      Return the JAX-RPC port interface to use.

    - #### setLookupServiceOnStartup

          public void setLookupServiceOnStartup(boolean lookupServiceOnStartup)

      Deprecated.
      Set whether to look up the JAX-RPC service on startup.

      Default is "true". Turn this flag off to allow for late start of the target server. In this case, the JAX-RPC service will be lazily fetched on first access.

    - #### setRefreshServiceAfterConnectFailure

          public void setRefreshServiceAfterConnectFailure(boolean refreshServiceAfterConnectFailure)

      Deprecated.
      Set whether to refresh the JAX-RPC service on connect failure, that is, whenever a JAX-RPC invocation throws a RemoteException.

      Default is "false", keeping a reference to the JAX-RPC service in any case, retrying the next invocation on the same service even in case of failure. Turn this flag on to reinitialize the entire service in case of connect failures.

    - #### afterPropertiesSet

          public void afterPropertiesSet()

      Deprecated.
      Prepares the JAX-RPC service and port if the "lookupServiceOnStartup" is turned on (which it is by default).
      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`

    - #### prepare

          public void prepare()
                       throws RemoteLookupFailureException

      Deprecated.
      Create and initialize the JAX-RPC service for the specified port.

      Prepares a JAX-RPC stub if possible (if an RMI interface is available); falls back to JAX-RPC dynamic calls else. Using dynamic calls can be enforced through overriding `alwaysUseJaxRpcCall()` to return `true`.

      `LocalJaxRpcServiceFactory.postProcessJaxRpcService(javax.xml.rpc.Service)` and `postProcessPortStub(javax.xml.rpc.Stub)` hooks are available for customization in subclasses. When using dynamic calls, each can be post-processed via `postProcessJaxRpcCall(javax.xml.rpc.Call, org.aopalliance.intercept.MethodInvocation)`.

      Throws:
        `RemoteLookupFailureException` - if service initialization or port stub creation failed

    - #### alwaysUseJaxRpcCall

          protected boolean alwaysUseJaxRpcCall()

      Deprecated.
      Return whether to always use JAX-RPC dynamic calls. Called by `afterPropertiesSet`.

      Default is "false"; if an RMI interface is specified as "portInterface" or "serviceInterface", it will be used to create a JAX-RPC port stub.

      Can be overridden to enforce the use of the JAX-RPC Call API, for example if there is a need to customize at the Call level. This just necessary if you you want to use an RMI interface as "serviceInterface", though; in case of only a non-RMI interface being available, this interceptor will fall back to the Call API anyway.

      See Also:
        `postProcessJaxRpcCall(javax.xml.rpc.Call, org.aopalliance.intercept.MethodInvocation)`

    - #### reset

          protected void reset()

      Deprecated.
      Reset the prepared service of this interceptor, allowing for reinitialization on next access.

    - #### isPrepared

          protected boolean isPrepared()

      Deprecated.
      Return whether this client interceptor has already been prepared, i.e. has already looked up the JAX-RPC service and port.

    - #### getPortQName

          protected final QName getPortQName()

      Deprecated.
      Return the prepared QName for the port.
      See Also:
        `setPortName(java.lang.String)`, `LocalJaxRpcServiceFactory.getQName(java.lang.String)`

    - #### preparePortStub

          protected void preparePortStub(Stub stub)

      Deprecated.
      Prepare the given JAX-RPC port stub, applying properties to it. Called by `prepare()`.

      Just applied when actually creating a JAX-RPC port stub, in case of a compliant port interface. Else, JAX-RPC dynamic calls will be used.

      Parameters:
        `stub` - the current JAX-RPC port stub
      See Also:
        `setUsername(java.lang.String)`, `setPassword(java.lang.String)`, `setEndpointAddress(java.lang.String)`, `setMaintainSession(boolean)`, `setCustomProperties(java.util.Properties)`, `setPortInterface(java.lang.Class)`, `prepareJaxRpcCall(javax.xml.rpc.Call)`

    - #### postProcessPortStub

          protected void postProcessPortStub(Stub stub)

      Deprecated.
      Post-process the given JAX-RPC port stub. Called by `prepare()`.

      The default implementation is empty.

      Just applied when actually creating a JAX-RPC port stub, in case of a compliant port interface. Else, JAX-RPC dynamic calls will be used.

      Parameters:
        `stub` - the current JAX-RPC port stub (can be cast to an implementation-specific class if necessary)
      See Also:
        `setPortInterface(java.lang.Class)`, `postProcessJaxRpcCall(javax.xml.rpc.Call, org.aopalliance.intercept.MethodInvocation)`

    - #### getPortStub

          protected Remote getPortStub()

      Deprecated.
      Return the underlying JAX-RPC port stub that this interceptor delegates to for each method invocation on the proxy.

    - #### invoke

          public Object invoke(MethodInvocation invocation)
                        throws Throwable

      Deprecated.
      Translates the method invocation into a JAX-RPC service invocation.

      Prepares the service on the fly, if necessary, in case of lazy lookup or a connect failure having happened.

      Specified by:
        `invoke` in interface `MethodInterceptor`
      Throws:
        `Throwable`
      See Also:
        `prepare()`, `doInvoke(org.aopalliance.intercept.MethodInvocation)`

    - #### doInvoke

          protected Object doInvoke(MethodInvocation invocation)
                             throws Throwable

      Deprecated.
      Perform a JAX-RPC service invocation based on the given method invocation.

      Uses traditional RMI stub invocation if a JAX-RPC port stub is available; falls back to JAX-RPC dynamic calls else.

      Parameters:
        `invocation` - the AOP method invocation
      Returns:
        the invocation result, if any
      Throws:
        `Throwable` - in case of invocation failure
      See Also:
        `getPortStub()`, `doInvoke(org.aopalliance.intercept.MethodInvocation, java.rmi.Remote)`, `performJaxRpcCall(org.aopalliance.intercept.MethodInvocation, javax.xml.rpc.Service)`

    - #### doInvoke

          protected Object doInvoke(MethodInvocation invocation,
                        Remote portStub)
                             throws Throwable

      Deprecated.
      Perform a JAX-RPC service invocation on the given port stub.
      Parameters:
        `invocation` - the AOP method invocation
        `portStub` - the RMI port stub to invoke
      Returns:
        the invocation result, if any
      Throws:
        `Throwable` - in case of invocation failure
      See Also:
        `getPortStub()`, `doInvoke(org.aopalliance.intercept.MethodInvocation, java.rmi.Remote)`, `performJaxRpcCall(org.aopalliance.intercept.MethodInvocation, javax.xml.rpc.Service)`

    - #### performJaxRpcCall

          protected Object performJaxRpcCall(MethodInvocation invocation,
                                 Service service)
                                      throws Throwable

      Deprecated.
      Perform a JAX-RPC dynamic call for the given AOP method invocation. Delegates to `prepareJaxRpcCall(javax.xml.rpc.Call)` and `postProcessJaxRpcCall(javax.xml.rpc.Call, org.aopalliance.intercept.MethodInvocation)` for setting up the call object.

      The default implementation uses method name as JAX-RPC operation name and method arguments as arguments for the JAX-RPC call. Can be overridden in subclasses for custom operation names and/or arguments.

      Parameters:
        `invocation` - the current AOP MethodInvocation that should be converted to a JAX-RPC call
        `service` - the JAX-RPC Service to use for the call
      Returns:
        the return value of the invocation, if any
      Throws:
        `Throwable` - the exception thrown by the invocation, if any
      See Also:
        `prepareJaxRpcCall(javax.xml.rpc.Call)`, `postProcessJaxRpcCall(javax.xml.rpc.Call, org.aopalliance.intercept.MethodInvocation)`

    - #### prepareJaxRpcCall

          protected void prepareJaxRpcCall(Call call)

      Deprecated.
      Prepare the given JAX-RPC call, applying properties to it. Called by `invoke(org.aopalliance.intercept.MethodInvocation)`.

      Just applied when actually using JAX-RPC dynamic calls, i.e. if no compliant port interface was specified. Else, a JAX-RPC port stub will be used.

      Parameters:
        `call` - the current JAX-RPC call object
      See Also:
        `setUsername(java.lang.String)`, `setPassword(java.lang.String)`, `setEndpointAddress(java.lang.String)`, `setMaintainSession(boolean)`, `setCustomProperties(java.util.Properties)`, `setPortInterface(java.lang.Class)`, `preparePortStub(javax.xml.rpc.Stub)`

    - #### postProcessJaxRpcCall

          protected void postProcessJaxRpcCall(Call call,
                                   MethodInvocation invocation)

      Deprecated.
      Post-process the given JAX-RPC call. Called by `invoke(org.aopalliance.intercept.MethodInvocation)`.

      The default implementation is empty.

      Just applied when actually using JAX-RPC dynamic calls, i.e. if no compliant port interface was specified. Else, a JAX-RPC port stub will be used.

      Parameters:
        `call` - the current JAX-RPC call object (can be cast to an implementation-specific class if necessary)
        `invocation` - the current AOP MethodInvocation that the call was created for (can be used to check method name, method parameters and/or passed-in arguments)
      See Also:
        `setPortInterface(java.lang.Class)`, `postProcessPortStub(javax.xml.rpc.Stub)`

    - #### handleRemoteException

          protected Throwable handleRemoteException(Method method,
                                        RemoteException ex)

      Deprecated.
      Handle the given RemoteException that was thrown from a JAX-RPC port stub or JAX-RPC call invocation.
      Parameters:
        `method` - the service interface method that we invoked
        `ex` - the original RemoteException
      Returns:
        the exception to rethrow (may be the original RemoteException or an extracted/wrapped exception, but never `null`)

    - #### isConnectFailure

          protected boolean isConnectFailure(RemoteException ex)

      Deprecated.
      Determine whether the given RMI exception indicates a connect failure.

      The default implementation returns `true` unless the exception class name (or exception superclass name) contains the term "Fault" (e.g. "AxisFault"), assuming that the JAX-RPC provider only throws RemoteException in case of WSDL faults and connect failures.

      Parameters:
        `ex` - the RMI exception to check
      Returns:
        whether the exception should be treated as connect failure
      See Also:
        `RmiClientInterceptorUtils.isConnectFailure(java.rmi.RemoteException)`