org.apache.axis2.jaxws.message.impl
Class XMLPartBase

java.lang.Object
  org.apache.axis2.jaxws.message.impl.XMLPartBase

All Implemented Interfaces:

XMLPart

Direct Known Subclasses:

XMLPartImpl

public abstract class XMLPartBase
extends java.lang.Object
implements XMLPart

XMLPartBase class for an XMLPart An XMLPart is an abstraction of the xml portion of the message. The actual representation can be in one of three different forms: * An OM tree * A SAAJ SOAPEnvelope * An XMLSpine (an optimized representation of the message) The representation is stored in the private variable (content)

The representation changes as the Message flows through the JAX-WS framework. For example, here is a typical flow on the inbound case: a) Message is built from OM (representation: OM) b) Message flows into SOAP Handler chain (representation: OM->SOAPEnvelope) c) Message flows out of the SOAP Handler chain d) Message flows into the logical dispatch processing (representation: SOAPEnvelope->XMLSpine)

The key to performance is the implementation of the transformations between OM, SAAJ SOAPEnvelope and XMLSpine. This base class defines all of the methods that are required on an XMLPart, the actual transformations are provided by the derived class. This division of work allows the derived class to concentrate on the optimization of the transformations. For example, the derived class may implement XMLSpine -> OM using OMObjectWrapperElement constructs...thus avoid expensive parsing.

Here are the methods that the derived XMLPart should implement. OMElement _convertSE2OM(SOAPEnvelope se) OMElement _convertSpine2OM(XMLSpine spine) SOAPEnvelope _convertOM2SE(OMElement om) SOAPEnvelope _convertSpine2SE(XMLSpine spine) XMLSpine _convertOM2Spine(OMElement om) XMLSpine _convertSE2Spine(SOAPEnvelope se) XMLSpine _createSpine(Protocol protocol)

NOTE: For XML/HTTP (REST), a SOAP 1.1. Envelope is built and the rest payload is placed in the body. This purposely mimics the Axis2 implementation.

See Also:

XMLPart, XMLPartImpl

Method Summary

