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:

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

public final class HeaderList
extends ArrayList<Header>

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, 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

HeaderList()
Creates an empty HeaderList.

HeaderList(HeaderList that)
Copy constructor.

Method Summary

boolean	add(Header header) Adds a new Header.
void	addAll(Header... headers) Adds all the headers.
static HeaderList	copy(HeaderList original) Creates a copy.
void	fillRequestAddressingHeaders(Packet packet, AddressingVersion av, SOAPVersion sv, boolean oneway, String action) 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(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.
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.
boolean	isUnderstood(int index) Returns true if a Header at the given index was "understood".
void	readResponseAddressingHeaders(WSDLPort wsdlPort, WSBinding binding)
Header	remove(int index) Deprecated. HeaderList is monotonic and you can't remove anything.
boolean	remove(Object o) Deprecated. HeaderList is monotonic and you can't remove anything.
boolean	removeAll(Collection<?> c) Deprecated. HeaderList is monotonic and you can't remove anything.
boolean	retainAll(Collection<?> c) Deprecated. HeaderList is monotonic and you can't remove anything.
int	size() The number of total headers.
void	understood(Header header) Deprecated. By the deifnition 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".

Methods inherited from class java.util.ArrayList

add, addAll, addAll, clear, clone, contains, ensureCapacity, indexOf, isEmpty, lastIndexOf, removeRange, set, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals, hashCode, iterator, listIterator, listIterator, subList

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, iterator, listIterator, listIterator, subList

Constructor Detail

HeaderList

public HeaderList()

Creates an empty HeaderList.

HeaderList

public HeaderList(HeaderList that)

Copy constructor.

Method Detail

size

public int size()

The number of total 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 deifnition 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".

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.

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.

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.)

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)

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.)

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:

javax.xml.ws.WebServiceException - if either av or sv is null.

fillRequestAddressingHeaders

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

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

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 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

public Header remove(int index)

Deprecated. HeaderList is monotonic and you can't remove anything.

Specified by:

remove in interface List<Header>

Overrides:

remove in class ArrayList<Header>

remove

public boolean remove(Object o)

Deprecated. HeaderList is monotonic and you can't remove anything.

Specified by:

remove in interface Collection<Header>

Specified by:

remove in interface List<Header>

Overrides:

remove in class ArrayList<Header>

removeAll

public boolean removeAll(Collection<?> c)

Deprecated. HeaderList is monotonic and you can't remove anything.

Specified by:

removeAll in interface Collection<Header>

Specified by:

removeAll in interface List<Header>

Overrides:

removeAll in class AbstractCollection<Header>

retainAll

public boolean retainAll(Collection<?> c)

Deprecated. HeaderList is monotonic and you can't remove anything.

Specified by:

retainAll in interface Collection<Header>

Specified by:

retainAll in interface List<Header>

Overrides:

retainAll in class AbstractCollection<Header>

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)