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">[email protected]</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">[email protected]</parameter>
+ </transportSender></pre>
+ </subsection>
</section>
</body>
</document>
