org.xins.client
Class XINSServiceCaller

java.lang.Object
  org.xins.common.service.ServiceCaller
      org.xins.client.XINSServiceCaller

public final class XINSServiceCaller

extends ServiceCaller

XINS service caller. This class can be used to perform a call to a XINS service, over HTTP, and fail-over to other XINS services if the first one fails.

Supported protocols

This service caller currently only supports the HTTP protocol. If a TargetDescriptor is passed to the constructor with a different protocol, then an UnsupportedProtocolException is thrown. In the future, HTTPS and other protocols are expected to be supported as well.

Load-balancing and fail-over

To perform a XINS call, use call(XINSCallRequest). Fail-over and load-balancing can be performed automatically.

How load-balancing is done depends on the Descriptor passed to the XINSServiceCaller(Descriptor) constructor. If it is a TargetDescriptor, then only this single target service is called and no load-balancing is performed. If it is a GroupDescriptor, then the configuration of the GroupDescriptor determines how the load-balancing is done. A GroupDescriptor is a recursive data structure, which allows for fairly advanced load-balancing algorithms.

If a call attempt fails and there are more available target services, then the XINSServiceCaller may or may not fail-over to a next target. If the request was not accepted by the target service, then fail-over is considered acceptable and will be performed. This includes the following situations:

• if the failOverAllowed property is set to true for the XINSCallRequest;
• on connection refusal;
• if a connection attempt times out;
• if an HTTP status code other than 200-299 is returned;
• if the XINS error code _InvalidRequest is returned;
• if the XINS error code _DisabledFunction is returned.

If none of these conditions holds, then fail-over is not considered acceptable and will not be performed.

Example code

The following example code snippet constructs a XINSServiceCaller instance:

// Initialize properties for the services. Normally these
// properties would come from a configuration source, like a file.
BasicPropertyReader properties = new org.xins.common.collections.BasicPropertyReader();
properties.set("myapi",         "group, random, server1, server2");
properties.set("myapi.server1", "service, http://server1/myapi, 10000");
properties.set("myapi.server2", "service, http://server2/myapi, 12000");

// Construct a descriptor and a XINSServiceCaller instance
Descriptor descriptor = DescriptorBuilder.build(properties, "myapi");
XINSServiceCaller caller = new XINSServiceCaller(descriptor);

Then the following code snippet uses this XINSServiceCaller to perform a call to a XINS function named _GetStatistics, using HTTP POST:

// Prepare for the call
String          function = "_GetStatistics";
PropertyReader  params   = null;
boolean         failOver = true;
HTTPMethod      method   = HTTPMethod.POST;
XINSCallRequest request  = new XINSCallRequest(function, params, failOver, method);

// Perform the call
XINSCallResult result = caller.call(request);

Since:

XINS 1.0.0

Version:

$Revision: 1.160 $ $Date: 2006/10/24 08:55:19 $

Author:

Ernst de Haan

Constructor Summary

XINSServiceCaller()
Constructs a new XINSServiceCaller with the specified descriptor and the default HTTP method.

XINSServiceCaller(Descriptor descriptor)
Constructs a new XINSServiceCaller with the specified descriptor and the default HTTP method.

XINSServiceCaller(Descriptor descriptor, XINSCallConfig callConfig)
Constructs a new XINSServiceCaller with the specified descriptor and call configuration.

Method Summary

XINSCallResult	call(XINSCallRequest request) Executes the specified XINS call request towards one of the associated targets.
XINSCallResult	call(XINSCallRequest request, XINSCallConfig callConfig) Executes the specified XINS call request towards one of the associated targets.
protected CallResult	createCallResult(CallRequest request, TargetDescriptor succeededTarget, long duration, CallExceptionList exceptions, Object result) Constructs an appropriate CallResult object for a successful call attempt.
Object	doCallImpl(CallRequest request, CallConfig callConfig, TargetDescriptor target) Executes the specified request on the given target.
protected CallConfig	getDefaultCallConfig() Returns a default CallConfig object.
XINSCallConfig	getXINSCallConfig() Returns the XINSCallConfig associated with this service caller.
protected boolean	isProtocolSupportedImpl(String protocol) Checks if the specified protocol is supported (implementation method).
void	setDescriptor(Descriptor descriptor) Sets the descriptor.
protected void	setXINSCallConfig(XINSCallConfig config) Sets the XINSCallConfig associated with this XINS service caller.
protected boolean	shouldFailOver(CallRequest request, CallConfig callConfig, CallExceptionList exceptions) Determines whether a call should fail-over to the next selected target based on a request, call configuration and exception list.

