1 /*
2 * Copyright 2005-2011 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.client.core;
18
19 import javax.xml.transform.Result;
20 import javax.xml.transform.Source;
21
22 import org.springframework.oxm.XmlMappingException;
23 import org.springframework.ws.client.WebServiceClientException;
24
25 /**
26 * Specifies a basic set of Web service operations. Implemented by {@link WebServiceTemplate}. Not often used directly,
27 * but a useful option to enhance testability, as it can easily be mocked or stubbed.
28 *
29 * @author Arjen Poutsma
30 * @see WebServiceTemplate
31 * @since 1.0.0
32 */
33 public interface WebServiceOperations {
34
35 /**
36 * Sends a web service message that can be manipulated with the given callback, reading the result with a
37 * <code>WebServiceMessageExtractor</code>.
38 * <p/>
39 * This will only work with a default uri specified!
40 *
41 * @param requestCallback the requestCallback to be used for manipulating the request message
42 * @param responseExtractor object that will extract results
43 * @return an arbitrary result object, as returned by the <code>WebServiceMessageExtractor</code>
44 * @throws WebServiceClientException if there is a problem sending or receiving the message
45 */
46 <T> T sendAndReceive(WebServiceMessageCallback requestCallback, WebServiceMessageExtractor<T> responseExtractor)
47 throws WebServiceClientException;
48
49 /**
50 * Sends a web service message that can be manipulated with the given callback, reading the result with a
51 * <code>WebServiceMessageExtractor</code>.
52 *
53 * @param uri the URI to send the message to
54 * @param requestCallback the requestCallback to be used for manipulating the request message
55 * @param responseExtractor object that will extract results
56 * @return an arbitrary result object, as returned by the <code>WebServiceMessageExtractor</code>
57 * @throws WebServiceClientException if there is a problem sending or receiving the message
58 */
59 <T> T sendAndReceive(String uri,
60 WebServiceMessageCallback requestCallback,
61 WebServiceMessageExtractor<T> responseExtractor) throws WebServiceClientException;
62
63 /**
64 * Sends a web service message that can be manipulated with the given request callback, handling the response with a
65 * response callback.
66 * <p/>
67 * This will only work with a default uri specified!
68 *
69 * @param requestCallback the callback to be used for manipulating the request message
70 * @param responseCallback the callback to be used for manipulating the response message
71 * @return <code>true</code> if a response was received; <code>false</code> otherwise
72 * @throws WebServiceClientException if there is a problem sending or receiving the message
73 */
74 boolean sendAndReceive(WebServiceMessageCallback requestCallback, WebServiceMessageCallback responseCallback)
75 throws WebServiceClientException;
76
77 /**
78 * Sends a web service message that can be manipulated with the given request callback, handling the response with a
79 * response callback.
80 *
81 * @param uri the URI to send the message to
82 * @param requestCallback the callback to be used for manipulating the request message
83 * @param responseCallback the callback to be used for manipulating the response message
84 * @return <code>true</code> if a response was received; <code>false</code> otherwise
85 * @throws WebServiceClientException if there is a problem sending or receiving the message
86 */
87 boolean sendAndReceive(String uri,
88 WebServiceMessageCallback requestCallback,
89 WebServiceMessageCallback responseCallback) throws WebServiceClientException;
90
91 //-----------------------------------------------------------------------------------------------------------------
92 // Convenience methods for sending and receiving marshalled messages
93 //-----------------------------------------------------------------------------------------------------------------
94
95 /**
96 * Sends a web service message that contains the given payload, marshalled by the configured
97 * <code>Marshaller</code>. Returns the unmarshalled payload of the response message, if any.
98 * <p/>
99 * This will only work with a default uri specified!
100 *
101 * @param requestPayload the object to marshal into the request message payload
102 * @return the unmarshalled payload of the response message, or <code>null</code> if no response is given
103 * @throws XmlMappingException if there is a problem marshalling or unmarshalling
104 * @throws WebServiceClientException if there is a problem sending or receiving the message
105 * @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
106 * @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
107 */
108 Object marshalSendAndReceive(Object requestPayload) throws XmlMappingException, WebServiceClientException;
109
110 /**
111 * Sends a web service message that contains the given payload, marshalled by the configured
112 * <code>Marshaller</code>. Returns the unmarshalled payload of the response message, if any.
113 *
114 * @param uri the URI to send the message to
115 * @param requestPayload the object to marshal into the request message payload
116 * @return the unmarshalled payload of the response message, or <code>null</code> if no response is given
117 * @throws XmlMappingException if there is a problem marshalling or unmarshalling
118 * @throws WebServiceClientException if there is a problem sending or receiving the message
119 * @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
120 * @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
121 */
122 Object marshalSendAndReceive(String uri, Object requestPayload)
123 throws XmlMappingException, WebServiceClientException;
124
125 /**
126 * Sends a web service message that contains the given payload, marshalled by the configured
127 * <code>Marshaller</code>. Returns the unmarshalled payload of the response message, if any. The given callback
128 * allows changing of the request message after the payload has been marshalled to it.
129 * <p/>
130 * This will only work with a default uri specified!
131 *
132 * @param requestPayload the object to marshal into the request message payload
133 * @param requestCallback callback to change message, can be <code>null</code>
134 * @return the unmarshalled payload of the response message, or <code>null</code> if no response is given
135 * @throws XmlMappingException if there is a problem marshalling or unmarshalling
136 * @throws WebServiceClientException if there is a problem sending or receiving the message
137 * @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
138 * @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
139 */
140 Object marshalSendAndReceive(Object requestPayload, WebServiceMessageCallback requestCallback)
141 throws XmlMappingException, WebServiceClientException;
142
143 /**
144 * Sends a web service message that contains the given payload, marshalled by the configured
145 * <code>Marshaller</code>. Returns the unmarshalled payload of the response message, if any. The given callback
146 * allows changing of the request message after the payload has been marshalled to it.
147 *
148 * @param uri the URI to send the message to
149 * @param requestPayload the object to marshal into the request message payload
150 * @param requestCallback callback to change message, can be <code>null</code>
151 * @return the unmarshalled payload of the response message, or <code>null</code> if no response is given
152 * @throws XmlMappingException if there is a problem marshalling or unmarshalling
153 * @throws WebServiceClientException if there is a problem sending or receiving the message
154 * @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
155 * @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
156 */
157 Object marshalSendAndReceive(String uri, Object requestPayload, WebServiceMessageCallback requestCallback)
158 throws XmlMappingException, WebServiceClientException;
159
160 //-----------------------------------------------------------------------------------------------------------------
161 // Convenience methods for sending Sources
162 //-----------------------------------------------------------------------------------------------------------------
163
164 /**
165 * Sends a web service message that contains the given payload, reading the result with a
166 * <code>SourceExtractor</code>.
167 * <p/>
168 * This will only work with a default uri specified!
169 *
170 * @param requestPayload the payload of the request message
171 * @param responseExtractor object that will extract results
172 * @return an arbitrary result object, as returned by the <code>SourceExtractor</code>
173 * @throws WebServiceClientException if there is a problem sending or receiving the message
174 */
175 <T> T sendSourceAndReceive(Source requestPayload, SourceExtractor<T> responseExtractor)
176 throws WebServiceClientException;
177
178 /**
179 * Sends a web service message that contains the given payload, reading the result with a
180 * <code>SourceExtractor</code>.
181 *
182 * @param uri the URI to send the message to
183 * @param requestPayload the payload of the request message
184 * @param responseExtractor object that will extract results
185 * @return an arbitrary result object, as returned by the <code>SourceExtractor</code>
186 * @throws WebServiceClientException if there is a problem sending or receiving the message
187 */
188 <T> T sendSourceAndReceive(String uri, Source requestPayload, SourceExtractor<T> responseExtractor)
189 throws WebServiceClientException;
190
191 /**
192 * Sends a web service message that contains the given payload, reading the result with a
193 * <code>SourceExtractor</code>.
194 * <p/>
195 * The given callback allows changing of the request message after the payload has been written to it.
196 * <p/>
197 * This will only work with a default uri specified!
198 *
199 * @param requestPayload the payload of the request message
200 * @param requestCallback callback to change message, can be <code>null</code>
201 * @param responseExtractor object that will extract results
202 * @return an arbitrary result object, as returned by the <code>SourceExtractor</code>
203 * @throws WebServiceClientException if there is a problem sending or receiving the message
204 */
205 <T> T sendSourceAndReceive(Source requestPayload,
206 WebServiceMessageCallback requestCallback,
207 SourceExtractor<T> responseExtractor) throws WebServiceClientException;
208
209 /**
210 * Sends a web service message that contains the given payload, reading the result with a
211 * <code>SourceExtractor</code>.
212 * <p/>
213 * The given callback allows changing of the request message after the payload has been written to it.
214 *
215 * @param uri the URI to send the message to
216 * @param requestPayload the payload of the request message
217 * @param requestCallback callback to change message, can be <code>null</code>
218 * @param responseExtractor object that will extract results
219 * @return an arbitrary result object, as returned by the <code>SourceExtractor</code>
220 * @throws WebServiceClientException if there is a problem sending or receiving the message
221 */
222 <T> T sendSourceAndReceive(String uri,
223 Source requestPayload,
224 WebServiceMessageCallback requestCallback,
225 SourceExtractor<T> responseExtractor) throws WebServiceClientException;
226
227 //-----------------------------------------------------------------------------------------------------------------
228 // Convenience methods for sending Sources and receiving to Results
229 //-----------------------------------------------------------------------------------------------------------------
230
231 /**
232 * Sends a web service message that contains the given payload. Writes the response, if any, to the given
233 * <code>Result</code>.
234 * <p/>
235 * This will only work with a default uri specified!
236 *
237 * @param requestPayload the payload of the request message
238 * @param responseResult the result to write the response payload to
239 * @return <code>true</code> if a response was received; <code>false</code> otherwise
240 * @throws WebServiceClientException if there is a problem sending or receiving the message
241 */
242 boolean sendSourceAndReceiveToResult(Source requestPayload, Result responseResult) throws WebServiceClientException;
243
244 /**
245 * Sends a web service message that contains the given payload. Writes the response, if any, to the given
246 * <code>Result</code>.
247 *
248 * @param uri the URI to send the message to
249 * @param requestPayload the payload of the request message
250 * @param responseResult the result to write the response payload to
251 * @return <code>true</code> if a response was received; <code>false</code> otherwise
252 * @throws WebServiceClientException if there is a problem sending or receiving the message
253 */
254 boolean sendSourceAndReceiveToResult(String uri, Source requestPayload, Result responseResult)
255 throws WebServiceClientException;
256
257 /**
258 * Sends a web service message that contains the given payload. Writes the response, if any, to the given
259 * <code>Result</code>.
260 * <p/>
261 * The given callback allows changing of the request message after the payload has been written to it.
262 * <p/>
263 * This will only work with a default uri specified!
264 *
265 * @param requestPayload the payload of the request message
266 * @param requestCallback callback to change message, can be <code>null</code>
267 * @param responseResult the result to write the response payload to
268 * @return <code>true</code> if a response was received; <code>false</code> otherwise
269 * @throws WebServiceClientException if there is a problem sending or receiving the message
270 */
271 boolean sendSourceAndReceiveToResult(Source requestPayload,
272 WebServiceMessageCallback requestCallback,
273 Result responseResult) throws WebServiceClientException;
274
275 /**
276 * Sends a web service message that contains the given payload. Writes the response, if any, to the given
277 * <code>Result</code>.
278 * <p/>
279 * The given callback allows changing of the request message after the payload has been written to it.
280 *
281 * @param uri the URI to send the message to
282 * @param requestPayload the payload of the request message
283 * @param requestCallback callback to change message, can be <code>null</code>
284 * @param responseResult the result to write the response payload to
285 * @return <code>true</code> if a response was received; <code>false</code> otherwise
286 * @throws WebServiceClientException if there is a problem sending or receiving the message
287 */
288 boolean sendSourceAndReceiveToResult(String uri,
289 Source requestPayload,
290 WebServiceMessageCallback requestCallback,
291 Result responseResult) throws WebServiceClientException;
292
293 }