org.xins.server

Class SOAPCallingConvention

java.lang.Object

org.xins.common.manageable.Manageable

org.xins.server.SOAPCallingConvention

Direct Known Subclasses:

SOAPMapCallingConvention

public class SOAPCallingConvention
extends Manageable

The SOAP calling convention. The SOAP message parsed by this calling convention is expected to match the WSDL generated by the _WSDL meta-function.

Version:

$Revision: 1.83 $ $Date: 2013/01/18 10:41:47 $

Author:

Anthony Goubard, Ernst de Haan

Nested Class Summary

Nested classes/interfaces inherited from class org.xins.common.manageable.Manageable

Manageable.State

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	REQUEST_NAMESPACE The key used to store the name of the namespace in the request attributes.
protected static String	RESPONSE_CONTENT_TYPE The content type of the HTTP response.
protected static String	RESPONSE_ENCODING The response encoding format.

Fields inherited from class org.xins.common.manageable.Manageable

BOOTSTRAPPED, BOOTSTRAPPING, DEINITIALIZING, INITIALIZING, UNUSABLE, USABLE

Constructor Summary

Constructors

Constructor and Description
SOAPCallingConvention(API api) Creates a new SOAPCallingConvention instance.

Method Summary

Methods

Modifier and Type	Method and Description
protected FunctionRequest	convertRequestImpl(HttpServletRequest httpRequest) Converts an HTTP request to a XINS request (implementation method).
protected void	convertResultImpl(FunctionResult xinsResult, HttpServletResponse httpResponse, Map<String,Object> backpack) Converts a XINS result to an HTTP response (implementation method).
protected API	getAPI() Determines the current API.
protected String[]	getSupportedMethods() Determines which HTTP methods are supported for function invocations.
protected String[]	getSupportedMethods(HttpServletRequest request) Determines which HTTP methods are supported for function invocations, for the specified request.
protected boolean	matches(HttpServletRequest httpRequest) Checks if the specified request can be handled by this calling convention.
protected Element	parseXMLRequest(HttpServletRequest httpRequest) Parses XML from the specified HTTP request and checks that the content type is correct.
protected Element	parseXMLRequest(HttpServletRequest httpRequest, boolean checkType) Parses XML from the specified HTTP request and optionally checks that the content type is correct.
protected Element	readDataSection(Element parametersElem, String functionName) Reads the input parameters.
protected Map<String,String>	readInputParameters(Element parametersElem, String functionName) Reads the input parameters.
protected void	setDataElementAttribute(Element builder, String attributeName, String attributeValue, String elementNameSpacePrefix) Writes the attribute a output data element for the returned SOAP element.
protected Element	soapElementTransformation(Map dataSection, boolean input, Element element, boolean top) Convert the values of element to the required format.
protected String	soapInputValueTransformation(Type parameterType, String value) Transforms the value of a input SOAP parameter to the XINS equivalent.
protected String	soapOutputValueTransformation(Type parameterType, String value) Transforms the value of a output XINS parameter to the SOAP equivalent.
protected void	writeFaultSection(String functionName, String namespaceURI, FunctionResult xinsResult, XMLOutputter xmlout) Writes the fault section to the SOAP XML when an error code is returned from the function call.
protected void	writeOutputDataSection(String functionName, FunctionResult xinsResult, XMLOutputter xmlout) Writes the output data section to the SOAP XML.
protected void	writeOutputParameters(String functionName, FunctionResult xinsResult, XMLOutputter xmlout) Writes the output parameters to the SOAP XML.

Methods inherited from class org.xins.common.manageable.Manageable

assertUsable, bootstrap, bootstrapImpl, deinit, deinitImpl, getState, init, initImpl, isBootstrapped, isUsable

Methods inherited from class java.lang.Object

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

Field Detail

RESPONSE_ENCODING

protected static final String RESPONSE_ENCODING

The response encoding format.

See Also:

Constant Field Values

RESPONSE_CONTENT_TYPE

protected static final String RESPONSE_CONTENT_TYPE

The content type of the HTTP response.

See Also:

Constant Field Values

REQUEST_NAMESPACE

protected static final String REQUEST_NAMESPACE

The key used to store the name of the namespace in the request attributes.

Since:

XINS 2.1.

See Also:

Constant Field Values

Constructor Detail

SOAPCallingConvention

public SOAPCallingConvention(API api)
                      throws IllegalArgumentException

Creates a new SOAPCallingConvention instance.

Parameters:

