View Javadoc

1   /*
2    * Copyright 2006 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.ws.soap;
18  
19  import java.util.Locale;
20  import javax.xml.transform.Result;
21  import javax.xml.transform.Source;
22  
23  import org.springframework.ws.WebServiceMessage;
24  
25  /**
26   * Represents the <code>Body</code> element in a SOAP message. A SOAP body contains the <strong>payload</strong> of the
27   * message. This payload can be custom XML, or a <code>SoapFault</code> (but not both).
28   * <p/>
29   * Note that the source returned by <code>getSource()</code> includes the SOAP Body element itself. For the contents of
30   * the body, use <code>getPayloadSource()</code>.
31   *
32   * @author Arjen Poutsma
33   * @see SoapEnvelope#getBody()
34   * @see #getPayloadSource()
35   * @see #getPayloadResult()
36   * @see SoapFault
37   * @since 1.0.0
38   */
39  public interface SoapBody extends SoapElement {
40  
41      /**
42       * Returns a <code>Source</code> that represents the contents of the body.
43       *
44       * @return the message contents
45       * @see WebServiceMessage#getPayloadSource()
46       */
47      Source getPayloadSource();
48  
49      /**
50       * Returns a <code>Result</code> that represents the contents of the body.
51       * <p/>
52       * Calling this method removes the current content of the body.
53       *
54       * @return the message contents
55       * @see WebServiceMessage#getPayloadResult()
56       */
57      Result getPayloadResult();
58  
59      /**
60       * Adds a <code>MustUnderstand</code> fault to the body. A <code>MustUnderstand</code> is returned when a SOAP
61       * header with a <code>MustUnderstand</code> attribute is not understood.
62       * <p/>
63       * Adding a fault removes the current content of the body.
64       *
65       * @param faultStringOrReason the SOAP 1.1 fault string or SOAP 1.2 reason text
66       * @param locale              the language of faultStringOrReason. Optional for SOAP 1.1
67       * @return the created <code>SoapFault</code>
68       */
69      SoapFault addMustUnderstandFault(String faultStringOrReason, Locale locale) throws SoapFaultException;
70  
71      /**
72       * Adds a <code>Client</code>/<code>Sender</code> fault to the body. For SOAP 1.1, this adds a fault with a
73       * <code>Client</code> fault code. For SOAP 1.2, this adds a fault with a <code>Sender</code> code.
74       * <p/>
75       * Adding a fault removes the current content of the body.
76       *
77       * @param faultStringOrReason the SOAP 1.1 fault string or SOAP 1.2 reason text
78       * @param locale              the language of faultStringOrReason. Optional for SOAP 1.1
79       * @return the created <code>SoapFault</code>
80       */
81      SoapFault addClientOrSenderFault(String faultStringOrReason, Locale locale) throws SoapFaultException;
82  
83      /**
84       * Adds a <code>Server</code>/<code>Receiver</code> fault to the body. For SOAP 1.1, this adds a fault with a
85       * <code>Server</code> fault code. For SOAP 1.2, this adds a fault with a <code>Receiver</code> code.
86       * <p/>
87       * Adding a fault removes the current content of the body.
88       *
89       * @param faultStringOrReason the SOAP 1.1 fault string or SOAP 1.2 reason text
90       * @param locale              the language of faultStringOrReason. Optional for SOAP 1.1
91       * @return the created <code>SoapFault</code>
92       */
93      SoapFault addServerOrReceiverFault(String faultStringOrReason, Locale locale) throws SoapFaultException;
94  
95      /**
96       * Adds a <code>VersionMismatch</code> fault to the body.
97       * <p/>
98       * Adding a fault removes the current content of the body.
99       *
100      * @param faultStringOrReason the SOAP 1.1 fault string or SOAP 1.2 reason text
101      * @param locale              the language of faultStringOrReason. Optional for SOAP 1.1
102      * @return the created <code>SoapFault</code>
103      */
104     SoapFault addVersionMismatchFault(String faultStringOrReason, Locale locale) throws SoapFaultException;
105 
106     /**
107      * Indicates whether this body has a <code>SoapFault</code>.
108      *
109      * @return <code>true</code> if the body has a fault; <code>false</code> otherwise
110      */
111     boolean hasFault();
112 
113     /**
114      * Returns the <code>SoapFault</code> of this body.
115      *
116      * @return the <code>SoapFault</code>, or <code>null</code> if none is present
117      */
118     SoapFault getFault();
119 }