Methods inherited from class org.xins.common.service.ServiceCaller

controlTimeOut, doCall, getCallConfig, getDescriptor, isProtocolSupported, setCallConfig, testTargetDescriptor

Methods inherited from class java.lang.Object

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

Constructor Detail

XINSServiceCaller

public XINSServiceCaller(Descriptor descriptor,
                         XINSCallConfig callConfig)
                  throws IllegalArgumentException,
                         UnsupportedProtocolException

Constructs a new XINSServiceCaller with the specified descriptor and call configuration.

Parameters:

descriptor - the descriptor of the service, cannot be null.

callConfig - the call configuration object for this service caller, or null if a default one should be associated with this service caller.

Throws:

IllegalArgumentException - if descriptor == null.

UnsupportedProtocolException - if descriptor is or contains a TargetDescriptor with an unsupported protocol.

Since:

XINS 1.1.0

XINSServiceCaller

public XINSServiceCaller(Descriptor descriptor)
                  throws IllegalArgumentException,
                         UnsupportedProtocolException

Constructs a new XINSServiceCaller with the specified descriptor and the default HTTP method.

Parameters:

descriptor - the descriptor of the service, cannot be null.

Throws:

IllegalArgumentException - if descriptor == null.

UnsupportedProtocolException - if descriptor is or contains a TargetDescriptor with an unsupported protocol (since XINS 1.1.0).

XINSServiceCaller

public XINSServiceCaller()

Constructs a new XINSServiceCaller with the specified descriptor and the default HTTP method.

Since:

XINS 1.2.0

Method Detail

isProtocolSupportedImpl

protected boolean isProtocolSupportedImpl(String protocol)

Checks if the specified protocol is supported (implementation method). The protocol is the part in a URL before the string "://").

This method should only ever be called from the ServiceCaller.isProtocolSupported(String) method.

The implementation of this method in class ServiceCaller throws an UnsupportedOperationException.

Overrides:

isProtocolSupportedImpl in class ServiceCaller

Parameters:

protocol - the protocol, guaranteed not to be null.

Returns:

true if the specified protocol is supported, or false if it is not.

Since:

XINS 1.2.0

setDescriptor

public void setDescriptor(Descriptor descriptor)

Description copied from class: ServiceCaller

Sets the descriptor.

Overrides:

setDescriptor in class ServiceCaller

Parameters:

descriptor - the descriptor for this service, or null.

getDefaultCallConfig

protected CallConfig getDefaultCallConfig()

Returns a default CallConfig object. This method is called by the ServiceCaller constructor if no CallConfig object was given.

The implementation of this method in class XINSServiceCaller returns a standard XINSCallConfig object which has unconditional fail-over disabled and the HTTP method set to POST.

Specified by:

getDefaultCallConfig in class ServiceCaller

Returns:

a new XINSCallConfig instance with default settings, never null.

setXINSCallConfig

protected final void setXINSCallConfig(XINSCallConfig config)
                                throws IllegalArgumentException

Sets the XINSCallConfig associated with this XINS service caller.

Parameters:

config - the fall-back XINSCallConfig object for this service caller, cannot be null.

Throws:

IllegalArgumentException - if config == null.

Since:

XINS 1.2.0

getXINSCallConfig

public final XINSCallConfig getXINSCallConfig()

Returns the XINSCallConfig associated with this service caller.

This method is the type-safe equivalent of ServiceCaller.getCallConfig().

Returns:

the fall-back XINSCallConfig object for this XINS service caller, never null.

Since:

XINS 1.2.0

call

public XINSCallResult call(XINSCallRequest request,
                           XINSCallConfig callConfig)
                    throws IllegalArgumentException,
                           GenericCallException,
                           HTTPCallException,
                           XINSCallException

Executes the specified XINS call request towards one of the associated targets. If the call succeeds with one of these targets, then a XINSCallResult object is returned. Otherwise, if none of the targets could successfully be called, a CallException is thrown.

If the call succeeds, but the result is unsuccessful, then an UnsuccessfulXINSCallException is thrown, which contains the result.

Parameters:

request - the call request, not null.