api - the API, needed for the SOAP messages, cannot be null.

Throws:

IllegalArgumentException - if api == null.

Method Detail

getSupportedMethods

protected String[] getSupportedMethods()

Determines which HTTP methods are supported for function invocations.

Each String in the returned array must be one supported method.

The returned array must not be null, it must only contain valid HTTP method names, so they may not contain whitespace, for example. Duplicates will be ignored. HTTP method names must be in uppercase.

There must be at least one HTTP method supported for function invocations.

Note that OPTIONS must not be returned by this method, as it is not an HTTP method that can ever be used to invoke a XINS function.

HTTP OPTIONS requests are treated differently. For the path * the capabilities of the whole server are returned. For other paths, the appropriate calling convention is determined, after which the set of supported HTTP methods is returned to the called.

Returns:

the HTTP methods supported, in a String array, must not be null.

matches

protected boolean matches(HttpServletRequest httpRequest)
                   throws Exception

Checks if the specified request can be handled by this calling convention.

This method will not throw any exception.

Parameters:

httpRequest - the HTTP request to investigate, cannot be null.

Returns:

true if this calling convention is possibly able to handle this request, or false if it definitely not able to handle this request.

Throws:

Exception - if analysis of the request causes an exception; false will be assumed.

convertRequestImpl

protected FunctionRequest convertRequestImpl(HttpServletRequest httpRequest)
                                      throws InvalidRequestException,
                                             FunctionNotSpecifiedException

Converts an HTTP request to a XINS request (implementation method). This method should only be called from the XINS/Java Server Framework self. Then it is guaranteed that:

• the state is usable;
• the httpRequest argument is not null;
• the HTTP method is in the set of supported methods, as indicated by getSupportedMethods().

Note that getSupportedMethods(HttpServletRequest) will not have been called prior to this method call.

Parameters:

httpRequest - the HTTP request.

Returns:

the XINS request object, should not be null.

Throws:

InvalidRequestException - if the request is considerd to be invalid.

FunctionNotSpecifiedException - if the request does not indicate the name of the function to execute.

convertResultImpl

protected void convertResultImpl(FunctionResult xinsResult,
                     HttpServletResponse httpResponse,
                     Map<String,Object> backpack)
                          throws IOException

Converts a XINS result to an HTTP response (implementation method). This method should only be called from the XINS/Java Server Framework self. Then it is guaranteed that none of the arguments is null.

Parameters:

xinsResult - the XINS result object that should be converted to an HTTP response, will not be null.

httpResponse - the HTTP response object to configure.

backpack - the backpack.

Throws:

IOException - if the invocation of any of the methods in either httpResponse or httpRequest caused an I/O error.

readInputParameters

protected Map<String,String> readInputParameters(Element parametersElem,
                                     String functionName)

Reads the input parameters.

Parameters:

parametersElem - the XML element which contains the parameters, cannot be null

functionName - the name of the function called, cannot be null.

Returns:

the parameters for the function, never null.

readDataSection

protected Element readDataSection(Element parametersElem,
                      String functionName)
                           throws InvalidRequestException

Reads the input parameters.

Parameters:

parametersElem - the XML element which contains the parameters and data section, cannot be null

functionName - the name of the function called, cannot be null.

Returns:

the data section for the function, can be null.

Throws:

InvalidRequestException - if the SOAP request is invalid.

writeFaultSection

protected void writeFaultSection(String functionName,
                     String namespaceURI,
                     FunctionResult xinsResult,
                     XMLOutputter xmlout)
                          throws IOException

Writes the fault section to the SOAP XML when an error code is returned from the function call.

Parameters:

functionName - the name of the function called.

namespaceURI - the namespace URI to use for the parameters.

xinsResult - the result of the call to the function.

xmlout - the XML outputter to write the parameters in.

Throws:

IOException - if the data cannot be written to the XML outputter for any reason.

writeOutputParameters

protected void writeOutputParameters(String functionName,
                         FunctionResult xinsResult,
                         XMLOutputter xmlout)
                              throws IOException

Writes the output parameters to the SOAP XML.

Parameters:

functionName - the name of the function called.

xinsResult - the result of the call to the function.

xmlout - the XML outputter to write the parameters in.

Throws:

IOException - if the data cannot be written to the XML outputter for any reason.

writeOutputDataSection

protected void writeOutputDataSection(String functionName,
                          FunctionResult xinsResult,
                          XMLOutputter xmlout)
                               throws IOException