protected abstract SOAPEnvelope	_convertOM2SE(org.apache.axiom.om.OMElement om) Convert OM tree into a SOAPEnvelope
protected abstract org.apache.axis2.jaxws.message.impl.XMLSpine	_convertOM2Spine(org.apache.axiom.om.OMElement om) Convert OM into XMLSpine
protected abstract org.apache.axiom.om.OMElement	_convertSE2OM(SOAPEnvelope se) Convert SOAPEnvelope into an OM tree
protected abstract org.apache.axis2.jaxws.message.impl.XMLSpine	_convertSE2Spine(SOAPEnvelope se) Convert SOAPEnvelope into XMLSPine
protected abstract org.apache.axiom.om.OMElement	_convertSpine2OM(org.apache.axis2.jaxws.message.impl.XMLSpine spine) Convert XMLSpine into an OM tree
protected abstract SOAPEnvelope	_convertSpine2SE(org.apache.axis2.jaxws.message.impl.XMLSpine spine) Convert XMLSpine into a SOAPEnvelope
protected static org.apache.axis2.jaxws.message.impl.XMLSpine	_createSpine(Protocol protocol, SOAPBinding.Style style, int indirection, org.apache.axiom.om.OMElement payload) Create an empty, default spine for the specificed protocol
void	appendHeaderBlock(java.lang.String namespace, java.lang.String localPart, Block block) appendHeaderBlock Append the block to the list of header blocks.
void	close() Used primarily to ensure the parser is forwarded to the end so it can be closed.
org.apache.axiom.om.OMElement	getAsOMElement() getAsOMElement Get the xml part as a read/write OM...note this returns an OM SOAPEnvelope for all protocols...even REST
SOAPEnvelope	getAsSOAPEnvelope() getAsEnvelope Get the xml part as a read/write SOAPEnvelope
Block	getBodyBlock(int index, java.lang.Object context, BlockFactory blockFactory) getBodyBlock Get the body block at the specificed index.
Block	getBodyBlock(java.lang.Object context, BlockFactory blockFactory) getBodyBlock Get the single Body Block.
Block	getHeaderBlock(java.lang.String namespace, java.lang.String localPart, java.lang.Object context, BlockFactory blockFactory) getHeaderBlock Get the firstheader block with the specified name.
java.util.List<Block>	getHeaderBlocks(java.lang.String namespace, java.lang.String localPart, java.lang.Object context, BlockFactory blockFactory, org.apache.axiom.soap.RolePlayer rolePlayer) getHeaderBlock Get the header blocks with the specified name The BlockFactory and object context are passed in to help create the proper kind of block.
java.util.Set<QName>	getHeaderQNames()
int	getIndirection() Get indirection.
int	getNumBodyBlocks() getNumBodyBlocks Calling this method will cache the OM.
int	getNumHeaderBlocks() getNumHeaderBlocks
QName	getOperationElement()
Message	getParent() getParent Get the Message object that this XMLPart is attached to, if it is attached to one at all.
Protocol	getProtocol() Get the protocol for this Message (soap11, soap12, etc.)
SOAPBinding.Style	getStyle()
XMLFault	getXMLFault() If the XMLPart represents a fault, an XMLFault is returned which describes the fault in a protocol agnostic manner
java.lang.String	getXMLPartContentType() The representation of the XMLPart may be in a number of different forms.
javax.xml.stream.XMLStreamReader	getXMLStreamReader(boolean consume) Get the XMLStreamReader represented by this Message for the xml part
boolean	isConsumed() isConsumed Return true if the part is consumed.
boolean	isFault() Determines whether the XMLPart represents a Fault
void	outputTo(javax.xml.stream.XMLStreamWriter writer, boolean consume) Write out the Message
void	removeBodyBlock(int index) removeBodyBlock Removes the indicated BodyBlock
void	removeHeaderBlock(java.lang.String namespace, java.lang.String localPart) removeHeaderBlock Removes all header blocks with this namespace/localpart
void	setBodyBlock(Block block) setBodyBlock Set this as block as the single block for the message.
void	setBodyBlock(int index, Block block) setBodyBlock Set the block at the specified index Once set, the Message owns the block.
void	setHeaderBlock(java.lang.String namespace, java.lang.String localPart, Block block) setHeaderBlock replaces the first existing header block with this new block.
void	setIndirection(int indirection) Set indirection.
void	setOperationElement(QName operationQName) Set the operation element qname.
void	setParent(Message p) setParent Set the Message object that will hold this XMLPart
void	setStyle(SOAPBinding.Style style) Set the Style.
void	setXMLFault(XMLFault xmlFault) Change the XMLPart so that it represents the fault described by XMLFault
java.lang.String	traceString(java.lang.String indent) Get a traceString...the trace string dumps the contents of the Block without forcing an underlying ill-performant transformation of the message.

Methods inherited from class java.lang.Object

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

Method Detail

getAsOMElement

public org.apache.axiom.om.OMElement getAsOMElement()
                                             throws WebServiceException

Description copied from interface: XMLPart

getAsOMElement Get the xml part as a read/write OM...note this returns an OM SOAPEnvelope for all protocols...even REST

Specified by:

getAsOMElement in interface XMLPart

Returns:

OMElement

Throws:

WebServiceException

getAsSOAPEnvelope

public SOAPEnvelope getAsSOAPEnvelope()
                               throws WebServiceException

Description copied from interface: XMLPart

getAsEnvelope Get the xml part as a read/write SOAPEnvelope

Specified by:

getAsSOAPEnvelope in interface XMLPart

Returns:

SOAPEnvelope

Throws:

WebServiceException

getProtocol

public Protocol getProtocol()

Description copied from interface: XMLPart

Get the protocol for this Message (soap11, soap12, etc.)

Specified by:

getProtocol in interface XMLPart

Returns:

Protocl

getStyle

public SOAPBinding.Style getStyle()

Specified by:

getStyle in interface XMLPart

Returns:

the Style (document or rpc)

getIndirection

public int getIndirection()

