public class HTTPServiceCaller extends ServiceCaller
This service caller supports both HTTP and HTTPS (which is HTTP
tunneled over a secure SSL connection). If a TargetDescriptor
is
passed to the constructor with a protocol other than "http"
or "https"
, then an UnsupportedProtocolException
is
thrown.
To perform an HTTP call using a
HTTPServiceCaller
use call(HTTPCallRequest)
.
How load-balancing is done depends on the Descriptor
passed to
the HTTPServiceCaller(Descriptor)
constructor:
TargetDescriptor
, then only this single target
service is called and no load-balancing is performed;
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.
Instances of this class can safely be used from multiple threads at the same time.
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.Map
properties = newHashMap
(); properties.put
("myapi", "group, random, server1, server2"); properties.put
("myapi.server1", "service, http://server1/myapi, 10000"); properties.put
("myapi.server2", "service, http://server2/myapi, 12000"); // Construct a descriptor and an HTTPServiceCaller instanceDescriptor
descriptor =DescriptorBuilder
.build
(properties, "myapi"); HTTPServiceCaller caller = newHTTPServiceCaller
(descriptor);
Then the following code snippet uses this HTTPServiceCaller
to perform an HTTP GET call:
Map
params = newHashMap
(); params.put
("street", "Broadband Avenue"); params.put
("houseNumber", "12");HTTPCallRequest
request = newHTTPCallRequest
(HTTPMethod
.GET
, params);HTTPCallResult
result = caller.call
(request);
Constructor and Description |
---|
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. |
Modifier and Type | Method and Description |
---|---|
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,
List<CallException> 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,
List<CallException> exceptions)
Determines whether a call should fail-over to the next selected target
based on a request, call configuration and exception list.
|
controlTimeOut, doCall, getCallConfig, getDescriptor, isProtocolSupported, setCallConfig, setDescriptor, testTargetDescriptor
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).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
HTTPServiceCaller
throws an
UnsupportedOperationException
unless the protocol equals either
"http"
or "https
(ignoring case)..
isProtocolSupportedImpl
in class ServiceCaller
protocol
- 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 ServiceCaller
HTTPCallConfig
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 ServiceCaller
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
.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, List<CallException> 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 ServiceCaller
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
; .HTTPCallResult
instance, never null
.ClassCastException
- if either request
or result
is not of the
correct class.protected boolean shouldFailOver(CallRequest request, CallConfig callConfig, List<CallException> 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 ServiceCaller
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 CallException
s; 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.See http://www.xins.org/.