public class XINSServiceCaller extends ServiceCaller
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.
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:
true
for the XINSCallRequest
;
If none of these conditions holds, then fail-over is not considered acceptable and will not be performed.
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.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 a XINSServiceCaller instanceDescriptor
descriptor =DescriptorBuilder
.build
(properties, "myapi"); XINSServiceCaller caller = newXINSServiceCaller
(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 callString
function = "_GetStatistics";Map
params = null; boolean failOver = true;HTTPMethod
method =HTTPMethod
.POST
;XINSCallRequest
request = newXINSCallRequest
(function, params, failOver, method); // Perform the callXINSCallResult
result = caller.call
(request);
Constructor and Description |
---|
XINSServiceCaller()
Constructs a new
XINSServiceCaller with no
descriptor (yet) 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. |
Modifier and Type | Method and Description |
---|---|
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,
List<CallException> 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,
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, testTargetDescriptor
public XINSServiceCaller(Descriptor descriptor, XINSCallConfig callConfig) throws IllegalArgumentException, UnsupportedProtocolException
XINSServiceCaller
with the specified
descriptor and call configuration.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.IllegalArgumentException
- if descriptor == null
.UnsupportedProtocolException
- if descriptor
is or contains a TargetDescriptor
with an unsupported protocol.public XINSServiceCaller(Descriptor descriptor) throws IllegalArgumentException, UnsupportedProtocolException
XINSServiceCaller
with the specified
descriptor and the default HTTP method.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).public XINSServiceCaller()
XINSServiceCaller
with no
descriptor (yet) and the default HTTP method.
Before actual calls can be made, setDescriptor(Descriptor)
should be used to set the descriptor.
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 ServiceCaller
protocol
- the protocol, guaranteed not to be null
.true
if the specified protocol is supported, or
false
if it is not.public void setDescriptor(Descriptor descriptor)
ServiceCaller
setDescriptor
in class ServiceCaller
descriptor
- the descriptor for this service, or null
.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 XINSServiceCaller
returns a standard XINSCallConfig
object which has unconditional
fail-over disabled and the HTTP method set to
POST
.
getDefaultCallConfig
in class ServiceCaller
XINSCallConfig
instance with default settings, never
null
.protected final void setXINSCallConfig(XINSCallConfig config) throws IllegalArgumentException
XINSCallConfig
associated with this XINS service
caller.config
- the fall-back XINSCallConfig
object for this service caller,
cannot be null
.IllegalArgumentException
- if config == null
.public final XINSCallConfig getXINSCallConfig()
XINSCallConfig
associated with this service
caller.
This method is the type-safe equivalent of ServiceCaller.getCallConfig()
.
XINSCallConfig
object for this XINS service
caller, never null
.public XINSCallResult call(XINSCallRequest request, XINSCallConfig callConfig) throws IllegalArgumentException, GenericCallException, HTTPCallException, XINSCallException
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.
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.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.XINSCallException
- if the first call attempt failed due to a XINS-related reason and
all the other call attempts failed as well.public XINSCallResult call(XINSCallRequest request) throws IllegalArgumentException, GenericCallException, HTTPCallException, XINSCallException
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.
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.XINSCallException
- if the first call attempt failed due to a XINS-related reason and
all the other call attempts failed as well.public Object doCallImpl(CallRequest request, CallConfig callConfig, TargetDescriptor target) throws IllegalArgumentException, ClassCastException, GenericCallException, HTTPCallException, XINSCallException
XINSCallResult
object is returned, otherwise a
CallException
is thrown.doCallImpl
in class ServiceCaller
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
.XINSCallResult
, never null
.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.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
XINSServiceCaller
expects an XINSCallRequest
and
returns an XINSCallResult
.
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 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
; .XINSCallResult
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)
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
and never empty.true
if the call should fail-over to the next target, or
false
if it should not.See http://www.xins.org/.