org.apache.muse.ws.addressing
Class MessageHeaders

java.lang.Object
  extended by org.apache.muse.ws.addressing.MessageHeaders
All Implemented Interfaces:
XmlSerializable

public class MessageHeaders
extends Object
implements XmlSerializable

MessageHeaders provides WS-Addressing processing for SOAP message headers. It can be used to parse SOAP headers according to WS-A spec and read the values or create a new set of headers that can be serialized to a set of valid SOAP headers.

This class references the W3C DOM API rather than the SAAJ API because SOAPElements can usually be converted into DOM Elements very easily, but having a DOM Element does not mean that the user code has access to (or wants access to) the SAAJ API and its SOAP factories.

Author:
Dan Jemiolo (danj)
See Also:
EndpointReference

Constructor Summary
MessageHeaders(Element soapHeaders)
          Creates a valid set of WS-A message headers from the given SOAP Header.
MessageHeaders(EndpointReference to, String action)
          Creates a new set of WS-A message headers targeted to the given EPR and Action.
 
Method Summary
 MessageHeaders createFaultHeaders()
          Returns a new set of WS-A message headers based on this object; the headers returned can be used when replying to a message with a fault.
 MessageHeaders createReplyHeaders()
          Returns a new set of WS-A message headers based on this object; the headers returned can be used when replying to a message (no fault).
 String getAction()
           
 Element getCustomHeader(QName elementName)
          This method is useful if you are only expecting one instance of a given SOAP header element and do not want to sort through a Collection or Iterator just to get one item.
 Collection getCustomHeaderNames()
           
 Collection getCustomHeaders(QName elementName)
           
 EndpointReference getFaultToAddress()
           
 EndpointReference getFromAddress()
           
 String getMessageID()
           
 String getMethodName()
           
 String getRelationship()
           
 QName getRelationshipType()
           
 EndpointReference getReplyToAddress()
           
 EndpointReference getToAddress()
           
protected  void setAction(String action)
           
 void setFaultToAddress(EndpointReference faultTo)
           
 void setFromAddress(EndpointReference from)
           
protected  void setMessageID(String messageID)
           
 void setRelationship(String relationship)
           
 void setReplyToAddress(EndpointReference replyTo)
           
protected  void setToAddress(EndpointReference to)
           
protected  void throwInvalidAddressingHeaderFault(String message)
           
 String toString()
           
 Element toXML()
          Converts this object into an XML representation, as defined by its related schema or specification.
 Element toXML(Document doc)
          Converts this object into an XML representation, as defined by its related schema or specification.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MessageHeaders

public MessageHeaders(Element soapHeaders)
               throws SoapFault
Creates a valid set of WS-A message headers from the given SOAP Header. The wsa:To URI and reference parameter elements become an EPR; this EPR can be used to determine which WS-resource is being targeted.

An appropriate set of reply headers can be generated with the createReplyHeaders(URI) and createFaultHeaders() methods, assuming the SOAP Header included the appropriate wsa:From, wsa:ReplyTo, or wsa:FaultTo EPR.

Parameters:
soapHeaders - The Element representing a SOAP envelope's Header. The Header should contain all of the required WS-A elements.
Throws:
SoapFault -
  • If either the wsa:To, wsa:From, wsa:ReplyTo, or wsa:FaultTo XML is invalid according to the WS-A EPR definition.
  • If either the wsa:To, wsa:MessageID, wsa:RelatesTo, or wsa:Action value is not a valid URI.
  • If either the wsa:To, wsa:MessageID, or wsa:Action value is undefined.
See Also:
createFaultHeaders(), createReplyHeaders()

MessageHeaders

public MessageHeaders(EndpointReference to,
                      String action)
Creates a new set of WS-A message headers targeted to the given EPR and Action. This constructor creates its own unique wsa:MessageID.

Parameters:
to - The EPR that will supply the URI for wsa:To.
action - The wsa:Action URI.
Method Detail

createFaultHeaders

public MessageHeaders createFaultHeaders()
Returns a new set of WS-A message headers based on this object; the headers returned can be used when replying to a message with a fault. The headers will be targeted to the wsa:FaultTo EPR and the WS-A fault action URI. If there is no wsa:FaultTo, wsa:From or the WS-A anonymous EPR is used.

Note: This method should not be used to create headers for "normal" responses - that is done with createReplyHeaders(URI).

Returns:
A new MessageHeaders where:
  • the wsa:To is the URI of this object's wsa:FaultTo, wsa:From, or the anonymous EPR
  • the wsa:From is this object's wsa:To EPR
  • the wsa:RelatesTo is the URI of this object's wsa:MessageID
  • the wsa:Action is the standard WS-A fault URI.
See Also:
createReplyHeaders(), getFaultToAddress(), setFaultToAddress(EndpointReference), WsaConstants.FAULT_URI

createReplyHeaders

public MessageHeaders createReplyHeaders()
Returns a new set of WS-A message headers based on this object; the headers returned can be used when replying to a message (no fault). The headers will be targeted to the wsa:ReplyTo EPR. If there is no wsa:ReplyTo, wsa:From or the WS-A anonymous EPR is used.

Note: This method should not be used to create headers for responses where a fault has occurred - that should be done with createFaultHeaders().

