com.sun.xml.ws.api.message

Class HeaderList

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<E>

java.util.ArrayList<Header>

com.sun.xml.ws.api.message.HeaderList

All Implemented Interfaces:

MessageHeaders, Serializable, Cloneable, Iterable<Header>, Collection<Header>, List<Header>, RandomAccess

public class HeaderList
extends ArrayList<Header>
implements MessageHeaders

A list of Headers on a Message.

This list can be modified to add headers from outside a Message, this is necessary since intermediate processing layers often need to put additional headers.

Following the SOAP convention, the order among headers are not significant. However, Codecs are expected to preserve the order of headers in the input message as much as possible.

MustUnderstand Processing

To perform SOAP mustUnderstang processing correctly, we need to keep track of headers that are understood and headers that are not. This is a collaborative process among Pipes, thus it's something a Pipe author needs to keep in mind.

Specifically, when a Pipe sees a header and processes it (that is, if it did enough computing with the header to claim that the header is understood), then it should mark the corresponding header as "understood". For example, when a pipe that handles JAX-WSA examins the <wsa:To> header, it can claim that it understood the header. But for example, if a pipe that does the signature verification checks <wsa:To> for a signature, that would not be considered as "understood".

There are two ways to mark a header as understood:

1. Use one of the getXXX methods that take a boolean markAsUnderstood parameter. Most often, a Pipe knows it's going to understand a header as long as it's present, so this is the easiest and thus the preferred way. For example, if JAX-WSA looks for <wsa:To>, then it can set markAsUnderstand to true, to do the obtaining of a header and marking at the same time.
2. Call understood(int). If under a rare circumstance, a pipe cannot determine whether it can understand it or not when you are fetching a header, then you can use this method afterward to mark it as understood.

Intuitively speaking, at the end of the day, if a header is not understood but Header.isIgnorable(SOAPVersion, java.util.Set) is false, a bad thing will happen. The actual implementation of the checking is more complicated, for that see ClientMUTube/ServerMUTube.

See Also:

Message.getHeaders(), Serialized Form

Field Summary

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

Constructors

Constructor and Description
HeaderList() Deprecated.
HeaderList(HeaderList that) Copy constructor.
HeaderList(SOAPVersion soapVersion) Creates an empty HeaderList with the given soap version

Method Summary

Methods

