axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nand...@apache.org
Subject svn commit: r688807 [9/17] - in /webservices/axis2/site/1_4_1: ./ adb/ adb/images/ images/ images/archi-guide/ images/userguide/ jibx/ src/
Date Mon, 25 Aug 2008 18:10:09 GMT
Added: webservices/axis2/site/1_4_1/json_support.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4_1/json_support.html?rev=688807&view=auto
==============================================================================
--- webservices/axis2/site/1_4_1/json_support.html (added)
+++ webservices/axis2/site/1_4_1/json_support.html Mon Aug 25 11:10:04 2008
@@ -0,0 +1,482 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Apache Axis2 - </title>
+    <style type="text/css" media="all">
+      @import url("../css/maven-base.css");
+      @import url("../css/maven-theme.css");
+      @import url("../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+      </head>
+  <body class="composite">
+    <div id="banner">
+                  <a href="../" id="bannerLeft">
+    
+                                    <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+    
+            </a>
+                          <span id="bannerRight">
+    
+                                            <img src="../../images/axis.jpg" alt="" />
+    
+            </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+          
+  
+
+  
+    
+  
+  
+    
+            <div class="xleft">
+        Last Published: 2008-08-24
+                      </div>
+            <div class="xright">            <a href="../index.html">Axis2/Java</a>
+            |
+                <a href="../../c">Axis2/C</a>
+            |
+                <a href="../../..">Apache WS</a>
+            |
+                <a href="http://www.apache.org" class="externalLink">Apache</a>
+            
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+           
+  
+
+  
+    
+  
+  
+    
+                   <h5>Axis2/Java</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../index.html">Home</a>
+          </li>
+          </ul>
+              <h5>Downloads</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../download.cgi">Releases</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../modules/index.html">Modules</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../tools/index.html">Tools</a>
+          </li>
+          </ul>
+              <h5>Documentation</h5>
+            <ul>
+              
+          
+              
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+              
+        <li class="expanded">
+                    <a href="../1_4_1/contents.html">Version 1.4.1</a>
+                  <ul>
+                  
+    <li class="none">
+                    <a href="../1_4_1/toc.html">Table of Contents</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/installationguide.html">Installation Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/quickstartguide.html">QuickStart Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/userguide.html">User Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/jaxws-guide.html">JAXWS Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/pojoguide.html">POJO Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/spring.html">Spring Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/webadminguide.html">Web Administrator's Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/migration.html">Migration Guide (from Axis1)</a>
+          </li>
+              </ul>
+        </li>
+              
+    <li class="none">
+                    <a href="../1_4/contents.html">Version 1.4</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_3/contents.html">Version 1.3</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_2/contents.html">Version 1.2</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1_1/contents.html">Version 1.1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1/contents.html">Version 1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_0/index.html">Version 1.0</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_95/index.html">Version 0.95</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_94/index.html">Version 0.94</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_93/index.html">Version 0.93</a>
+          </li>
+          </ul>
+              <h5>Resources</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../faq.html">FAQ</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../articles.html">Articles</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink">Wiki</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../refLib.html">Reference Library</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../../1_4_1/api/index.html">Online Java Docs</a>
+          </li>
+          </ul>
+              <h5>Get Involved</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../overview.html">Overview</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../svn.html">Checkout the Source</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../mail-lists.html">Mailing Lists</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../release-process.html">Release Process</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../guidelines.html">Developer Guidelines</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../siteHowTo.html">Build the Site</a>
+          </li>
+          </ul>
+              <h5>Project Information</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../team-list.html">Project Team</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../issue-tracking.html">Issue Tracking</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink">Source Code</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../thanks.html">Acknowledgements</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a>
+          </li>
+          </ul>
+                                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+          </a>
+                       
+  
+
+  
+    
+  
+  
+    
+        </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <html xmlns="http://www.w3.org/1999/xhtml"><head><meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org"><meta http-equiv="content-type" content="text/html; charset=us-ascii"><meta name="AUTHOR" content="Isuru Suriarachchi"><meta name="CREATED" content="20070203;331600"><meta name="CHANGEDBY" content="Isuru Suriarachchi"><meta name="CHANGED" content="20070208;12031400"><style type="text/css">
+/**/
+        &lt;!--
+@page { size: 8.5in 11in; margin: 0.79in }
+P { margin-bottom: 0.08in }
+--&gt;
+
+/**/
+</style></head><h1 class="title">JSON Support in Axis2</h1><p>This document explains the JSON support implementation in Axis2.
+It includes an introduction to JSON, an outline as to why JSON
+support is useful to Axis2 and how it should be used. This document
+also provides details on test cases and samples.</p>
+<h3>What is JSON?</h3><p><a class="externalLink" href="http://www.json.org/">JSON</a> (Java Script Object
+Notation) is another data exchangeable format like XML, but more
+lightweight and easily readable. It is based on a subset of the
+JavaScript language. Therefore, JavaScript can understand JSON, and
+it can make JavaScript objects by using JSON strings. JSON is based
+on key-value pairs and it uses colons to separate keys and values.
+JSON doesn't use end tags, and it uses braces (curly brackets) to
+enclose JSON Objects.</p>
+<p><font size="3">e.g. <font size="2">&lt;root&gt;&lt;test&gt;json
+object&lt;/test&gt;&lt;/root&gt; ==
+{{json object}}</font></font></p>
+<p>When it comes to converting XML to JSON and vice versa, there
+are two major conventions, one named &quot;<a class="externalLink" href="http://badgerfish.ning.com/">Badgerfish</a>&quot; and the other,
+Mapped. The main difference
+between these two conventions exists in the way they map XML
+namespaces into JSON.</p>
+<p><font size="3">e.g. <font size="2">&lt;xsl:root
+xmlns:xsl=&quot;http://foo.com&quot;&gt;&lt;data&gt;my json
+string&lt;/data&gt;&lt;/xsl:root&gt;</font></font></p>
+<p>This XML string can be converted into JSON as follows.</p>
+<p><b>Using Badgerfish</b></p>
+<p><font size="2">{&quot;xsl:root&quot;:{&quot;@xmlns&quot;:{&quot;xsl&quot;:&quot;http://foo.com&quot;},&quot;data&quot;:{&quot;$&quot;:&quot;my
+json string&quot;}}}</font></p>
+<p><b>Using Mapped</b></p>
+<p>If we use the namespace mapping as http://foo.com -&gt; foo</p>
+<p><font size="2">{&quot;foo.root&quot;:{&quot;data&quot;:&quot;my json string&quot;}}</font></p>
+<p>JSON support is a new feature in <a class="externalLink" href="http://ws.apache.org/axis2/">Apache Axis2/Java</a>. It will become
+a crucial improvement in the future with applications like
+JavaScript Web services.</p>
+<h2>Why JSON Support for Axis2?</h2><p><a class="externalLink" href="http://ws.apache.org/axis2/">Apache Axis2</a> is a Web
+services stack that delivers incoming messages into target
+applications. In most cases, these messages are SOAP messages. In
+addition, it is also possible to send REST messages through Axis2.
+Both types of messages use XML as their data exchangeable format.
+So if we can use XML as a format, why use JSON as another
+format?</p>
+<p>There are many advantages of implementing JSON support in Axis2.
+Mainly, it helps the JavaScript users (services and clients written
+in JavaScript) to deal with Axis2. When the service or the client
+is in JavaScript, it can use the JSON string and directly build
+JavaScript objects to retrieve information, without having to build
+the object model (OMElement in Axis2). Also, JavaScript services
+can return the response through Axis2, just as a JSON string can be
+shipped in a JSONDataSource.</p>
+<p>Other than for that, there are some extra advantages of using
+JSON in comparison to XML. Although the conversation
+XML or JSON? is still a hot topic,
+many people accept the fact that JSON can be passed and built more
+easily by machines than XML.</p>
+<p>For more details of this implementation architecture, refer to
+the article <a class="externalLink" href="http://wso2.org/library/768">&quot;JSON Support for
+Apache Axis2&quot;</a></p>
+<h2>How to use JSON in Axis2</h2><p>At the moment JSON doesn't have a standard and unique content
+type. application/json (this is
+the content type which is approved in the <a class="externalLink" href="http://www.ietf.org/rfc/rfc4627.txt?number=4627">JSON RFC</a> ),
+text/javascript and
+text/json are some of the commonly
+used content types of JSON. Due to this problem, in Axis2, the user
+has been given the freedom of selecting the content type.</p>
+<h3>Step 1</h3><p>Map the appropriate MessageFormatter and OMBuilder with the
+content type you are using in the axis2.xml file.</p>
+<p>e.g.1: If you are using the
+Mapped convention with the content
+type application/json</p>
+<pre>
+        &lt;messageFormatters&gt;        
+                &lt;messageFormatter contentType=&quot;application/json&quot;
+                                 class=&quot;org.apache.axis2.json.JSONMessageFormatter&quot;/&gt;
+                &lt;!-- more message formatters --&gt;
+        &lt;/messageFormatters&gt;   
+    
+        &lt;messageBuilders&gt;
+                &lt;messageBuilder contentType=&quot;application/json&quot;
+                                 class=&quot;org.apache.axis2.json.JSONOMBuilder&quot;/&gt;
+                &lt;!-- more message builders --&gt;
+        &lt;/messageBuilders&gt;
+</pre><p>e.g.2: If you are using the
+Badgerfish convention with the
+content type text/javascript</p>
+<pre>
+        &lt;messageFormatters&gt;        
+                &lt;messageFormatter contentType=&quot;text/javascript&quot;
+                                 class=&quot;org.apache.axis2.json.JSONBadgerfishMessageFormatter&quot;/&gt;
+                &lt;!-- more message formatters --&gt;
+        &lt;/messageFormatters&gt; 
+
+        &lt;messageBuilders&gt;
+                &lt;messageBuilder contentType=&quot;text/javascript&quot;
+                                 class=&quot;org.apache.axis2.json.JSONBadgerfishOMBuilder&quot;/&gt;
+                &lt;!-- more message builders --&gt;
+        &lt;/messageBuilders&gt;
+</pre><h3>Step 2</h3><p>On the client side, make the ConfigurationContext by reading the
+axis2.xml in which the correct mappings are given.</p>
+<p>e.g.</p>
+<pre>
+        File configFile = new File(&quot;test-resources/axis2.xml&quot;);
+        configurationContext = ConfigurationContextFactory
+                        .createConfigurationContextFromFileSystem(null, configFile.getAbsolutePath());
+        ..........        
+        ServiceClient sender = new ServiceClient(configurationContext, null);
+</pre><h3>Step 3</h3><p>Set the <i>MESSAGE_TYPE</i> option with exactly the same content
+type you used in the axis2.xml.</p>
+<p>e.g. If you use the content type
+application/json,</p>
+<pre>
+        Options options = new Options();        
+        options.setProperty(Constants.Configuration.MESSAGE_TYPE, application/json);
+        //more options
+        //...................        
+
+        ServiceClient sender = new ServiceClient(configurationContext, null);        
+        sender.setOptions(options);
+</pre><p>If you are sending a request to a remote service, you have to
+know the exact JSON content type that is used by that service, and
+you have to use that content type in your client as well.</p>
+<p>HTTP POST is used as the default method to send JSON messages
+through Axis2, if the HTTP method is not explicitly set by the
+user. But if you want to send JSON in HTTP GET method as a
+parameter, you can do that by just setting an option on the client
+side.</p>
+<p>e.g.
+<code>options.setProperty(Constants.Configuration.HTTP_METHOD,
+Constants.Configuration.HTTP_METHOD_GET);</code></p>
+<p>Here, the Axis2 receiving side (JSONOMBuilder) builds the
+OMElement by reading the JSON string which is sent as a parameter.
+The request can be made even through the browser.</p>
+<p>e.g. Sample JSON request through HTTP GET. The JSON message is
+encoded and sent.</p>
+<p><code>GET
+/axis2/services/EchoXMLService/echoOM?query=%7B%22echoOM%22:%7B%22data%22:%5B%22my%20json%20string%22,%22my%20second%20json%20string%22%5D%7D%7D
+HTTP/1.1</code></p>
+<h2>Tests and Samples</h2><h3>Integration Test</h3><p>The JSON integration test is available under
+test in the
+json module of Axis2. It uses the
+SimpleHTTPServer to deploy the service. A simple echo service is
+used to return the incoming OMSourcedElementImpl object, which
+contains the JSONDataSource. There are two test cases for two
+different conventions and another one test case to send the request
+in GET.</p>
+<h3>Yahoo-JSON Sample</h3><p>This sample is available in the
+samples module of Axis2. It is a
+client which calls the Yahoo search API using the GET method, with
+the parameter output=json. The
+Yahoo search service sends the response as a
+formatted JSON string with
+the content type text/javascript.
+This content type is mapped with the JSONOMBuilder in the
+axis2.xml. All the results are shown in a GUI. To run the sample,
+execute the ant script.</p>
+<p>These two applications provide good examples of using JSON
+within Axis2. By reviewing these samples, you will be able to
+better understand Axis2's JSON support implementation.</p>
+</html>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">&#169;  
+          2004-2008
+    
+          Apache Software Foundation
+          
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>

Added: webservices/axis2/site/1_4_1/mail-configuration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4_1/mail-configuration.html?rev=688807&view=auto
==============================================================================
--- webservices/axis2/site/1_4_1/mail-configuration.html (added)
+++ webservices/axis2/site/1_4_1/mail-configuration.html Mon Aug 25 11:10:04 2008
@@ -0,0 +1,544 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Apache Axis2 - </title>
+    <style type="text/css" media="all">
+      @import url("../css/maven-base.css");
+      @import url("../css/maven-theme.css");
+      @import url("../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+      </head>
+  <body class="composite">
+    <div id="banner">
+                  <a href="../" id="bannerLeft">
+    
+                                    <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+    
+            </a>
+                          <span id="bannerRight">
+    
+                                            <img src="../../images/axis.jpg" alt="" />
+    
+            </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+          
+  
+
+  
+    
+  
+  
+    
+            <div class="xleft">
+        Last Published: 2008-08-24
+                      </div>
+            <div class="xright">            <a href="../index.html">Axis2/Java</a>
+            |
+                <a href="../../c">Axis2/C</a>
+            |
+                <a href="../../..">Apache WS</a>
+            |
+                <a href="http://www.apache.org" class="externalLink">Apache</a>
+            
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+           
+  
+
+  
+    
+  
+  
+    
+                   <h5>Axis2/Java</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../index.html">Home</a>
+          </li>
+          </ul>
+              <h5>Downloads</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../download.cgi">Releases</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../modules/index.html">Modules</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../tools/index.html">Tools</a>
+          </li>
+          </ul>
+              <h5>Documentation</h5>
+            <ul>
+              
+          
+              
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+              
+        <li class="expanded">
+                    <a href="../1_4_1/contents.html">Version 1.4.1</a>
+                  <ul>
+                  
+    <li class="none">
+                    <a href="../1_4_1/toc.html">Table of Contents</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/installationguide.html">Installation Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/quickstartguide.html">QuickStart Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/userguide.html">User Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/jaxws-guide.html">JAXWS Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/pojoguide.html">POJO Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/spring.html">Spring Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/webadminguide.html">Web Administrator's Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/migration.html">Migration Guide (from Axis1)</a>
+          </li>
+              </ul>
+        </li>
+              
+    <li class="none">
+                    <a href="../1_4/contents.html">Version 1.4</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_3/contents.html">Version 1.3</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_2/contents.html">Version 1.2</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1_1/contents.html">Version 1.1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1/contents.html">Version 1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_0/index.html">Version 1.0</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_95/index.html">Version 0.95</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_94/index.html">Version 0.94</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_93/index.html">Version 0.93</a>
+          </li>
+          </ul>
+              <h5>Resources</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../faq.html">FAQ</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../articles.html">Articles</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink">Wiki</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../refLib.html">Reference Library</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../../1_4_1/api/index.html">Online Java Docs</a>
+          </li>
+          </ul>
+              <h5>Get Involved</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../overview.html">Overview</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../svn.html">Checkout the Source</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../mail-lists.html">Mailing Lists</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../release-process.html">Release Process</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../guidelines.html">Developer Guidelines</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../siteHowTo.html">Build the Site</a>
+          </li>
+          </ul>
+              <h5>Project Information</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../team-list.html">Project Team</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../issue-tracking.html">Issue Tracking</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink">Source Code</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../thanks.html">Acknowledgements</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a>
+          </li>
+          </ul>
+                                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+          </a>
+                       
+  
+
+  
+    
+  
+  
+    
+        </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <html><head><meta http-equiv="content-type" content="">Mail transport<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></head><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 class="externalLink" 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
+    &quot;transport&quot;</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>
+<div class="source"><pre><pre>   &lt;transportSender name=&quot;mailto&quot; class=&quot;org.apache.axis2.transport.mail.MailTransportSender&quot;&gt;
+        &lt;parameter name=&quot;mail.smtp.host&quot;&gt;hostname&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.smtp.user&quot;&gt;username&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.smtp.password&quot;&gt;password&lt;/parameter&gt;
+   &lt;/transportSender&gt;
+  </pre></pre>
+</div>
+
+and
+<div class="source"><pre><pre>
+&lt;transportReceiver name=&quot;mailto&quot; class=&quot;org.apache.axis2.transport.mail.SimpleMailListener&quot;&gt;
+        &lt;parameter name=&quot;mail.pop3.host&quot;&gt;mailhost&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.pop3.user&quot;&gt;username&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.store.protocol&quot;&gt;pop3&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.pop3.password&quot;&gt;password&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.replyToAddress&quot;&gt;server_emailaddress&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.listener.interval&quot;&gt;3000&lt;/parameter&gt;
+    &lt;/transportReceiver&gt;
+</pre></pre>
+</div>
+
+
+and the following to the client axis2.xml
+
+<div class="source"><pre><pre>   &lt;transportSender name=&quot;mailto&quot; class=&quot;org.apache.axis2.transport.mail.MailTransportSender&quot;&gt;
+        &lt;parameter name=&quot;mail.smtp.host&quot;&gt;hostname&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.smtp.user&quot;&gt;username&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.smtp.password&quot;&gt;password&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.smtp.from&quot;&gt;client_email_address&lt;/parameter&gt;
+   &lt;/transportSender&gt;
+  </pre></pre>
+</div>
+
+and
+<div class="source"><pre><pre>
+&lt;transportReceiver name=&quot;mailto&quot; class=&quot;org.apache.axis2.transport.mail.SimpleMailListener&quot;&gt;
+        &lt;parameter name=&quot;mail.pop3.host&quot;&gt;mailhost&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.pop3.user&quot;&gt;username&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.store.protocol&quot;&gt;pop3&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.pop3.password&quot;&gt;password&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.replyToAddress&quot;&gt;client_emailaddress&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.listener.interval&quot;&gt;3000&lt;/parameter&gt;
+    &lt;/transportReceiver&gt;</pre></pre>
+</div>
+<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><div class="source"><pre><pre>
+private static EndpointReference targetEPR = 
+             new EndpointReference(
+               &quot;mailto:test@mail.com?x-service-path=/axis2/services/SampleService&quot;);
+</pre></pre>
+</div>
+
+
+and <div class="source"><pre><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(&quot;urn:SampleService&quot;);
+ sender.setOptions(options);                
+ sender.engageModule(&quot;addressing&quot;);
+
+...</pre></pre>
+</div>
+
+
+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 class="externalLink" href="http://wso2.org/library/2537">Axis2 Mail Transport</a> document.</p>
+. Configure the options object as above and,
+<div class="source"><pre><pre>...
+Properties props = 
+                  new Properties();
+        props.put(&quot;mail.smtp.user&quot;, &quot;address@gmail.com&quot;);
+        props.put(&quot;mail.smtp.host&quot;, &quot;smtp.gmail.com&quot;);
+        props.put(&quot;mail.smtp.port&quot;, &quot;465&quot;);
+        props.put(&quot;mail.smtp.starttls.enable&quot;,&quot;true&quot;);
+        props.put(&quot;mail.smtp.auth&quot;, &quot;true&quot;);
+        //props.put(&quot;mail.smtp.debug&quot;, &quot;true&quot;); // if the user wants
+        props.put(&quot;mail.smtp.socketFactory.port&quot;, &quot;465&quot;);
+        props.put(&quot;mail.smtp.socketFactory.class&quot;, &quot;javax.net.ssl.SSLSocketFactory&quot;);
+        props.put(&quot;mail.smtp.socketFactory.fallback&quot;, &quot;false&quot;);
+		props.put(&quot;transport.mail.smtp.password&quot;, &quot;password&quot;);
+		
+		//then set the Properties object in the Option object.
+		options.set(org.apache.axis2.transport.mail.Constants.MAILTO, props);
+
+...</pre></pre>
+</div>
+<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>
+<div class="source"><pre><pre>   &lt;transportReceiver name=&quot;mailto&quot; class=&quot;org.apache.axis2.transport.mail.SimpleMailListener&quot;&gt;
+        &lt;parameter name=&quot;mail.pop3.host&quot;&gt;hostname&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.pop3.user&quot;&gt;username&lt;/parameter&gt;
+	&lt;parameter name=&quot;mail.store.protocol&quot;&gt;pop3&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.pop3.password&quot;&gt;password&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.replyToAddress&quot;&gt;email_address&lt;/parameter&gt;
+	&lt;parameter name=&quot;transport.listener.interval&quot;&gt;3000&lt;/parameter&gt;
+  &lt;/transportReceiver&gt;
+  </pre></pre>
+</div>
+<p><i>Note:</i> The @name=&quot;transport.mail.replyToAddress&quot; 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>
+<div class="source"><pre><pre>&lt;transportReceiver name=&quot;mailto&quot; class=&quot;org.apache.axis2.transport.mail.SimpleMailListener&quot;&gt;
+        &lt;parameter name=&quot;mail.pop3.host&quot;&gt;pop.gmail.com&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.pop3.user&quot;&gt;address@gmail.com&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.pop3.socketFactory.class&quot;&gt;javax.net.ssl.SSLSocketFactory&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.pop3.socketFactory.fallback&quot;&gt;false&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.pop3.port&quot;&gt;995&lt;/parameter&gt;
+        &lt;parameter name=&quot;mail.pop3.socketFactory.port&quot;&gt;995&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.pop3.password&quot;&gt;password&lt;/parameter&gt;
+        &lt;parameter name=&quot;transport.mail.replyToAddress&quot;&gt;address@gmail.com&lt;/parameter&gt;
+&lt;/transportReceiver&gt;</pre></pre>
+</div>
+<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>
+<div class="source"><pre><pre>java org.apache.axis2.transport.mail.SimpleMailListener repository-directory</pre></pre>
+</div>
+<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>
+<div class="source"><pre><pre>        
+        OMElement payload = ....
+        String targetEPR = &quot;mailto:user@mailhost.com?x-service-path=/axis2/services/Foo&quot;;
+
+        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(&quot;urn:SampleService&quot;);
+        servicClient.setOptions(options);		
+		sender.engageModule(&quot;addressing&quot;);
+		
+        servicClient.fireAndForget(payload);</pre></pre>
+</div>
+<p>For further reading, please refer to <a class="externalLink" 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 class="externalLink" 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>
+<div class="source"><pre><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></pre>
+</div>
+<p>Add users to James</p>
+<div class="source"><pre><pre>adduser axis2-server axis2
+User axis2-server added
+adduser axis2-client axis2
+User axis2-client added
+Connection closed by foreign host.</pre></pre>
+</div>
+<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>
+<div class="source"><pre><pre>java org.apache.axis2.transport.mail.server.MailServer</pre></pre>
+</div>
+<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 />
+</html>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">&#169;  
+          2004-2008
+    
+          Apache Software Foundation
+          
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>

Added: webservices/axis2/site/1_4_1/mail-transport.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4_1/mail-transport.html?rev=688807&view=auto
==============================================================================
--- webservices/axis2/site/1_4_1/mail-transport.html (added)
+++ webservices/axis2/site/1_4_1/mail-transport.html Mon Aug 25 11:10:04 2008
@@ -0,0 +1,486 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Apache Axis2 - </title>
+    <style type="text/css" media="all">
+      @import url("../css/maven-base.css");
+      @import url("../css/maven-theme.css");
+      @import url("../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+      </head>
+  <body class="composite">
+    <div id="banner">
+                  <a href="../" id="bannerLeft">
+    
+                                    <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+    
+            </a>
+                          <span id="bannerRight">
+    
+                                            <img src="../../images/axis.jpg" alt="" />
+    
+            </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+          
+  
+
+  
+    
+  
+  
+    
+            <div class="xleft">
+        Last Published: 2008-08-24
+                      </div>
+            <div class="xright">            <a href="../index.html">Axis2/Java</a>
+            |
+                <a href="../../c">Axis2/C</a>
+            |
+                <a href="../../..">Apache WS</a>
+            |
+                <a href="http://www.apache.org" class="externalLink">Apache</a>
+            
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+           
+  
+
+  
+    
+  
+  
+    
+                   <h5>Axis2/Java</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../index.html">Home</a>
+          </li>
+          </ul>
+              <h5>Downloads</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../download.cgi">Releases</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../modules/index.html">Modules</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../tools/index.html">Tools</a>
+          </li>
+          </ul>
+              <h5>Documentation</h5>
+            <ul>
+              
+          
+              
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+              
+        <li class="expanded">
+                    <a href="../1_4_1/contents.html">Version 1.4.1</a>
+                  <ul>
+                  
+    <li class="none">
+                    <a href="../1_4_1/toc.html">Table of Contents</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/installationguide.html">Installation Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/quickstartguide.html">QuickStart Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/userguide.html">User Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/jaxws-guide.html">JAXWS Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/pojoguide.html">POJO Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/spring.html">Spring Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/webadminguide.html">Web Administrator's Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/migration.html">Migration Guide (from Axis1)</a>
+          </li>
+              </ul>
+        </li>
+              
+    <li class="none">
+                    <a href="../1_4/contents.html">Version 1.4</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_3/contents.html">Version 1.3</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_2/contents.html">Version 1.2</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1_1/contents.html">Version 1.1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1/contents.html">Version 1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_0/index.html">Version 1.0</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_95/index.html">Version 0.95</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_94/index.html">Version 0.94</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_93/index.html">Version 0.93</a>
+          </li>
+          </ul>
+              <h5>Resources</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../faq.html">FAQ</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../articles.html">Articles</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink">Wiki</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../refLib.html">Reference Library</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../../1_4_1/api/index.html">Online Java Docs</a>
+          </li>
+          </ul>
+              <h5>Get Involved</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../overview.html">Overview</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../svn.html">Checkout the Source</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../mail-lists.html">Mailing Lists</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../release-process.html">Release Process</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../guidelines.html">Developer Guidelines</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../siteHowTo.html">Build the Site</a>
+          </li>
+          </ul>
+              <h5>Project Information</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../team-list.html">Project Team</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../issue-tracking.html">Issue Tracking</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink">Source Code</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../thanks.html">Acknowledgements</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a>
+          </li>
+          </ul>
+                                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+          </a>
+                       
+  
+
+  
+    
+  
+  
+    
+        </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <html><head><meta http-equiv="content-type" content="">Invoking a service using mail<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></head><h1>Invoking a Service Using a Mail Transport</h1><p>This document explains how to invoke a service through Mail transports.</p>
+<p><i>Send your feedback or questions to: <a class="externalLink" href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a></i>.
+(Subscription details are available on the <a class="externalLink" 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="#prologue">Prologue</a></li>
+<li><a href="#intro">Introduction</a></li>
+<li><a href="#axis2">Using Simple Mail Server Included in Axis2</a></li>
+<li><a href="#generic">Using a Generic Mail Server</a></li>
+</ul>
+<a name="prologue"></a><h2>Prologue</h2><p>Most of the Web services that we interact with are synchronous and
+request-response in nature. However, we see that the synchronous
+request-response type of interaction is only a part of the messaging
+scenarios we encounter in real life. Asynchronous messaging is very important
+in constructing loosely coupled systems. Take for instance a chain of stores.
+At the end of the day, all the stores can send a mail to the central system
+telling it about that day's business activities, and when the store opens in
+the morning, there will be a reply to that mail with new instructions and
+updates. It is a lot like the way old businesses worked, but with a modern
+touch. Similarly, the Axis2 mail transport can be used to implement
+asynchronous messaging through mail.</p>
+<a name="intro"></a><h2>Introduction</h2><p>First, you need to go through the <a href="mail-configuration.html">Mail Transport Configuration</a> document. It provides first
+hand experience in setting up the mail transports to operate with Axis2.</p>
+<p>Broadly speaking, there are three ways of calling a service through
+mail.</p>
+<blockquote>
+  1. Using the simple mail server included in Axis2 (not recommended in
+  production).<br />
+
+  2. Using a generic mail server.<br />
+
+  3. Using mailets.<br />
+</blockquote><p>Options 1 and 2 are fairly simple and easy to implement, whereas option 3
+is somewhat harder. The mailet scenario however does provide a more robust
+and useful solution in a production environment.</p>
+<p>It is very easy to start learning the workings of mail transports with the
+aid of the Simple Mail Server that is provided with Axis2. Once you get the
+hang of Axis2 related issues, then you can move on to tackle the mail beast.
+Please do note that the Simple Mail Server provided with Axis2 is not graded
+for production use.</p>
+<a name="axis2"></a><h2>1. Using the Simple Mail Server Included in Axis2</h2><p>The SMTP/POP server that we have included has the ability to function as a
+standalone SMTP/POP server and also has the ability to work as a mailet. All
+this is done through a small filter that keeps watch for certain
+pre-configured email addresses. These pre-configured email addresses can be
+changed by doing a simple edit of the filter class
+org.apache.axis2.transport.mail.server.Sorter.</p>
+<p>Now that we have the environment set up, we can use the code below to get
+the mail functionality started. First we'll have a look at it from the mail
+server side. <br />
+</p>
+<div class="source"><pre><pre>        // Start the mail server using the default configurations.
+        ConfigurationContext configContext = UtilsMailServer.start();
+
+        // Start the default mail listener. It will starting polling for mail
+        // using the configuration from the XML file.
+        SimpleMailListener ml = new SimpleMailListener();
+        ml.init(configContext,
+                configContext.getAxisConfiguration().getTransportIn(
+                        new QName(Constants.TRANSPORT_MAIL)));
+        ml.start();
+
+        private QName serviceName = new QName(&quot;EchoXMLService&quot;);
+        private QName operationName = new QName(&quot;echoOMElement&quot;);
+    
+        // Setup a service that will echo what we send to the server.
+        AxisService service = Utils.createSimpleService(serviceName, Echo.class
+                .getName(), operationName);
+        serverConfigContext.getAxisConfiguration().addService(service);</pre></pre>
+</div>
+<p>This code sets up your Axis2 server which uses a single service to work
+through the mail. If you want to have a look under the hood, check out the
+MailServer and UtilsMailServer classes.</p>
+<p>Moving onto the client side, have a look at the code listing below. It
+will call the axisService that was setup in the previous code listing.</p>
+<div class="source"><pre><pre>        ConfigurationContext configContext = UtilsMailServer
+                .createClientConfigurationContext();
+        AxisService service = new AxisService(serviceName.getLocalPart());
+        AxisOperation axisOperation = new OutInAxisOperation();
+        axisOperation.setName(operationName);
+        axisOperation.setMessageReceiver(new MessageReceiver() {
+            public void receive(MessageContext messageCtx) {
+                envelope = messageCtx.getEnvelope();
+            }
+        });
+        service.addOperation(axisOperation);
+        configContext.getAxisConfiguration().addService(service);
+        ServiceContext serviceContext = new ServiceGroupContext(configContext,
+                        (AxisServiceGroup) service.getParent()).getServiceContext(service);
+
+        Options options = new Options();
+        options.setTo(targetEPR);
+        options.setAction(operationName.getLocalPart());
+        options.setTransportInProtocol(Constants.TRANSPORT_MAIL);
+        options.setUseSeparateListener(true);
+
+        Callback callback = new Callback() {
+            public void onComplete(AsyncResult result) {
+                try {
+                    result.getResponseEnvelope().serializeAndConsume(
+                            XMLOutputFactory.newInstance()
+                                    .createXMLStreamWriter(System.out));
+                } catch (XMLStreamException e) {
+                    onError(e);
+                } finally {
+                    finish = true;
+                }
+            }
+
+            public void onError(Exception e) {
+                log.info(e.getMessage());
+                finish = true;
+            }
+        };
+
+        ServiceClient sender = new ServiceClient(configContext, service);
+        sender.setOptions(options);
+        //options.setTo(targetEPR);
+        sender.sendReceiveNonBlocking(operationName, createEnvelope(), callback);
+
+        int index = 0;
+        while (!finish) {
+            Thread.sleep(1000);
+            index++;
+            if (index &gt; 10) {
+                throw new AxisFault(
+                        &quot;Server was shutdown as the async response is taking too long to complete.&quot;);
+            }
+        }
+
+    }</pre></pre>
+</div>
+<p>This will call the service that was setup on the server, and will poll the
+mail server until the response is received. Please note that the serviceName
+and operationName need to be QNames.</p>
+<a name="generic"></a><h2>2. Using a Generic Mail Server</h2><p>First you will need two email accounts that work with POP/SMTP. One will act as
+a server and the other will act as the client. For the time being, we will
+use server@somewhere.org and client@somewhere.org as the server and the
+client email addresses. Now that we have the email addresses, you will have
+to set up the client and the server using the Mail Transport <a href="mail-configuration.html">configuration document</a>.</p>
+<p>When you call the generic mail server, the client side code will remain
+the same and there will be some modification to the server-side code.</p>
+<p></p>
+<div class="source"><pre><pre>        // Create a configuration context. This will also load the details about the mail
+        // address to listen to from the configuration file.
+        File file = new File(MAIL_TRANSPORT_SERVER_ENABLED_REPO_PATH);
+        ConfigurationContextFactory builder = new ConfigurationContextFactory();
+        ConfigurationContext configContext = configContextbuilder
+                .buildConfigurationContext(file.getAbsolutePath());
+
+        // Start the default mail listener. It will starting poling for mail
+        // using the configuration from the XML file.
+        SimpleMailListener ml = new SimpleMailListener();
+        ml.init(configContext,
+                configContext.getAxisConfiguration().getTransportIn(
+                        new QName(Constants.TRANSPORT_MAIL)));
+        ml.start();
+
+        private QName serviceName = new QName(&quot;EchoXMLService&quot;);
+        private QName operationName = new QName(&quot;echoOMElement&quot;);
+    
+        // Setup a service that will echo what we send to the server.
+        AxisService service = Utils.createSimpleService(serviceName, Echo.class
+                .getName(), operationName);
+        serverConfigContext.getAxisConfiguration().addService(service);</pre></pre>
+</div>
+<p>Note that a separate ConfigurationContext needs to be created and used.</p>
+<h2>Resources</h2><p>For more information on Mail client invocation, see
+AXIS2_HOME\samples\userguide\src\userguide\clients\MailClient.java</p>
+<p></p>
+</html>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">&#169;  
+          2004-2008
+    
+          Apache Software Foundation
+          
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>



Mime
View raw message