org.xins.client
Class XINSCallRequest

java.lang.Object
  org.xins.common.service.CallRequest
      org.xins.client.XINSCallRequest

All Implemented Interfaces:

Serializable

public final class XINSCallRequest

extends CallRequest

Abstraction of a XINS request.

Note that instances of this class are not thread-safe.

Since:

XINS 1.0.0

Version:

$Revision: 1.50 $ $Date: 2006/08/28 09:12:31 $

Author:

Ernst de Haan

See Also:

XINSServiceCaller, Serialized Form

Field Summary

static String

PARAMETER_NAME_PATTERN_STRING The pattern for a parameter name, as a character string.

Constructor Summary

XINSCallRequest(String functionName)
Constructs a new XINSCallRequest for the specified function with no parameters, disallowing fail-over unless the request was definitely not (yet) accepted by the service.

XINSCallRequest(String functionName, PropertyReader parameters)
Constructs a new XINSCallRequest for the specified function and parameters, disallowing fail-over unless the request was definitely not (yet) accepted by the service.

XINSCallRequest(String functionName, PropertyReader parameters, boolean failOverAllowed)
Deprecated. Deprecated since XINS 1.1.0. Use XINSCallRequest(String,PropertyReader) in combination with setXINSCallConfig(XINSCallConfig) instead. This constructor is guaranteed not to be removed before XINS 2.0.0.

XINSCallRequest(String functionName, PropertyReader parameters, boolean failOverAllowed, HTTPMethod method)
Deprecated. Deprecated since XINS 1.1.0. Use XINSCallRequest(String,PropertyReader) in combination with setXINSCallConfig(XINSCallConfig) instead. This constructor is guaranteed not to be removed before XINS 2.0.0.

XINSCallRequest(String functionName, PropertyReader parameters, Element dataSection)
Constructs a new XINSCallRequest for the specified function and parameters, disallowing fail-over unless the request was definitely not (yet) accepted by the service.

Method Summary

String	describe() Describes this request.
Element	getDataSection() Retrieves the data section for the input.
String	getFunctionName() Returns the name of the function to call.
String	getParameter(String name) Gets the value of the specified parameter.
PropertyReader	getParameters() Gets all parameters to pass with the call, with their respective values.
XINSCallConfig	getXINSCallConfig() Returns the XINS call configuration.
boolean	isFailOverAllowed() Deprecated. Deprecated since XINS 1.1.0. Call getXINSCallConfig() instead and then call isFailOverAllowed() on the returned call configuration object. This method is guaranteed not to be removed before XINS 2.0.0.
void	setDataSection(Element dataSection) Sets the data section for the input.
void	setParameter(String name, String value) Sets the parameter with the specified name.
void	setParameters(PropertyReader parameters) Sets the parameters for this function, replacing any existing parameters.
void	setXINSCallConfig(XINSCallConfig callConfig) Sets the associated XINS call configuration.

Methods inherited from class org.xins.common.service.CallRequest

getCallConfig, setCallConfig, toString

Methods inherited from class java.lang.Object

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

Field Detail

PARAMETER_NAME_PATTERN_STRING

public static final String PARAMETER_NAME_PATTERN_STRING

The pattern for a parameter name, as a character string.

See Also:

Constant Field Values

Constructor Detail

XINSCallRequest

public XINSCallRequest(String functionName)
                throws IllegalArgumentException

Constructs a new XINSCallRequest for the specified function with no parameters, disallowing fail-over unless the request was definitely not (yet) accepted by the service.

Parameters:

functionName - the name of the function to call, cannot be null.

Throws:

IllegalArgumentException - if functionName == null.

XINSCallRequest

public XINSCallRequest(String functionName,
                       PropertyReader parameters)
                throws IllegalArgumentException

Constructs a new XINSCallRequest for the specified function and parameters, disallowing fail-over unless the request was definitely not (yet) accepted by the service.

Parameters:

functionName - the name of the function to call, cannot be null.

parameters - the input parameters, if any, can be null if there are none.

Throws:

IllegalArgumentException - if functionName == null.

XINSCallRequest

public XINSCallRequest(String functionName,
                       PropertyReader parameters,
                       Element dataSection)
                throws IllegalArgumentException

Constructs a new XINSCallRequest for the specified function and parameters, disallowing fail-over unless the request was definitely not (yet) accepted by the service.

Parameters:

functionName - the name of the function to call, cannot be null.

parameters - the input parameters, if any, can be null if there are none.

dataSection - the data section for the input, if any, can be null if there are none.

Throws:

IllegalArgumentException - if functionName == null.

Since:

XINS 1.1.0

XINSCallRequest