Modifier and Type	Method and Description
boolean	add(Header header) Adds a new Header.
void	addAll(Header... headers) Adds all the headers.
protected void	addInternal(int index, Header header)
boolean	addOrReplace(Header header) Replaces an existing Header or adds a new Header.
static HeaderList	copy(HeaderList original) Creates a copy.
void	fillRequestAddressingHeaders(Packet packet, AddressingVersion av, SOAPVersion sv, boolean oneway, String action)
void	fillRequestAddressingHeaders(Packet packet, AddressingVersion av, SOAPVersion sv, boolean oneway, String action, boolean mustUnderstand) Creates a set of outbound WS-Addressing headers on the client with the specified Action Message Addressing Property value.
void	fillRequestAddressingHeaders(WSDLPort wsdlPort, WSBinding binding, Packet packet) Creates a set of outbound WS-Addressing headers on the client with the default Action Message Addressing Property value.
Header	get(int index) Gets the Header at the specified index.
Header	get(QName name) Deprecated. Use get(QName)
Header	get(QName name, boolean markAsUnderstood) Gets the first Header of the specified name.
Header	get(String nsUri, String localName) Deprecated. Use get(String, String, boolean)
Header	get(String nsUri, String localName, boolean markAsUnderstood) Gets the first Header of the specified name.
String	getAction(AddressingVersion av, SOAPVersion sv) Returns the value of WS-Addressing Action header.
WSEndpointReference	getFaultTo(AddressingVersion av, SOAPVersion sv) Returns the value of WS-Addressing FaultTo header.
Iterator<Header>	getHeaders()
Iterator<Header>	getHeaders(QName headerName, boolean markAsUnderstood)
Iterator<Header>	getHeaders(String nsUri) Deprecated. use getHeaders(String, boolean).
Iterator<Header>	getHeaders(String nsUri, boolean markAsUnderstood) Gets an iteration of headers Header in the specified namespace, including duplicates (if any.)
Iterator<Header>	getHeaders(String nsUri, String localName) Deprecated. Use getHeaders(String, String, boolean)
Iterator<Header>	getHeaders(String nsUri, String localName, boolean markAsUnderstood) Gets all the Headers of the specified name, including duplicates (if any.)
String	getMessageID(AddressingVersion av, SOAPVersion sv) Returns the value of WS-Addressing MessageID header.
Set<QName>	getNotUnderstoodHeaders(Set<String> roles, Set<QName> knownHeaders, WSBinding binding) Returns a Set of QNames of headers that satisfy ALL the following conditions: (a) Have mustUnderstand = true (b) have NOT been explicitly marked as understood (c) If roles argument is non-null, the header has isIgnorable = false for the roles argument and SOAP version (d) If non-null binding is passed in, are NOT understood by the binding (e) If (d) is met, the header is NOT in the knownHeaders list passed in
String	getRelatesTo(AddressingVersion av, SOAPVersion sv) Returns the value of WS-Addressing RelatesTo header.
WSEndpointReference	getReplyTo(AddressingVersion av, SOAPVersion sv) Returns the value of WS-Addressing ReplyTo header.
String	getTo(AddressingVersion av, SOAPVersion sv) Returns the value of WS-Addressing To header.
Set<QName>	getUnderstoodHeaders() Return a Set of QNames of headers that have been explicitly marked as understood.
boolean	isUnderstood(Header header) True if the header has been explicitly marked understood, false otherwise
boolean	isUnderstood(int index) Returns true if a Header at the given index was "understood".
boolean	isUnderstood(QName name) True if the header has been explicitly marked understood, false otherwise
boolean	isUnderstood(String nsUri, String localName) True if the header has been explicitly marked understood, false otherwise
void	readResponseAddressingHeaders(WSDLPort wsdlPort, WSBinding binding)
Header	remove(Header h)
Header	remove(int index) Removes the first Header of the specified name.
boolean	remove(Object o) Removes a single instance of the specified element from this header list, if it is present.
Header	remove(QName name) Removes the first Header of the specified name.
Header	remove(String nsUri, String localName) Removes the first Header of the specified name.
protected Header	removeInternal(int index)
void	setSoapVersion(SOAPVersion soapVersion)
int	size() The total number of headers.
void	understood(Header header) Deprecated. By the definition of ArrayList, this operation requires O(n) search of the array, and thus inherently inefficient. Because of this, if you are developing a Pipe for a performance sensitive environment, do not use this method.
void	understood(int index) Marks the Header at the specified index as "understood".
void	understood(QName name)
void	understood(String nsUri, String localName)

Methods inherited from class java.util.ArrayList

add, addAll, addAll, clear, clone, contains, ensureCapacity, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, removeAll, removeRange, retainAll, set, subList, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals, hashCode

Methods inherited from class java.util.AbstractCollection

containsAll, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

containsAll, equals, hashCode

Constructor Detail

HeaderList

@Deprecated
public HeaderList()

Deprecated.

This method is deprecated - instead use this one: public HeaderList(SOAPVersion) Creates an empty HeaderList.

HeaderList

public HeaderList(SOAPVersion soapVersion)

Creates an empty HeaderList with the given soap version

Parameters:

soapVersion -

HeaderList

public HeaderList(HeaderList that)

Copy constructor.

Method Detail

size

public int size()

The total number of headers.

Specified by:

size in interface Collection<Header>

Specified by:

size in interface List<Header>

Overrides:

size in class ArrayList<Header>

addAll

public void addAll(Header... headers)

Adds all the headers.

get

public Header get(int index)

Gets the Header at the specified index.

This method does not mark the returned Header as understood.

Specified by:

get in interface List<Header>

Overrides:

get in class ArrayList<Header>