callConfig - the call configuration, or null if the one specified in the request should be used, or -if the request does not specify any either- the one specified for this service caller.

Returns:

the result of the call, cannot be null.

Throws:

IllegalArgumentException - if request == null.

GenericCallException - if the first call attempt failed due to a generic reason and all the other call attempts failed as well.

HTTPCallException - if the first call attempt failed due to an HTTP-related reason and all the other call attempts failed as well.

XINSCallException - if the first call attempt failed due to a XINS-related reason and all the other call attempts failed as well.

Since:

XINS 1.1.0

call

public XINSCallResult call(XINSCallRequest request)
                    throws IllegalArgumentException,
                           GenericCallException,
                           HTTPCallException,
                           XINSCallException

Executes the specified XINS call request towards one of the associated targets. If the call succeeds with one of these targets, then a XINSCallResult object is returned. Otherwise, if none of the targets could successfully be called, a CallException is thrown.

If the call succeeds, but the result is unsuccessful, then an UnsuccessfulXINSCallException is thrown, which contains the result.

Parameters:

request - the call request, not null.

Returns:

the result of the call, cannot be null.

Throws:

IllegalArgumentException - if request == null.

GenericCallException - if the first call attempt failed due to a generic reason and all the other call attempts failed as well.

HTTPCallException - if the first call attempt failed due to an HTTP-related reason and all the other call attempts failed as well.

XINSCallException - if the first call attempt failed due to a XINS-related reason and all the other call attempts failed as well.

doCallImpl

public Object doCallImpl(CallRequest request,
                         CallConfig callConfig,
                         TargetDescriptor target)
                  throws IllegalArgumentException,
                         ClassCastException,
                         GenericCallException,
                         HTTPCallException,
                         XINSCallException

Executes the specified request on the given target. If the call succeeds, then a XINSCallResult object is returned, otherwise a CallException is thrown.

Specified by:

doCallImpl in class ServiceCaller

Parameters:

target - the target to call, cannot be null.

callConfig - the call configuration, never null.

request - the call request to be executed, must be an instance of class XINSCallRequest, cannot be null.

Returns:

the result, if and only if the call succeeded, always an instance of class XINSCallResult, never null.

Throws:

IllegalArgumentException - if request == null || callConfig == null || target == null.

ClassCastException - if the specified request object is not null and not an instance of class XINSCallRequest.

GenericCallException - if the call attempt failed due to a generic reason. other call attempts failed as well.

HTTPCallException - if the call attempt failed due to an HTTP-related reason.

XINSCallException - if the call attempt failed due to a XINS-related reason.

createCallResult

protected CallResult createCallResult(CallRequest request,
                                      TargetDescriptor succeededTarget,
                                      long duration,
                                      CallExceptionList exceptions,
                                      Object result)
                               throws ClassCastException

Constructs an appropriate CallResult object for a successful call attempt. This method is called from ServiceCaller.doCall(CallRequest,CallConfig).

The implementation of this method in class XINSServiceCaller expects an XINSCallRequest and returns an XINSCallResult.

Specified by:

createCallResult in class ServiceCaller

Parameters:

request - the CallRequest that was to be executed, never null when called from ServiceCaller.doCall(CallRequest,CallConfig); should be an instance of class XINSCallRequest.

succeededTarget - the TargetDescriptor for the service that was successfully called, never null when called from ServiceCaller.doCall(CallRequest,CallConfig).

duration - the call duration in milliseconds, must be a non-negative number.

exceptions - the list of CallException instances, or null if there were no call failures.

result - the result from the call, which is the object returned by doCallImpl(CallRequest,CallConfig,TargetDescriptor), always an instance of class XINSCallResult, never null; .

Returns:

a XINSCallResult instance, never null.

Throws:

ClassCastException - if either request or result is not of the correct class.

shouldFailOver

protected boolean shouldFailOver(CallRequest request,
                                 CallConfig callConfig,
                                 CallExceptionList exceptions)

Determines whether a call should fail-over to the next selected target based on a request, call configuration and exception list.

Overrides:

shouldFailOver in class ServiceCaller

Parameters:

request - the request for the call, as passed to ServiceCaller.doCall(CallRequest,CallConfig), should not be null.

callConfig - the call config that is currently in use, never null.

exceptions - the current list of CallExceptions; never null.

Returns:

true if the call should fail-over to the next target, or false if it should not.