Spring/spring-ws
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fixed SWS-119: Remove IOExceptions from WebServiceTemplate

Browse Source
This commit is contained in:
Arjen Poutsma
2007-05-13 01:19:12 +00:00
parent 0a07669a15
commit bf37f1fd36
12 changed files with 360 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
core/src/main/java/org/springframework/ws/client/WebServiceClientException.java
View File

@@ -19,9 +19,11 @@ package org.springframework.ws.client;
import org.springframework.ws.WebServiceException;
/**
* Exception thrown whenever an error occurs on the client-side.
*
* @author Arjen Poutsma
*/
public class WebServiceClientException extends WebServiceException {
public abstract class WebServiceClientException extends WebServiceException {
public WebServiceClientException(String msg) {
super(msg);

4
core/src/main/java/org/springframework/ws/client/core/WebServiceFaultException.java → core/src/main/java/org/springframework/ws/client/WebServiceFaultException.java
View File

@@ -14,9 +14,7 @@
* limitations under the License.
*/
package org.springframework.ws.client.core;
import org.springframework.ws.client.WebServiceClientException;
package org.springframework.ws.client;
/**
* Thrown by <code>SimpleFaultResolver</code> when the response message has a fault.

35
core/src/main/java/org/springframework/ws/client/WebServiceIOException.java Normal file
View File

@@ -0,0 +1,35 @@
/*
* Copyright 2007 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.ws.client;
import java.io.IOException;
/**
* Exception thrown whenever an I/O error occurs on the client-side.
*
* @author Arjen Poutsma
*/
public class WebServiceIOException extends WebServiceClientException {
public WebServiceIOException(String msg) {
super(msg);
}
public WebServiceIOException(String msg, IOException ex) {
super(msg, ex);
}
}

35
core/src/main/java/org/springframework/ws/client/WebServiceTransformerException.java Normal file
View File

@@ -0,0 +1,35 @@
/*
* Copyright 2007 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.ws.client;
import javax.xml.transform.TransformerException;
/**
* Exception thrown whenever an transformation error occurs on the client-side.
*
* @author Arjen Poutsma
*/
public class WebServiceTransformerException extends WebServiceClientException {
public WebServiceTransformerException(String msg) {
super(msg);
}
public WebServiceTransformerException(String msg, TransformerException ex) {
super(msg, ex);
}
}

35
core/src/main/java/org/springframework/ws/client/WebServiceTransportException.java Normal file
View File

@@ -0,0 +1,35 @@
/*
* Copyright 2007 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.ws.client;
import org.springframework.ws.transport.TransportException;
/**
* Exception thrown whenever an transport error occurs on the client-side.
*
* @author Arjen Poutsma
*/
public class WebServiceTransportException extends WebServiceIOException {
public WebServiceTransportException(String msg) {
super(msg);
}
public WebServiceTransportException(String msg, TransportException ex) {
super(msg, ex);
}
}

10
core/src/main/java/org/springframework/ws/client/core/SimpleFaultResolver.java
View File

@@ -17,18 +17,18 @@
package org.springframework.ws.client.core;
import org.springframework.ws.WebServiceMessage;
import org.springframework.ws.client.WebServiceFaultException;
/**
* Simple fault resolver that simply throws a {@link WebServiceFaultException} when a fault occurs.
* Simple fault resolver that simply throws a {@link org.springframework.ws.client.WebServiceFaultException} when a
* fault occurs.
*
* @author Arjen Poutsma
* @see WebServiceFaultException
* @see org.springframework.ws.client.WebServiceFaultException
*/
public class SimpleFaultResolver implements FaultResolver {
/**
* Throws a new <code>WebServiceFaultException</code>.
*/
/** Throws a new <code>WebServiceFaultException</code>. */
public void resolveFault(WebServiceMessage message) {
throw new WebServiceFaultException(message.getFaultReason());
}

40
core/src/main/java/org/springframework/ws/client/core/WebServiceOperations.java
View File

@@ -16,10 +16,12 @@
package org.springframework.ws.client.core;
import java.io.IOException;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import org.springframework.oxm.GenericMarshallingFailureException;
import org.springframework.ws.client.WebServiceClientException;
/**
* Specifies a basic set of Web service operations. Implemented by {@link WebServiceTemplate}. Not often used directly,
* but a useful option to enhance testability, as it can easily be mocked or stubbed.
@@ -35,11 +37,14 @@ public interface WebServiceOperations {
*
* @param requestPayload the object to marshal into the request message payload
* @return the unmarshalled payload of the response message, or <code>null</code> if no response is given
* @throws IOException in case of I/O errors
* @throws GenericMarshallingFailureException
* if there is a problem marshalling or unmarshalling
* @throws WebServiceClientException if there is a problem sending or receiving the message
* @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
* @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
*/
Object marshalSendAndReceive(Object requestPayload) throws IOException;
Object marshalSendAndReceive(Object requestPayload)
throws GenericMarshallingFailureException, WebServiceClientException;
/**
* Sends a web service message that contains the given payload, marshalled by the configured
@@ -49,11 +54,14 @@ public interface WebServiceOperations {
* @param requestPayload the object to marshal into the request message payload
* @param requestCallback callback to change message, can be <code>null</code>
* @return the unmarshalled payload of the response message, or <code>null</code> if no response is given
* @throws IOException in case of I/O errors
* @throws GenericMarshallingFailureException
* if there is a problem marshalling or unmarshalling
* @throws WebServiceClientException if there is a problem sending or receiving the message
* @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
* @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
*/
Object marshalSendAndReceive(Object requestPayload, WebServiceMessageCallback requestCallback) throws IOException;
Object marshalSendAndReceive(Object requestPayload, WebServiceMessageCallback requestCallback)
throws GenericMarshallingFailureException, WebServiceClientException;
/**
* Sends a web service message that contains the given payload, reading the result with a
@@ -62,8 +70,9 @@ public interface WebServiceOperations {
* @param requestPayload the payload of the request message
* @param responseExtractor object that will extract results
* @return an arbitrary result object, as returned by the <code>SourceExtractor</code>
* @throws WebServiceClientException if there is a problem sending or receiving the message
*/
Object sendAndReceive(Source requestPayload, SourceExtractor responseExtractor) throws IOException;
Object sendAndReceive(Source requestPayload, SourceExtractor responseExtractor) throws WebServiceClientException;
/**
* Sends a web service message that contains the given payload, reading the result with a
@@ -75,10 +84,11 @@ public interface WebServiceOperations {
* @param requestCallback callback to change message, can be <code>null</code>
* @param responseExtractor object that will extract results
* @return an arbitrary result object, as returned by the <code>SourceExtractor</code>
* @throws WebServiceClientException if there is a problem sending or receiving the message
*/
Object sendAndReceive(Source requestPayload,
WebServiceMessageCallback requestCallback,
SourceExtractor responseExtractor) throws IOException;
SourceExtractor responseExtractor) throws WebServiceClientException;
/**
* Sends a web service message that contains the given payload. Writes the response, if any, to the given
@@ -86,9 +96,9 @@ public interface WebServiceOperations {
*
* @param requestPayload the payload of the request message
* @param responseResult the result to write the response payload to
* @throws IOException in case of I/O errors
* @throws WebServiceClientException if there is a problem sending or receiving the message
*/
void sendAndReceive(Source requestPayload, Result responseResult) throws IOException;
void sendAndReceive(Source requestPayload, Result responseResult) throws WebServiceClientException;
/**
* Sends a web service message that contains the given payload. Writes the response, if any, to the given
@@ -99,10 +109,10 @@ public interface WebServiceOperations {
* @param requestPayload the payload of the request message
* @param requestCallback callback to change message, can be <code>null</code>
* @param responseResult the result to write the response payload to
* @throws IOException in case of I/O errors
* @throws WebServiceClientException if there is a problem sending or receiving the message
*/
void sendAndReceive(Source requestPayload, WebServiceMessageCallback requestCallback, Result responseResult)
throws IOException;
throws WebServiceClientException;
/**
* Sends a web service message that can be manipulated with the given callback, reading the result with a
@@ -111,10 +121,10 @@ public interface WebServiceOperations {
* @param requestCallback the requestCallback to be used for manipulating the request message
* @param responseExtractor object that will extract results
* @return an arbitrary result object, as returned by the <code>WebServiceMessageExtractor</code>
* @throws IOException in case of I/O errors
* @throws WebServiceClientException if there is a problem sending or receiving the message
*/
Object sendAndReceive(WebServiceMessageCallback requestCallback, WebServiceMessageExtractor responseExtractor)
throws IOException;
throws WebServiceClientException;
/**
* Sends a web service message that can be manipulated with the given callback, reading the result with a
@@ -122,8 +132,8 @@ public interface WebServiceOperations {
*
* @param requestCallback the callback to be used for manipulating the request message
* @param responseCallback the callback to be used for manipulating the response message
* @throws IOException in case of I/O errors
* @throws WebServiceClientException if there is a problem sending or receiving the message
*/
void sendAndReceive(WebServiceMessageCallback requestCallback, WebServiceMessageCallback responseCallback)
throws IOException;
throws WebServiceClientException;
}

54
core/src/main/java/org/springframework/ws/client/core/WebServiceTemplate.java
View File

@@ -36,10 +36,13 @@ import org.springframework.util.Assert;
import org.springframework.util.ClassUtils;
import org.springframework.ws.WebServiceMessage;
import org.springframework.ws.WebServiceMessageFactory;
import org.springframework.ws.client.WebServiceClientException;
import org.springframework.ws.client.WebServiceIOException;
import org.springframework.ws.client.WebServiceTransformerException;
import org.springframework.ws.client.WebServiceTransportException;
import org.springframework.ws.client.support.WebServiceAccessor;
import org.springframework.ws.context.MessageContext;
import org.springframework.ws.transport.FaultAwareWebServiceConnection;
import org.springframework.ws.transport.TransportException;
import org.springframework.ws.transport.TransportInputStream;
import org.springframework.ws.transport.TransportOutputStream;
import org.springframework.ws.transport.WebServiceConnection;
@@ -144,12 +147,11 @@ public class WebServiceTemplate extends WebServiceAccessor implements WebService
* Marshalling methods
*/
public Object marshalSendAndReceive(final Object requestPayload) throws IOException {
public Object marshalSendAndReceive(final Object requestPayload) {
return marshalSendAndReceive(requestPayload, null);
}
public Object marshalSendAndReceive(final Object requestPayload, final WebServiceMessageCallback requestCallback)
throws IOException {
public Object marshalSendAndReceive(final Object requestPayload, final WebServiceMessageCallback requestCallback) {
if (getMarshaller() == null) {
throw new IllegalStateException("No marshaller registered. Check configuration of WebServiceTemplate.");
}
@@ -176,13 +178,13 @@ public class WebServiceTemplate extends WebServiceAccessor implements WebService
* Result-handling methods
*/
public void sendAndReceive(Source requestPayload, Result responseResult) throws IOException {
public void sendAndReceive(Source requestPayload, Result responseResult) {
sendAndReceive(requestPayload, null, responseResult);
}
public void sendAndReceive(Source requestPayload,
WebServiceMessageCallback requestCallback,
final Result responseResult) throws IOException {
final Result responseResult) {
try {
final Transformer transformer = createTransformer();
doSendAndReceive(transformer, requestPayload, requestCallback, new SourceExtractor() {
@@ -192,14 +194,14 @@ public class WebServiceTemplate extends WebServiceAccessor implements WebService
transformer.transform(source, responseResult);
}
catch (TransformerException ex) {
throw new WebServiceClientException("Could not transform payload", ex);
throw new WebServiceTransformerException("Could not transform payload", ex);
}
return null;
}
});
}
catch (TransformerException ex) {
throw new WebServiceClientException("Could not create transformer", ex);
catch (TransformerConfigurationException ex) {
throw new WebServiceTransformerException("Could not create transformer", ex);
}
}
@@ -207,27 +209,26 @@ public class WebServiceTemplate extends WebServiceAccessor implements WebService
* Source-handling methods
*/
public Object sendAndReceive(final Source requestPayload, final SourceExtractor responseExtractor)
throws IOException {
public Object sendAndReceive(final Source requestPayload, final SourceExtractor responseExtractor) {
return sendAndReceive(requestPayload, null, responseExtractor);
}
public Object sendAndReceive(final Source requestPayload,
final WebServiceMessageCallback requestCallback,
final SourceExtractor responseExtractor) throws IOException {
final SourceExtractor responseExtractor) {
try {
return doSendAndReceive(createTransformer(), requestPayload, requestCallback, responseExtractor);
}
catch (TransformerConfigurationException ex) {
throw new WebServiceClientException("Could not create transformer", ex);
throw new WebServiceTransformerException("Could not create transformer", ex);
}
}
private Object doSendAndReceive(final Transformer transformer,
final Source requestPayload,
final WebServiceMessageCallback requestCallback,
final SourceExtractor responseExtractor) throws IOException {
final SourceExtractor responseExtractor) {
Assert.notNull(responseExtractor, "responseExtractor must not be null");
return sendAndReceive(new WebServiceMessageCallback() {
public void doInMessage(WebServiceMessage message) throws IOException {
@@ -238,7 +239,7 @@ public class WebServiceTemplate extends WebServiceAccessor implements WebService
}
}
catch (TransformerException ex) {
throw new WebServiceClientException("Could not transform payload to request message", ex);
throw new WebServiceTransformerException("Could not transform payload to request message", ex);
}
}
}, new SourceExtractorMessageExtractor(responseExtractor));
@@ -248,18 +249,18 @@ public class WebServiceTemplate extends WebServiceAccessor implements WebService
* WebServiceMessage-handling methods
*/
public void sendAndReceive(WebServiceMessageCallback requestCallback, WebServiceMessageCallback responseCallback)
throws IOException {
public void sendAndReceive(WebServiceMessageCallback requestCallback, WebServiceMessageCallback responseCallback) {
Assert.notNull(responseCallback, "responseCallback must not be null");
sendAndReceive(requestCallback, new WebServiceMessageCallbackMessageExtractor(responseCallback));
}
public Object sendAndReceive(WebServiceMessageCallback requestCallback,
WebServiceMessageExtractor responseExtractor) throws IOException {
WebServiceMessageExtractor responseExtractor) {
Assert.notNull(responseExtractor, "response extractor must not be null");
MessageContext messageContext = createMessageContext();
WebServiceConnection connection = getMessageSender().createConnection();
WebServiceConnection connection = null;
try {
connection = getMessageSender().createConnection();
WebServiceMessage request = messageContext.getRequest();
if (requestCallback != null) {
requestCallback.doInMessage(request);
@@ -287,8 +288,21 @@ public class WebServiceTemplate extends WebServiceAccessor implements WebService
}
return null;
}
catch (TransportException ex) {
throw new WebServiceTransportException("Could not use transport: " + ex.getMessage(), ex);
}
catch (IOException ex) {
throw new WebServiceIOException("I/O error: " + ex.getMessage(), ex);
}
finally {
connection.close();
if (connection != null) {
try {
connection.close();
}
catch (IOException ex) {
logger.debug("Could not close WebServiceConnection", ex);
}
}
}
}

1
core/src/test/java/org/springframework/ws/client/core/SimpleFaultResolverTest.java
View File

@@ -19,6 +19,7 @@ package org.springframework.ws.client.core;
import junit.framework.TestCase;
import org.easymock.MockControl;
import org.springframework.ws.WebServiceMessage;
import org.springframework.ws.client.WebServiceFaultException;
public class SimpleFaultResolverTest extends TestCase {

3
src/changes/changes.xml
View File

@@ -6,6 +6,9 @@
</properties>
<body>
<release version="1.0-RC1">
<action dev="poutsma" type="fix" issue="SWS-119">Remove IOExceptions from WebServiceTemplate. A runtime
exception hierarchy has been created in org.springframework.ws.client.
</action>
<action dev="poutsma" type="fix" issue="SWS-116">Support JAXB's MTOM/XOP/MIME support. As a result, all
Mime-related code in SoapMessage has been moved to the org.springframework.ws.mime package
</action>

287
src/docbkx/client.xml
View File

@@ -1,73 +1,117 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="client">
<title>Using Spring Web Services on the Client</title>
<section>
<title>Introduction</title>
<para>
Spring-WS provides a client-side Web service API that allows for consistent, XML-driven access to Web
services. It also allows for use of <link linkend="oxm">marshallers and unmarshallers</link>.
</para>
<para>
The package <package>org.springframework.ws.client.core</package> provides the core functionality for using
the client-side access API. It contains template classes that simplifies the use of Web services, much like
the <classname>JdbcTemplate</classname> does for JDBC. The design principle common to Spring template
classes is to provide helper methods to perform common operations and for more sophisticated usage, delegate
the essence of the processing task to user implemented callback interfaces. The Web service template
follows the same design. The classes offer various
convenience methods for the sending and receiving of XML messages, marshalling objects to XML before sending,
and allows for multiple transports,
</para>
</section>
<section>
<title>Using the client-side API</title>
<section>
<title><classname>WebServiceTemplate</classname></title>
<para>
The <classname>WebServiceTemplate</classname> is the core class for client-side Web service access in
Spring-WS. It contains methods for sending <classname>Source</classname> objects, and receiving response
messages as either <classname>Source</classname> or <classname>Result</classname>. Additionally, it can
marshal objects to XML before sending them across a transport, and unmarshal the response XML into an
object again.
</para>
<section>
<title>Transports</title>
<para>
The <classname>WebServiceTemplate</classname> requires a reference to a
<classname>MessageSender</classname>. The message sender is responsible for sending the XML message
across a transport layer.
</para>
<para>
There are two implementations of the <classname>MessageSender</classname> interface for sending messages
via HTTP. The simplest implementation is the <classname>HttpUrlConnectionMessageSender</classname>,
which uses the facilities provided by Java SE itself. The alternative is the
<classname>CommonsHttpMessageSender</classname>, which uses the Jakarta Commons HttpClient. Use the
latter if you need more advanced and easy-to-use functionality. Both HTTP message senders require an
URL to be set using the <property>url</property> property.
</para>
</section>
<section>
<title>Message factories</title>
<para>
In addition to a message sender, the <classname>WebServiceTemplate</classname> requires a Web service
message factory. As explained in <xref linkend="message-factories"/>, there are two message factories
for SOAP: <classname>SaajSoapMessageFactory</classname> and
<classname>AxiomSoapMessageFactory</classname>. If no message factory is specified, Spring-WS will
use the <classname>SaajSoapMessageFactory</classname> by default.
</para>
</section>
</section>
<section>
<title>Sending and receiving a <interfacename>WebServiceMessage</interfacename></title>
<para>
The <classname>WebServiceTemplate</classname> contains many convenience methods to send and receive
web service messages. There are methods that take and return <interfacename>Source</interfacename>
and those that return a <interfacename>Result</interfacename>. Additionally, there are methods which
marshal and unmarshal objects to XML. Here is an example that sends a simple XML message to a Web
service.</para>
<title>Using Spring Web Services on the Client</title>
<section>
<title>Introduction</title>
<para>
Spring-WS provides a client-side Web service API that allows for consistent, XML-driven access to Web
services. It also allows for use of
<link linkend="oxm">marshallers and unmarshallers</link>
.
</para>
<para>
The package
<package>org.springframework.ws.client.core</package>
provides the core functionality for using
the client-side access API. It contains template classes that simplifies the use of Web services, much like
the
<classname>JdbcTemplate</classname>
does for JDBC. The design principle common to Spring template
classes is to provide helper methods to perform common operations and for more sophisticated usage, delegate
the essence of the processing task to user implemented callback interfaces. The Web service template
follows the same design. The classes offer various
convenience methods for the sending and receiving of XML messages, marshalling objects to XML before
sending,
and allows for multiple transports,
</para>
</section>
<section>
<title>Using the client-side API</title>
<section>
<title>
<classname>WebServiceTemplate</classname>
</title>
<para>
The
<classname>WebServiceTemplate</classname>
is the core class for client-side Web service access in
Spring-WS. It contains methods for sending
<classname>Source</classname>
objects, and receiving response
messages as either
<classname>Source</classname>
or
<classname>Result</classname>
. Additionally, it can
marshal objects to XML before sending them across a transport, and unmarshal the response XML into an
object again.
</para>
<section>
<title>Transports</title>
<para>
The
<classname>WebServiceTemplate</classname>
requires a reference to a
<classname>MessageSender</classname>
. The message sender is responsible for sending the XML message
across a transport layer.
</para>
<para>
There are two implementations of the
<classname>MessageSender</classname>
interface for sending messages
via HTTP. The simplest implementation is the
<classname>HttpUrlConnectionMessageSender</classname>
,
which uses the facilities provided by Java SE itself. The alternative is the
<classname>CommonsHttpMessageSender</classname>
, which uses the Jakarta Commons HttpClient. Use the
latter if you need more advanced and easy-to-use functionality. Both HTTP message senders require an
URL to be set using the
<property>url</property>
property.
</para>
</section>
<section>
<title>Message factories</title>
<para>
In addition to a message sender, the
<classname>WebServiceTemplate</classname>
requires a Web service
message factory. As explained in
<xref linkend="message-factories"/>
, there are two message factories
for SOAP:
<classname>SaajSoapMessageFactory</classname>
and
<classname>AxiomSoapMessageFactory</classname>
. If no message factory is specified, Spring-WS will
use the
<classname>SaajSoapMessageFactory</classname>
by default.
</para>
</section>
</section>
<section>
<title>Sending and receiving a
<interfacename>WebServiceMessage</interfacename>
</title>
<para>
The
<classname>WebServiceTemplate</classname>
contains many convenience methods to send and receive
web service messages. There are methods that take and return
<interfacename>Source</interfacename>
and those that return a
<interfacename>Result</interfacename>
. Additionally, there are methods which
marshal and unmarshal objects to XML. Here is an example that sends a simple XML message to a Web
service.
</para>
<programlisting><![CDATA[import java.io.IOException;
<programlisting><![CDATA[
import java.io.StringReader;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;
@@ -89,17 +133,17 @@ public class WebServiceClient {
webServiceTemplate.setMessageSender(messageSender);
}
public void simpleSendAndReceive() throws IOException {
public void simpleSendAndReceive() {
StreamSource source = new StreamSource(new StringReader(MESSAGE));
StreamResult result = new StreamResult(System.out);
webServiceTemplate.sendAndReceive(source, result);
}
}]]></programlisting>
<para>
Here is the corresponding configuration:
</para>
<programlisting><![CDATA[
<para>
Here is the corresponding configuration:
</para>
<programlisting><![CDATA[
<beans xmlns="http://www.springframework.org/schema/beans">
<bean id="webServiceClient" class="WebServiceClient">
@@ -111,48 +155,73 @@ public class WebServiceClient {
</bean>
</beans>]]></programlisting>
<para>
This example uses the template to send a hello world message to the web service located at
<uri>http://localhost:8080/WebService</uri>, and writes the result to the console.
The <classname>WebServiceTemplate</classname> is injected with the message sender.
A zero argument constructor and <property>messageFactory</property> /
<property>messageSender</property> bean properties are provided and can be used for constructing
the instance (using a BeanFactory or plain Java code). Alternatively, consider deriving from
Spring-WS's <classname>WebServiceGatewaySupport</classname> convenience base class, which provides
pre-built bean properties for configuration.
</para>
</section>
<section>
<title>Marshalling, sending, receiving, and unmarshalling</title>
<para>
In order to facilitate the sending of plain Java objects, the <classname>WebServiceTemplate</classname>
has a send methods that take an object as an argument for a message's data content.
The method <methodname>marshalSendAndReceive</methodname> in <classname>WebServiceTemplate</classname>
delegates the conversion of the request object to XML to a <interface>Marshaller</interface>, and
the conversion of the response XML to an object to an <interface>Unmarshaller</interface>.
For more information about marshalling and unmarshaller, refer to <xref linkend="oxm"/>.
By using the marshallers, you and your application code can focus on the business object that is being
sent or received and not be concerned with the details of how it is represented as XML.
In order to use the marshalling functionality, you have to set a marshaller and unmarshaller with the
<property>marshaller</property>/<property>unmarshaller</property> properties of the
<classname>WebServiceTemplate</classname>.
</para>
</section>
<section>
<title><interface>WebServiceMessageCallback</interface></title>
<para>
To accommodate the setting of a SOAP headers, and other settings on the message, the
<interfacename>WebServiceMessageCallback</interfacename> interface gives you access to the message
after it has been created, but before it is sent. The example below demonstrates how to set the SOAP
Action header on a message that is created by marshalling an object.
</para>
<programlisting><![CDATA[public void marshalWithSoapActionHeader(MyObject o) {
<para>
This example uses the template to send a hello world message to the web service located at
<uri>http://localhost:8080/WebService</uri>
, and writes the result to the console.
The
<classname>WebServiceTemplate</classname>
is injected with the message sender.
A zero argument constructor and
<property>messageFactory</property>
/
<property>messageSender</property>
bean properties are provided and can be used for constructing
the instance (using a BeanFactory or plain Java code). Alternatively, consider deriving from
Spring-WS's
<classname>WebServiceGatewaySupport</classname>
convenience base class, which provides
pre-built bean properties for configuration.
</para>
</section>
<section>
<title>Marshalling, sending, receiving, and unmarshalling</title>
<para>
In order to facilitate the sending of plain Java objects, the
<classname>WebServiceTemplate</classname>
has a send methods that take an object as an argument for a message's data content.
The method
<methodname>marshalSendAndReceive</methodname>
in
<classname>WebServiceTemplate</classname>
delegates the conversion of the request object to XML to a
<interface>Marshaller</interface>
, and
the conversion of the response XML to an object to an
<interface>Unmarshaller</interface>
.
For more information about marshalling and unmarshaller, refer to
<xref linkend="oxm"/>
.
By using the marshallers, you and your application code can focus on the business object that is being
sent or received and not be concerned with the details of how it is represented as XML.
In order to use the marshalling functionality, you have to set a marshaller and unmarshaller with the
<property>marshaller</property>
/
<property>unmarshaller</property>
properties of the
<classname>WebServiceTemplate</classname>
.
</para>
</section>
<section>
<title>
<interface>WebServiceMessageCallback</interface>
</title>
<para>
To accommodate the setting of a SOAP headers, and other settings on the message, the
<interfacename>WebServiceMessageCallback</interfacename>
interface gives you access to the message
after it has been created, but before it is sent. The example below demonstrates how to set the SOAP
Action header on a message that is created by marshalling an object.
</para>
<programlisting><![CDATA[public void marshalWithSoapActionHeader(MyObject o) {
webServiceTemplate.marshalSendAndReceive(o, new WebServiceMessageCallback() {
public void doInMessage(WebServiceMessage message) {
((SoapMessage)message).setSoapAction("http://tempuri.org/Action");
}
});
}]]></programlisting>
</section>
</section>
</section>
</section>
</chapter>

5
src/site/apt/upgrading.apt
View File

@@ -15,6 +15,11 @@ Upgrading from version 1.0-M3 to 1.0-RC1
* Methods for getting and adding attachments were taken from <<<SoapMessage>> and extraced into a new interface:
<<<MimeMessage>>>. Adding a method requires a content id now.
* WebServiceTemplate
The <<<WebServiceTemplate>> no longer declares an IOException for each method. Rather, an runtime exception
hierarchy has been created in <<<org.springframework.ws.client>>>.
Upgrading from version 1.0-M2 to 1.0-M3
Several changes were made between version 1.0 Milestone 2 and Milestone 3 of the project. These changes increased