org.xins.server
Class SOAPMapCallingConvention

java.lang.Object
  extended byorg.xins.common.manageable.Manageable
      extended byorg.xins.server.CallingConvention
          extended byorg.xins.server.SOAPCallingConvention
              extended byorg.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:

Here is the mapping for the output:

Since:
XINS 2.1.
Version:
$Revision: 1.10 $ $Date: 2008/07/04 10:22:51 $
Author:
Anthony Goubard

Nested Class Summary
 
Nested classes inherited from class org.xins.common.manageable.Manageable
Manageable.State
 
Field Summary
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
FUNCTION_NAME, REQUEST_NAMESPACE, RESPONSE_CONTENT_TYPE, RESPONSE_ENCODING
 
Fields inherited from class org.xins.common.manageable.Manageable
BOOTSTRAPPED, BOOTSTRAPPING, DEINITIALIZING, INITIALIZING, UNUSABLE, USABLE
 
Constructor Summary
SOAPMapCallingConvention(API api)
          Creates a new SOAPCallingConvention instance.
 
Method Summary
protected  FunctionRequest convertRequestImpl(HttpServletRequest httpRequest)
          Converts an HTTP request to a XINS request (implementation method).
protected  void convertResultImpl(FunctionResult xinsResult, HttpServletResponse httpResponse, HttpServletRequest httpRequest)
          Converts a XINS result to an HTTP response (implementation method).
protected  boolean matches(HttpServletRequest httpRequest)
          Checks if the specified request can be handled by this calling convention.
protected  FunctionRequest readInput(Element functionElem, String functionName)
          Generates the function request based the the SOAP request.
protected  Element readInputElem(Element inputElem, String functionName, String parent, Element parentElement, BasicPropertyReader inputParams)
          Parses the SOAP request element according to the rules specified in this class description.
protected  void setDataElementAttribute(ElementBuilder 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(HttpServletRequest httpRequest, FunctionResult xinsResult)
           
 
Methods inherited from class org.xins.server.SOAPCallingConvention
getAPI, getSupportedMethods, getSupportedMethods, parseXMLRequest, parseXMLRequest, 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
Description copied from class: org.xins.server.CallingConvention
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:

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

Overrides:
convertRequestImpl in class SOAPCallingConvention
Throws:
InvalidRequestException
FunctionNotSpecifiedException

readInput

protected FunctionRequest readInput(Element functionElem,
                                    String functionName)
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.
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,
                                BasicPropertyReader 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 PropertyReader 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,
                                 HttpServletRequest httpRequest)
                          throws IOException
Description copied from class: org.xins.server.CallingConvention
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
Throws:
IOException

writeResponse

protected Element writeResponse(HttpServletRequest httpRequest,
                                FunctionResult xinsResult)
                         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(ElementBuilder 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.


See http://www.xins.org/.