PageRenderTime 53ms CodeModel.GetById 23ms RepoModel.GetById 0ms app.codeStats 0ms

/java-1.7.0-openjdk/openjdk/jaxws/sources/jaxws_src/src/javax/xml/soap/SOAPBody.java

#
Java | 297 lines | 22 code | 18 blank | 257 comment | 0 complexity | 2976c48fd0850e58f4f65cf39c913668 MD5 | raw file
Possible License(s): GPL-2.0, BSD-3-Clause-No-Nuclear-License-2014, LGPL-3.0, LGPL-2.0
  1. /*
  2. * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved.
  3. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  4. *
  5. * This code is free software; you can redistribute it and/or modify it
  6. * under the terms of the GNU General Public License version 2 only, as
  7. * published by the Free Software Foundation. Oracle designates this
  8. * particular file as subject to the "Classpath" exception as provided
  9. * by Oracle in the LICENSE file that accompanied this code.
  10. *
  11. * This code is distributed in the hope that it will be useful, but WITHOUT
  12. * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13. * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  14. * version 2 for more details (a copy is included in the LICENSE file that
  15. * accompanied this code).
  16. *
  17. * You should have received a copy of the GNU General Public License version
  18. * 2 along with this work; if not, write to the Free Software Foundation,
  19. * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20. *
  21. * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22. * or visit www.oracle.com if you need additional information or have any
  23. * questions.
  24. */
  25. package javax.xml.soap;
  26. import java.util.Locale;
  27. import org.w3c.dom.Document;
  28. import javax.xml.namespace.QName;
  29. /**
  30. * An object that represents the contents of the SOAP body
  31. * element in a SOAP message. A SOAP body element consists of XML data
  32. * that affects the way the application-specific content is processed.
  33. * <P>
  34. * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code>
  35. * objects, which have the content for the SOAP body.
  36. * A <code>SOAPFault</code> object, which carries status and/or
  37. * error information, is an example of a <code>SOAPBodyElement</code> object.
  38. *
  39. * @see SOAPFault
  40. */
  41. public interface SOAPBody extends SOAPElement {
  42. /**
  43. * Creates a new <code>SOAPFault</code> object and adds it to
  44. * this <code>SOAPBody</code> object. The new <code>SOAPFault</code> will
  45. * have default values set for the mandatory child elements. The type of
  46. * the <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code>
  47. * depending on the <code>protocol</code> specified while creating the
  48. * <code>MessageFactory</code> instance.
  49. * <p>
  50. * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
  51. * child element.
  52. *
  53. * @return the new <code>SOAPFault</code> object
  54. * @exception SOAPException if there is a SOAP error
  55. */
  56. public SOAPFault addFault() throws SOAPException;
  57. /**
  58. * Creates a new <code>SOAPFault</code> object and adds it to
  59. * this <code>SOAPBody</code> object. The type of the
  60. * <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2
  61. * <code>SOAPFault</code> depending on the <code>protocol</code>
  62. * specified while creating the <code>MessageFactory</code> instance.
  63. * <p>
  64. * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
  65. * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
  66. * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
  67. * the <code>faultCode</code> parameter is the value of the <code>faultcode</code>
  68. * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>
  69. * element.
  70. * <p>
  71. * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
  72. * child element.
  73. *
  74. * @param faultCode a <code>Name</code> object giving the fault
  75. * code to be set; must be one of the fault codes defined in the Version
  76. * of SOAP specification in use
  77. * @param faultString a <code>String</code> giving an explanation of
  78. * the fault
  79. * @param locale a {@link java.util.Locale} object indicating
  80. * the native language of the <code>faultString</code>
  81. * @return the new <code>SOAPFault</code> object
  82. * @exception SOAPException if there is a SOAP error
  83. * @see SOAPFault#setFaultCode
  84. * @see SOAPFault#setFaultString
  85. * @since SAAJ 1.2
  86. */
  87. public SOAPFault addFault(Name faultCode, String faultString, Locale locale) throws SOAPException;
  88. /**
  89. * Creates a new <code>SOAPFault</code> object and adds it to this
  90. * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>
  91. * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
  92. * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
  93. * instance.
  94. * <p>
  95. * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
  96. * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
  97. * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
  98. * the <code>faultCode</code> parameter is the value of the <code>faultcode</code>
  99. * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>
  100. * element.
  101. * <p>
  102. * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
  103. * child element.
  104. *
  105. * @param faultCode
  106. * a <code>QName</code> object giving the fault code to be
  107. * set; must be one of the fault codes defined in the version
  108. * of SOAP specification in use.
  109. * @param faultString
  110. * a <code>String</code> giving an explanation of the fault
  111. * @param locale
  112. * a {@link java.util.Locale Locale} object indicating the
  113. * native language of the <code>faultString</code>
  114. * @return the new <code>SOAPFault</code> object
  115. * @exception SOAPException
  116. * if there is a SOAP error
  117. * @see SOAPFault#setFaultCode
  118. * @see SOAPFault#setFaultString
  119. * @see SOAPBody#addFault(Name faultCode, String faultString, Locale locale)
  120. *
  121. * @since SAAJ 1.3
  122. */
  123. public SOAPFault addFault(QName faultCode, String faultString, Locale locale)
  124. throws SOAPException;
  125. /**
  126. * Creates a new <code>SOAPFault</code> object and adds it to this
  127. * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>
  128. * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
  129. * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
  130. * instance.
  131. * <p>
  132. * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
  133. * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
  134. * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
  135. * the <code>faultCode</code> parameter is the value of the <i>faultcode</i>
  136. * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>
  137. * element.
  138. * <p>
  139. * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>
  140. * attribute on the <i>Fault/Reason/Text</i> element will be set to
  141. * <code>java.util.Locale.getDefault()</code>
  142. * <p>
  143. * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
  144. * child element.
  145. *
  146. * @param faultCode
  147. * a <code>Name</code> object giving the fault code to be set;
  148. * must be one of the fault codes defined in the version of SOAP
  149. * specification in use
  150. * @param faultString
  151. * a <code>String</code> giving an explanation of the fault
  152. * @return the new <code>SOAPFault</code> object
  153. * @exception SOAPException
  154. * if there is a SOAP error
  155. * @see SOAPFault#setFaultCode
  156. * @see SOAPFault#setFaultString
  157. * @since SAAJ 1.2
  158. */
  159. public SOAPFault addFault(Name faultCode, String faultString)
  160. throws SOAPException;
  161. /**
  162. * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code>
  163. * object. The type of the <code>SOAPFault</code>
  164. * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
  165. * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
  166. * instance.
  167. * <p>
  168. * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
  169. * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
  170. * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
  171. * the <code>faultCode</code> parameter is the value of the <i>faultcode</i>
  172. * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>
  173. * element.
  174. * <p>
  175. * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>
  176. * attribute on the <i>Fault/Reason/Text</i> element will be set to
  177. * <code>java.util.Locale.getDefault()</code>
  178. * <p>
  179. * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
  180. * child element
  181. *
  182. * @param faultCode
  183. * a <code>QName</code> object giving the fault code to be
  184. * set; must be one of the fault codes defined in the version
  185. * of SOAP specification in use
  186. * @param faultString
  187. * a <code>String</code> giving an explanation of the fault
  188. * @return the new <code>SOAPFault</code> object
  189. * @exception SOAPException
  190. * if there is a SOAP error
  191. * @see SOAPFault#setFaultCode
  192. * @see SOAPFault#setFaultString
  193. * @see SOAPBody#addFault(Name faultCode, String faultString)
  194. * @since SAAJ 1.3
  195. */
  196. public SOAPFault addFault(QName faultCode, String faultString)
  197. throws SOAPException;
  198. /**
  199. * Indicates whether a <code>SOAPFault</code> object exists in this
  200. * <code>SOAPBody</code> object.
  201. *
  202. * @return <code>true</code> if a <code>SOAPFault</code> object exists
  203. * in this <code>SOAPBody</code> object; <code>false</code>
  204. * otherwise
  205. */
  206. public boolean hasFault();
  207. /**
  208. * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code>
  209. * object.
  210. *
  211. * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code>
  212. * object if present, null otherwise.
  213. */
  214. public SOAPFault getFault();
  215. /**
  216. * Creates a new <code>SOAPBodyElement</code> object with the specified
  217. * name and adds it to this <code>SOAPBody</code> object.
  218. *
  219. * @param name
  220. * a <code>Name</code> object with the name for the new <code>SOAPBodyElement</code>
  221. * object
  222. * @return the new <code>SOAPBodyElement</code> object
  223. * @exception SOAPException
  224. * if a SOAP error occurs
  225. * @see SOAPBody#addBodyElement(javax.xml.namespace.QName)
  226. */
  227. public SOAPBodyElement addBodyElement(Name name) throws SOAPException;
  228. /**
  229. * Creates a new <code>SOAPBodyElement</code> object with the specified
  230. * QName and adds it to this <code>SOAPBody</code> object.
  231. *
  232. * @param qname
  233. * a <code>QName</code> object with the qname for the new
  234. * <code>SOAPBodyElement</code> object
  235. * @return the new <code>SOAPBodyElement</code> object
  236. * @exception SOAPException
  237. * if a SOAP error occurs
  238. * @see SOAPBody#addBodyElement(Name)
  239. * @since SAAJ 1.3
  240. */
  241. public SOAPBodyElement addBodyElement(QName qname) throws SOAPException;
  242. /**
  243. * Adds the root node of the DOM <code>{@link org.w3c.dom.Document}</code>
  244. * to this <code>SOAPBody</code> object.
  245. * <p>
  246. * Calling this method invalidates the <code>document</code> parameter.
  247. * The client application should discard all references to this <code>Document</code>
  248. * and its contents upon calling <code>addDocument</code>. The behavior
  249. * of an application that continues to use such references is undefined.
  250. *
  251. * @param document
  252. * the <code>Document</code> object whose root node will be
  253. * added to this <code>SOAPBody</code>.
  254. * @return the <code>SOAPBodyElement</code> that represents the root node
  255. * that was added.
  256. * @exception SOAPException
  257. * if the <code>Document</code> cannot be added
  258. * @since SAAJ 1.2
  259. */
  260. public SOAPBodyElement addDocument(org.w3c.dom.Document document)
  261. throws SOAPException;
  262. /**
  263. * Creates a new DOM <code>{@link org.w3c.dom.Document}</code> and sets
  264. * the first child of this <code>SOAPBody</code> as it's document
  265. * element. The child <code>SOAPElement</code> is removed as part of the
  266. * process.
  267. *
  268. * @return the <code>{@link org.w3c.dom.Document}</code> representation
  269. * of the <code>SOAPBody</code> content.
  270. *
  271. * @exception SOAPException
  272. * if there is not exactly one child <code>SOAPElement</code> of the <code>
  273. * <code>SOAPBody</code>.
  274. *
  275. * @since SAAJ 1.3
  276. */
  277. public org.w3c.dom.Document extractContentAsDocument()
  278. throws SOAPException;
  279. }