| <!-- 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> |
| |
| <p><i>Send your feedback or questions to: <a |
| href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a></i>. |
| (Subscription details are available on the <a |
| href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly |
| prefix subject with [Axis2]. </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, 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 <parameter/>. |
| Thus, an SSL connection is mapped the way it is done in JavaMail</li> |
| <li>Few properties, such as 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 axis2.xml file.</p> |
| <source><pre> <transportSender name="mail" class="org.apache.axis2.transport.mail.MailTransportSender"> |
| <parameter name="mail.smtp.host" locked="false">localhost</parameter> |
| <parameter name="mail.smtp.user" locked="false">mary</parameter> |
| <parameter name="transport.mail.smtp.password" locked="false">mary</parameter> |
| </transportSender> |
| </pre> |
| </source> |
| <p>At runtime, tuning a client to set the 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 who is familiar with setting up an SSL connection, |
| should easily do it with the MailProperties object. For example, tuning the |
| sender to talk to the gmail account. This configuration should also be done |
| with <parameter/> 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, the mail Listener can be |
| activated by adding the following entry to the axis2.xml file.</p> |
| <source><pre> <transportReceiver name="mail" class="org.apache.axis2.transport.mail.SimpleMailListener"> |
| <parameter name="mail.pop3.host" locked="false">localhost</parameter> |
| <parameter name="mail.pop3.user" locked="false">bob</parameter> |
| <parameter name="transport.mail.pop3.password" locked="false">bob</parameter> |
| <parameter name="transport.mail.replyToAddress" locked="false">bob@localhost</parameter> |
| </transportReceiver> |
| </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><transportReceiver name="mail" class="org.apache.axis2.transport.mail.SimpleMailListener"> |
| <parameter name="mail.pop3.host" locked="false">pop.gmail.com</parameter> |
| <parameter name="mail.pop3.user" locked="false">address@gmail.com</parameter> |
| <parameter name="mail.pop3.socketFactory.class" locked="false">javax.net.ssl.SSLSocketFactory</parameter> |
| <parameter name="mail.pop3.socketFactory.fallback" locked="false">false</parameter> |
| <parameter name="mail.pop3.port" locked="false">995</parameter> |
| <parameter name="mail.pop3.socketFactory.port" locked="false">995</parameter> |
| <parameter name="transport.mail.pop3.password" locked="false">password</parameter> |
| <parameter name="transport.mail.replyToAddress" locked="false">address@gmail.com</parameter> |
| </transportReceiver></pre> |
| </source><a name="server"></a> |
| |
| <h2>Using Mail Transport in 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 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 to be |
| 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 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 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 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> |
