| /* |
| * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package com.sun.xml.internal.ws.api.message; |
| |
| import com.sun.istack.internal.NotNull; |
| import com.sun.istack.internal.Nullable; |
| import com.sun.xml.internal.bind.api.Bridge; |
| import com.sun.xml.internal.ws.api.SOAPVersion; |
| import com.sun.xml.internal.ws.api.addressing.AddressingVersion; |
| import com.sun.xml.internal.ws.api.addressing.WSEndpointReference; |
| import com.sun.xml.internal.ws.spi.db.XMLBridge; |
| |
| import org.xml.sax.ContentHandler; |
| import org.xml.sax.ErrorHandler; |
| import org.xml.sax.SAXException; |
| import org.xml.sax.SAXParseException; |
| |
| import javax.xml.bind.JAXBException; |
| import javax.xml.bind.Unmarshaller; |
| import javax.xml.namespace.QName; |
| import javax.xml.soap.SOAPException; |
| import javax.xml.soap.SOAPMessage; |
| import javax.xml.stream.XMLStreamException; |
| import javax.xml.stream.XMLStreamReader; |
| import javax.xml.stream.XMLStreamWriter; |
| import javax.xml.ws.WebServiceException; |
| import java.util.Set; |
| |
| |
| /** |
| * A SOAP header. |
| * |
| * <p> |
| * A header is immutable, but unlike body it can be read |
| * multiple times. |
| * The {@link Header} abstraction hides how the header |
| * data is represented in memory; instead, it commits to |
| * the ability to write itself to XML infoset. |
| * |
| * <p> |
| * When a message is received from the transport and |
| * being processed, the processor needs to "peek" |
| * some information of a header, such as the tag name, |
| * the mustUnderstand attribute, and so on. Therefore, |
| * the {@link Header} interface exposes those information |
| * as properties, so that they can be checked without |
| * replaying the infoset, which is efficiently but still |
| * costly. |
| * |
| * <p> |
| * A {@link Header} may belong to more than one {@link HeaderList} |
| * due to wrapping of {@link Message}. |
| * |
| * @see HeaderList |
| * @see Headers |
| */ |
| public interface Header { |
| // TODO: Vivek pointed out that the only time we are looking at |
| // mustUnderstand and role are when we do the mustUnderstand error check |
| // (that is, to find out if there's any header with @mustUnderstand that |
| // has appropriate role for us.) |
| // if that's the case, it might be better if we define this whole operation |
| // as one method, instead of exposing two properties. |
| |
| /** |
| * Checks if this header is ignorable for us (IOW, make sure |
| * that this header has a problematic "mustUnderstand" header value |
| * that we have to reject.) |
| * |
| * <p> |
| * This method is used as a part of the |
| * <a href="HeaderList.html#MU">mustUnderstanx processing</a>. |
| * At the end of the processing, the JAX-WS identifies a list of {@link Header}s |
| * that were not understood. This method is invoked on those {@link Header}s, |
| * to verify that we don't need to report an error for it. |
| * |
| * <p> |
| * specifically, this method has to perform the following tasks: |
| * |
| * <ul> |
| * <li>If this header does not have {@code mustUnderstand} as "1" nor "true", |
| * then this method must return true. |
| * <li>Otherwise, check the role attribute (for SOAP 1.2) or the actor attribute (for SOAP 1.1). |
| * When those attributes are absent, the default values have to be assumed. |
| * See {@link #getRole(SOAPVersion)} for how the values are defaulted. |
| * Now, see if the {@code roles} set contains the value. |
| * If so, this method must return false (indicating that an error is in order.) |
| * <li>Otherwise return true (since we don't play the role this header is intended for.) |
| * </ul> |
| * |
| * @param soapVersion |
| * The caller specifies the SOAP version that the pipeline is working against. |
| * Often each {@link Header} implementation already knows the SOAP version |
| * anyway, but this allows some {@link Header}s to avoid keeping it. |
| * That's why this redundant parameter is passed in. |
| * @param roles |
| * The set of role values that the current JAX-WS pipeline is assuming. |
| * Note that SOAP 1.1 and SOAP 1.2 use different strings for the same role, |
| * and the caller is responsible for supplying a proper value depending on the |
| * active SOAP version in use. |
| * |
| * @return |
| * true if no error needs to be reported. False if an error needs to be raised. |
| * See the method javadoc for more discussion. |
| */ |
| public boolean isIgnorable(@NotNull SOAPVersion soapVersion, @NotNull Set<String> roles); |
| |
| /** |
| * Gets the value of the soap:role attribute (or soap:actor for SOAP 1.1). |
| * |
| * <p> |
| * If the attribute is omitted, the value defaults to {@link SOAPVersion#implicitRole}. |
| * |
| * @param soapVersion |
| * The caller specifies the SOAP version that the pipeline is working against. |
| * Often each {@link Header} implementation already knows the SOAP version |
| * anyway, but this allows some {@link Header}s to avoid keeping it. |
| * That's why this redundant parameter is passed in. |
| * @return |
| * never null. This string need not be interned. |
| */ |
| public @NotNull String getRole(@NotNull SOAPVersion soapVersion); |
| |
| /** |
| * True if this header is to be relayed if not processed. |
| * For SOAP 1.1 messages, this method always return false. |
| * |
| * <p> |
| * IOW, this method returns true if there's @soap:relay='true' |
| * is present. |
| * |
| * <h3>Implementation Note</h3> |
| * <p> |
| * The implementation needs to check for both "true" and "1", |
| * but because attribute values are normalized, it doesn't have |
| * to consider " true", " 1 ", and so on. |
| * |
| * @return |
| * false. |
| */ |
| public boolean isRelay(); |
| |
| /** |
| * Gets the namespace URI of this header element. |
| * |
| * @return |
| * this string must be interned. |
| */ |
| public @NotNull String getNamespaceURI(); |
| |
| /** |
| * Gets the local name of this header element. |
| * |
| * @return |
| * this string must be interned. |
| */ |
| public @NotNull String getLocalPart(); |
| |
| /** |
| * Gets the attribute value on the header element. |
| * |
| * @param nsUri |
| * The namespace URI of the attribute. Can be empty. |
| * @param localName |
| * The local name of the attribute. |
| * |
| * @return |
| * if the attribute is found, return the whitespace normalized value. |
| * (meaning no leading/trailing space, no consequtive whitespaces in-between.) |
| * Otherwise null. Note that the XML parsers are responsible for |
| * whitespace-normalizing attributes, so {@link Header} implementation |
| * doesn't have to do anything. |
| */ |
| @Nullable String getAttribute(@NotNull String nsUri, @NotNull String localName); |
| |
| /** |
| * Gets the attribute value on the header element. |
| * |
| * <p> |
| * This is a convenience method that calls into {@link #getAttribute(String, String)} |
| * |
| * @param name |
| * Never null. |
| * |
| * @see #getAttribute(String, String) |
| */ |
| @Nullable String getAttribute(@NotNull QName name); |
| |
| /** |
| * Reads the header as a {@link XMLStreamReader}. |
| * |
| * <p> |
| * The returned parser points at the start element of this header. |
| * (IOW, {@link XMLStreamReader#getEventType()} would return |
| * {@link XMLStreamReader#START_ELEMENT}. |
| * |
| * <h3>Performance Expectation</h3> |
| * <p> |
| * For some {@link Header} implementations, this operation |
| * is a non-trivial operation. Therefore, use of this method |
| * is discouraged unless the caller is interested in reading |
| * the whole header. |
| * |
| * <p> |
| * Similarly, if the caller wants to use this method only to do |
| * the API conversion (such as simply firing SAX events from |
| * {@link XMLStreamReader}), then the JAX-WS team requests |
| * that you talk to us. |
| * |
| * <p> |
| * {@link Message}s that come from tranport usually provides |
| * a reasonably efficient implementation of this method. |
| * |
| * @return |
| * must not null. |
| */ |
| public XMLStreamReader readHeader() throws XMLStreamException; |
| |
| /** |
| * Reads the header as a JAXB object by using the given unmarshaller. |
| */ |
| public <T> T readAsJAXB(Unmarshaller unmarshaller) throws JAXBException; |
| |
| /** |
| * Reads the header as a JAXB object by using the given unmarshaller. |
| * @deprecated |
| */ |
| public <T> T readAsJAXB(Bridge<T> bridge) throws JAXBException; |
| |
| /** |
| * Reads the header as a data-bond object |
| */ |
| public <T> T readAsJAXB(XMLBridge<T> bridge) throws JAXBException; |
| |
| /** |
| * Reads this header as an {@link WSEndpointReference}. |
| * |
| * @param expected |
| * The version of the addressing used to parse the EPR. |
| * If the actual infoset and this doesn't agree, then |
| * you'll get an {@link WebServiceException} stating that fact. |
| * |
| * @return |
| * On a successful return, this method never returns null. |
| */ |
| public @NotNull WSEndpointReference readAsEPR(AddressingVersion expected) throws XMLStreamException; |
| |
| /** |
| * Writes out the header as a fragment. |
| * |
| * @throws XMLStreamException |
| * if the operation fails for some reason. This leaves the |
| * writer to an undefined state. |
| */ |
| public void writeTo(XMLStreamWriter w) throws XMLStreamException; |
| |
| /** |
| * Writes out the header to the given SOAPMessage. |
| * |
| * <p> |
| * Sometimes a {@link Message} needs to produce itself |
| * as {@link SOAPMessage}, in which case each header needs |
| * to turn itself into a header. |
| * |
| * @throws SOAPException |
| * if the operation fails for some reason. This leaves the |
| * writer to an undefined state. |
| */ |
| public void writeTo(SOAPMessage saaj) throws SOAPException; |
| |
| /** |
| * Writes out the header as SAX events. |
| * |
| * <p> |
| * Sometimes a {@link Message} needs to produce SAX events, |
| * and this method is necessary for headers to participate to it. |
| * |
| * <p> |
| * A header is responsible for producing the SAX events for its part, |
| * including {@code startPrefixMapping} and {@code endPrefixMapping}, |
| * but not startDocument/endDocument. |
| * |
| * <p> |
| * Note that SAX contract requires that any error that does NOT originate |
| * from {@link ContentHandler} (meaning any parsing error and etc) must |
| * be first reported to {@link ErrorHandler}. If the SAX event production |
| * cannot be continued and the processing needs to abort, the code may |
| * then throw the same {@link SAXParseException} reported to {@link ErrorHandler}. |
| * |
| * @param contentHandler |
| * The {@link ContentHandler} that receives SAX events. |
| * |
| * @param errorHandler |
| * The {@link ErrorHandler} that receives parsing errors. |
| */ |
| public void writeTo(ContentHandler contentHandler, ErrorHandler errorHandler) throws SAXException; |
| |
| /** |
| * Used to obtain value XYZ from a header that looks like |
| * "<header>XYZ</header>". The primary use of this header |
| * for now is to access certain Addressing headers quickly. |
| * |
| * @throws WebServiceException |
| * If the structure of the header is more complicated than |
| * a simple string header. |
| * |
| * @return |
| * Can be empty but always non-null. |
| */ |
| public @NotNull String getStringContent(); |
| } |