<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements. See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership. The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License. You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied. See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<!-- 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 guidelines on how to configure Axis2 in order to
get the mail transport working.</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 on the Server Side</a></li>
  <li><a href="#james">Configuring James as an 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, the mail transport sender sends emails to a mail server to 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 directs any message that
comes in to a particular address into the Axis engine. The engine will
process the message and 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. They should be available in your classpath to get the mail
transport to 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 <a
href="http://james.apache.org/">James mail server</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, an SSL connection is mapped the way it is done in JavaMail</li>
  <li>A few properties, such as the password, are set to @name with the prefix
    "transport"</li>
</ul>

<p>For a non-SSL connection, as an example, the mail transport sender can be
activated by adding the following entry to the server axis2.xml file.(Or look for and uncomment and modify the following
in the default axis2.xml)</p>
<source><pre>   &lt;transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender"&gt;
        &lt;parameter name="mail.smtp.host"&gt;hostname&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.user"&gt;username&lt;/parameter&gt;
        &lt;parameter name="transport.mail.smtp.password"&gt;password&lt;/parameter&gt;
   &lt;/transportSender&gt;
  </pre>
</source>
and
<source>
<pre>
&lt;transportReceiver name="mailto" class="org.apache.axis2.transport.mail.SimpleMailListener"&gt;
        &lt;parameter name="mail.pop3.host"&gt;mailhost&lt;/parameter&gt;
        &lt;parameter name="mail.pop3.user"&gt;username&lt;/parameter&gt;
        &lt;parameter name="mail.store.protocol"&gt;pop3&lt;/parameter&gt;
        &lt;parameter name="transport.mail.pop3.password"&gt;password&lt;/parameter&gt;
        &lt;parameter name="transport.mail.replyToAddress"&gt;server_emailaddress&lt;/parameter&gt;
        &lt;parameter name="transport.listener.interval"&gt;3000&lt;/parameter&gt;
    &lt;/transportReceiver&gt;
</pre></source>

and the following to the client axis2.xml

<source><pre>   &lt;transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender"&gt;
        &lt;parameter name="mail.smtp.host"&gt;hostname&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.user"&gt;username&lt;/parameter&gt;
        &lt;parameter name="transport.mail.smtp.password"&gt;password&lt;/parameter&gt;
        &lt;parameter name="mail.smtp.from"&gt;client_email_address&lt;/parameter&gt;
   &lt;/transportSender&gt;
  </pre>
</source>
and
<source><pre>
&lt;transportReceiver name="mailto" class="org.apache.axis2.transport.mail.SimpleMailListener"&gt;
        &lt;parameter name="mail.pop3.host"&gt;mailhost&lt;/parameter&gt;
        &lt;parameter name="mail.pop3.user"&gt;username&lt;/parameter&gt;
        &lt;parameter name="mail.store.protocol"&gt;pop3&lt;/parameter&gt;
        &lt;parameter name="transport.mail.pop3.password"&gt;password&lt;/parameter&gt;
        &lt;parameter name="transport.mail.replyToAddress"&gt;client_emailaddress&lt;/parameter&gt;
        &lt;parameter name="transport.listener.interval"&gt;3000&lt;/parameter&gt;
    &lt;/transportReceiver&gt;</pre></source>


<p>At runtime, tuning a client to set the mail transport is as easy as
follows:</p>
Set the end point reference to use mail transport. Say for a service named <i>SampleService</i> with
a server email address of <i>test@mail.com</i>
<source><pre>
private static EndpointReference targetEPR = 
             new EndpointReference(
               "mailto:test@mail.com?x-service-path=/axis2/services/SampleService");
</pre></source>