Description copied from interface: XMLPart

Get indirection. Used to force the code to look for blocks at a particular location. For DOCUMENT the default is 0 For RPC the default is 1 This method is used to override these settings for special cases.

Specified by:

getIndirection in interface XMLPart

Returns:

indirection (0 or 1)

setStyle

public void setStyle(SOAPBinding.Style style)
              throws WebServiceException

Description copied from interface: XMLPart

Set the Style. If the style is DOCUMENT, the body blocks are located underneath the body element. If the style is set to RPC, then the body blocks are located underneath the rpc operation.

Specified by:

setStyle in interface XMLPart

Parameters:

style - Style

Throws:

WebServiceException

See Also:

indirection

setIndirection

public void setIndirection(int indirection)

Description copied from interface: XMLPart

Set indirection. Used to force the code to look for blocks at a particular location. For DOCUMENT the default is 0 For RPC the default is 1 This method is used to override these settings for special cases.

Specified by:

setIndirection in interface XMLPart

Parameters:

indirection - (0 or 1)

getOperationElement

public QName getOperationElement()
                          throws WebServiceException

Specified by:

getOperationElement in interface XMLPart

Returns:

the QName of the operation element if Style.rpc. Otherwise null

Throws:

WebServiceException

setOperationElement

public void setOperationElement(QName operationQName)
                         throws WebServiceException

Description copied from interface: XMLPart

Set the operation element qname. The operation qname is only used if Style.rpc

Specified by:

setOperationElement in interface XMLPart

Throws:

WebServiceException

getXMLPartContentType

public java.lang.String getXMLPartContentType()

Description copied from interface: XMLPart

The representation of the XMLPart may be in a number of different forms. Currently the forms are UNKNOWN, OM, SOAPENVELOPE, and SPINE. This method returns a String containing one of these types. This method should only be used for trace and testing purposes. The consumer of a Message should not make any decisions based on the representation of the XMLPart

Specified by:

getXMLPartContentType in interface XMLPart

Returns:

String

getXMLStreamReader

public javax.xml.stream.XMLStreamReader getXMLStreamReader(boolean consume)
                                                    throws WebServiceException

Description copied from interface: XMLPart

Get the XMLStreamReader represented by this Message for the xml part

Specified by:

getXMLStreamReader in interface XMLPart

Parameters:

consume - true if this is the last request on the Message

Returns:

XMLStreamReader

Throws:

WebServiceException

getXMLFault

public XMLFault getXMLFault()
                     throws WebServiceException

Description copied from interface: XMLPart

If the XMLPart represents a fault, an XMLFault is returned which describes the fault in a protocol agnostic manner

Specified by:

getXMLFault in interface XMLPart

Returns:

the XMLFault object or null

Throws:

WebServiceException

See Also:

XMLFault

setXMLFault

public void setXMLFault(XMLFault xmlFault)
                 throws WebServiceException

Description copied from interface: XMLPart

Change the XMLPart so that it represents the fault described by XMLFault

Specified by:

setXMLFault in interface XMLPart

Throws:

WebServiceException

See Also:

XMLFault

isFault

public boolean isFault()
                throws WebServiceException

Description copied from interface: XMLPart

Determines whether the XMLPart represents a Fault

Specified by:

isFault in interface XMLPart

Returns:

true if the message represents a fault

Throws:

WebServiceException

isConsumed

public boolean isConsumed()

Description copied from interface: XMLPart

isConsumed Return true if the part is consumed. Once consumed, the information in the part is no longer available.

Specified by:

isConsumed in interface XMLPart

Returns:

true if the block is consumed (a method was called with consume=true)

outputTo

public void outputTo(javax.xml.stream.XMLStreamWriter writer,
                     boolean consume)
              throws javax.xml.stream.XMLStreamException,
                     WebServiceException

Description copied from interface: XMLPart

Write out the Message

Specified by:

outputTo in interface XMLPart

Parameters:

writer - XMLStreamWriter

consume - true if this is the last request on the block.

Throws:

WebServiceException

