Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.muse.ws.addressing
Class MessageHeaders

    java.lang.Object
      org.apache.muse.ws.addressing.MessageHeaders

All Implemented Interfaces:
  XmlSerializable

public class MessageHeaders
extends java.lang.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(org.w3c.dom.Element soapHeaders)` Creates a valid set of WS-A message headers from the given SOAP Header.
`MessageHeaders(EndpointReference to, java.lang.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).
`java.lang.String` | `getAction()`
`org.w3c.dom.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.
`java.util.Collection` | `getCustomHeaderNames()`
`java.util.Collection` | `getCustomHeaders(QName elementName)`
`EndpointReference` | `getFaultToAddress()`
`EndpointReference` | `getFromAddress()`
`java.lang.String` | `getMessageID()`
`java.lang.String` | `getMethodName()`
`java.lang.String` | `getRelationship()`
`QName` | `getRelationshipType()`
`EndpointReference` | `getReplyToAddress()`
`EndpointReference` | `getToAddress()`
`protected void` | `setAction(java.lang.String action)`
`void` | `setFaultToAddress(EndpointReference faultTo)`
`void` | `setFromAddress(EndpointReference from)`
`protected void` | `setMessageID(java.lang.String messageID)`
`void` | `setRelationship(java.lang.String relationship)`
`void` | `setReplyToAddress(EndpointReference replyTo)`
`protected void` | `setToAddress(EndpointReference to)`
`protected void` | `throwInvalidAddressingHeaderFault(java.lang.String message)`
`java.lang.String` | `toString()`
`org.w3c.dom.Element` | `toXML()` Converts this object into an XML representation, as defined by its related schema or specification.
`org.w3c.dom.Element` | `toXML(org.w3c.dom.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(org.w3c.dom.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,
                          java.lang.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 java.lang.String getAction()

  Returns:
    The wsa:Action URI. This is required value.

### getCustomHeader

    public org.w3c.dom.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 java.util.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 java.util.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 java.lang.String getMessageID()

  Returns:
    The unique wsa:MessageID UUID. This is a required value.

### getMethodName

    public java.lang.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 java.lang.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(java.lang.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(java.lang.String messageID)

  Parameters:
    `messageID` - The wsa:MessageID. This cannot be null.

### setRelationship

    public void setRelationship(java.lang.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(java.lang.String message)
                                              throws SoapFault

  Throws:
    `SoapFault`

### toString

    public java.lang.String toString()

  Returns:
    An XML string representing the collection of WS-A headers. The XML would be a valid SOAP Header element.

### toXML

    public org.w3c.dom.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 org.w3c.dom.Element toXML(org.w3c.dom.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`

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD