org.xins.common.http
Class HTTPServiceCaller

java.lang.Object
  org.xins.common.service.ServiceCaller
      org.xins.common.http.HTTPServiceCaller

public final class HTTPServiceCaller

extends ServiceCaller

HTTP service caller. This class can be used to perform a call to an HTTP server and fail-over to other HTTP servers 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 is expected to be supported as well.

Load-balancing and fail-over

There are 2 ways to perform an HTTP call using a HTTPServiceCaller instance:

• to a single HTTP service, using call(HTTPCallRequest,TargetDescriptor);
• to a set of one or more HTTP services, using call(HTTPCallRequest);

With the second form of a HTTP call, fail-over and load-balancing can be performed.

How load-balancing is done (in the second form) depends on the Descriptor passed to the HTTPServiceCaller(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 HTTPServiceCaller 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 active HTTPCallConfig;
• if the connection cannot be established (e.g. due to connection refusal, a DNS error, connection time-out, etc.)
• if an HTTP status code other than 200-299 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 an HTTPServiceCaller instance:

// Initialize properties for the services. Normally these
// properties would come from a configuration source, like a file.
BasicPropertyReader properties = new 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 an HTTPServiceCaller instance
Descriptor descriptor = DescriptorBuilder.build(properties, "myapi");
HTTPServiceCaller caller = new HTTPServiceCaller(descriptor);

Then the following code snippet uses this HTTPServiceCaller to perform an HTTP GET call:

BasicPropertyReader params = new BasicPropertyReader();
params.set("street",      "Broadband Avenue");
params.set("houseNumber", "12");

HTTPCallRequest request = new HTTPCallRequest(HTTPMethod.GET, params);
HTTPCallResult result = caller.call(request);

Since:

XINS 1.0.0

Version:

$Revision: 1.99.2.1 $ $Date: 2007/03/22 15:19:41 $

Author:

Ernst de Haan, Anthony Goubard

Constructor Summary

HTTPServiceCaller(Descriptor descriptor)
Constructs a new HTTPServiceCaller object.

HTTPServiceCaller(Descriptor descriptor, HTTPCallConfig callConfig)
Constructs a new HTTPServiceCaller object with the specified descriptor and call configuration.

Method Summary

HTTPCallResult	call(HTTPCallRequest request) Performs the specified request towards the HTTP service.
HTTPCallResult	call(HTTPCallRequest request, HTTPCallConfig callConfig) Performs the specified request towards the HTTP service.
HTTPCallResult	call(HTTPCallRequest request, HTTPCallConfig callConfig, TargetDescriptor target) Deprecated. Deprecated since XINS 1.1.0, since this method is expected to be removed. Please do not use it directly.
HTTPCallResult	call(HTTPCallRequest request, TargetDescriptor target) Deprecated. Deprecated since XINS 1.0.0, since this method is expected to be removed. Please do not use it directly.
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 a request towards the specified target.
protected CallConfig	getDefaultCallConfig() Returns a default CallConfig object.
HTTPCallConfig	getHTTPCallConfig() Returns the HTTPCallConfig associated with this service caller.
protected boolean	isProtocolSupportedImpl(String protocol) Checks if the specified protocol is supported (implementation method).
protected void	setHTTPCallConfig(HTTPCallConfig config) Sets the HTTPCallConfig associated with this HTTP 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, setDescriptor, testTargetDescriptor

Methods inherited from class java.lang.Object

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

Constructor Detail

HTTPServiceCaller

public HTTPServiceCaller(Descriptor descriptor,
                         HTTPCallConfig callConfig)
                  throws IllegalArgumentException,
                         UnsupportedProtocolException

Constructs a new HTTPServiceCaller object with the specified descriptor and call configuration.

Parameters:

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

callConfig - the call configuration, or null if a default one should be used.

Throws:

IllegalArgumentException - if descriptor == null.

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

Since:

XINS 1.1.0

HTTPServiceCaller

public HTTPServiceCaller(Descriptor descriptor)
                  throws IllegalArgumentException,
                         UnsupportedProtocolException

Constructs a new HTTPServiceCaller object.

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

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

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 HTTPServiceCaller returns a standard HTTPCallConfig object which has unconditional fail-over disabled and the HTTP method set to POST.

Specified by:

getDefaultCallConfig in class ServiceCaller

Returns:

a new HTTPCallConfig instance, never null.

setHTTPCallConfig

protected void setHTTPCallConfig(HTTPCallConfig config)
                          throws IllegalArgumentException

Sets the HTTPCallConfig associated with this HTTP service caller.

Parameters:

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

Throws:

IllegalArgumentException - if config == null.

Since:

XINS 1.2.0

getHTTPCallConfig

public HTTPCallConfig getHTTPCallConfig()

Returns the HTTPCallConfig associated with this service caller.

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

Returns:

the fall-back HTTPCallConfig object for this HTTP service caller, never null.

Since:

XINS 1.2.0

doCallImpl

public Object doCallImpl(CallRequest request,
                         CallConfig callConfig,
                         TargetDescriptor target)
                  throws ClassCastException,
                         IllegalArgumentException,
                         CallException

Executes a request towards the specified target. If the call succeeds, then a HTTPCallResult object is returned, otherwise a CallException is thrown.

The implementation of this method in class HTTPServiceCaller delegates to call(HTTPCallRequest,TargetDescriptor).

Specified by:

doCallImpl in class ServiceCaller

Parameters:

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

callConfig - the call configuration, never null and should always be an instance of class HTTPCallConfig.

target - the target to call, cannot be null.

Returns:

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

Throws:

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

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

CallException - if the call to the specified target failed.

Since:

XINS 1.1.0

call

public HTTPCallResult call(HTTPCallRequest request,
                           HTTPCallConfig callConfig)
                    throws IllegalArgumentException,
                           GenericCallException,
                           HTTPCallException

Performs the specified request towards the HTTP service. If the call succeeds with one of the targets, then a HTTPCallResult object is returned, that combines the HTTP status code and the data returned. Otherwise, if none of the targets could successfully be called, a CallException is thrown.

Parameters:

request - the call request, not null.

callConfig - the call configuration to use, or 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.

Since:

XINS 1.1.0

call

public HTTPCallResult call(HTTPCallRequest request)
                    throws IllegalArgumentException,
                           GenericCallException,
                           HTTPCallException

Performs the specified request towards the HTTP service. If the call succeeds with one of the targets, then a HTTPCallResult object is returned, that combines the HTTP status code and the data returned. Otherwise, if none of the targets could successfully be called, a CallException is thrown.

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.

call

public HTTPCallResult call(HTTPCallRequest request,
                           HTTPCallConfig callConfig,
                           TargetDescriptor target)
                    throws IllegalArgumentException,
                           GenericCallException,
                           HTTPCallException

Deprecated. Deprecated since XINS 1.1.0, since this method is expected to be removed. Please do not use it directly.

Executes the specified HTTP call request on the specified target with the specified call configuration. If the call fails in any way, then a CallException is thrown.

Parameters:

request - the call request to execute, cannot be null.

callConfig - the (optional) call configuration, or null if it should be determined at a lower level.

target - the service target on which to execute the request, cannot be null.

Returns:

the call result, never null.

Throws:

IllegalArgumentException - if target == null || 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.

Since:

XINS 1.1.0

call

public HTTPCallResult call(HTTPCallRequest request,
                           TargetDescriptor target)
                    throws IllegalArgumentException,
                           GenericCallException,
                           HTTPCallException

Deprecated. Deprecated since XINS 1.0.0, since this method is expected to be removed. Please do not use it directly.

Executes the specified HTTP call request on the specified target. If the call fails in any way, then a CallException is thrown.

Parameters:

request - the call request to execute, cannot be null.

target - the service target on which to execute the request, cannot be null.

Returns:

the call result, never null.

Throws:

IllegalArgumentException - if target == null || 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.

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 HTTPServiceCaller expects an HTTPCallRequest and returns an HTTPCallResult.

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 HTTPCallRequest.

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 HTTPCallResult, never null; .

Returns:

an HTTPCallResult 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. This method should only be called from ServiceCaller.doCall(CallRequest,CallConfig).

The implementation of this method in class HTTPServiceCaller returns true if and only if one of the following conditions holds true:

• super.shouldFailOver(request, callConfig, exceptions)
• exceptions.last() instanceof StatusCodeHTTPCallException and for that exception getStatusCode() is not in the range 200-299.

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; get the most recent one by calling exceptions.last().

Returns:

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