org.xins.server

Class SOAPMapCallingConvention

java.lang.Object

org.xins.common.manageable.Manageable

org.xins.server.SOAPCallingConvention

org.xins.server.SOAPMapCallingConvention

public class SOAPMapCallingConvention
extends SOAPCallingConvention

The SOAP calling convention that tries to map the SOAP request to the parameters of the function. The rules applied for the mapping are the same as for the command wsdl-to-api.

Note that by default any SOAP message will be handled by the _xins_soap calling convention. If you want to use this calling convention you will need to explicitly have _convention=_xins_soap_map in the URL parameters.

This calling convention is easily extendable in order to adapt to the specificity of your SOAP requests.

Here is the mapping for the input:

• If the element in the Body ends with 'Request', the function name is considered to be what is specified before
• Otherwise the name of the element is used for the name of the function
• Elements in the request are mapped to input parameters if available.
• Elements with sub-elements are mapped to input parameters element1.sub-element1... if available.
• If no parameter is found, try to find an input data element with the name.
• If not found, go to the sub-elements and try to find an input data element with the name.
• If not found, skip it. Here it's up to you to override this convention and provide a mapping.

Here is the mapping for the output:

• Response name = function name + "Response"
• Output parameters with dots are transformed to XML. e.g. element1.element2 -> <element1><element2>value</element2></element1>
• The data section is not put in the returned XML, only the elements it contains.
• Data section element attributes are changed to sub-elements with the same rule as for output parameters.

Since:

XINS 2.1.

Version:

$Revision: 1.19 $ $Date: 2013/01/12 16:36:29 $

Author:

Anthony Goubard

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_BODY The key used to store the Body element of the request.
protected static String	REQUEST_ENVELOPE The key used to store the Envelope element of the request.
protected static String	REQUEST_FUNCTION The key used to store the function element of the request.

Fields inherited from class org.xins.server.SOAPCallingConvention

REQUEST_NAMESPACE, RESPONSE_CONTENT_TYPE, RESPONSE_ENCODING

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

BOOTSTRAPPED, BOOTSTRAPPING, DEINITIALIZING, INITIALIZING, UNUSABLE, USABLE

Constructor Summary

Constructors

Constructor and Description
SOAPMapCallingConvention(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(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 FunctionRequest	readInput(Element functionElem, String functionName, Map<String,Object> backpack) Generates the function request based the the SOAP request.
protected Element	readInputElem(Element inputElem, String functionName, String parent, Element parentElement, Map<String,String> inputParams) Parses the SOAP request element according to the rules specified in this class description.
protected void	setDataElementAttribute(Element builder, String attributeName, String attributeValue, String elementNameSpacePrefix) Writes the attribute a output data element for the returned SOAP element.
protected void	writeOutputDataElement(Map dataSectionSpec, Element dataElement, Element parent) Write the given output data element in the SOAP response.
protected void	writeOutputDataSection(String functionName, FunctionResult xinsResult, Element response) Writes the output data section to the SOAP XML.
protected void	writeOutputParameter(String parameterName, String parameterValue, Element parent) Write an output parameter to the SOAP response.
protected void	writeOutputParameters(String functionName, FunctionResult xinsResult, Element response) Writes the output parameters to the SOAP XML.
protected Element	writeResponse(FunctionResult xinsResult, Map<String,Object> backpack)

Methods inherited from class org.xins.server.SOAPCallingConvention

getSupportedMethods, readDataSection, readInputParameters, soapElementTransformation, soapInputValueTransformation, soapOutputValueTransformation, writeFaultSection, writeOutputDataSection, writeOutputParameters

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

REQUEST_ENVELOPE

protected static final String REQUEST_ENVELOPE

The key used to store the Envelope element of the request.

See Also:

Constant Field Values

REQUEST_BODY

protected static final String REQUEST_BODY

The key used to store the Body element of the request.

See Also:

Constant Field Values

REQUEST_FUNCTION

protected static final String REQUEST_FUNCTION

The key used to store the function element of the request.

See Also:

Constant Field Values

Constructor Detail

SOAPMapCallingConvention

public SOAPMapCallingConvention(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

matches

protected boolean matches(HttpServletRequest httpRequest)
                   throws Exception

Description copied from class: SOAPCallingConvention

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

This method will not throw any exception.

Overrides:

matches in class SOAPCallingConvention

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.

Overrides:

convertRequestImpl in class SOAPCallingConvention

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.

readInput

protected FunctionRequest readInput(Element functionElem,
                        String functionName,
                        Map<String,Object> backpack)

Generates the function request based the the SOAP request. This function will get the XML element in the SOAP request and associate the values with the input parameter or data section element of the function.

Parameters:

functionElem - the SOAP element of the function request, cannot be null.

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

backpack - the backpack of this request, cannot be null.

Returns:

the function request that will be passed to the XINS function, cannot be null.

readInputElem

protected Element readInputElem(Element inputElem,
                    String functionName,
                    String parent,
                    Element parentElement,
                    Map<String,String> inputParams)
                         throws Exception

Parses the SOAP request element according to the rules specified in this class description.

Parameters:

inputElem - the SOAP request element, cannot be null.

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

parent - the name of the super element, can be null.

parentElement - the input data element that is being created, can be null.

inputParams - the Map where the input parameters should be stored, cannot be null.

Returns:

the input data element for the FunctionRequest or null if the SOAP request does not need to create a input data element.

Throws:

Exception - if anything goes wrong such specifications not available or incorrect SOAP request.

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.

Overrides:

convertResultImpl in class SOAPCallingConvention

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.

writeResponse

protected Element writeResponse(FunctionResult xinsResult,
                    Map<String,Object> backpack)
                         throws IOException

Throws:

IOException

writeOutputParameters

protected void writeOutputParameters(String functionName,
                         FunctionResult xinsResult,
                         Element response)

Writes the output parameters to the SOAP XML.

Parameters:

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

xinsResult - the result of the call to the function, cannot be null.

response - the SOAP response element, cannot be null.

writeOutputParameter

protected void writeOutputParameter(String parameterName,
                        String parameterValue,
                        Element parent)

Write an output parameter to the SOAP response.

Parameters:

parameterName - the name of the output parameter, cannot be null.

parameterValue - the value of the output parameter, cannot be null.

parent - the parent element to put the created element in, cannot be null.

writeOutputDataSection

protected void writeOutputDataSection(String functionName,
                          FunctionResult xinsResult,
                          Element response)

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.

response - the SOAP response element, cannot be null.

writeOutputDataElement

protected void writeOutputDataElement(Map dataSectionSpec,
                          Element dataElement,
                          Element parent)

Write the given output data element in the SOAP response.

Parameters:

dataSectionSpec - the specification of the output data elements for the function, cannot be null.

dataElement - the data element to tranform as SOAP element, cannot be null.

parent - the parent element to add the created element, cannot be null.

setDataElementAttribute

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

Description copied from class: SOAPCallingConvention

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

Overrides:

setDataElementAttribute in class SOAPCallingConvention

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.

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