Most of unique features of Cluster4Spring remoting derived from implementation of client-side remoting functionality.
Components of proxy
Internally, the structure of the Cluster4Spring client side proxy is quite simple and is illustrated by diagram below:
Exactly as Spring proxy, Cluster4Spring remote proxy utilizes RemoteInvocationFactory for creating instances of RemoteInvocation. While it is not highlighted in Spring documentation, this is important part of remoting since custom instances (or customized instances) of RemoteInvocation class may be created if proper RemoteInvocationFactory is specified (if one is not explicitly specified during configuration of remote proxy, default one will be created automatically). With this mechanism it is possible to pass some additional information to server transparently for caller code with every (or particular, depending on implementation) remote call. For example, it is possible to pass information about security credentials, some session data associated with particular user etc.
Cluster4Spring client proxy utilizes notion that is absent in standard Spring remoting - Endpoint. Endpoint represents wrapper over actual remoting protocol. For example, for RMI based remoting there is appropriate implementation of Endpoint which holds reference to Remote object and is responsible for invoking remote service either via InvocationHandler (if Spring based remoting is used on server-side) or via ordinary RMI stub.
Accordingly, EndpointFactory is responsible for locating remote service by known location (like using Naming.lookup() method for RMI based remoting) and for creation of endpoints. Finally, there is another very important component of client Cluster4Spring proxy - EndpointProvider. EndpointProvider represents policy that defines which remoting scheme is used. While overall functionality of client proxy does not relate to remoting scheme, EndpointProvider knows where (and now) to find remote service and provides Endpoint that corresponds to particular remote service location for actual method invocation.
Remote call execution
The following diagram (very simplified) illustrates steps that are performed within client proxy during processing remote call:
As soon as caller code of application initiates remote call, RemoteProxy requests Endpoint from EndpointProvider (step 3). As soon as Endpoint is obtained, proxy delegates method invocation to it (step 4). Endpoint performs necessary actions to perform remote call according to currently used remote protocol (step 5). As soon as remote service finished execution of call, results are sent back to client and to then to application code.
The nature of remoting assumes that in real life various unexpected situations can occur. For example, network connection may be broken; server may become inaccessible or shut down unexpectedly and so on.
While "normal" application exceptions, which are thrown by server-side code, are leaved untouched by Cluster4Spring logic and passed back to caller code of client application, the remoting related ones are internally captured by Cluster4Spring logic and processing (defined by appropriate settings) is performed by Cluster4Spring code.
The additional processing of network related issues is performed to increase stability of distributed application and provide additional recovering mechanisms (for example, try to re-locate remote service and call it again or select another instance of remote service and redirect remote call to it).
The following diagram illustrates simplified scheme of handling networking related exceptions that can occur during remote call execution performed by Cluster4Spring core:
We can see on the diagram that, if some networking related exception occurred during performing remote call, that exception is caught within RemoteProxy and EndpointProvider is informed that Endpoint used to perform remote call is invalid (step 6). It is assumed that endpoints that were marked as invalid ones will not be returned by EndpointProvider during all subsequent requests for endpoints.
Further behavior (not shown on this diagram for simplicity's sake) depends on configuration of remote proxy.
At the moment, there are two options (specified by appropriate properties in the corresponding proxy class) which specify the actions that should be performed later.
These properties are:
If both these options are set to true, the refreshEndpointsOnConnectFailure option has higher priority in current implementation of Cluster4Spring. If both of these options are set to false, the original remoting exception will be passed to caller code.
It is possible to implement various schemes of resolving remote service. Two options control this:
By default, endpoints are not cached and are refreshed on startup.
Selecting instance of remote service for invocation
If there are several instances of remote service available, during performing remote call it is necessary to define which one should be used. Such an issue occurs if one of one-to-many remoting schemes is used.
It is possible to implement various schemes of invocations there using appropriate policy. Corresponding EndpointProvider that supports one-to-many remoting scheme does not perform actual selection of endpoint for invocation. Instead, it delegates selection of endpoint for invocation to the appropriate policy (one implemented via EndpointSelectionPolicy interface).
The following diagram illustrates the process of performing remote call for one-to-many remoting scheme:
The actual implementation class of policy must be used to select endpoints, which can be provided during configuration of remote proxy.
Cluster4Spring has three built-in implementations of EndpointSelectionPolicy (and obviously, it is possible to use custom ones):
This section of document includes various small features that can be configured on client side of Cluster4Spring remoting.
For futher details about configuration of client part of Cluster4Spring remoting, please refer Examples of Configuration.