See Also:

understood(int)

understood

public void understood(int index)

Marks the Header at the specified index as "understood".

isUnderstood

public boolean isUnderstood(int index)

Returns true if a Header at the given index was "understood".

understood

public void understood(@NotNull
              Header header)

Deprecated. By the definition of ArrayList, this operation requires O(n) search of the array, and thus inherently inefficient. Because of this, if you are developing a Pipe for a performance sensitive environment, do not use this method.

Marks the specified Header as "understood".

Specified by:

understood in interface MessageHeaders

Throws:

IllegalArgumentException - if the given header is not contained in this header.

get

@Nullable
public Header get(@NotNull
                  String nsUri,
                  @NotNull
                  String localName,
                  boolean markAsUnderstood)

Gets the first Header of the specified name.

Specified by:

get in interface MessageHeaders

Parameters:

markAsUnderstood - If this parameter is true, the returned header will be marked as "understood".

Returns:

null if not found.

get

public Header get(String nsUri,
         String localName)

Deprecated. Use get(String, String, boolean)

get

@Nullable
public Header get(@NotNull
                  QName name,
                  boolean markAsUnderstood)

Gets the first Header of the specified name.

Specified by:

get in interface MessageHeaders

Parameters:

markAsUnderstood - If this parameter is true, the returned header will be marked as "understood".

Returns:

null if not found.

get

@Nullable
public Header get(@NotNull
                  QName name)

Deprecated. Use get(QName)

getHeaders

public Iterator<Header> getHeaders(String nsUri,
                          String localName)

Deprecated. Use getHeaders(String, String, boolean)

getHeaders

@NotNull
public Iterator<Header> getHeaders(@NotNull
                                  String nsUri,
                                  @NotNull
                                  String localName,
                                  boolean markAsUnderstood)

Gets all the Headers of the specified name, including duplicates (if any.)

Specified by:

getHeaders in interface MessageHeaders

Parameters:

markAsUnderstood - If this parameter is true, the returned headers will be marked as "understood" when they are returned from Iterator.next().

Returns:

empty iterator if not found.

getHeaders

@NotNull
public Iterator<Header> getHeaders(@NotNull
                                  QName headerName,
                                  boolean markAsUnderstood)

Specified by:

getHeaders in interface MessageHeaders

See Also:

getHeaders(String, String, boolean)

getHeaders

@NotNull
public Iterator<Header> getHeaders(@NotNull
                                  String nsUri)

Deprecated. use getHeaders(String, boolean).

getHeaders

@NotNull
public Iterator<Header> getHeaders(@NotNull
                                  String nsUri,
                                  boolean markAsUnderstood)

Gets an iteration of headers Header in the specified namespace, including duplicates (if any.)

Specified by:

getHeaders in interface MessageHeaders

Parameters:

markAsUnderstood - If this parameter is true, the returned headers will be marked as "understood" when they are returned from Iterator.next().

Returns:

empty iterator if not found.

getTo

public String getTo(AddressingVersion av,
           SOAPVersion sv)

Returns the value of WS-Addressing To header. The version identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. Duplicate To headers are detected earlier.

Parameters:

av - WS-Addressing version

sv - SOAP version

Returns:

Value of WS-Addressing To header, anonymous URI if no header is present

Throws:

IllegalArgumentException - if either av or sv is null.

getAction

public String getAction(@NotNull
               AddressingVersion av,
               @NotNull
               SOAPVersion sv)

Returns the value of WS-Addressing Action header. The version identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. Duplicate Action headers are detected earlier.

Parameters:

av - WS-Addressing version

sv - SOAP version

Returns:

Value of WS-Addressing Action header, null if no header is present

Throws:

IllegalArgumentException - if either av or sv is null.

getReplyTo

public WSEndpointReference getReplyTo(@NotNull
                             AddressingVersion av,
                             @NotNull
                             SOAPVersion sv)

Returns the value of WS-Addressing ReplyTo header. The version identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. Duplicate ReplyTo headers are detected earlier.

Parameters:

