You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commons-dev@ws.apache.org by ve...@apache.org on 2009/05/23 19:58:16 UTC
svn commit: r777977 -
/webservices/commons/trunk/modules/transport/src/site/xdoc/mail.xml
Author: veithen
Date: Sat May 23 17:58:15 2009
New Revision: 777977
URL: http://svn.apache.org/viewvc?rev=777977&view=rev
Log:
Some improvements of the documentation for the mail transport.
Modified:
webservices/commons/trunk/modules/transport/src/site/xdoc/mail.xml
Modified: webservices/commons/trunk/modules/transport/src/site/xdoc/mail.xml
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/transport/src/site/xdoc/mail.xml?rev=777977&r1=777976&r2=777977&view=diff
==============================================================================
--- webservices/commons/trunk/modules/transport/src/site/xdoc/mail.xml (original)
+++ webservices/commons/trunk/modules/transport/src/site/xdoc/mail.xml Sat May 23 17:58:15 2009
@@ -29,21 +29,19 @@
<a href="http://java.sun.com/products/javamail/">JavaMail</a> and therefore supports any mail store protocol
for which a JavaMail provider is available.</p>
</section>
- <section name="Transport configuration">
- <pre xml:space="preserve"> <transportSender name="mailto" class="org.apache.synapse.transport.mail.MailTransportSender">
- <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
- <parameter name="mail.smtp.port">587</parameter>
- <parameter name="mail.smtp.starttls.enable">true</parameter>
- <parameter name="mail.smtp.auth">true</parameter>
- <parameter name="mail.smtp.user">synapse.demo.0</parameter>
- <parameter name="mail.smtp.password">mailpassword</parameter>
- <parameter name="mail.smtp.from">synapse.demo.0@gmail.com</parameter>
- </transportSender></pre>
- </section>
- <section name="Endpoint configuration">
- <p>Endpoints can be configured both at the transport level and at the service level. In order receive messages using
+ <section name="Transport listener">
+ <subsection name="Configuration">
+ <pre><![CDATA[ <transportReceiver name="mailto" class="org.apache.axis2.transport.mail.MailTransportListener"/>]]></pre>
+ </subsection>
+ <subsection name="Endpoint configuration">
+ <p>Endpoints can be configured both at the transport level and at the service level. In order to receive messages using
the mail transport, the listener or the service must be configured with a set of parameters
- to access the corresponding mailbox account. All service parameters starting with <tt>mail.</tt> are
+ to access the corresponding mailbox account. If messages from the mail account should be
+ directly dispatched to a given service, than the parameters must be specified on that service.
+ If on the other hand messages from that account can't be pre-dispatched to a specific service
+ (e.g. because the account is used to receive responses to outgoing messages), then the parameters
+ must be added to the <tt>transportReceiver</tt> element in <tt>axis2.xml</tt>.</p>
+ <p>All parameters starting with <tt>mail.</tt> are
interpreted as JavaMail environment properties. The most relevant are <tt>mail.<em><protocol></em>.host</tt>
and <tt>mail.<em><protocol></em>.user</tt>, where <tt><em><protocol></em></tt> is typically <tt>pop3</tt>
or <tt>imap</tt>. Assuming that Sun's JavaMail implementation is used, the complete list of supported properties for these
@@ -86,7 +84,10 @@
<tr>
<td>transport.mail.ContentType</td>
<td>No</td>
- <td>[FIXME: why do we need a content type at this level if we assume that the mails are MIME messages???]</td>
+ <td>This parameter allows to override the content type of incoming messages. This parameter
+ is useful if the service can only receive messages of a single content type and the client
+ is known to send incorrect content type information. If this parameter is set, the
+ <tt>Content-Type</tt> MIME header in incoming messages is ignored.</td>
</tr>
<tr>
<td>transport.mail.ReplyAddress</td>
@@ -148,6 +149,52 @@
[FIXME: either it is not implemented as intended or the name of the property is misleading; it is not a timeout, but an interval]</td>
</tr>
</table>
+ </subsection>
+ <subsection name="Content extraction">
+ <p>Content is extracted from incoming mails using the following rules:</p>
+ <ol>
+ <li>If the content type of the message is not <tt>multipart/mixed</tt>, the message is extracted
+ from the body of the message.</li>
+ <li>If the content type of the message is <tt>multipart/mixed</tt>, the listener will attempt to
+ find a MIME part with a content type different from <tt>text/plain</tt> and for which a
+ message builder is registered. If a matching part is found, the message will be extracted
+ from that part. Otherwise, the listener will extract the message from
+ the last <tt>text/plain</tt> part if a message builder is registered for that content type.
+ Finally, if no message builder is registered for any of the content types appearing in the multipart
+ message, an error is triggered.</li>
+ </ol>
+ <p>Note that these rules only apply if the content type has not been overridden using the
+ <tt>transport.mail.ContentType</tt> property. If this property is set, the message will always be
+ extracted from the body of the message and support for <tt>multipart/mixed</tt> is disabled.</p>
+ <p>In all cases the transport listener will use the corresponding message builder registered in the
+ Axis configuration to build the SOAP infoset from the message.</p>
+ <p>The special rules for <tt>multipart/mixed</tt> are designed to enable the following use cases:</p>
+ <ul>
+ <li>Allow humans to send messages to a Web service using a standard mail client. The user
+ can do so by adding the message as attachment to the mail. Note that this only works
+ if the mail client correctly sets the <tt>Content-Type</tt> header on the attachment.
+ This works best for SOAP 1.1 messages: when attaching a file with suffix <tt>.xml</tt>,
+ most mail clients will set the content type to <tt>text/xml</tt>, exactly as required
+ for SOAP 1.1.</li>
+ <li>Allow clients to send a human readable message together with the actual message.
+ This is useful if the message may be read by a human before being processed.</li>
+ </ul>
+ <p>Note that these rules don't interfere with the support for SOAP with Attachments, because
+ SwA uses <tt>multipart/related</tt>.</p>
+ </subsection>
+ </section>
+ <section name="Transport sender">
+ <subsection name="Configuration">
+ <pre xml:space="preserve"> <transportSender name="mailto" class="org.apache.synapse.transport.mail.MailTransportSender">
+ <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
+ <parameter name="mail.smtp.port">587</parameter>
+ <parameter name="mail.smtp.starttls.enable">true</parameter>
+ <parameter name="mail.smtp.auth">true</parameter>
+ <parameter name="mail.smtp.user">synapse.demo.0</parameter>
+ <parameter name="mail.smtp.password">mailpassword</parameter>
+ <parameter name="mail.smtp.from">synapse.demo.0@gmail.com</parameter>
+ </transportSender></pre>
+ </subsection>
</section>
</body>
</document>