<!-- saved from url=(0022)http://internet.e-mail -->
<html>
<head>
  <meta http-equiv="content-type" content="">
  <title>Mail transport</title>
  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
</head>

<body lang="en">
<h1>Mail Transport Configuration</h1>

<p>This document provides the guidelines on how to configure Axis2 in order
to get the mail transport working.</p>

<p><i>Send your feedback or questions to: <a
href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
subject with [Axis2]. To subscribe to mailing list see <a
href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>

<h2>Content</h2>
<ul>
  <li><a href="#intro">Introduction</a></li>
  <li><a href="#sender">Transport Sender</a></li>
  <li><a href="#receiver">Transport Receiver</a></li>
  <li><a href="#server">Using Mail Transport in the Server Side</a></li>
  <li><a href="#james">Configure James as SMTP and POP Server</a></li>
  <li><a href="#included">Using the Included Mail Server</a></li>
</ul>
<a name="intro"></a>

<h2>Introduction</h2>

<p>The inner workings of the mail transport has been divided into two parts,
the transport sender for SMTP and the transport listener for POP3. The
transport listener will listen to a particular email address periodically.
When an email comes in it will be tunneled into an Axis2 engine. On the other
hand, mail transport sender sends emails to a mail server for a particular
email address.</p>

<p>Mail transport can be used against a generic mail server or it can be used
like a mailet. The simple mailet provided with Axis2 will direct any message
that is coming to a particular address into the Axis engine. The engine will
process the message and will use the Transport sender to send the reply.</p>

<p>The mail transports have been written with the use of Sun's JavaMail and
Activation jars. These should be available in your classpath to get the mail
transport work.</p>
<a name="sender"></a>

<h2>Transport Sender</h2>

<p>You need to have a mail account to activate the mail functionality. This
can either be a generic mail server or you can start up a James mail server,
which will be available <a href="http://james.apache.org/">here</a>.</p>

<p>JavaMail sets its properties to a Properties object. In Axis2, this has
been mapped to a Parameter object. Mapping has been done as follows,</p>
<ul>
  <li>Every JavaMail property can be set to @name of the &lt;parameter/&gt;.
    Thus, SSL connection is mapped the way it is done in JavaMail</li>
  <li>Few properties, such as password etc., are set to @name with the prefix
    "transport"</li>
</ul>

<p>For a non-SSL connection, as an example,mail transport sender can be
activated by adding following entry to the axis2.xml file.</p>
<source><pre>   &lt;transportSender name="mail" class="org.apache.axis2.transport.mail.MailTransportSender"&gt;
        &lt;parameter name="mail.smtp.host" locked="false"&gt;localhost&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.user" locked="false"&gt;mary&lt;/parameter&gt;
        &lt;parameter name="transport.mail.smtp.password" locked="false"&gt;mary&lt;/parameter&gt;     
   &lt;/transportSender&gt;
  </pre>
</source>
<p>In runtime tuning a client to set mail transport is as easy as follows,</p>
<source><pre>...

Options options =  new Options();
HttpTransportProperties.MailProperties mailProps 
                    = new HttpTransportProperties.MailProperties();
mailProps.addProperty("mail.smtp.host","localhost");
mailProps.addProperty("mail.smtp.user","mary");
mailProps.setPassword("mary");

options.setProperty(HTTPConstants.MAIL_SMTP,mailProps);

...</pre>
</source>Thus, a user familiar with setting up a SSL connection, should
easily do it with the MailProperties object. For Eg.: tuning the sender to
talk to gmail account. This configuration should also be done with
&lt;parameter/&gt; in axis2.xml. <source>
<pre>...
HttpTransportProperties.MailProperties props = 
                  new HttpTransportProperties.MailProperties();
        props.put("mail.smtp.user", "address@gmail.com");
        props.put("mail.smtp.host", "smtp.gmail.com");
        props.put("mail.smtp.port", "465");
        props.put("mail.smtp.starttls.enable","true");
        props.put("mail.smtp.auth", "true");
        //props.put("mail.smtp.debug", "true"); // if the user wants
        props.put("mail.smtp.socketFactory.port", "465");
        props.put("mail.smtp.socketFactory.class", "javax.net.ssl.SSLSocketFactory");
        props.put("mail.smtp.socketFactory.fallback", "false");
        props.setPassword("password");

...</pre>
</source><a name="receiver"></a>

<h2>Transport Receiver</h2>

