soap tutorial

adriani.jws.template.util
Class SoapHandler

java.lang.Object
  extended by adriani.jws.template.util.SoapHandler

public class SoapHandler
extends java.lang.Object

This class is used by the XXXMessageReceiverInOut handler to acknowledge data stored in the SOAP's header. Access to this class should be inserted in the XXXMessageReceiverInOut source file, right after the

if("my_method".equals(methodName)) {

statement. The suggested usage is:


 adriani.jws.template.util.SoapElements    elements        = adriani.jws.template.util.SoapHandler.getElements(msgContext) ;
 org.apache.axiom.om.OMElement             first_element   = elements.getFirstElement() ;
 String                                    header_value    = elements.getHeaderData() ;
 skel.setHeaderField(header_value) ;
 

The handler class allows also to manage the SOAP response when validation of the input SOAP message fails. This class offers two main methods allowing to override the Axis2 behavior: the manage() method and the getParsingError() method.

The getParsingError() method should be invoked within a skeleton class, as produced by the wsdl2java tool. The method should be called in the catch() section at the end of the parse() method, right after the

catch (javax.xml.stream.XMLStreamException e)

statement, using a code block like this:

 catch (java.lang.Exception e) {
    // Keep for testing or debug
    //adriani.jws.template.util.ParsingHandler.analyzeThrowable(e) ;
    String msg = adriani.jws.template.util.ParsingHandler.getParsingError(MY_QNAME, reader, e) ;
    throw new java.lang.Exception(msg, e) ;
 }
 

The manage() method should be invoked only by the class BtwsMessageReceiverInOut. The method should be called in the catch() section at the end of the invokeBusinessLogic() method, by substituting the original exception management, which should be something like

throw org.apache.axis2.AxisFault.makeFault(e)

The modified code block should result something like the following:

 catch (java.lang.Exception e) {
   org.apache.axiom.soap.SOAPFactory    factory         = getSOAPFactory(msgContext) ;
   org.apache.axiom.soap.SOAPEnvelope   envelope        = adriani.jws.template.util.ParsingHandler.manage(msgContext, factory) ;
   newMsgContext.setEnvelope(envelope) ;
 }
 


Field Summary
static java.lang.String BLANK
          Static final String value stored as class fields to improve performances.
static java.lang.String COLON
          Static final String value stored as class fields to improve performances.
static java.lang.String EMPTY
          Static final String value stored as class fields to improve performances.
static java.lang.String GET_INFORMATION
          Static final String value stored as class fields to improve performances.
protected static java.lang.String leadingName
          Beginning of each logging message produced by this class.
protected static WSLogger logger
          Retrieving the logger instance to be used for this class.
static java.lang.String MANAGE
          Static final String value stored as class fields to improve performances.
static java.util.regex.Pattern pattern
          Static final Pattern object stored as class field to improve performances.
static java.lang.String RET
          Static final String value stored as class fields to improve performances.
static java.lang.String TAB
          Static final String value stored as class fields to improve performances.
static java.lang.String UNKNOWN
          Static final String value stored as class fields to improve performances.
 
Constructor Summary
SoapHandler()
           
 
Method Summary
static void analyzeAxisFault(java.lang.Throwable cause)
          NOT USED AT THE MOMENT!
static java.lang.StringBuffer analyzeThrowable(java.lang.Throwable cause)
          Produce some logging information about a general Throwable object.
static java.lang.StringBuffer getElementInfo(java.lang.StackTraceElement element)
          Return some information (already formatted) about the input StackTraceElement instance.
static SoapElements getElements(MessageContext msgContext)
          Retrieves the OMElement representing the SOAP's body and the SOAP's header, fetching them from the MessageContext Axis2's handler.
static java.lang.String getEventType(int id)
          Recognize the integer code describing the XML element pointed by a XMLStreamReader instance and return a string message describing the XML element (or event) type.
static java.lang.StackTraceElement getFirstElement(java.lang.Throwable cause)
          Return the first StackTraceElement instance from the stack trace element bound to the input Throwable object.
static java.lang.StringBuffer getFirstElementInfo(java.lang.Throwable cause)
          Return some information (already formatted) about the first StackTraceElement of the the input Throwable stack array.
static java.lang.String getParsingError(javax.xml.namespace.QName qName, javax.xml.stream.XMLStreamReader reader, java.lang.Throwable cause)
          Get detailed information about the XML validation failure from the Axis2 stream reader, in this case a XMLStreamReader object, then uses these information to log a proper ERROR message in the log system and to produce the string message describing the error.
static java.lang.String getSOAPMethod(javax.xml.namespace.QName qName)
          Return the local part of the input ADBBean object that generates the parsing error.
static SOAPEnvelope manage(MessageContext msgContext, SOAPFactory factory)
          Identifies the current SOAP operation (the SOAP method) in order to choose the proper output wrapper to be used to produce the SOAP envelope.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

pattern

public static final java.util.regex.Pattern pattern
Static final Pattern object stored as class field to improve performances.


RET

public static final java.lang.String RET
Static final String value stored as class fields to improve performances.

See Also:
Constant Field Values

TAB

public static final java.lang.String TAB
Static final String value stored as class fields to improve performances.

See Also:
Constant Field Values

COLON

public static final java.lang.String COLON
Static final String value stored as class fields to improve performances.

See Also:
Constant Field Values

EMPTY

public static final java.lang.String EMPTY
Static final String value stored as class fields to improve performances.

See Also:
Constant Field Values

BLANK

public static final java.lang.String BLANK
Static final String value stored as class fields to improve performances.

See Also:
Constant Field Values

UNKNOWN

public static final java.lang.String UNKNOWN
Static final String value stored as class fields to improve performances.

See Also:
Constant Field Values

MANAGE

public static final java.lang.String MANAGE
Static final String value stored as class fields to improve performances.

See Also:
Constant Field Values

GET_INFORMATION

public static final java.lang.String GET_INFORMATION
Static final String value stored as class fields to improve performances.

See Also:
Constant Field Values

logger

protected static WSLogger logger
Retrieving the logger instance to be used for this class.


leadingName

protected static final java.lang.String leadingName
Beginning of each logging message produced by this class.

See Also:
Constant Field Values
Constructor Detail

SoapHandler

public SoapHandler()
Method Detail

getElements

public static SoapElements getElements(MessageContext msgContext)
Retrieves the OMElement representing the SOAP's body and the SOAP's header, fetching them from the MessageContext Axis2's handler. This MUST BE done before invoking others "Axis2 stuff" because the MessageContext has a very short live and cannot be parsed twice.
Body and header should be (also) instances of following interfaces:

header : interface org.apache.axiom.soap.SOAPHeader
body : interface org.apache.axiom.soap.SOAPBody

Parameters:
msgContext - the input message context used to invoke the business logic
Returns:
the SoapElements wrapper containing all envelope's elements
Throws:
AxisFault - if an ADBException occurs while producing the SOAP envelope

manage

public static SOAPEnvelope manage(MessageContext msgContext,
                                  SOAPFactory factory)
                           throws AxisFault
Identifies the current SOAP operation (the SOAP method) in order to choose the proper output wrapper to be used to produce the SOAP envelope. By this mechanism we return a complete SOAPEnvelope object that can be set on the newMsgContext instance. For the time being this method relies only of one wrapper: the WrapperSearchOut.
This wrapper is used to invoke the wrapper.getElement() method, in order to get the proper ADBBean instance to be added the the SOAP envelope's body.

Parameters:
msgContext - the input message context used to invoke the business logic
factory - a SOAP factory retrieved using getSOAPFactory(msgContext)
Returns:
the SOAP envelope that can be set on the newMsgContext object
Throws:
AxisFault - if an ADBException occurs while producing the SOAP envelope

getParsingError

public static java.lang.String getParsingError(javax.xml.namespace.QName qName,
                                               javax.xml.stream.XMLStreamReader reader,
                                               java.lang.Throwable cause)
Get detailed information about the XML validation failure from the Axis2 stream reader, in this case a XMLStreamReader object, then uses these information to log a proper ERROR message in the log system and to produce the string message describing the error. The string message could be used to set the SOAP response: this is not necessary at the moment, since the error management is completely performed by the manage() method.

Remark: if the verbose flag is true some detailed information about the XMLStreamReader object are also logged using the INFO logger label.

Parameters:
qName - the qualified name of the input ADBBean who generates the error
reader - the XMLStreamReader used to parse the SOAP request
cause - an instance of a general Throwable object
Returns:
a string describing the error, usually taken from the ErrorMessage class

getSOAPMethod

public static java.lang.String getSOAPMethod(javax.xml.namespace.QName qName)
Return the local part of the input ADBBean object that generates the parsing error.

Parameters:
qName - the qualified name of an ADBBean instance
Returns:
the name of the ADBBean instance

getEventType

public static java.lang.String getEventType(int id)
Recognize the integer code describing the XML element pointed by a XMLStreamReader instance and return a string message describing the XML element (or event) type. The mapping between integers and string messages is retrieved from the constants defined in the javax.xml.stream.XMLStreamConstants class.

Parameters:
id - the integer number retrieved from the reader.getEventType() method
Returns:
the string message describing the event: for example "1" should be "START_ELEMENT"

getFirstElement

public static java.lang.StackTraceElement getFirstElement(java.lang.Throwable cause)
Return the first StackTraceElement instance from the stack trace element bound to the input Throwable object.

Parameters:
cause - an instance of a general Throwable object
Returns:
a valid StackTraceElement instance

getFirstElementInfo

public static java.lang.StringBuffer getFirstElementInfo(java.lang.Throwable cause)
Return some information (already formatted) about the first StackTraceElement of the the input Throwable stack array. These information are retrieved by invoking the getElementInfo() method.

Parameters:
cause - an instance of a general Throwable object
Returns:
some information (already formatted) about the first stack trace element

getElementInfo

public static java.lang.StringBuffer getElementInfo(java.lang.StackTraceElement element)
Return some information (already formatted) about the input StackTraceElement instance.

Parameters:
element - a valid StackTraceElement instance
Returns:
some information (already formatted) about the stack trace element

analyzeThrowable

public static java.lang.StringBuffer analyzeThrowable(java.lang.Throwable cause)
Produce some logging information about a general Throwable object.
This method can be used at the end of the method fromOM() of the message receiver class (in this case a XXXMessageReceiverInOut instance) in order to obtain information about the general Exception used to invoke the org.apache.axis2.AxisFault.makeFault(e) method. Example:

 catch (java.lang.Exception e) {
        //adriani.jws.template.util.ParsingHandler.analyzeThrowable(e) ;        // Keep for testing or debug
        throw org.apache.axis2.AxisFault.makeFault(e) ;                                         // Original code
        //throw adriani.jws.template.util.ParsingException.makeFault(e) ;       // Modified code
 }
 

Parameters:
cause - an instance of a general Throwable object
Returns:
the formatted string message containing the analysis results

analyzeAxisFault

public static void analyzeAxisFault(java.lang.Throwable cause)
NOT USED AT THE MOMENT!

This method it's never invoked because the classes generated by the "wsdl to java" Axis2 tool do not create any AxisFault exception when parsing the SOAP request, neither when invoking the skeleton business logic. The AxisFault faults are created only by the BtwsMessageReceiverInOut handler class, after "the point" where we want to insert the management of general parsing errors (and the "too late").

Parameters:
cause - an instance of a general Throwable object

Build 18/09/2012

Morpheus Quality Technologies - Making the Zion software
Copyright © 2009-2013 Morpheus Quality Technologies. All Rights Reserved