av - WS-Addressing version

sv - SOAP version

Returns:

Value of WS-Addressing ReplyTo header, null if no header is present

Throws:

IllegalArgumentException - if either av or sv is null.

getFaultTo

public WSEndpointReference getFaultTo(@NotNull
                             AddressingVersion av,
                             @NotNull
                             SOAPVersion sv)

Returns the value of WS-Addressing FaultTo header. The version identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. Duplicate FaultTo headers are detected earlier.

Parameters:

av - WS-Addressing version

sv - SOAP version

Returns:

Value of WS-Addressing FaultTo header, null if no header is present

Throws:

IllegalArgumentException - if either av or sv is null.

getMessageID

public String getMessageID(@NotNull
                  AddressingVersion av,
                  @NotNull
                  SOAPVersion sv)

Returns the value of WS-Addressing MessageID header. The version identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. Duplicate MessageID headers are detected earlier.

Parameters:

av - WS-Addressing version

sv - SOAP version

Returns:

Value of WS-Addressing MessageID header, null if no header is present

Throws:

WebServiceException - if either av or sv is null.

getRelatesTo

public String getRelatesTo(@NotNull
                  AddressingVersion av,
                  @NotNull
                  SOAPVersion sv)

Returns the value of WS-Addressing RelatesTo header. The version identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. Duplicate RelatesTo headers are detected earlier.

Parameters:

av - WS-Addressing version

sv - SOAP version

Returns:

Value of WS-Addressing RelatesTo header, null if no header is present

Throws:

WebServiceException - if either av or sv is null.

fillRequestAddressingHeaders

public void fillRequestAddressingHeaders(Packet packet,
                                AddressingVersion av,
                                SOAPVersion sv,
                                boolean oneway,
                                String action,
                                boolean mustUnderstand)

Creates a set of outbound WS-Addressing headers on the client with the specified Action Message Addressing Property value.

This method needs to be invoked right after such a Message is created which is error prone but so far only MEX, RM and JAX-WS creates a request so this ugliness is acceptable. This method is also used to create protocol messages that are not associated with any WSBinding and WSDLPort.

Parameters:

packet - request packet

av - WS-Addressing version

sv - SOAP version

oneway - Indicates if the message exchange pattern is oneway

action - Action Message Addressing Property value

mustUnderstand - to indicate if the addressing headers are set with mustUnderstand attribute

fillRequestAddressingHeaders

public void fillRequestAddressingHeaders(Packet packet,
                                AddressingVersion av,
                                SOAPVersion sv,
                                boolean oneway,
                                String action)

fillRequestAddressingHeaders

public void fillRequestAddressingHeaders(WSDLPort wsdlPort,
                                @NotNull
                                WSBinding binding,
                                Packet packet)

Creates a set of outbound WS-Addressing headers on the client with the default Action Message Addressing Property value.

This method needs to be invoked right after such a Message is created which is error prone but so far only MEX, RM and JAX-WS creates a request so this ugliness is acceptable. If more components are identified using this, then we may revisit this.

This method is used if default Action Message Addressing Property is to be used. See fillRequestAddressingHeaders(Packet, com.sun.xml.ws.api.addressing.AddressingVersion, com.sun.xml.ws.api.SOAPVersion, boolean, String) if non-default Action is to be used, for example when creating a protocol message not associated with WSBinding and WSDLPort. This method uses SOAPAction as the Action unless set expplicitly in the wsdl.

Parameters:

wsdlPort - request WSDL port

binding - request WSBinding

packet - request packet

add

public boolean add(Header header)

Adds a new Header.

Order doesn't matter in headers, so this method does not make any guarantee as to where the new header is inserted.

Specified by:

add in interface MessageHeaders

Specified by:

add in interface Collection<Header>

Specified by:

add in interface List<Header>

Overrides:

add in class ArrayList<Header>

Returns:

always true. Don't use the return value.

remove

@Nullable
public Header remove(@NotNull
                     String nsUri,
                     @NotNull
                     String localName)

