- All Implemented Interfaces:
MessageHeaders
,Serializable
,Cloneable
,Iterable<Header>
,Collection<Header>
,List<Header>
,RandomAccess
Header
s 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, Codec
s 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 Pipe
s, 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:
- Use one of the
getXXX
methods that take a booleanmarkAsUnderstood
parameter. Most often, aPipe
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 setmarkAsUnderstand
to true, to do the obtaining of a header and marking at the same time. - 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:
-
Field Summary
Fields inherited from class java.util.AbstractList
modCount
-
Constructor Summary
ConstructorsConstructorDescriptionHeaderList
(HeaderList that) Copy constructor.HeaderList
(MessageHeaders that) HeaderList
(SOAPVersion soapVersion) Creates an emptyHeaderList
with the given soap version -
Method Summary
Modifier and TypeMethodDescriptionboolean
Adds a newHeader
.void
Deprecated.throws UnsupportedOperationException from some HeaderList implementations - better iterate over items one by oneprotected void
addInternal
(int index, Header header) boolean
addOrReplace
(Header header) asList()
ReturnsHeader
instances in aList
.static HeaderList
copy
(HeaderList original) Creates a copy.static HeaderList
copy
(MessageHeaders 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.get
(int index) Gets theHeader
at the specified index.Gets the firstHeader
of the specified name.Gets the firstHeader
of the specified name.getAction
(AddressingVersion av, SOAPVersion sv) Returns the value of WS-AddressingAction
header.getFaultTo
(AddressingVersion av, SOAPVersion sv) Returns the value of WS-AddressingFaultTo
header.getHeaders
(String nsUri, boolean markAsUnderstood) Gets an iteration of headersHeader
in the specified namespace, including duplicates (if any.)getHeaders
(String nsUri, String localName, boolean markAsUnderstood) Gets all theHeader
s of the specified name, including duplicates (if any.)getHeaders
(QName headerName, boolean markAsUnderstood) getMessageID
(AddressingVersion av, SOAPVersion sv) Returns the value of WS-AddressingMessageID
header.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 ingetRelatesTo
(AddressingVersion av, SOAPVersion sv) Returns the value of WS-AddressingRelatesTo
header.getReplyTo
(AddressingVersion av, SOAPVersion sv) Returns the value of WS-AddressingReplyTo
header.getTo
(AddressingVersion av, SOAPVersion sv) Returns the value of WS-AddressingTo
header.Return a Set of QNames of headers that have been explicitly marked as understood.boolean
boolean
isUnderstood
(int index) Returns true if aHeader
at the given index was "understood".boolean
isUnderstood
(Header header) True if the header has been explicitly marked understood, false otherwiseboolean
isUnderstood
(String nsUri, String localName) True if the header has been explicitly marked understood, false otherwiseboolean
isUnderstood
(QName name) True if the header has been explicitly marked understood, false otherwisevoid
readResponseAddressingHeaders
(WSDLPort wsdlPort, WSBinding binding) remove
(int index) Removes the firstHeader
of the specified name.boolean
Removes a single instance of the specified element from this header list, if it is present.Removes the firstHeader
of the specified name.Removes the firstHeader
of the specified name.protected Header
removeInternal
(int index) void
void
setSoapVersion
(SOAPVersion soapVersion) int
size()
The total number of headers.void
understood
(int index) Marks theHeader
at the specified index as "understood".void
understood
(Header header) Deprecated.By the definition ofArrayList
, this operation requires O(n) search of the array, and thus inherently inefficient.void
understood
(String nsUri, String localName) void
understood
(QName name) Methods inherited from class java.util.ArrayList
add, addAll, addAll, clear, clone, contains, ensureCapacity, equals, forEach, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, removeAll, removeIf, removeRange, replaceAll, retainAll, set, sort, spliterator, subList, toArray, toArray, trimToSize
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.Collection
parallelStream, stream, toArray
Methods inherited from interface java.util.List
containsAll
-
Constructor Details
-
HeaderList
Creates an emptyHeaderList
with the given soap version -
HeaderList
Copy constructor. -
HeaderList
-
-
Method Details
-
size
public int size()The total number of headers. -
hasHeaders
public boolean hasHeaders()- Specified by:
hasHeaders
in interfaceMessageHeaders
-
addAll
Deprecated.throws UnsupportedOperationException from some HeaderList implementations - better iterate over items one by oneAdds all the headers. -
get
-
understood
public void understood(int index) Marks theHeader
at the specified index as "understood". -
isUnderstood
public boolean isUnderstood(int index) Returns true if aHeader
at the given index was "understood". -
understood
Deprecated.Marks the specifiedHeader
as "understood".- Specified by:
understood
in interfaceMessageHeaders
- Throws:
IllegalArgumentException
- if the given header is notcontained
in this header.
-
get
@Nullable public Header get(@NotNull String nsUri, @NotNull String localName, boolean markAsUnderstood) Gets the firstHeader
of the specified name.- Specified by:
get
in interfaceMessageHeaders
- Parameters:
markAsUnderstood
- If this parameter is true, the returned header will be marked as "understood".- Returns:
- null if not found.
-
get
Gets the firstHeader
of the specified name.- Specified by:
get
in interfaceMessageHeaders
- Parameters:
markAsUnderstood
- If this parameter is true, the returned header will be marked as "understood".- Returns:
- null if not found.
-
getHeaders
@NotNull public Iterator<Header> getHeaders(@NotNull String nsUri, @NotNull String localName, boolean markAsUnderstood) Gets all theHeader
s of the specified name, including duplicates (if any.)- Specified by:
getHeaders
in interfaceMessageHeaders
- Parameters:
markAsUnderstood
- If this parameter is true, the returned headers will be marked as "understood" when they are returned fromIterator.next()
.- Returns:
- empty iterator if not found.
-
getHeaders
- Specified by:
getHeaders
in interfaceMessageHeaders
- See Also:
-
getHeaders
Gets an iteration of headersHeader
in the specified namespace, including duplicates (if any.)- Specified by:
getHeaders
in interfaceMessageHeaders
- Parameters:
markAsUnderstood
- If this parameter is true, the returned headers will be marked as "understood" when they are returned fromIterator.next()
.- Returns:
- empty iterator if not found.
-
getTo
Returns the value of WS-AddressingTo
header. Theversion
identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. DuplicateTo
headers are detected earlier.- Parameters:
av
- WS-Addressing versionsv
- SOAP version- Returns:
- Value of WS-Addressing To header, anonymous URI if no header is present
- Throws:
IllegalArgumentException
- if eitherav
orsv
is null.
-
getAction
Returns the value of WS-AddressingAction
header. Theversion
identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. DuplicateAction
headers are detected earlier.- Parameters:
av
- WS-Addressing versionsv
- SOAP version- Returns:
- Value of WS-Addressing Action header, null if no header is present
- Throws:
IllegalArgumentException
- if eitherav
orsv
is null.
-
getReplyTo
Returns the value of WS-AddressingReplyTo
header. Theversion
identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. DuplicateReplyTo
headers are detected earlier.- Parameters:
av
- WS-Addressing versionsv
- SOAP version- Returns:
- Value of WS-Addressing ReplyTo header, null if no header is present
- Throws:
IllegalArgumentException
- if eitherav
orsv
is null.
-
getFaultTo
Returns the value of WS-AddressingFaultTo
header. Theversion
identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. DuplicateFaultTo
headers are detected earlier.- Parameters:
av
- WS-Addressing versionsv
- SOAP version- Returns:
- Value of WS-Addressing FaultTo header, null if no header is present
- Throws:
IllegalArgumentException
- if eitherav
orsv
is null.
-
getMessageID
Returns the value of WS-AddressingMessageID
header. Theversion
identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. DuplicateMessageID
headers are detected earlier.- Parameters:
av
- WS-Addressing versionsv
- SOAP version- Returns:
- Value of WS-Addressing MessageID header, null if no header is present
- Throws:
jakarta.xml.ws.WebServiceException
- if eitherav
orsv
is null.
-
getRelatesTo
Returns the value of WS-AddressingRelatesTo
header. Theversion
identifies the WS-Addressing version and the header returned is targeted at the current implicit role. Caches the value for subsequent invocation. DuplicateRelatesTo
headers are detected earlier.- Parameters:
av
- WS-Addressing versionsv
- SOAP version- Returns:
- Value of WS-Addressing RelatesTo header, null if no header is present
- Throws:
jakarta.xml.ws.WebServiceException
- if eitherav
orsv
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
andWSDLPort
.- Parameters:
packet
- request packetav
- WS-Addressing versionsv
- SOAP versiononeway
- Indicates if the message exchange pattern is onewayaction
- Action Message Addressing Property valuemustUnderstand
- 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 withWSBinding
andWSDLPort
. This method uses SOAPAction as the Action unless set expplicitly in the wsdl.- Parameters:
wsdlPort
- request WSDL portbinding
- request WSBindingpacket
- request packet
-
add
Adds a newHeader
.Order doesn't matter in headers, so this method does not make any guarantee as to where the new header is inserted.
-
remove
Removes the firstHeader
of the specified name.- Specified by:
remove
in interfaceMessageHeaders
- Parameters:
nsUri
- namespace URI of the header to removelocalName
- local part of the FQN of the header to remove- Returns:
- null if not found.
-
addOrReplace
Replaces an existingHeader
or adds a newHeader
.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 interfaceMessageHeaders
- Returns:
- always true. Don't use the return value.
-
replace
- Specified by:
replace
in interfaceMessageHeaders
-
addInternal
-
removeInternal
-
remove
Removes the firstHeader
of the specified name.- Specified by:
remove
in interfaceMessageHeaders
- Parameters:
name
- fully qualified name of the header to remove- Returns:
- null if not found.
-
remove
Removes the firstHeader
of the specified name. -
remove
Removes a single instance of the specified element from this header list, if it is present. More formally, removes a headerh
such that(o==null ? h==null : o.equals(h))
, if the header list contains one or more such headers. Returnstrue
if the list contained the specified element (or equivalently, if the list changed as a result of the call). -
remove
-
copy
Creates a copy. This handles nullHeaderList
correctly.- Parameters:
original
- Can be null, in which case null will be returned.
-
copy
Creates a copy. This handles nullHeaderList
correctly.- Parameters:
original
- Can be null, in which case null will be returned.
-
readResponseAddressingHeaders
-
understood
- Specified by:
understood
in interfaceMessageHeaders
-
understood
- Specified by:
understood
in interfaceMessageHeaders
-
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 interfaceMessageHeaders
-
isUnderstood
Description copied from interface:MessageHeaders
True if the header has been explicitly marked understood, false otherwise- Specified by:
isUnderstood
in interfaceMessageHeaders
-
isUnderstood
Description copied from interface:MessageHeaders
True if the header has been explicitly marked understood, false otherwise- Specified by:
isUnderstood
in interfaceMessageHeaders
-
isUnderstood
Description copied from interface:MessageHeaders
True if the header has been explicitly marked understood, false otherwise- Specified by:
isUnderstood
in interfaceMessageHeaders
-
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 interfaceMessageHeaders
-
setSoapVersion
-
getHeaders
- Specified by:
getHeaders
in interfaceMessageHeaders
-
asList
Description copied from interface:MessageHeaders
ReturnsHeader
instances in aList
.- Specified by:
asList
in interfaceMessageHeaders
- Returns:
List
containingHeader
instances
-