Writes the output data section to the SOAP XML.

Parameters:

functionName - the name of the function called.

xinsResult - the result of the call to the function.

xmlout - the XML outputter to write the data section in.

Throws:

IOException - if the data cannot be written to the XML outputter for any reason.

soapInputValueTransformation

protected String soapInputValueTransformation(Type parameterType,
                                  String value)
                                       throws InvalidSpecificationException

Transforms the value of a input SOAP parameter to the XINS equivalent.

Parameters:

parameterType - the type of the parameter, cannot be null.

value - the value of the SOAP parameter, cannot be null.

Returns:

the XINS value, never null.

Throws:

InvalidSpecificationException - if the specification is incorrect.

soapOutputValueTransformation

protected String soapOutputValueTransformation(Type parameterType,
                                   String value)
                                        throws InvalidSpecificationException

Transforms the value of a output XINS parameter to the SOAP equivalent.

Parameters:

parameterType - the type of the parameter, cannot be null.

value - the value returned by the XINS function, cannot be null.

Returns:

the SOAP value, never null.

Throws:

InvalidSpecificationException - if the specification is incorrect.

soapElementTransformation

protected Element soapElementTransformation(Map dataSection,
                                boolean input,
                                Element element,
                                boolean top)

Convert the values of element to the required format.

Parameters:

dataSection - the specification of the elements, cannot be null.

input - true if it's the input parameter that should be transform, false if it's the output parameter.

element - the element node to process, cannot be null.

top - true if it's the top element, false otherwise.

Returns:

the converted value, never null.

setDataElementAttribute

protected void setDataElementAttribute(Element builder,
                           String attributeName,
                           String attributeValue,
                           String elementNameSpacePrefix)

Writes the attribute a output data element for the returned SOAP element.

Parameters:

builder - the builder used to create the SOAP Element, cannot be null.

attributeName - the name of the attribute, cannot be null.

attributeValue - the value of the attribute, cannot be null.

elementNameSpacePrefix - the namespace prefix of the parent element, can be null.

Since:

XINS 2.1.

getAPI

protected final API getAPI()

Determines the current API.

Returns:

the current API, never null.

Since:

XINS 1.5.0

getSupportedMethods

protected String[] getSupportedMethods(HttpServletRequest request)

Determines which HTTP methods are supported for function invocations, for the specified request.

Each String in the returned array must be one supported method.

The returned array may be null. If it is not, then the returned array must only contain valid HTTP method names, so they may not contain whitespace, for example. HTTP method names must be in uppercase.

There must be at least one HTTP method supported for function invocations.

Note that OPTIONS must not be returned by this method, as it is not an HTTP method that can ever be used to invoke a XINS function.

The set of supported methods must be a subset of the set returned by getSupportedMethods().

The default implementation of this method returns the set returned by getSupportedMethods().

Parameters:

request - the request to determine the supported methods for.

Returns:

the HTTP methods supported for the specified request, in a String array, can be null.

Since:

XINS 1.5.0

parseXMLRequest

protected Element parseXMLRequest(HttpServletRequest httpRequest)
                           throws IllegalArgumentException,
                                  InvalidRequestException

Parses XML from the specified HTTP request and checks that the content type is correct.

This method uses a cache to optimize performance if either of the parseXMLRequest methods is called multiple times for the same request.

Calling this method is equivalent with calling parseXMLRequest(HttpServletRequest,boolean) with the checkType argument set to true.

Parameters:

httpRequest - the HTTP request, cannot be null.

Returns:

the parsed element, never null.

Throws:

IllegalArgumentException - if httpRequest == null.

InvalidRequestException - if the HTTP request cannot be read or cannot be parsed correctly.

Since:

XINS 1.4.0

parseXMLRequest

protected Element parseXMLRequest(HttpServletRequest httpRequest,
                      boolean checkType)
                           throws IllegalArgumentException,
                                  InvalidRequestException

Parses XML from the specified HTTP request and optionally checks that the content type is correct.

Since XINS 1.4.0, this method uses a cache to optimize performance if either of the parseXMLRequest methods is called multiple times for the same request.

Parameters:

httpRequest - the HTTP request, cannot be null.

checkType - flag indicating whether this method should check that the content type of the request is text/xml.

Returns:

the parsed element, never null.

Throws:

IllegalArgumentException - if httpRequest == null.

InvalidRequestException - if the HTTP request cannot be read or cannot be parsed correctly.

Since:

XINS 1.3.0