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

Finished client-side docs.

Browse Source
This commit is contained in:
Arjen Poutsma
2007-02-16 23:51:33 +00:00
parent 0128036328
commit 8a3a9e21d1
2 changed files with 116 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
doc/src/docbkx/client.xml
View File

@@ -31,32 +31,130 @@
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>.
</para>
</section>
</section>
<section>
<title>Transports</title>
<title>Sending and receiving a <interfacename>WebServiceMessage</interfacename></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.
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;
import java.io.StringReader;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;
import org.springframework.ws.WebServiceMessageFactory;
import org.springframework.ws.client.core.WebServiceTemplate;
import org.springframework.ws.transport.WebServiceMessageSender;
public class WebServiceClient {
private static final String MESSAGE = "<message xmlns=\"http://tempuri.org\">Helo World</message>";
private WebServiceTemplate webServiceTemplate = new WebServiceTemplate();
public void setMessageFactory(WebServiceMessageFactory messageFactory) {
webServiceTemplate.setMessageFactory(messageFactory);
}
public void setMessageSender(WebServiceMessageSender messageSender) {
webServiceTemplate.setMessageSender(messageSender);
}
public void simpleSendAndReceive() throws IOException {
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[
<beans xmlns="http://www.springframework.org/schema/beans">
<bean id="webServiceClient" class="WebServiceClient">
<property name="messageFactory">
<bean class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory"/>
</property>
<property name="messageSender">
<bean class="org.springframework.ws.transport.http.HttpUrlConnectionMessageSender">
<property name="url" value="http://localhost:8080/WebService"/>
</bean>
</property>
</bean>
</beans>]]></programlisting>
<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.
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 factory and 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>Message factories</title>
<title>Marshalling, sending, receiving, and unmarshalling</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>.
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>
</chapter>
</chapter>

2
doc/src/docbkx/index.xml
View File

@@ -37,7 +37,7 @@
<title>Document-driven Web services with Spring-WS</title>
<para>This chapter will contain the reference for server-side Spring-WS usage.</para>
</chapter>
<xi:include href="server.xml" />
<!--<xi:include href="server.xml" />-->
<xi:include href="client.xml" />
<xi:include href="security.xml" />
<xi:include href="oxm.xml" />