javax.xml.stream.XMLStreamException

traceString

public java.lang.String traceString(java.lang.String indent)

Description copied from interface: XMLPart

Get a traceString...the trace string dumps the contents of the Block without forcing an underlying ill-performant transformation of the message.

Specified by:

traceString in interface XMLPart

Returns:

String containing trace information

getBodyBlock

public Block getBodyBlock(int index,
                          java.lang.Object context,
                          BlockFactory blockFactory)
                   throws WebServiceException

Description copied from interface: XMLPart

getBodyBlock Get the body block at the specificed index. The BlockFactory and object context are passed in to help create the proper kind of block. Calling this method will cache the OM. Avoid it in performant situations.

Specified by:

getBodyBlock in interface XMLPart

Returns:

Block or null

Throws:

WebServiceException

See Also:

getBodyBlock

getBodyBlock

public Block getBodyBlock(java.lang.Object context,
                          BlockFactory blockFactory)
                   throws WebServiceException

Description copied from interface: XMLPart

getBodyBlock Get the single Body Block. The BlockFactory and object context are passed in to help create the proper kind of block. This method should only be invoked when it is known that there is zero or one block.

Specified by:

getBodyBlock in interface XMLPart

Returns:

Block or null

Throws:

WebServiceException

getHeaderBlock

public Block getHeaderBlock(java.lang.String namespace,
                            java.lang.String localPart,
                            java.lang.Object context,
                            BlockFactory blockFactory)
                     throws WebServiceException

Description copied from interface: XMLPart

getHeaderBlock Get the firstheader block with the specified name. The BlockFactory and object context are passed in to help create the proper kind of block.

Specified by:

getHeaderBlock in interface XMLPart

Returns:

Block

Throws:

WebServiceException

getHeaderQNames

public java.util.Set<QName> getHeaderQNames()

Specified by:

getHeaderQNames in interface XMLPart

Returns:

QNames of headers

getHeaderBlocks

public java.util.List<Block> getHeaderBlocks(java.lang.String namespace,
                                             java.lang.String localPart,
                                             java.lang.Object context,
                                             BlockFactory blockFactory,
                                             org.apache.axiom.soap.RolePlayer rolePlayer)
                                      throws WebServiceException

Description copied from interface: XMLPart

getHeaderBlock Get the header blocks with the specified name The BlockFactory and object context are passed in to help create the proper kind of block.

Specified by:

getHeaderBlocks in interface XMLPart

Parameters:

namespace - uri of header

localPart - local name of header

context - context for blockFactory

blockFactory - kind of factory (i.e. JAXB)

Returns:

List

Throws:

WebServiceException

getNumBodyBlocks

public int getNumBodyBlocks()
                     throws WebServiceException

Description copied from interface: XMLPart

getNumBodyBlocks Calling this method will cache the OM. Avoid it in performant situations.

Specified by:

getNumBodyBlocks in interface XMLPart

Returns:

number of body blocks

Throws:

WebServiceException

getNumHeaderBlocks

public int getNumHeaderBlocks()
                       throws WebServiceException

Description copied from interface: XMLPart

getNumHeaderBlocks

Specified by:

getNumHeaderBlocks in interface XMLPart

Returns:

number of header blocks

Throws:

WebServiceException

removeBodyBlock

public void removeBodyBlock(int index)
                     throws WebServiceException

Description copied from interface: XMLPart

removeBodyBlock Removes the indicated BodyBlock

Specified by:

removeBodyBlock in interface XMLPart

Throws:

WebServiceException

removeHeaderBlock

public void removeHeaderBlock(java.lang.String namespace,
                              java.lang.String localPart)
                       throws WebServiceException

Description copied from interface: XMLPart

removeHeaderBlock Removes all header blocks with this namespace/localpart

Specified by:

removeHeaderBlock in interface XMLPart

Throws:

WebServiceException

setBodyBlock

public void setBodyBlock(int index,
                         Block block)
                  throws WebServiceException

Description copied from interface: XMLPart

setBodyBlock Set the block at the specified index Once set, the Message owns the block. You must use the getBodyBlock method to access it.