Returns:
A new MessageHeaders where:
  • the wsa:To is the URI of this object's wsa:ReplyTo, wsa:From, or the anonymous EPR
  • the wsa:From is this object's wsa:To EPR
  • the wsa:RelatesTo is the URI of this object's wsa:MessageID
  • the wsa:Action is the current URI with a "Response" suffix.
See Also:
getReplyToAddress(), setReplyToAddress(EndpointReference)

getAction

public String getAction()
Returns:
The wsa:Action URI. This is required value.

getCustomHeader

public Element getCustomHeader(QName elementName)
This method is useful if you are only expecting one instance of a given SOAP header element and do not want to sort through a Collection or Iterator just to get one item.

Parameters:
elementName - The name of the non-WS-A SOAP header to return.
Returns:
The first DOM Element found with the given name, or null if no such element was found.

getCustomHeaders

public Collection getCustomHeaders(QName elementName)
Parameters:
elementName - The name of the non-WS-A SOAP header(s) to return.
Returns:
A collection of DOM Elements with the given name. The collection may be empty.

getCustomHeaderNames

public Collection getCustomHeaderNames()
Returns:
A collection of QNames, one for each SOAP header that a) does not have the WS-A namespace, and b) is not a WS-A reference parameter. The collection may be empty.

getFaultToAddress

public EndpointReference getFaultToAddress()
Returns:
The wsa:FaultTo EPR. The method returns null if the value is not set.

getFromAddress

public EndpointReference getFromAddress()
Returns:
The wsa:From EPR. The method returns null if the value is not set.

getMessageID

public String getMessageID()
Returns:
The unique wsa:MessageID UUID. This is a required value.

getMethodName

public String getMethodName()
Returns:
The identifier found after the last slash in the wsa:Action URI. If the URI is 'http://example.com/spec/DoStuff', the value that is returned is 'DoStuff'.

getRelationship

public String getRelationship()
Returns:
The wsa:RelatesTo value. The method returns null if the value is not set. wsa:RelatesTo is a UUID that maps to another MessageHeader's wsa:MessageID.

getRelationshipType

public QName getRelationshipType()
Returns:
This method always returns WsaUtils.REPLY_RELATIONSHIP_QNAME.
See Also:
WsaConstants.REPLY_RELATIONSHIP_QNAME

getReplyToAddress

public EndpointReference getReplyToAddress()
Returns:
The wsa:ReplyTo EPR. The method returns null if the value is not set.

getToAddress

public EndpointReference getToAddress()
Returns:
An EPR representing the wsa:To URI and the reference properties defined in the SOAP Header (if any). This is a required value.

setAction

protected void setAction(String action)
Parameters:
action - The wsa:Action URI. This cannot be null.

setFaultToAddress

public void setFaultToAddress(EndpointReference faultTo)
Parameters:
faultTo - The wsa:FaultTo EPR - if non-null, a copy of EPR will be made, so modifications to the original will have no effect on this set of headers.

setFromAddress

public void setFromAddress(EndpointReference from)
Parameters:
from - The wsa:From EPR - if non-null, a copy of EPR will be made, so modifications to the original will have no effect on this set of headers.

setMessageID

protected void setMessageID(String messageID)
Parameters:
messageID - The wsa:MessageID. This cannot be null.

setRelationship

public void setRelationship(String relationship)
Parameters:
relationship - The wsa:RelatesTo ID. This cannot be null;

setReplyToAddress

public void setReplyToAddress(EndpointReference replyTo)
Parameters:
replyTo - The wsa:ReplyTo EPR - if non-null, a copy of EPR will be made, so modifications to the original will have no effect on this set of headers.

setToAddress

protected void setToAddress(EndpointReference to)
Parameters:
to - An EPR with the address value for the wsa:To URI. This cannot be null. No copy of the given EPR is made, so subsequent modifications to it will affect this object.

throwInvalidAddressingHeaderFault

protected void throwInvalidAddressingHeaderFault(String message)
                                          throws SoapFault
Throws:
SoapFault

toString

public String toString()
Overrides:
toString in class Object
Returns:
An XML string representing the collection of WS-A headers. The XML would be a valid SOAP Header element.

toXML

public Element toXML()
Description copied from interface: XmlSerializable
Converts this object into an XML representation, as defined by its related schema or specification. The format of the XML is dependent on the concrete type.

Specified by:
toXML in interface XmlSerializable
Returns:
An XML representation of this object.
See Also:
toXML(Document)

toXML

public Element toXML(Document doc)
Description copied from interface: XmlSerializable
Converts this object into an XML representation, as defined by its related schema or specification. The format of the XML is dependent on the concrete type.

Specified by:
toXML in interface XmlSerializable
Parameters:
doc - The XML Document to use when creating new elements for the SOAP Header XML. The elements that are created will not be appended to this Document.
Returns:
A SOAP Header element with all of the valid WS-A headers as child elements. There is no guarantee on the order of the WS-A headers. All reference parameters and properties in the wsa:To EPR will be appended as children of the root SOAP Header element.
See Also:
SoapConstants.HEADER_QNAME


Copyright © 2005-2011 Apache Web Services - Muse. All Rights Reserved.