public XINSCallRequest(String functionName,
                       PropertyReader parameters,
                       boolean failOverAllowed)
                throws IllegalArgumentException

Deprecated. Deprecated since XINS 1.1.0. Use XINSCallRequest(String,PropertyReader) in combination with setXINSCallConfig(XINSCallConfig) instead. This constructor is guaranteed not to be removed before XINS 2.0.0.

Constructs a new XINSCallRequest for the specified function and parameters, possibly allowing fail-over even if the request was possibly already received by a target service.

Parameters:

functionName - the name of the function to call, cannot be null.

parameters - the input parameters, if any, can be null if there are none.

failOverAllowed - flag that indicates whether fail-over is in principle allowed, even if the request was already sent to the other end.

Throws:

IllegalArgumentException - if functionName == null.

XINSCallRequest

public XINSCallRequest(String functionName,
                       PropertyReader parameters,
                       boolean failOverAllowed,
                       HTTPMethod method)
                throws IllegalArgumentException

Deprecated. Deprecated since XINS 1.1.0. Use XINSCallRequest(String,PropertyReader) in combination with setXINSCallConfig(XINSCallConfig) instead. This constructor is guaranteed not to be removed before XINS 2.0.0.

Constructs a new XINSCallRequest for the specified function and parameters, possibly allowing fail-over, optionally specifying the HTTP method to use.

Parameters:

functionName - the name of the function to call, cannot be null.

parameters - the input parameters, if any, can be null if there are none.

failOverAllowed - flag that indicates whether fail-over is in principle allowed, even if the request was already sent to the other end.

method - the HTTP method to use, or null if a default should be used.

Throws:

IllegalArgumentException - if functionName == null or if parameters contains a name that does not match the constraints for a parameter name, see PARAMETER_NAME_PATTERN_STRING or if it equals "function", which is currently still reserved.

Method Detail

describe

public String describe()

Describes this request.

Specified by:

describe in class CallRequest

Returns:

the description of this request, never null.

getXINSCallConfig

public XINSCallConfig getXINSCallConfig()

Returns the XINS call configuration.

Returns:

the XINS call configuration object, or null.

Since:

XINS 1.1.0

setXINSCallConfig

public void setXINSCallConfig(XINSCallConfig callConfig)

Sets the associated XINS call configuration.

Parameters:

callConfig - the XINS call configuration object to associate with this request, or null.

Since:

XINS 1.1.0

getFunctionName

public String getFunctionName()

Returns the name of the function to call.

Returns:

the name of the function to call, never null.

setParameters

public void setParameters(PropertyReader parameters)
                   throws IllegalArgumentException

Sets the parameters for this function, replacing any existing parameters. First the existing parameters are cleaned and then all the specified parameters are copied to the internal set one-by-one. If any of the parameters has an invalid name, then the internal parameter set is cleaned and then an exception is thrown.

Parameters:

parameters - the input parameters, if any, can be null if there are none.

Throws:

IllegalArgumentException - if parameters contains a name that does not match the constraints for a parameter name, see PARAMETER_NAME_PATTERN_STRING or if it equals "function", which is currently still reserved.

Since:

XINS 1.1.0

setParameter

public void setParameter(String name,
                         String value)
                  throws IllegalArgumentException

Sets the parameter with the specified name.

Parameters:

name - the parameter name, cannot be null.

value - the new value for the parameter, can be null.

Throws:

IllegalArgumentException - if name does not match the constraints for a parameter name, see PARAMETER_NAME_PATTERN_STRING or if it equals "function", which is currently still reserved.

Since:

XINS 1.2.0

getParameters

public PropertyReader getParameters()

Gets all parameters to pass with the call, with their respective values.

Returns:

the parameters, or null if there are none.

getParameter

public String getParameter(String name)
                    throws IllegalArgumentException

Gets the value of the specified parameter.

Parameters:

name - the parameter name, not null.

Returns:

string containing the value of the parameter, not null.

Throws:

IllegalArgumentException - if name == null.

setDataSection

public void setDataSection(Element dataSection)

Sets the data section for the input.

Parameters:

dataSection - the data section for the input, or null if there is none.

Since:

XINS 1.1.0

getDataSection

public Element getDataSection()

Retrieves the data section for the input.

Returns:

the data section for the input, or null if there is none.

Since:

XINS 1.1.0

isFailOverAllowed

public boolean isFailOverAllowed()

Deprecated. Deprecated since XINS 1.1.0. Call getXINSCallConfig() instead and then call isFailOverAllowed() on the returned call configuration object. This method is guaranteed not to be removed before XINS 2.0.0.

Determines whether fail-over is unconditionally allowed.

Returns:

true if fail-over is unconditionally allowed, even if the request was already received or even processed by the other end, false otherwise.