A list of {@link Header}s on a {@link Message}.
This list can be modified to add headers from outside a {@link 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, {@link 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 {@link Pipe}s, thus it's something a {@link Pipe} author needs to keep in mind.
Specifically, when a {@link 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 boolean markAsUnderstood parameter. Most often, a {@link Pipe} knows it's going to understand a headeras 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.
- Call {@link #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 {@link Header#isIgnorable(SOAPVersion,java.util.Set)} is false, a bad thingwill happen. The actual implementation of the checking is more complicated, for that see {@link ClientMUTube}/ {@link ServerMUTube}.
@see Message#getHeaders()