org.xins.client
Class AbstractCAPI

java.lang.Object
  org.xins.client.AbstractCAPI

public abstract class AbstractCAPI

extends Object

Base class for generated Client-side Application Programming Interface (CAPI) classes.

This class should not be derived from manually. This class is only intended to be used as a superclass of CAPI classes generated by the XINS framework.

The constructors of this class are considered internal to XINS and should not be used directly. The behavior of the constructors may be changed in later releases of XINS or they may even be removed.

Since:

XINS 1.0.0

Version:

$Revision: 1.63 $ $Date: 2006/08/28 09:12:30 $

Author:

Ernst de Haan, Anthony Goubard

Constructor Summary

protected	AbstractCAPI(Descriptor descriptor) Creates a new AbstractCAPI object, using the specified service descriptor.
protected	AbstractCAPI(Descriptor descriptor, XINSCallConfig callConfig) Creates a new AbstractCAPI object, using the specified XINSServiceCaller.
protected	AbstractCAPI(PropertyReader properties, String apiName) Creates a new AbstractCAPI object based on the specified set of properties and the specified name.

Method Summary

protected XINSCallResult	callImpl(AbstractCAPICallRequest request) Executes the specified call request.
protected AbstractCAPIErrorCodeException	createErrorCodeException(XINSCallRequest request, TargetDescriptor target, long duration, XINSCallResultData resultData) Creates an AbstractCAPIErrorCodeException for the specified error code.
String	getAPIName() Determines the name of the API.
protected String	getAPINameImpl() Retrieves the name of the API (implementation method).
APISpec	getAPISpecification() Get the specification of the API.
protected XINSServiceCaller	getCaller() Returns the XINS service caller to use.
XINSCallConfig	getXINSCallConfig() Retrieves the call configuration currently associated with this CAPI object.
abstract String	getXINSVersion() Returns the version of XINS used to build this CAPI class.
void	setXINSCallConfig(XINSCallConfig config) Assigns the specified call configuration to this CAPI object.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractCAPI

protected AbstractCAPI(Descriptor descriptor,
                       XINSCallConfig callConfig)
                throws IllegalArgumentException,
                       UnsupportedProtocolException

Creates a new AbstractCAPI object, using the specified XINSServiceCaller.

This constructor is considered internal to XINS. Do not use it directly.

Parameters:

descriptor - the descriptor for the service(s), cannot be null.

callConfig - fallback configuration for the calls, or null if a default should be used.

Throws:

IllegalArgumentException - if descriptor == null.

UnsupportedProtocolException - if any of the target descriptors in descriptor specifies an unsupported protocol.

Since:

XINS 1.1.0

AbstractCAPI

protected AbstractCAPI(Descriptor descriptor)
                throws IllegalArgumentException,
                       UnsupportedProtocolException

Creates a new AbstractCAPI object, using the specified service descriptor.

A default XINS call configuration will be used.

This constructor is considered internal to XINS. Do not use it directly.

Parameters:

descriptor - the descriptor for the service(s), cannot be null.

Throws:

IllegalArgumentException - if descriptor == null.

UnsupportedProtocolException - if any of the target descriptors in descriptor specifies an unsupported protocol (since XINS 1.1.0).

AbstractCAPI

protected AbstractCAPI(PropertyReader properties,
                       String apiName)
                throws IllegalArgumentException,
                       MissingRequiredPropertyException,
                       InvalidPropertyValueException

Creates a new AbstractCAPI object based on the specified set of properties and the specified name.

A default XINS call configuration will be used.

This constructor is considered internal to XINS. Do not use it directly.

Parameters:

properties - the properties to read from, cannot be null.

apiName - the name of the API, cannot be null and must be a valid API name.

Throws:

IllegalArgumentException - if properties == null || apiName == null or if apiName is not considered to be a valid API name.

MissingRequiredPropertyException - if a required property is missing in the specified properties set.

InvalidPropertyValueException - if one of the properties in the specified properties set is used to create a CAPI instance but its value is considered invalid.

Since:

XINS 1.2.0

Method Detail

getAPIName

public final String getAPIName()

Determines the name of the API.

Returns:

the name of the API, or a special indication (e.g. "<unknown>") if the name cannot be determined; never null.

Since:

XINS 1.2.0

getAPINameImpl

protected String getAPINameImpl()

Retrieves the name of the API (implementation method).

The implementation of this method in class AbstractCAPI returns null.

Returns:

the name of the API, or null if unknown.

Since:

XINS 1.2.0

getAPISpecification

public final APISpec getAPISpecification()
                                  throws InvalidSpecificationException

Get the specification of the API.

Returns:

the APISpec specification object.

Throws:

InvalidSpecificationException - if the specification cannot be found or is invalid.

Since:

XINS 1.3.0

setXINSCallConfig

public final void setXINSCallConfig(XINSCallConfig config)

Assigns the specified call configuration to this CAPI object.

Parameters:

config - the call configuration to apply when executing a call with this CAPI object, or null if no specific call configuration should be associated with CAPI object; note that the call configuration can be overridden by the request, see AbstractCAPICallRequest.configure(XINSCallConfig).

Since:

XINS 1.2.0

getXINSCallConfig

public final XINSCallConfig getXINSCallConfig()

Retrieves the call configuration currently associated with this CAPI object.

Returns:

the call configuration currently associated with this CAPI object, or null if no specific call configuration is associated with this cAPI object; note that the call configuration can be overridden by the request, see AbstractCAPICallRequest.configuration().

Since:

XINS 1.2.0

getCaller

protected XINSServiceCaller getCaller()

Returns the XINS service caller to use.

This method is considered internal to XINS. It should not be called directly, nor overridden.

This method is expected to be marked final in XINS 2.0. This is not done yet to remain fully compatible with XINS 1.x.

Returns:

the XINSServiceCaller to use, never null.

getXINSVersion

public abstract String getXINSVersion()

Returns the version of XINS used to build this CAPI class.

Returns:

the version as a String, cannot be null.

callImpl

protected final XINSCallResult callImpl(AbstractCAPICallRequest request)
                                 throws IllegalArgumentException,
                                        UnacceptableRequestException,
                                        GenericCallException,
                                        HTTPCallException,
                                        XINSCallException

Executes the specified call request.

This method is provided for CAPI subclasses.

Parameters:

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

Returns:

the result, not null.

Throws:

IllegalArgumentException - if request == null.

UnacceptableRequestException - if the request is considered to be unacceptable; this is determined by calling request.checkParameters().

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

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

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

Since:

XINS 1.2.0

createErrorCodeException

protected AbstractCAPIErrorCodeException createErrorCodeException(XINSCallRequest request,
                                                                  TargetDescriptor target,
                                                                  long duration,
                                                                  XINSCallResultData resultData)
                                                           throws IllegalArgumentException,
                                                                  UnacceptableErrorCodeXINSCallException

Creates an AbstractCAPIErrorCodeException for the specified error code. If the specified error code is not recognized, then null is returned.

Parameters:

request - the original request, should not be null.

target - descriptor for the target that was attempted to be called, should not be null.

duration - the call duration in milliseconds, should be >= 0.

resultData - the result data, should not be null and should have an error code set.

Returns:

if the error code is recognized, then a matching AbstractCAPIErrorCodeException instance, otherwise null.

Throws:

IllegalArgumentException - if request == null || target == null || duration < 0 || resultData == null || resultData.getErrorCode() == null.

UnacceptableErrorCodeXINSCallException - if the specified error code is recognized but is considered unacceptable for the function specified in the request.

Since:

XINS 1.2.0