and <source><pre>...

 ConfigurationContext ct = ConfigurationContextFactory.createConfigurationContextFromFileSystem(
                repository_path, axis2.xml_path);
 ServiceClient sender = new ServiceClient(ct, null);
 Options options = new Options();
 options.setTo(targetEPR);
 options.setSoapVersionURI(SOAP12Constants.SOAP_ENVELOPE_NAMESPACE_URI);        
 options.setProperty(AddressingConstants.WS_ADDRESSING_VERSION, AddressingConstants.Final.WSA_NAMESPACE);
 options.setAction("urn:SampleService");
 sender.setOptions(options);                
 sender.engageModule("addressing");

...</pre>
</source>

Also add the parameter
<actionMapping>urn:SampleService</actionMapping> inside the operation element of the services.xml file of the service, assuming the service name is SampleService.
<p>
Thus, a user who is familiar with setting up an SSL connection2,
could easily do it with a Properties object. For example, tuning the
sender to talk to the gmail account. This configuration could also be done
with &lt;parameter/&gt; in axis2.xml as shown in the <a href="http://wso2.org/library/2537">Axis2 Mail Transport</a> document.</p>. Configure the options object as above and,
<source>
<pre>...
Properties props = 
                  new Properties();
        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.put("transport.mail.smtp.password", "password");
		
		//then set the Properties object in the Option object.
		options.set(org.apache.axis2.transport.mail.Constants.MAILTO, props);

...</pre>
</source><a name="receiver"></a>
<p><i>Please note that according to the mail transport specification, only SOAP 1.2 is supported.</i></p>

<h2>Transport Receiver</h2>

<p>For a non-SSL connection, as an example, the mail Listener can be
activated by adding the following entry to the server axis2.xml file.(or look for and uncomment
the section)</p>
<source><pre>   &lt;transportReceiver name="mailto" class="org.apache.axis2.transport.mail.SimpleMailListener"&gt;
        &lt;parameter name="mail.pop3.host"&gt;hostname&lt;/parameter&gt;
        &lt;parameter name="mail.pop3.user"&gt;username&lt;/parameter&gt;
	&lt;parameter name="mail.store.protocol"&gt;pop3&lt;/parameter&gt;
        &lt;parameter name="transport.mail.pop3.password"&gt;password&lt;/parameter&gt;
        &lt;parameter name="transport.mail.replyToAddress"&gt;email_address&lt;/parameter&gt;
	&lt;parameter name="transport.listener.interval"&gt;3000&lt;/parameter&gt;
  &lt;/transportReceiver&gt;
  </pre>
</source>
<p><i>Note:</i> The @name="transport.mail.replyToAddress" is an important
parameter. It supplies the Endpoint reference to the listener.</p>

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

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

<p>If the Mail Listener is to be started as a standalone mail listener, it
can be done with the 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 on 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 to be
configured.</p>
<source><pre>        
        OMElement payload = ....
        String targetEPR = "mailto:user@mailhost.com?x-service-path=/axis2/services/Foo";

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

        ServiceClient servicClient = new ServiceClient(configurationContext, null);

        Options options = new Options();
        options.setTo(targetEPR);
        options.setTransportInProtocol(Constants.TRANSPORT_MAIL);
	options.setSoapVersionURI(SOAP12Constants.SOAP_ENVELOPE_NAMESPACE_URI);        
	options.setProperty(AddressingConstants.WS_ADDRESSING_VERSION, AddressingConstants.Final.WSA_NAMESPACE);
	options.setAction("urn:SampleService");
        servicClient.setOptions(options);		
		sender.engageModule("addressing");
		
        servicClient.fireAndForget(payload);</pre>
</source>
<p>For further reading, please refer to <a href="http://wso2.org/library/2537">Axis2 Mail Transport</a> document.</p>
<a name="james"></a>

<h2>Configuring James as an SMTP and POP Server</h2>

<p>Download <a href="http://james.apache.org/">Apache James</a> and start
James. Connect to the James server via Telnet as administrator James using
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 command 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 the memory against the recipient till the
recipient pops it from the server. To facilitate the use in Linux
environments as a non root user, the POP and SMTP ports used by default
configuration/test cases are, 1024, 25 and 1024, 110 respectively.</p>
<hr/>
</body>
</html>
