|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Objectorg.xins.common.service.ServiceCaller
org.xins.common.http.HTTPServiceCaller
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.
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.
To perform an HTTP call using a
HTTPServiceCaller use call(HTTPCallRequest).
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:
true
for the active HTTPCallConfig;
If none of these conditions holds, then fail-over is not considered acceptable and will not be performed.
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.BasicPropertyReaderproperties = newBasicPropertyReader(); 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 instanceDescriptordescriptor =DescriptorBuilder.build(properties, "myapi"); HTTPServiceCaller caller = newHTTPServiceCaller(descriptor);
Then the following code snippet uses this HTTPServiceCaller
to perform an HTTP GET call:
BasicPropertyReaderparams = newBasicPropertyReader(); params.set("street", "Broadband Avenue"); params.set("houseNumber", "12");HTTPCallRequestrequest = newHTTPCallRequest(HTTPMethod.GET, params);HTTPCallResultresult = caller.call(request);
| 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. |
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 |
public HTTPServiceCaller(Descriptor descriptor,
HTTPCallConfig callConfig)
throws IllegalArgumentException,
UnsupportedProtocolException
HTTPServiceCaller object with the
specified descriptor and call configuration.
descriptor - the descriptor of the service, cannot be null.callConfig - the call configuration, or null if a default one should
be used.
IllegalArgumentException - if descriptor == null.
UnsupportedProtocolException - if descriptor is or contains a TargetDescriptor
with an unsupported protocol.
public HTTPServiceCaller(Descriptor descriptor)
throws IllegalArgumentException,
UnsupportedProtocolException
HTTPServiceCaller object.
descriptor - the descriptor of the service, cannot be null.
IllegalArgumentException - if descriptor == null.
UnsupportedProtocolException - if descriptor is or contains a TargetDescriptor
with an unsupported protocol (since XINS 1.1.0).| Method Detail |
protected boolean isProtocolSupportedImpl(String protocol)
"://").
This method should only ever be called from the
ServiceCaller.isProtocolSupported(String) method.
The implementation of this method in class ServiceCaller
throws an UnsupportedOperationException.
isProtocolSupportedImpl in class ServiceCallerprotocol - the protocol, guaranteed not to be null.
true if the specified protocol is supported, or
false if it is not.protected CallConfig getDefaultCallConfig()
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.
getDefaultCallConfig in class ServiceCallerHTTPCallConfig instance, never null.
protected void setHTTPCallConfig(HTTPCallConfig config)
throws IllegalArgumentException
HTTPCallConfig associated with this HTTP service
caller.
config - the fall-back HTTPCallConfig object for this service caller,
cannot be null.
IllegalArgumentException - if config == null.public HTTPCallConfig getHTTPCallConfig()
HTTPCallConfig associated with this service
caller.
This method is the type-safe equivalent of ServiceCaller.getCallConfig().
HTTPCallConfig object for this HTTP service
caller, never null.
public Object doCallImpl(CallRequest request,
CallConfig callConfig,
TargetDescriptor target)
throws ClassCastException,
IllegalArgumentException,
CallException
HTTPCallResult object is returned, otherwise a
CallException is thrown.
doCallImpl in class ServiceCallerrequest - 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.
HTTPCallResult, never null.
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.
public HTTPCallResult call(HTTPCallRequest request,
HTTPCallConfig callConfig)
throws IllegalArgumentException,
GenericCallException,
HTTPCallException
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.
request - the call request, not null.callConfig - the call configuration to use, or null.
null.
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.
public HTTPCallResult call(HTTPCallRequest request)
throws IllegalArgumentException,
GenericCallException,
HTTPCallException
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.
request - the call request, not null.
null.
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.
protected CallResult createCallResult(CallRequest request,
TargetDescriptor succeededTarget,
long duration,
CallExceptionList exceptions,
Object result)
throws ClassCastException
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.
createCallResult in class ServiceCallerrequest - 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; .
HTTPCallResult instance, never null.
ClassCastException - if either request or result is not of the
correct class.
protected boolean shouldFailOver(CallRequest request,
CallConfig callConfig,
CallExceptionList exceptions)
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.
shouldFailOver in class ServiceCallerrequest - 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().
true if the call should fail-over to the next target, or
false if it should not.
|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||