• file
• revisions
• annotate
• diff
• comparison
• raw

src/share/jaxws_classes/javax/xml/soap/SOAPHeader.java@9c07ef4934dd (annotated)

src/share/jaxws_classes/javax/xml/soap/SOAPHeader.java

Thu, 31 Aug 2017 15:18:52 +0800

author

aoqi

date

Thu, 31 Aug 2017 15:18:52 +0800

changeset 637

9c07ef4934dd

parent 368

0989ad8c0860

parent 0

373ffda63c9a

permissions

-rw-r--r--

merge

aoqi@0	1	/*
aoqi@0	2	* Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.
aoqi@0	3	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
aoqi@0	4	*
aoqi@0	5	* This code is free software; you can redistribute it and/or modify it
aoqi@0	6	* under the terms of the GNU General Public License version 2 only, as
aoqi@0	7	* published by the Free Software Foundation. Oracle designates this
aoqi@0	8	* particular file as subject to the "Classpath" exception as provided
aoqi@0	9	* by Oracle in the LICENSE file that accompanied this code.
aoqi@0	10	*
aoqi@0	11	* This code is distributed in the hope that it will be useful, but WITHOUT
aoqi@0	12	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
aoqi@0	13	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
aoqi@0	14	* version 2 for more details (a copy is included in the LICENSE file that
aoqi@0	15	* accompanied this code).
aoqi@0	16	*
aoqi@0	17	* You should have received a copy of the GNU General Public License version
aoqi@0	18	* 2 along with this work; if not, write to the Free Software Foundation,
aoqi@0	19	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
aoqi@0	20	*
aoqi@0	21	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
aoqi@0	22	* or visit www.oracle.com if you need additional information or have any
aoqi@0	23	* questions.
aoqi@0	24	*/
aoqi@0	25
aoqi@0	26	package javax.xml.soap;
aoqi@0	27
aoqi@0	28	import java.util.Iterator;
aoqi@0	29
aoqi@0	30	import javax.xml.namespace.QName;
aoqi@0	31
aoqi@0	32	/**
aoqi@0	33	* A representation of the SOAP header
aoqi@0	34	* element. A SOAP header element consists of XML data that affects
aoqi@0	35	* the way the application-specific content is processed by the message
aoqi@0	36	* provider. For example, transaction semantics, authentication information,
aoqi@0	37	* and so on, can be specified as the content of a <code>SOAPHeader</code>
aoqi@0	38	* object.
aoqi@0	39	* <P>
aoqi@0	40	* A <code>SOAPEnvelope</code> object contains an empty
aoqi@0	41	* <code>SOAPHeader</code> object by default. If the <code>SOAPHeader</code>
aoqi@0	42	* object, which is optional, is not needed, it can be retrieved and deleted
aoqi@0	43	* with the following line of code. The variable <i>se</i> is a
aoqi@0	44	* <code>SOAPEnvelope</code> object.
aoqi@0	45	* <PRE>
aoqi@0	46	* se.getHeader().detachNode();
aoqi@0	47	* </PRE>
aoqi@0	48	*
aoqi@0	49	* A <code>SOAPHeader</code> object is created with the <code>SOAPEnvelope</code>
aoqi@0	50	* method <code>addHeader</code>. This method, which creates a new header and adds it
aoqi@0	51	* to the envelope, may be called only after the existing header has been removed.
aoqi@0	52	*
aoqi@0	53	* <PRE>
aoqi@0	54	* se.getHeader().detachNode();
aoqi@0	55	* SOAPHeader sh = se.addHeader();
aoqi@0	56	* </PRE>
aoqi@0	57	* <P>
aoqi@0	58	* A <code>SOAPHeader</code> object can have only <code>SOAPHeaderElement</code>
aoqi@0	59	* objects as its immediate children. The method <code>addHeaderElement</code>
aoqi@0	60	* creates a new <code>HeaderElement</code> object and adds it to the
aoqi@0	61	* <code>SOAPHeader</code> object. In the following line of code, the
aoqi@0	62	* argument to the method <code>addHeaderElement</code> is a <code>Name</code>
aoqi@0	63	* object that is the name for the new <code>HeaderElement</code> object.
aoqi@0	64	* <PRE>
aoqi@0	65	* SOAPHeaderElement shElement = sh.addHeaderElement(name);
aoqi@0	66	* </PRE>
aoqi@0	67	*
aoqi@0	68	* @see SOAPHeaderElement
aoqi@0	69	*/
aoqi@0	70	public interface SOAPHeader extends SOAPElement {
aoqi@0	71	/**
aoqi@0	72	* Creates a new <code>SOAPHeaderElement</code> object initialized with the
aoqi@0	73	* specified name and adds it to this <code>SOAPHeader</code> object.
aoqi@0	74	*
aoqi@0	75	* @param name a <code>Name</code> object with the name of the new
aoqi@0	76	* <code>SOAPHeaderElement</code> object
aoqi@0	77	* @return the new <code>SOAPHeaderElement</code> object that was
aoqi@0	78	* inserted into this <code>SOAPHeader</code> object
aoqi@0	79	* @exception SOAPException if a SOAP error occurs
aoqi@0	80	* @see SOAPHeader#addHeaderElement(javax.xml.namespace.QName)
aoqi@0	81	*/
aoqi@0	82	public SOAPHeaderElement addHeaderElement(Name name)
aoqi@0	83	throws SOAPException;
aoqi@0	84
aoqi@0	85	/**
aoqi@0	86	* Creates a new <code>SOAPHeaderElement</code> object initialized with the
aoqi@0	87	* specified qname and adds it to this <code>SOAPHeader</code> object.
aoqi@0	88	*
aoqi@0	89	* @param qname a <code>QName</code> object with the qname of the new
aoqi@0	90	* <code>SOAPHeaderElement</code> object
aoqi@0	91	* @return the new <code>SOAPHeaderElement</code> object that was
aoqi@0	92	* inserted into this <code>SOAPHeader</code> object
aoqi@0	93	* @exception SOAPException if a SOAP error occurs
aoqi@0	94	* @see SOAPHeader#addHeaderElement(Name)
aoqi@0	95	* @since SAAJ 1.3
aoqi@0	96	*/
aoqi@0	97	public SOAPHeaderElement addHeaderElement(QName qname)
aoqi@0	98	throws SOAPException;
aoqi@0	99
aoqi@0	100	/**
aoqi@0	101	* Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
aoqi@0	102	* in this <code>SOAPHeader</code> object
aoqi@0	103	* that have the specified <i>actor</i> and that have a MustUnderstand attribute
aoqi@0	104	* whose value is equivalent to <code>true</code>.
aoqi@0	105	* <p>
aoqi@0	106	* In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
aoqi@0	107	* attribute, but with essentially the same semantics.
aoqi@0	108	*
aoqi@0	109	* @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
aoqi@0	110	* for which to search
aoqi@0	111	* @return an <code>Iterator</code> object over all the
aoqi@0	112	* <code>SOAPHeaderElement</code> objects that contain the specified
aoqi@0	113	* <code>actor</code> / <code>role</code> and are marked as MustUnderstand
aoqi@0	114	* @see #examineHeaderElements
aoqi@0	115	* @see #extractHeaderElements
aoqi@0	116	* @see SOAPConstants#URI_SOAP_ACTOR_NEXT
aoqi@0	117	*
aoqi@0	118	* @since SAAJ 1.2
aoqi@0	119	*/
aoqi@0	120	public Iterator examineMustUnderstandHeaderElements(String actor);
aoqi@0	121
aoqi@0	122	/**
aoqi@0	123	* Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
aoqi@0	124	* in this <code>SOAPHeader</code> object
aoqi@0	125	* that have the specified <i>actor</i>.
aoqi@0	126	*
aoqi@0	127	* An <i>actor</i> is a global attribute that indicates the intermediate
aoqi@0	128	* parties that should process a message before it reaches its ultimate
aoqi@0	129	* receiver. An actor receives the message and processes it before sending
aoqi@0	130	* it on to the next actor. The default actor is the ultimate intended
aoqi@0	131	* recipient for the message, so if no actor attribute is included in a
aoqi@0	132	* <code>SOAPHeader</code> object, it is sent to the ultimate receiver
aoqi@0	133	* along with the message body.
aoqi@0	134	* <p>
aoqi@0	135	* In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
aoqi@0	136	* attribute, but with essentially the same semantics.
aoqi@0	137	*
aoqi@0	138	* @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
aoqi@0	139	* for which to search
aoqi@0	140	* @return an <code>Iterator</code> object over all the
aoqi@0	141	* <code>SOAPHeaderElement</code> objects that contain the specified
aoqi@0	142	* <code>actor</code> / <code>role</code>
aoqi@0	143	* @see #extractHeaderElements
aoqi@0	144	* @see SOAPConstants#URI_SOAP_ACTOR_NEXT
aoqi@0	145	*/
aoqi@0	146	public Iterator examineHeaderElements(String actor);
aoqi@0	147
aoqi@0	148	/**
aoqi@0	149	* Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
aoqi@0	150	* in this <code>SOAPHeader</code> object
aoqi@0	151	* that have the specified <i>actor</i> and detaches them
aoqi@0	152	* from this <code>SOAPHeader</code> object.
aoqi@0	153	* <P>
aoqi@0	154	* This method allows an actor to process the parts of the
aoqi@0	155	* <code>SOAPHeader</code> object that apply to it and to remove
aoqi@0	156	* them before passing the message on to the next actor.
aoqi@0	157	* <p>
aoqi@0	158	* In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
aoqi@0	159	* attribute, but with essentially the same semantics.
aoqi@0	160	*
aoqi@0	161	* @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
aoqi@0	162	* for which to search
aoqi@0	163	* @return an <code>Iterator</code> object over all the
aoqi@0	164	* <code>SOAPHeaderElement</code> objects that contain the specified
aoqi@0	165	* <code>actor</code> / <code>role</code>
aoqi@0	166	*
aoqi@0	167	* @see #examineHeaderElements
aoqi@0	168	* @see SOAPConstants#URI_SOAP_ACTOR_NEXT
aoqi@0	169	*/
aoqi@0	170	public Iterator extractHeaderElements(String actor);
aoqi@0	171
aoqi@0	172	/**
aoqi@0	173	* Creates a new NotUnderstood <code>SOAPHeaderElement</code> object initialized
aoqi@0	174	* with the specified name and adds it to this <code>SOAPHeader</code> object.
aoqi@0	175	* This operation is supported only by SOAP 1.2.
aoqi@0	176	*
aoqi@0	177	* @param name a <code>QName</code> object with the name of the
aoqi@0	178	* <code>SOAPHeaderElement</code> object that was not understood.
aoqi@0	179	* @return the new <code>SOAPHeaderElement</code> object that was
aoqi@0	180	* inserted into this <code>SOAPHeader</code> object
aoqi@0	181	* @exception SOAPException if a SOAP error occurs.
aoqi@0	182	* @exception UnsupportedOperationException if this is a SOAP 1.1 Header.
aoqi@0	183	* @since SAAJ 1.3
aoqi@0	184	*/
aoqi@0	185	public SOAPHeaderElement addNotUnderstoodHeaderElement(QName name)
aoqi@0	186	throws SOAPException;
aoqi@0	187
aoqi@0	188	/**
aoqi@0	189	* Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
aoqi@0	190	* with the specified List of supported SOAP URIs and adds it to this
aoqi@0	191	* <code>SOAPHeader</code> object.
aoqi@0	192	* This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
aoqi@0	193	*
aoqi@0	194	* @param supportedSOAPURIs an <code>Iterator</code> object with the URIs of SOAP
aoqi@0	195	* versions supported.
aoqi@0	196	* @return the new <code>SOAPHeaderElement</code> object that was
aoqi@0	197	* inserted into this <code>SOAPHeader</code> object
aoqi@0	198	* @exception SOAPException if a SOAP error occurs.
aoqi@0	199	* @since SAAJ 1.3
aoqi@0	200	*/
aoqi@0	201	public SOAPHeaderElement addUpgradeHeaderElement(Iterator supportedSOAPURIs)
aoqi@0	202	throws SOAPException;
aoqi@0	203
aoqi@0	204	/**
aoqi@0	205	* Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
aoqi@0	206	* with the specified array of supported SOAP URIs and adds it to this
aoqi@0	207	* <code>SOAPHeader</code> object.
aoqi@0	208	* This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
aoqi@0	209	*
aoqi@0	210	* @param supportedSoapUris an array of the URIs of SOAP versions supported.
aoqi@0	211	* @return the new <code>SOAPHeaderElement</code> object that was
aoqi@0	212	* inserted into this <code>SOAPHeader</code> object
aoqi@0	213	* @exception SOAPException if a SOAP error occurs.
aoqi@0	214	* @since SAAJ 1.3
aoqi@0	215	*/
aoqi@0	216	public SOAPHeaderElement addUpgradeHeaderElement(String[] supportedSoapUris)
aoqi@0	217	throws SOAPException;
aoqi@0	218
aoqi@0	219	/**
aoqi@0	220	* Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
aoqi@0	221	* with the specified supported SOAP URI and adds it to this
aoqi@0	222	* <code>SOAPHeader</code> object.
aoqi@0	223	* This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
aoqi@0	224	*
aoqi@0	225	* @param supportedSoapUri the URI of SOAP the version that is supported.
aoqi@0	226	* @return the new <code>SOAPHeaderElement</code> object that was
aoqi@0	227	* inserted into this <code>SOAPHeader</code> object
aoqi@0	228	* @exception SOAPException if a SOAP error occurs.
aoqi@0	229	* @since SAAJ 1.3
aoqi@0	230	*/
aoqi@0	231	public SOAPHeaderElement addUpgradeHeaderElement(String supportedSoapUri)
aoqi@0	232	throws SOAPException;
aoqi@0	233
aoqi@0	234	/**
aoqi@0	235	* Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
aoqi@0	236	* in this <code>SOAPHeader</code> object.
aoqi@0	237	*
aoqi@0	238	* @return an <code>Iterator</code> object over all the
aoqi@0	239	* <code>SOAPHeaderElement</code> objects contained by this
aoqi@0	240	* <code>SOAPHeader</code>
aoqi@0	241	* @see #extractAllHeaderElements
aoqi@0	242	*
aoqi@0	243	* @since SAAJ 1.2
aoqi@0	244	*/
aoqi@0	245	public Iterator examineAllHeaderElements();
aoqi@0	246
aoqi@0	247	/**
aoqi@0	248	* Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
aoqi@0	249	* in this <code>SOAPHeader</code> object and detaches them
aoqi@0	250	* from this <code>SOAPHeader</code> object.
aoqi@0	251	*
aoqi@0	252	* @return an <code>Iterator</code> object over all the
aoqi@0	253	* <code>SOAPHeaderElement</code> objects contained by this
aoqi@0	254	* <code>SOAPHeader</code>
aoqi@0	255	*
aoqi@0	256	* @see #examineAllHeaderElements
aoqi@0	257	*
aoqi@0	258	* @since SAAJ 1.2
aoqi@0	259	*/
aoqi@0	260	public Iterator extractAllHeaderElements();
aoqi@0	261
aoqi@0	262	}