From 642281dc89f953c3666dc4405e4d3a3f3da9b239 Mon Sep 17 00:00:00 2001
From: Arjen Poutsma <apoutsma@vmware.com>
Date: Tue, 13 Nov 2007 19:43:22 +0000
Subject: [PATCH] SWS-139: mail support

---
 src/docbkx/client.xml | 98 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 95 insertions(+), 3 deletions(-)

diff --git a/src/docbkx/client.xml b/src/docbkx/client.xml
index de993540..517c7289 100644
--- a/src/docbkx/client.xml
+++ b/src/docbkx/client.xml
@@ -61,6 +61,37 @@
                         <uri>http://example.com/services</uri>, or supply the <parameter>uri</parameter> parameter
                         for one of the methods.
                     </para>
+                    <para>
+                        The following example shows how the default configuration can be used for HTTP transports:
+                        <programlisting><![CDATA[<beans>
+
+    <bean id="messageFactory" class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory"/>
+
+    <bean id="webServiceTemplate" class="org.springframework.ws.client.core.WebServiceTemplate">
+        <constructor-arg ref="messageFactory"/>
+        <property name="defaultUri" value="http://example.com/WebService"/>
+    </bean>
+
+</beans>]]></programlisting>
+                    </para>
+                    <para>
+                        The folowing example shows how override the default configuration, and to use Commons Http to
+                        authenticate using HTTP authentication:
+                        <programlisting><![CDATA[<bean id="webServiceTemplate" class="org.springframework.ws.client.core.WebServiceTemplate">
+    <constructor-arg ref="messageFactory"/>
+    <property name="messageSender">
+        <bean class="org.springframework.ws.transport.http.CommonsHttpMessageSender">
+            <property name="credentials">
+                <bean class="org.apache.commons.httpclient.UsernamePasswordCredentials">
+                    <constructor-arg value="john"/>
+                    <constructor-arg value="secret"/>
+                </bean>
+            </property>
+        </bean>
+    </property>
+    <property name="defaultUri" value="http://example.com/WebService"/>
+</bean>]]></programlisting>
+                    </para>
                 </section>
                 <section>
                     <title>JMS transport</title>
@@ -74,7 +105,7 @@
                     </para>
                     <para>
                         To use the <classname>JmsMessageSender</classname>, you need to set the
-                        <property>defaultUri</property> or <parameter>uri</parameter> to a JMS URI, which - at a
+                        <property>defaultUri</property> or <parameter>uri</parameter> parameter to a JMS URI, which - at a
                         minimum - consists of the <literal>jms:</literal> prefix and a destination name. Some examples of
                         JMS URIs are: <uri>jms:SomeQueue</uri>,
                         <uri>jms:SomeTopic?priority=3&amp;deliveryMode=NON_PERSISTENT</uri>, and
@@ -82,6 +113,67 @@
                         For more information on this URI syntax, refer to the class level Javadocs of the
                         <classname>JmsMessageSender</classname>.
                     </para>
+                    <para>
+                        The following example shows how to use the JMS transport in combination with an ActiceMQ
+                        connection factory:<programlisting><![CDATA[<beans>
+
+    <bean id="messageFactory" class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory"/>
+
+    <bean id="connectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
+        <property name="brokerURL" value="vm://localhost?broker.persistent=false"/>
+    </bean>
+
+    <bean id="webServiceTemplate" class="org.springframework.ws.client.core.WebServiceTemplate">
+        <constructor-arg ref="messageFactory"/>
+        <property name="messageSender">
+            <bean class="org.springframework.ws.transport.jms.JmsMessageSender">
+                <property name="connectionFactory" ref="connectionFactory"/>
+            </bean>
+        </property>
+        <property name="defaultUri" value="jms:RequestQueue?deliveryMode=NON_PERSISTENT"/>
+    </bean>
+
+</beans>]]></programlisting>
+                    </para>
+                </section>
+                <section>
+                    <title>Email transport</title>
+                    <para>
+                        Spring Web Services also provides an email transport, which can be used to send web service
+                        messages via SMTP, and retrieve them via either POP3 or IMAP. The client-side email
+                        functionality is contained in the <classname>MailMessageSender</classname> class.
+                        This class creates an email message from the request
+                        <interfacename>WebServiceMessage</interfacename>, and sends it via SMTP. It then waits for a
+                        response message to arrive in the incoming POP3 or IMAP server.
+                    </para>
+                    <para>
+                        To use the <classname>MailMessageSender</classname>, set the <property>defaultUri</property> or
+                        <parameter>uri</parameter> parameter to a <literal>mailto</literal> URI. Here are some URI
+                        examples: <uri>mailto:john@example.com</uri>, and
+                        <uri>mailto:server@localhost?subject=SOAP%20Test</uri>. Make sure that the message sender is
+                        properly configured with a <property>transportUri</property>, which indicates the server to
+                        send requests (typically a SMTP server), and a <property>storeUri</property>, which indicates
+                        the server to poll for responses (typically a POP3 or IMAP server).
+                    </para>
+                    <para>
+                        The following example shows how to use the email transport:<programlisting><![CDATA[<beans>
+
+    <bean id="messageFactory" class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory"/>
+
+    <bean id="webServiceTemplate" class="org.springframework.ws.client.core.WebServiceTemplate">
+        <constructor-arg ref="messageFactory"/>
+        <property name="messageSender">
+            <bean class="org.springframework.ws.transport.mail.MailMessageSender">
+                <property name="from" value="Spring-WS SOAP Client &lt;client@example.com&gt;"/>
+                <property name="transportUri" value="smtp://client:s04p@smtp.example.com"/>
+                <property name="storeUri" value="imap://client:s04p@imap.example.com/INBOX"/>
+            </bean>
+        </property>
+        <property name="defaultUri" value="mailto:server@example.com?subject=SOAP%20Test"/>
+    </bean>
+
+</beans>]]></programlisting>
+                    </para>
                 </section>
             </section>
             <section>
@@ -90,7 +182,7 @@
                     In addition to a message sender, the <classname>WebServiceTemplate</classname> requires a Web
                     service message factory. There are two message factories for SOAP:
                     <classname>SaajSoapMessageFactory</classname> and <classname>AxiomSoapMessageFactory</classname>.
-                    If no message factory is specified (via the '<literal>messageFactory</literal>' property),
+                    If no message factory is specified (via the <property>messageFactory</property> property),
                     Spring-WS will use the <classname>SaajSoapMessageFactory</classname> by default.
                 </para>
             </section>
@@ -237,7 +329,7 @@ public void marshalWithSoapActionHeader(final Source s) {
 
         public Object extractData(WebServiceMessage message) throws IOException
             ]]><lineannotation>// do your own transforms with message.getPayloadResult()</lineannotation><![CDATA[
-            ]]><lineannotation>//     or message.getPayloadSource()</lineannotation><![CDATA[
+                    ]]><lineannotation>//     or message.getPayloadSource()</lineannotation><![CDATA[
         }
     });
 }]]></programlisting>