<p>For a non-SSL connection, as an example, mail Listener can be activated by
adding the following entry to the axis2.xml file.</p>
<source><pre>   &lt;transportReceiver name="mail" class="org.apache.axis2.transport.mail.SimpleMailListener"&gt;
        &lt;parameter name="mail.pop3.host" locked="false"&gt;localhost&lt;/parameter&gt;
        &lt;parameter name="mail.pop3.user" locked="false"&gt;bob&lt;/parameter&gt;
        &lt;parameter name="transport.mail.pop3.password" locked="false"&gt;bob&lt;/parameter&gt;
        &lt;parameter name="transport.mail.replyToAddress" locked="false"&gt;bob@localhost&lt;/parameter&gt;
  &lt;/transportReceiver&gt;
  </pre>
</source>
<p><i>Note:</i> The @name="transport.mail.replyToAddress" is an important
parameter. It supply the Endpoint reference to the listener.</p>

<p>For an advanced user, this can be set to a SSL connection. As an example,
lets use this transport listener to pop from a specified gmail account.</p>
<source><pre>&lt;transportReceiver name="mail" class="org.apache.axis2.transport.mail.SimpleMailListener"&gt;
        &lt;parameter name="mail.pop3.host" locked="false"&gt;pop.gmail.com&lt;/parameter&gt;
        &lt;parameter name="mail.pop3.user" locked="false"&gt;address@gmail.com&lt;/parameter&gt;
        &lt;parameter name="mail.pop3.socketFactory.class" locked="false"&gt;javax.net.ssl.SSLSocketFactory&lt;/parameter&gt;
        &lt;parameter name="mail.pop3.socketFactory.fallback" locked="false"&gt;false&lt;/parameter&gt;
        &lt;parameter name="mail.pop3.port" locked="false"&gt;995&lt;/parameter&gt;
        &lt;parameter name="mail.pop3.socketFactory.port" locked="false"&gt;995&lt;/parameter&gt;
        &lt;parameter name="transport.mail.pop3.password" locked="false"&gt;password&lt;/parameter&gt;
        &lt;parameter name="transport.mail.replyToAddress" locked="false"&gt;address@gmail.com&lt;/parameter&gt;
&lt;/transportReceiver&gt;</pre>
</source><a name="server"></a>

<h2>Using Mail Transport in the Server Side</h2>

<p>If the Mail Listener is need to be started as a standalone mail listener,
it can be done with following command with the all the Axis2 jars and the
mail dependency jars in the classpath.</p>
<source><pre>java org.apache.axis2.transport.mail.SimpleMailListener repository-directory</pre>
</source><a name="client"></a>

<h2>Using Mail Transport in the Client Side</h2>

<p>The following code segment shows how to send a one-way (IN-Only MEP) SOAP
message using the mail transport, this needs the Transport Sender
configured.</p>
<source><pre>        
        OMElement payload = ....
        String targetEPR = "mail:axis2@localhost/axis2/services/Foo";

        ConfigurationContext configurationContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(repo,
                axis2XML);

        ServiceClient servicClient = new ServiceClient(configurationContext, null);

        Options options = new Options();
        options.setTo(targetEPR);
        options.setTransportInProtocol(Constants.TRANSPORT_MAIL);

        servicClient.setOptions(options);

        servicClient.sendRobust(payload);</pre>
</source><a name="james"></a>

<h2>Configure James as SMTP and POP Server</h2>

<p>Download the <a href="http://james.apache.org/">Apache James</a> and start
James, connect to the James via Telnet for administrator James with the
following code:</p>
<source><pre>$telnet 127.0.0.1 4555
Trying 127.0.0.1...
Connected to localhost.localdomain (127.0.0.1).
Escape character is '^]'.
JAMES Remote Administration Tool 2.2.0
Please enter your login and password
Login id:
root
Password:
root
Welcome root. HELP for a list of commands</pre>
</source>
<p>Add users to James</p>
<source><pre>adduser axis2-server axis2
User axis2-server added
adduser axis2-client axis2
User axis2-client added
Connection closed by foreign host.</pre>
</source>
<p>Now James is up and running with the accounts.</p>
<a name="included"></a>

<h2>Using the Included Mail Server</h2>

<p>The inbuilt mail server can be started from the command line using the
following piece of code when all the necessary jars are in the class path.</p>
<source><pre>java org.apache.axis2.transport.mail.server.MailServer</pre>
</source>
<p>The server itself does not need any configuration or tinkering to work. A
ConfigurationContext and the ports to operate on are the only details needed.
The server will store the mails in memory against the recipient till the
recipient pops it from the server. To facilitate the use in *nix environments
as a non root user the POP and SMTP ports used by default config/test cases
are (1024 + 25) and (1024 + 110).</p>
<hr>
</body>
</html>