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

Fleshed out the client chapter (a tad).

Browse Source
This commit is contained in:
Rick Evans
2007-05-28 14:41:30 +00:00
parent d069a7fdaf
commit 1514def3a6
1 changed files with 106 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
src/docbkx/client.xml
View File

@@ -6,17 +6,19 @@
<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 the use of <link linkend="oxm">marshallers and unmarshallers</link>.
Spring-WS provides a client-side Web service API that allows for consistent, XML-driven access to
Web services. It also caters for the use of <link linkend="oxm">marshallers and unmarshallers</link>
so that your service tier code can deal exclusively with Java objects.
</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 simplify 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
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 transport options.
The <package>org.springframework.ws.client.core</package> package provides the core functionality
for using the client-side access API. It contains template classes that simplify the use of Web
services, much like the core Spring <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 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 transport options.
</para>
</section>
<section>
@@ -24,28 +26,33 @@
<section id="client-web-service-template">
<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.
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 any response XML into an object again.
</para>
<section>
<title>URIs and Transports</title>
<para>
The <classname>WebServiceTemplate</classname> uses an URI as the message destination. You can either
set a <property>defaultUri</property> property on the template itself, or give an URI when calling
a method on the template. The URI will be resolved into a
a <interfacename>MessageSender</interfacename>. The message sender is responsible for sending the XML
message across a transport layer. You can set one or more message senders using the
<property>messageSender</property> or <property>messageSenders</property>.
The <classname>WebServiceTemplate</classname> class uses an URI as the message destination.
You can either set a <property>defaultUri</property> property on the template itself,
or supply an URI explicitly when calling a method on the template. The URI will be
resolved into a <interfacename>WebServiceMessageSender</interfacename>, which is
responsible for sending the XML message across a transport layer. You can set one or
more message senders using the <property>messageSender</property> or
<property>messageSenders</property> properties of the
<classname>WebServiceTemplate</classname> class.
</para>
<para>
There are two implementations of the <classname>MessageSender</classname> interface for sending
messages via HTTP. The default 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.
There are two implementations of the <classname>WebServiceMessageSender</classname>
interface for sending messages via HTTP. The default implementation is the
<classname>HttpUrlConnectionMessageSender</classname>, which uses the facilities provided
by Java itself. The alternative is the <classname>CommonsHttpMessageSender</classname>,
which uses the
<link linkend="http://jakarta.apache.org/commons/httpclient/">Jakarta Commons HttpClient</link>.
Use the latter if you need more advanced and easy-to-use functionality (such as authentication,
HTTP connection pooling, and so forth).
</para>
</section>
<section>
@@ -64,7 +71,7 @@
</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>
web service messages. There are methods that accept and return a <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.
@@ -83,18 +90,26 @@ public class WebServiceClient {
private static final String MESSAGE = "<message xmlns=\"http://tempuri.org\">Hello Web Service World</message>";
private WebServiceTemplate webServiceTemplate = new WebServiceTemplate();
private final WebServiceTemplate webServiceTemplate = new WebServiceTemplate();
public void setDefaultUri(String defaultUri) {
webServiceTemplate.setDefaultUri(defaultUri);
}
]]><lineannotation>// send to the configured default URI</lineannotation><![CDATA[
public void simpleSendAndReceive() {
StreamSource source = new StreamSource(new StringReader(MESSAGE));
StreamResult result = new StreamResult(System.out);
webServiceTemplate.sendAndReceive(source, result);
}
]]><lineannotation>// send to an explicit URI</lineannotation><![CDATA[
public void customSendAndReceive() {
StreamSource source = new StreamSource(new StringReader(MESSAGE));
StreamResult result = new StreamResult(System.out);
webServiceTemplate.sendAndReceive("http://localhost:8080/AnotherWebService", source, result);
}
}]]></programlisting>
<programlisting><![CDATA[
<beans xmlns="http://www.springframework.org/schema/beans">
@@ -105,30 +120,43 @@ public class WebServiceClient {
</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 default URI. 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.
The above example uses the <classname>WebServiceTemplate</classname> to send a hello
world message to the web service located at <uri>http://localhost:8080/WebService</uri>
(in the case of the <methodname>simpleSendAndReceive()</methodname> method),
and writes the result to the console. The <classname>WebServiceTemplate</classname> is
injected with the default URI, which is used because no URI was supplied explicitly
in the Java code.
</para>
<para>
Please note that the <classname>WebServiceTemplate</classname> class is threadsafe once
configured (assuming that all of it's dependencies are threadsafe too, which is the case for
all of the dependencies that ship with Spring-WS), and so multiple objects can use the same
shared <classname>WebServiceTemplate</classname> instance if so desired.
The <classname>WebServiceTemplate</classname> exposes a zero argument constructor and
<property>messageFactory</property>/<property>messageSender</property> bean properties which
can be used for constructing the instance (using a Spring container or plain Java code).
Alternatively, consider deriving from Spring-WS's <classname>WebServiceGatewaySupport</classname>
convenience base class, which exposes convenient bean properties to enable easy configuration.
(You do <emphasis>not</emphasis> have to extend this base class... it is provided as a convenience
class only.)
</para>
</section>
<section>
<title>Marshalling, sending, receiving, and unmarshalling</title>
<title>Sending and receiving POJOs - marshalling and unmarshalling</title>
<para>
In order to facilitate the sending of plain Java objects, the <classname>WebServiceTemplate</classname>
has a number of 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 <interfacename>Marshaller</interfacename>, and
the conversion of the response XML to an object to an <interfacename>Unmarshaller</interfacename>.
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
In order to facilitate the sending of plain Java objects, the
<classname>WebServiceTemplate</classname> has a number of <literal>send(..)</literal> methods
that take an <classname>Object</classname> as an argument for a message's data content.
The method <methodname>marshalSendAndReceive(..)</methodname> in the
<classname>WebServiceTemplate</classname> class delegates the conversion of the request object
to XML to a <interfacename>Marshaller</interfacename>, and the conversion of the response
XML to an object to an <interfacename>Unmarshaller</interfacename>. (For more information
about marshalling and unmarshaller, refer to <xref linkend="oxm"/>.) By using the
marshallers, 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>.
<classname>WebServiceTemplate</classname> class.
</para>
</section>
<section>
@@ -137,17 +165,46 @@ public class WebServiceClient {
</title>
<para>
To accommodate the setting of 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.
<interfacename>WebServiceMessageCallback</interfacename> interface gives you access to the
message <emphasis>after</emphasis> it has been created, but <emphasis>before</emphasis> 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>
<title>
<interfacename>WebServiceMessageExtractor</interfacename>
</title>
<para>
The <interfacename>WebServiceMessageExtractor</interfacename> interface is a low-level
callback interface that allows you to have full control over the process to extract an
<classname>Object</classname> from a received <interfacename>WebServiceMessage</interfacename>.
The <classname>WebServiceTemplate</classname> will invoke the <methodname>extractData(..)</methodname>
method on a supplied <interfacename>WebServiceMessageExtractor</interfacename>
<emphasis>while the underlying connection to the serving resource is still open</emphasis>.
The following example illustrates the <interfacename>WebServiceMessageExtractor</interfacename>
in action:
</para>
<programlisting><![CDATA[
public void marshalWithSoapActionHeader(MyObject o) {
webServiceTemplate.sendAndReceive(o, new WebServiceMessageExtractor() {
public Object extractData(WebServiceMessage message) throws IOException
]]><lineannotation>// do your own transforms with message.getPayloadResult()</lineannotation><![CDATA[
]]><lineannotation>// or message.getPayloadSource()</lineannotation><![CDATA[
}
});
}]]></programlisting>
</section>
</section>