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.

Handling errors

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:

• refreshEndpointsOnConnectFailure- if set to true, RemoteProxy will force EndpointProvider to refresh all endpoints (by re-locating them) and will try to perform remote method invocation again;
• switchEndpointOnFailure - if set to true, RemoteProxy will ask EndpointProvider for another Endpoint available and will try to perform remote call using obtained endpoint. This process will be repeated (if other exceptions occur) until some non-invalid Endpoint exists;

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.

Caching endpoints

It is possible to implement various schemes of resolving remote service. Two options control this:

• refreshEndpointsOnStartup (on RemoteProxy) - if set to true, during initialization of proxy the corresponding EndpointProvider will be requested to locate all available endpoints. Such scheme requires that at least one instance of remote service should be available during client application start. If this option is set to false, EndpointProvider will perform actual lookup of remote services during first invocation of the remote method of remote service;
• cacheEndpoints (on EndpointProvider) - if set to true, EndpointProvider will cache located endpoints for remote service and will use them during subsequent invocation. If option is set to false, EndpointProvider will perform lookup of endpoints on every call of any method of remote service;

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

• DefaultEndpointSelectionPolicy - returns first valid endpoint from available endpoints list. If such policy is used, all remote calls will be performed to the same instance of remote service (shortly, to one server) until it is available;
• ShuffleEndpointSelectionPolicy - shuffles content of available endpoints list and returns the first endpoint from the list. If such policy is used, each remote call will be potentially executed with different endpoints thus making workload of servers more uniform;
• LastAccessTimeEndpointSelectionPolicy - selects endpoint for invocation that was not accessed for longest period of time. Such a policy also pays a way for sharing the workload among servers on a uniform basis.

Miscellaneous

This section of document includes various small features that can be configured on client side of Cluster4Spring remoting.

• It is possible to customize all internals of client proxy - RemoteInvocationFactory, EndpointProvider, EndpointFactory, EndpointSelectionPolicy using appropriate properties available on proxy;
• It is possible to state that trace interceptor should be used as well as specify implementation of such interceptor. Trace interceptor can be used to trace (or profile or what ever you want) all remote calls which are performed by the particular proxy;
• It is possible to specify list of interceptor names which will be applied to remote calls invocation which are performed by proxy;
• There are two possible ways to configure client proxy for remote service using Spring configuration. In general, these ways are functionally identical, but require more or less verbose declaration markup in XML configuration. Please refer to examples for Cluster4Spring remoting configuration to find more about possible configuration options.

For futher details about configuration of client part of Cluster4Spring remoting, please refer Examples of Configuration.