Removes the first Header of the specified name.

Specified by:

remove in interface MessageHeaders

Parameters:

nsUri - namespace URI of the header to remove

localName - local part of the FQN of the header to remove

Returns:

null if not found.

addOrReplace

public boolean addOrReplace(Header header)

Replaces an existing Header or adds a new Header.

Order doesn't matter in headers, so this method does not make any guarantee as to where the new header is inserted.

Specified by:

addOrReplace in interface MessageHeaders

Returns:

always true. Don't use the return value.

addInternal

protected void addInternal(int index,
               Header header)

removeInternal

protected Header removeInternal(int index)

remove

@Nullable
public Header remove(@NotNull
                     QName name)

Removes the first Header of the specified name.

Specified by:

remove in interface MessageHeaders

Parameters:

name - fully qualified name of the header to remove

Returns:

null if not found.

remove

public Header remove(int index)

Removes the first Header of the specified name.

Specified by:

remove in interface List<Header>

Overrides:

remove in class ArrayList<Header>

Parameters:

index - index of the header to remove

Returns:

removed header

remove

public boolean remove(Object o)

Removes a single instance of the specified element from this header list, if it is present. More formally, removes a header h such that (o==null ? h==null : o.equals(h)), if the header list contains one or more such headers. Returns true if the list contained the specified element (or equivalently, if the list changed as a result of the call).

Specified by:

remove in interface Collection<Header>

Specified by:

remove in interface List<Header>

Overrides:

remove in class ArrayList<Header>

Parameters:

o - element to be removed from this list, if present.

Returns:

true if the list contained the specified element.

See Also:

remove(javax.xml.namespace.QName)

remove

public Header remove(Header h)

copy

public static HeaderList copy(HeaderList original)

Creates a copy. This handles null HeaderList correctly.

Parameters:

original - Can be null, in which case null will be returned.

readResponseAddressingHeaders

public void readResponseAddressingHeaders(WSDLPort wsdlPort,
                                 WSBinding binding)

understood

public void understood(QName name)

Specified by:

understood in interface MessageHeaders

understood

public void understood(String nsUri,
              String localName)

Specified by:

understood in interface MessageHeaders

getUnderstoodHeaders

public Set<QName> getUnderstoodHeaders()

Description copied from interface: MessageHeaders

Return a Set of QNames of headers that have been explicitly marked as understood. If none have been marked, this method could return null

Specified by:

getUnderstoodHeaders in interface MessageHeaders

isUnderstood

public boolean isUnderstood(Header header)

Description copied from interface: MessageHeaders

True if the header has been explicitly marked understood, false otherwise

Specified by:

isUnderstood in interface MessageHeaders

Returns:

isUnderstood

public boolean isUnderstood(String nsUri,
                   String localName)

Description copied from interface: MessageHeaders

True if the header has been explicitly marked understood, false otherwise

Specified by:

isUnderstood in interface MessageHeaders

Returns:

isUnderstood

public boolean isUnderstood(QName name)

Description copied from interface: MessageHeaders

True if the header has been explicitly marked understood, false otherwise

Specified by:

isUnderstood in interface MessageHeaders

Returns:

getNotUnderstoodHeaders

public Set<QName> getNotUnderstoodHeaders(Set<String> roles,
                                 Set<QName> knownHeaders,
                                 WSBinding binding)

Description copied from interface: MessageHeaders

Returns a Set of QNames of headers that satisfy ALL the following conditions: (a) Have mustUnderstand = true (b) have NOT been explicitly marked as understood (c) If roles argument is non-null, the header has isIgnorable = false for the roles argument and SOAP version (d) If non-null binding is passed in, are NOT understood by the binding (e) If (d) is met, the header is NOT in the knownHeaders list passed in

Specified by:

getNotUnderstoodHeaders in interface MessageHeaders

Returns:

setSoapVersion

public void setSoapVersion(SOAPVersion soapVersion)

getHeaders

public Iterator<Header> getHeaders()

Specified by:

getHeaders in interface MessageHeaders