Specified by:

setBodyBlock in interface XMLPart

Throws:

WebServiceException

setBodyBlock

public void setBodyBlock(Block block)
                  throws WebServiceException

Description copied from interface: XMLPart

setBodyBlock Set this as block as the single block for the message.

Specified by:

setBodyBlock in interface XMLPart

Throws:

WebServiceException

setHeaderBlock

public void setHeaderBlock(java.lang.String namespace,
                           java.lang.String localPart,
                           Block block)
                    throws WebServiceException

Description copied from interface: XMLPart

setHeaderBlock replaces the first existing header block with this new block. If there is no existing header block, one is added to the end of the headers

Specified by:

setHeaderBlock in interface XMLPart

Throws:

WebServiceException

appendHeaderBlock

public void appendHeaderBlock(java.lang.String namespace,
                              java.lang.String localPart,
                              Block block)
                       throws WebServiceException

Description copied from interface: XMLPart

appendHeaderBlock Append the block to the list of header blocks. The Message owns the block. You must use the getHeaderBlock method to access it.

Specified by:

appendHeaderBlock in interface XMLPart

Throws:

WebServiceException

getParent

public Message getParent()

Description copied from interface: XMLPart

getParent Get the Message object that this XMLPart is attached to, if it is attached to one at all.

Specified by:

getParent in interface XMLPart

Returns:

setParent

public void setParent(Message p)

Description copied from interface: XMLPart

setParent Set the Message object that will hold this XMLPart

Specified by:

setParent in interface XMLPart

_convertSE2OM

protected abstract org.apache.axiom.om.OMElement _convertSE2OM(SOAPEnvelope se)
                                                        throws WebServiceException

Convert SOAPEnvelope into an OM tree

Parameters:

se - SOAPEnvelope

Returns:

OM

Throws:

WebServiceException

_convertSpine2OM

protected abstract org.apache.axiom.om.OMElement _convertSpine2OM(org.apache.axis2.jaxws.message.impl.XMLSpine spine)
                                                           throws WebServiceException

Convert XMLSpine into an OM tree

Parameters:

spine - XMLSpine

Returns:

OM

Throws:

WebServiceException

_convertOM2SE

protected abstract SOAPEnvelope _convertOM2SE(org.apache.axiom.om.OMElement om)
                                       throws WebServiceException

Convert OM tree into a SOAPEnvelope

Parameters:

om -

Returns:

SOAPEnvelope

Throws:

WebServiceException

_convertSpine2SE

protected abstract SOAPEnvelope _convertSpine2SE(org.apache.axis2.jaxws.message.impl.XMLSpine spine)
                                          throws WebServiceException

Convert XMLSpine into a SOAPEnvelope

Parameters:

spine -

Returns:

SOAPEnvelope

Throws:

WebServiceException

_convertOM2Spine

protected abstract org.apache.axis2.jaxws.message.impl.XMLSpine _convertOM2Spine(org.apache.axiom.om.OMElement om)
                                                                          throws WebServiceException

Convert OM into XMLSpine

Parameters:

om -

Returns:

Throws:

WebServiceException

_convertSE2Spine

protected abstract org.apache.axis2.jaxws.message.impl.XMLSpine _convertSE2Spine(SOAPEnvelope se)
                                                                          throws WebServiceException

Convert SOAPEnvelope into XMLSPine

Parameters:

SOAPEnvelope -

Returns:

XMLSpine

Throws:

WebServiceException

_createSpine

protected static org.apache.axis2.jaxws.message.impl.XMLSpine _createSpine(Protocol protocol,
                                                                           SOAPBinding.Style style,
                                                                           int indirection,
                                                                           org.apache.axiom.om.OMElement payload)
                                                                    throws WebServiceException

Create an empty, default spine for the specificed protocol

Parameters:

protocol -

Returns:

Throws:

WebServiceException

close

public void close()

Description copied from interface: XMLPart

Used primarily to ensure the parser is forwarded to the end so it can be closed.

Specified by:

close in interface XMLPart