You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by de...@apache.org on 2007/08/13 12:13:23 UTC
svn commit: r565295 [7/14] - in /webservices/axis2/site/1_3: ./ adb/ jibx/
src/
Added: webservices/axis2/site/1_3/mail-configuration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/mail-configuration.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/mail-configuration.html (added)
+++ webservices/axis2/site/1_3/mail-configuration.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,564 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+<html>
+ <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="http://ws.apache.org/axis2/images/axis.jpg" alt="" />
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 08/13/2007
+ </div>
+ <div class="xright"> <a href="../index.html">Axis2/Java</a>
+ |
+ <a href="http://ws.apache.org/axis2/c">Axis2/C</a>
+ |
+ <a href="../../../">Apache WS</a>
+ |
+ <a href="http://www.apache.org">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_3/contents.html">Version 1.3</a>
+ <ul>
+
+ <li class="none">
+ <a href="../1_3/toc.html">Table of Contents</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/installationguide.html">Installation Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/quickstartguide.html">QuickStart Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/userguide.html">User Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/pojoguide.html">POJO Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/spring.html">Spring Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/webadminguide.html">Web Administrator's Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/migration.html">Migration Guide (from Axis1)</a>
+ </li>
+ </ul>
+ </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/">Wiki</a>
+ </li>
+
+ <li class="none">
+ <a href="../refLib.html">Reference Library</a>
+ </li>
+
+ <li class="none">
+ <a href="http://ws.apache.org/axis2/1_3/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">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">License</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" id="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=""></meta>
+ Mail transport
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</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>
+
+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.
+
+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.
+
+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.
+<a name="sender"></a>
+
+<h2>Transport Sender</h2>
+
+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>.
+
+JavaMail sets its properties to a Properties object. In Axis2, this has
+been mapped to a Parameter object. Mapping has been done as follows,
+<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>A few properties, such as the password, are set to @name with the prefix
+ "transport"</li>
+</ul>
+
+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)
+<div class="source"><pre><pre> <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
+ <parameter name="mail.smtp.host">hostname</parameter>
+ <parameter name="mail.smtp.user">username</parameter>
+ <parameter name="transport.mail.smtp.password">password</parameter>
+ </transportSender>
+ </pre>
+</pre></div>
+and
+<div class="source"><pre>
+<pre>
+<transportReceiver name="mailto" class="org.apache.axis2.transport.mail.SimpleMailListener">
+ <parameter name="mail.pop3.host">mailhost</parameter>
+ <parameter name="mail.pop3.user">username</parameter>
+ <parameter name="mail.store.protocol">pop3</parameter>
+ <parameter name="transport.mail.pop3.password">password</parameter>
+ <parameter name="transport.mail.replyToAddress">server_emailaddress</parameter>
+ <parameter name="transport.listener.interval">3000</parameter>
+ </transportReceiver>
+</pre></pre></div>
+
+and the following to the client axis2.xml
+
+<div class="source"><pre><pre> <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
+ <parameter name="mail.smtp.host">hostname</parameter>
+ <parameter name="mail.smtp.user">username</parameter>
+ <parameter name="transport.mail.smtp.password">password</parameter>
+ <parameter name="mail.smtp.from">client_email_address</parameter>
+ </transportSender>
+ </pre>
+</pre></div>
+and
+<div class="source"><pre><pre>
+<transportReceiver name="mailto" class="org.apache.axis2.transport.mail.SimpleMailListener">
+ <parameter name="mail.pop3.host">mailhost</parameter>
+ <parameter name="mail.pop3.user">username</parameter>
+ <parameter name="mail.store.protocol">pop3</parameter>
+ <parameter name="transport.mail.pop3.password">password</parameter>
+ <parameter name="transport.mail.replyToAddress">client_emailaddress</parameter>
+ <parameter name="transport.listener.interval">3000</parameter>
+ </transportReceiver></pre></pre></div>
+
+
+At runtime, tuning a client to set the mail transport is as easy as
+follows:
+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(
+ "mailto:test@mail.com?x-service-path=/axis2/services/SampleService");
+</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("urn:SampleService");
+ sender.setOptions(options);
+ sender.engageModule("addressing");
+
+...</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.
+
+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 <parameter/> in axis2.xml as shown in the <a href="http://wso2.org/library/2537">Axis2 Mail Transport</a> document.. Configure the options object as above and,
+<div class="source"><pre>
+<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>
+</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> <transportReceiver name="mailto" class="org.apache.axis2.transport.mail.SimpleMailListener">
+ <parameter name="mail.pop3.host">hostname</parameter>
+ <parameter name="mail.pop3.user">username</parameter>
+ <parameter name="mail.store.protocol">pop3</parameter>
+ <parameter name="transport.mail.pop3.password">password</parameter>
+ <parameter name="transport.mail.replyToAddress">email_address</parameter>
+ <parameter name="transport.listener.interval">3000</parameter>
+ </transportReceiver>
+ </pre>
+</pre></div>
+<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>
+<div class="source"><pre><pre><transportReceiver name="mailto" class="org.apache.axis2.transport.mail.SimpleMailListener">
+ <parameter name="mail.pop3.host">pop.gmail.com</parameter>
+ <parameter name="mail.pop3.user">address@gmail.com</parameter>
+ <parameter name="mail.pop3.socketFactory.class">javax.net.ssl.SSLSocketFactory</parameter>
+ <parameter name="mail.pop3.socketFactory.fallback">false</parameter>
+ <parameter name="mail.pop3.port">995</parameter>
+ <parameter name="mail.pop3.socketFactory.port">995</parameter>
+ <parameter name="transport.mail.pop3.password">password</parameter>
+ <parameter name="transport.mail.replyToAddress">address@gmail.com</parameter>
+</transportReceiver></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 = "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>
+</pre></div>
+<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>
+<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></hr>
+
+</html>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">©
+ 2004-2007
+
+ Apache Software Foundation
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: webservices/axis2/site/1_3/mail-transport.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/mail-transport.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/mail-transport.html (added)
+++ webservices/axis2/site/1_3/mail-transport.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,510 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+<html>
+ <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="http://ws.apache.org/axis2/images/axis.jpg" alt="" />
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 08/13/2007
+ </div>
+ <div class="xright"> <a href="../index.html">Axis2/Java</a>
+ |
+ <a href="http://ws.apache.org/axis2/c">Axis2/C</a>
+ |
+ <a href="../../../">Apache WS</a>
+ |
+ <a href="http://www.apache.org">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_3/contents.html">Version 1.3</a>
+ <ul>
+
+ <li class="none">
+ <a href="../1_3/toc.html">Table of Contents</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/installationguide.html">Installation Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/quickstartguide.html">QuickStart Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/userguide.html">User Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/pojoguide.html">POJO Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/spring.html">Spring Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/webadminguide.html">Web Administrator's Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/migration.html">Migration Guide (from Axis1)</a>
+ </li>
+ </ul>
+ </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/">Wiki</a>
+ </li>
+
+ <li class="none">
+ <a href="../refLib.html">Reference Library</a>
+ </li>
+
+ <li class="none">
+ <a href="http://ws.apache.org/axis2/1_3/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">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">License</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" id="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=""></meta>
+ Invoking a service using mail
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</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 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="#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>
+
+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.
+<a name="intro"></a>
+
+<h2>Introduction</h2>
+
+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.
+
+Broadly speaking, there are three ways of calling a service through
+mail.
+
+<blockquote>
+ 1. Using the simple mail server included in Axis2 (not recommended in
+ production).<br></br>
+ 2. Using a generic mail server.<br></br>
+ 3. Using mailets.<br></br>
+</blockquote>
+
+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>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></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("EchoXMLService");
+ private QName operationName = new QName("echoOMElement");
+
+ // 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 > 10) {
+ throw new AxisFault(
+ "Server was shutdown as the async response is taking too long to complete.");
+ }
+ }
+
+ }</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("EchoXMLService");
+ private QName operationName = new QName("echoOMElement");
+
+ // 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">©
+ 2004-2007
+
+ Apache Software Foundation
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: webservices/axis2/site/1_3/migration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/migration.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/migration.html (added)
+++ webservices/axis2/site/1_3/migration.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,986 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+<html>
+ <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="http://ws.apache.org/axis2/images/axis.jpg" alt="" />
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 08/13/2007
+ </div>
+ <div class="xright"> <a href="../index.html">Axis2/Java</a>
+ |
+ <a href="http://ws.apache.org/axis2/c">Axis2/C</a>
+ |
+ <a href="../../../">Apache WS</a>
+ |
+ <a href="http://www.apache.org">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_3/contents.html">Version 1.3</a>
+ <ul>
+
+ <li class="none">
+ <a href="../1_3/toc.html">Table of Contents</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/installationguide.html">Installation Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/quickstartguide.html">QuickStart Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/userguide.html">User Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/pojoguide.html">POJO Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/spring.html">Spring Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/webadminguide.html">Web Administrator's Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/migration.html">Migration Guide (from Axis1)</a>
+ </li>
+ </ul>
+ </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/">Wiki</a>
+ </li>
+
+ <li class="none">
+ <a href="../refLib.html">Reference Library</a>
+ </li>
+
+ <li class="none">
+ <a href="http://ws.apache.org/axis2/1_3/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">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">License</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" id="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>
+<meta http-equiv="content-type" content=""></meta>
+Migrating from Axis 1.x
+<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</head>
+
+<h1>Migrating from Apache Axis 1.x to Axis2</h1>
+<p>This document is intended for helping Axis 1.x users migrate to
+the Axis2 series. We'll begin by listing the improvements in Axis2
+in comparison with Axis1. This will be followed by guidelines for
+migration to the new version.</p>
+<p><i>Send your feedback or questions to: <a href="mailto:axis-user@ws.apache.org?subject=[Axis2]">axis-user@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="#comp">Compatibility</a></li>
+<li><a href="#start">Getting Started</a></li>
+<li><a href="#custom_deployment">Custom Deployment of Services,
+Handlers and Modules</a></li>
+<li><a href="#transports">Transports for HTTP Connection</a></li>
+<li><a href="#data_binding">Data Binding Support</a></li>
+<li><a href="#best">Best Usage</a></li>
+</ul>
+<a name="comp"></a>
+<h2>Compatibility</h2>
+Axis1.x and Axis2 have evolved from different architectures.
+<strong>Speed</strong> - Axis2 is based on the StAX API, which
+gives greater speed than the SAX event based parsing used in
+Axis1.x.
+<strong>Stability</strong> - Axis2 has fixed phases as well as
+user-defined phases for extensions. This allows far more stability
+as well as flexibility than Axis1.x.
+<strong>Transport framework</strong> - Transports (i.e., senders
+and listeners for SOAP over various protocols such as HTTP, SMTP,
+etc.), have been abstracted away from the Axis2 engine. Having a
+transport-independent Axis engine allows far more flexibility in
+transport options.
+<strong>WSDL 2.0 support</strong> - Axis2 supports both WSDL
+versions 1.1 and 2.0, which are used by Axis2's code generation
+tools to create web service skeletons and client stubs.
+<strong>Component-oriented architecture</strong> - Axis2
+components consist of handlers and modules in .mar and .aar
+archives. These easily reusable components allow extended
+functionality such as pattern processing for your applications or
+distribution to partners. Axis2 emphasizes the "Module" concept
+over the "Handler" concept of Axis 1.x. Modules contain handlers
+that are ordered by phase rules. These are attached to specific
+service(s).
+<a name="start"></a>
+<h2>Getting Started</h2>
+<p>Let's look at a simple example of echoing at client API.</p>
+<p><b>Axis 1.x</b></p>
+<pre>
+import org.apache.axis.client.Call;
+import org.apache.axis.client.Service;
+import javax.xml.namespace.QName;
+
+public class TestClient {
+ public static void main(String [] args) {
+ try {
+ String endpoint ="http://ws.apache.org:5049/axis/services/echo";
+ Service service = new Service();
+ Call call = (Call) service.createCall();
+ call.setTargetEndpointAddress( new java.net.URL(endpoint) );
+ call.setOperationName(new QName("http://soapinterop.org/", "echoString"));
+ String ret = (String) call.invoke( new Object[] { "Hello!" } );
+ System.out.println("Sent 'Hello!', got '" + ret + "'");
+ } catch (Exception e) {
+ System.err.println(e.toString());
+ }
+ }
+}
+</pre>
+<p><b>Axis 2</b></p>
+<pre>
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.om.OMNamespace;
+import org.apache.axis2.AxisFault;
+import org.apache.axis2.addressing.EndpointReference;
+import org.apache.axis2.client.Options;
+import org.apache.axis2.client.ServiceClient;
+
+
+public class EchoBlockingClient {
+ private static EndpointReference targetEPR = new EndpointReference(
+ "http://127.0.0.1:8080/axis2/services/MyService");
+ public static void main(String[] args) {
+ try {
+ OMFactory fac = OMAbstractFactory.getOMFactory();
+ OMNamespace ns = fac.createOMNamespace("http://soapinterop.org/", "ns1");
+ OMElement payload = fac.createOMElement("echoString", ns);
+ payload.setText("Hello!");
+ Options options = new Options();
+ ServiceClient client = new ServiceClient();
+ options.setTo(targetEPR);
+ client.setOptions(options);
+ //Blocking invocation
+ OMElement result = client.sendReceive(payload);
+ System.out.println("Sent Hello, got : " + result.toString());
+
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ }
+
+ }
+}
+</pre>
+<p>The above code demonstrates that Axis2 service invocations deal
+with the SOAP body element itself. The simple shows a synchronous
+invocation, but Axis2 can handle asynchronous invocations as well.
+The "payload" variable above contains the SOAP body element which
+will go in the SOAP envelope.</p>
+<p>Once the service is called by the client stub in Axis2, the
+"payload" will be bound according to the data binding framework in
+use. So the extra work of parsing the "payload" will vanish.</p>
+<p>Axis2 supports asynchronous invocation through
+sendReceiveNonblocking(). Synchronous/Asynchronous invocations can
+handle both single and double HTTP connections.</p>
+<p>With this advanced architecture, Axis2 is capable of handling
+megabytes of requests and responses, well above the capabilities of
+Axis1.x.</p>
+<a name="custom_deployment"></a>
+<h2>Custom Deployment of Services, Handlers, and Modules</h2>
+<p>In Axis 1.x, the deployment of services was via the rather
+cumbersome WSDD. Service deployment in Axis2 is straightforward and
+dynamic using the web-based Axis2 Admin application. Deployment is
+just a matter of creating the service archive (.aar) file and
+deploying it. More details regarding this is given in the Axis2
+user guide.</p>
+<p>Axis2 has moved away from the "Handler concept" and is more into
+the "Module concept". Abstractly speaking, the module concept is a
+collection of handlers with rules that govern which modules are
+created as .mar files. It uses a module.xml file to specify handler
+configuration and activation.</p>
+<p>When a service is called through a handler, it is just a matter
+of giving a reference to the module that includes the handler in
+the services.xml (using <module ref="foo/>").</p>
+<p>Services are hot deployable in Axis2, but modules are not. This
+is one feature which is unique to Axis2.</p>
+<p>Let's take a detailed look at what it takes to migrate the Axis
+1.x handlers to the Axis 2 modules via the "SOAP Monitor". The SOAP
+monitor is really a combination of three components: An applet
+which displays responses/requests, a servlet which binds to a
+default port of 5001 and connects to the applet, and a handler
+chain used to intercept the SOAP messages. Here we'll focus on the
+handler.</p>
+<p><b>Axis 1.x required two WSDD's to use the SOAP Monitor. First,
+the SOAP Monitor Handler itself:</b></p>
+<pre>
+<deployment xmlns="http://xml.apache.org/axis/wsdd/"
+ xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
+
+ <handler name="soapmonitor"
+ type="java:org.apache.axis.handlers.SOAPMonitorHandler">
+ <parameter name="wsdlURL"
+ value="/wzs/SOAPMonitorService-impl.wsdl"/>
+ <parameter name="namespace"
+ value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/>
+ <parameter name="serviceName" value="SOAPMonitorService"/>
+ <parameter name="portName" value="Demo"/>
+ </handler>
+
+ <service name="SOAPMonitorService" provider="java:RPC">
+ <parameter name="allowedMethods" value="publishMessage"/>
+ <parameter name="className"
+ value="org.apache.axis.monitor.SOAPMonitorService"/>
+ <parameter name="scope" value="Application"/>
+ </service>
+</deployment>
+</pre>
+<p><b>Axis 1.x requires a reference to the handler in the user's
+WSDD that defines their Web Service:</b></p>
+<pre>
+<deployment name="example" xmlns="http://xml.apache.org/axis/wsdd/"
+ xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
+
+ <service name="urn:myService" provider="java:RPC">
+ <parameter name="className" value="org.MyService"/>
+ <parameter name="allowedMethods" value="*"/>
+
+ <requestFlow>
+ <handler type="soapmonitor"/>
+ </requestFlow>
+ <responseFlow>
+ <handler type="soapmonitor"/>
+ </responseFlow>
+
+ </service>
+</deployment>
+</pre>
+<p><b>Axis 2 requires a module.xml, placed inside a jar with a .mar
+extension under WEB-INF/modules, to define a Handler:</b></p>
+<pre>
+<module name="soapmonitor" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorModule">
+ <inflow>
+ <handler name="InFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler">
+ <order phase="soapmonitorPhase"/>
+ </handler>
+ </inflow>
+
+ <outflow>
+ <handler name="OutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler">
+ <order phase="soapmonitorPhase"/>
+ </handler>
+ </outflow>
+
+ <Outfaultflow>
+ <handler name="FaultOutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler">
+ <order phase="soapmonitorPhase"/>
+ </handler>
+ </Outfaultflow>
+
+ <INfaultflow>
+ <handler name="FaultInFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler">
+ <order phase="soapmonitorPhase"/>
+ </handler>
+ </INfaultflow>
+</module>
+</pre>
+<p>The SOAPMonitorModule referenced above simply implements the
+org.apache.axis2.modules.Module, and is used for any additional
+tasks needed to initialize the module and shutdown the module. In
+this situation, nothing is needed and the implemented interface
+methods have blank bodies. Furthermore, the 'soapmonitorPhase' will
+be used later (below) in the axis2.xml .</p>
+<p><b>Axis 1.x the SOAPMonitorHandler has the class signature
+as:</b></p>
+<pre>
+public class SOAPMonitorHandler extends BasicHandler
+</pre>
+<p><b>Axis 2 the SOAPMonitorHandler has the class signature
+as:</b></p>
+<pre>
+public class SOAPMonitorHandler extends AbstractHandler
+</pre>
+<p><b>In Axis2, you need to reference the module that contains the
+handler chain that you want to use inside your
+services.xml:</b></p>
+<pre>
+<service name="ExampleService">
+ <module ref="soapmonitor"/>
+ <description>
+ This service has the SOAP Monitor wired in
+ </description>
+ <parameter name="ServiceClass">org.ExampleService</parameter>
+ <operation name="myExecute">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+</service>
+</pre>
+<p><b>Finally, Axis2 requires you to make some changes to
+axis2.xml. Start by adding a global module:</b></p>
+<pre>
+ <module ref="soapmonitor"/>
+</pre>
+<p><b>Then define your phase orders for the 'soapmonitorPhase'
+referenced in the module.xml :</b></p>
+<pre>
+ <phaseOrder type="inflow">
+ <!-- Global Phases -->
+ <phase name="TransportIn"/>
+ <phase name="PreDispatch"/>
+ <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">
+ <handler name="AddressingBasedDispatcher"
+ class="org.apache.axis2.dispatchers.AddressingBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="RequestURIBasedDispatcher"
+ class="org.apache.axis2.dispatchers.RequestURIBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPActionBasedDispatcher"
+ class="org.apache.axis2.dispatchers.SOAPActionBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPMessageBodyBasedDispatcher"
+ class="org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+ <handler name="InstanceDispatcher"
+ class="org.apache.axis2.engine.InstanceDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+ </phase>
+ <!-- Global Phases -->
+ <!-- After Dispatch phase module author or service author can add any phase he wants -->
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ </phaseOrder>
+ <phaseOrder type="outflow">
+ <!-- user can add his own phases to this area -->
+ <!-- Global phases -->
+ <!-- these phases will run irrespective of the service -->
+ <phase name="MessageOut"/>
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ <phase name="PolicyDetermination"/>
+ <!-- Global phases -->
+ </phaseOrder>
+ <phaseOrder type="INfaultflow">
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ <!-- user can add his own phases to this area -->
+ </phaseOrder>
+ <phaseOrder type="Outfaultflow">
+ <!-- user can add his own phases to this area -->
+ <!-- Global phases -->
+ <phase name="MessageOut"/>
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ <phase name="PolicyDetermination"/>
+ <!-- Global phases -->
+ </phaseOrder>
+</pre>
+<p>See the user guide for more information on Axis2 modules.</p>
+<a name="transports"></a>
+<h2>Transports for HTTP Connection</h2>
+<p>Axis2 comes with the CommonsHTTPTransportSender which is based
+on commons-httpclient.</p>
+<p>It should be noted that axis2.xml should be configured to call
+the commons transports in this manner:</p>
+<pre>
+...
+<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+ <parameter name="PROTOCOL">HTTP/1.1</parameter>
+ <parameter name="Transfer-Encoding">chunked</parameter>
+</transportSender>
+...
+</pre>
+<a name="data_binding"></a>
+<h2>Data Binding Support</h2>
+<p>ADB is used to provide data binding support. In Axis2, XML is
+manipulated via AXIOM, which is based on the StAX API. AXIOM
+provides full XML schema support. Thus, serialization and
+de-serialization of XML is handled in Axis2 via the xml-data
+binding framework.</p>
+<p>Below is an example of migrating a WSDL based Axis 1.x Web
+Service to Axis2.</p>
+<p>First, let's take a look at a simple document/literal style WSDL
+used in an Axis 1.x Web Service. This example assumes the name
+simple.wsdl for the WSDL below:</p>
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+
+<definitions name="SimpleService" targetNamespace="http://simpleNS" xmlns:tns="http://simpleNS"
+xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns2="http://simpleNS/types">
+ <types>
+ <schema targetNamespace="http://simpleNS/types" xmlns:tns="http://simpleNS/types"
+xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+xmlns="http://www.w3.org/2001/XMLSchema">
+ <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
+ <element name="simpleLogin">
+ <complexType>
+ <sequence>
+ <element name="user_name" type="xsd:string"/>
+ <element name="user_password" type="xsd:string"/>
+ </sequence>
+ </complexType>
+ </element>
+ <element name="simpleLoginResponse">
+ <complexType>
+ <sequence>
+ <element name="soap_session_id" type="xsd:string"/>
+ <element name="web_user_name" type="xsd:string"/>
+ </sequence>
+ </complexType>
+ </element>
+</schema></types>
+ <message name="SimpleEndpoint_simpleLogin">
+ <part name="parameters" element="ns2:simpleLogin"/>
+ </message>
+ <message name="SimpleEndpoint_simpleLoginResponse">
+ <part name="result" element="ns2:simpleLoginResponse"/>
+ </message>
+ <portType name="SimpleEndpoint">
+ <operation name="simpleLogin">
+ <input message="tns:SimpleEndpoint_simpleLogin" name="SimpleEndpoint_simpleLogin"/>
+ <output message="tns:SimpleEndpoint_simpleLoginResponse" name="SimpleEndpoint_simpleLoginResponse"/>
+ </operation>
+ </portType>
+ <binding name="SimpleEndpointBinding" type="tns:SimpleEndpoint">
+ <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
+ <operation name="simpleLogin">
+ <soap:operation soapAction="simpleLogin"/>
+ <input name="SimpleEndpoint_simpleLogin">
+ <soap:body use="literal"/>
+ </input>
+ <output name="SimpleEndpoint_simpleLoginResponse">
+ <soap:body use="literal"/>
+ </output>
+ </operation>
+ </binding>
+ <service name="SimpleService">
+ <port name="SimpleEndpointPort" binding="tns:SimpleEndpointBinding">
+ <soap:address location="http://localhost:8080/axis/services/SimpleEndpointPort"/></port></service></definitions>
+</pre>
+<p>The next step is to run WSDL2Java on the wsdl. For axis 1.x,
+this example uses the following Ant task:</p>
+<pre>
+<target name="wsdl2java" description="axis 1.x">
+ <delete dir="output" />
+ <mkdir dir="output" />
+ <axis-wsdl2java
+ output="output"
+ verbose="true"
+ url="wsdl/simple.wsdl"
+ serverside="true"
+ skeletondeploy="true"
+ nowrapped="true">
+ </axis-wsdl2java>
+ </target>
+</pre>
+<p>The Axis 1.x Ant task above takes the simple.wsdl under the
+directory 'wsdl' , and from that creates files under the directory
+'output'. The files created are shown below:</p>
+<pre>
+output/
+output/simpleNS
+output/simpleNS/types
+output/simpleNS/types/SimpleLoginResponse.java
+output/simpleNS/types/SimpleLogin.java
+output/simpleNS/SimpleEndpoint.java
+output/simpleNS/SimpleEndpointBindingStub.java
+output/simpleNS/SimpleEndpointBindingSkeleton.java
+output/simpleNS/SimpleEndpointBindingImpl.java
+output/simpleNS/SimpleService.java
+output/simpleNS/SimpleServiceLocator.java
+output/simpleNS/deploy.wsdd
+output/simpleNS/undeploy.wsdd
+</pre>
+<p>Now let's run WSDL2Java with Axis2. In this example, the only
+change to simple.wsdl required for Axis2 is that 'soap:address
+location' be changed to:</p>
+<pre>
+<soap:address location="http://localhost:8080/axis2/services/SimpleEndpoint"/></port></service></definitions>
+</pre>
+<p>In Axis2, the default databinding uses ADB. However, XMLBeans,
+JiBX and JaxMe are also supported. This example uses XMLBeans. For
+Axis2, our example uses the following Ant task:</p>
+<pre>
+<target name="wsdl2java">
+ <delete dir="output" />
+ <java classname="org.apache.axis2.wsdl.WSDL2Java" fork="true">
+ <classpath refid="axis.classpath"/>
+ <arg value="-d"/>
+ <arg value="xmlbeans"/>
+ <arg value="-uri"/>
+ <arg file="wsdl/simple.wsdl"/>
+ <arg value="-ss"/>
+ <arg value="-g"/>
+ <arg value="-sd"/>
+ <arg value="-o"/>
+ <arg file="output"/>
+ <arg value="-p"/>
+ <arg value="org.simple.endpoint"/>
+ </java>
+
+ <!-- Move the schema folder to classpath-->
+ <move todir="${build.classes}">
+ <fileset dir="output/resources">
+ <include name="*schema*/**/*.class"/>
+ <include name="*schema*/**/*.xsb"/>
+ </fileset>
+ </move>
+
+ </target>
+</pre>
+<p>For an explanation of the Axis2 WSDL2Java Ant task and its
+options, see the <a href="../tools/1_3/CodegenToolReference.html">CodegenToolReference
+Guide.</a></p>
+<p>A feature of XMLBeans is that there is one class file created
+with WSDL2java, and a series of .xsb files. They must be referenced
+when compiling, and as the example shows, these files are moved to
+a build directory.</p>
+<p>The Axis2 WSDL2Java example also takes the simple.wsdl, which is
+under the directory 'wsdl', and creates files under the directory
+'output'. The relevant non-xmlbean files created are shown
+below:</p>
+<pre>
+output/resources/services.xml
+output/src/org/simple
+output/src/org/simple/endpoint
+output/src/org/simple/endpoint/SimpleEndpointSkeleton.java
+output/src/org/simple/endpoint/SimpleEndpointMessageReceiverInOut.java
+output/src/org/simple/endpoint/SimpleEndpointCallbackHandler.java
+output/src/org/simple/endpoint/SimpleEndpointStub.java
+output/src/simplens
+output/src/simplens/types
+output/src/simplens/types/SimpleLoginDocument.java
+output/src/simplens/types/impl
+output/src/simplens/types/impl/SimpleLoginDocumentImpl.java
+output/src/simplens/types/impl/SimpleLoginResponseDocumentImpl.java
+output/src/simplens/types/SimpleLoginResponseDocument.java
+</pre>
+<p>The first important distinction is that while the Axis 1.x
+example generated deploy.wsdd and undeploy.wsdd, the Axis2 example
+created a services.xml. The files deploy.wsdd and services.xml are
+a breed apart, coming from different architectures. There is no
+direct parallel between them. See the Axis2 user guide for an
+explanation about services.xml</p>
+<p>Now we're ready to code. We'll start with Axis 1.x on the
+service side. To implement the business logic, we'll change
+simpleNS/SimpleEndpointBindingImpl.java from:</p>
+<pre class="code">
+package simpleNS;
+
+public class SimpleEndpointBindingImpl implements simpleNS.SimpleEndpoint{
+ public simpleNS.types.SimpleLoginResponse simpleLogin(simpleNS.types.SimpleLogin parameters)
+ throws java.rmi.RemoteException {
+ return null;
+ }
+
+}
+</pre>
+<p>To:</p>
+<pre class="code">
+package simpleNS;
+
+public class SimpleEndpointBindingImpl implements simpleNS.SimpleEndpoint{
+ public simpleNS.types.SimpleLoginResponse simpleLogin(simpleNS.types.SimpleLogin parameters)
+ throws java.rmi.RemoteException {
+
+ String userName = parameters.getUser_name();
+ String password = parameters.getUser_password();
+ // do something with those vars...
+ return new simpleNS.types.SimpleLoginResponse("mySessionID", "username");
+ }
+
+}
+</pre>
+<p>In Axis 1.x, the next step is to compile the classes and put
+them in the Axis.war, and then run the admin client with the
+generated deploy.wsdd. You then look at the happy axis page to
+verify that the service has been installed correctly.</p>
+<p>Now let's code Axis2. In Axis 1.x, while the Ant task shown in
+the example created a skeleton, a peek inside shows that the
+skeleton calls the binding implementation class. In Axis2, we work
+with the skeleton directly. To implement the business logic in the
+generated Axis2 classes, we'll change
+org/simple/endpoint/SimpleEndpointSkeleton.java from:</p>
+<pre class="code">
+package org.simple.endpoint;
+ /**
+ * SimpleEndpointSkeleton java skeleton for the axisService
+ */
+ public class SimpleEndpointSkeleton {
+
+ /**
+ * Auto generated method signature
+ * @param param0
+ */
+ public simplens.types.SimpleLoginResponseDocument simpleLogin
+ (simplens.types.SimpleLoginDocument param0 ) throws Exception {
+ //Todo fill this with the necessary business logic
+ throw new java.lang.UnsupportedOperationException();
+ }
+}
+</pre>
+<p>To:</p>
+<pre class="code">
+package org.simple.endpoint;
+
+ import simplens.types.*;
+ import simplens.types.SimpleLoginResponseDocument.*;
+ import simplens.types.SimpleLoginDocument.*;
+ /**
+ * SimpleEndpointSkeleton java skeleton for the axisService
+ */
+ public class SimpleEndpointSkeleton {
+
+ /**
+ * Modified
+ * @param simpleLoginDocument
+ */
+ public SimpleLoginResponseDocument simpleLogin
+ (simplens.types.SimpleLoginDocument simpleLoginDocument){
+
+ SimpleLoginResponseDocument retDoc =
+ SimpleLoginResponseDocument.Factory.newInstance();
+
+ SimpleLoginResponse retElement =
+ SimpleLoginResponse.Factory.newInstance();
+
+ // Get parameters passed in
+ SimpleLogin simpleLogin = simpleLoginDocument.getSimpleLogin();
+ String userName = simpleLogin.getUserName();
+ String password = simpleLogin.getUserPassword();
+
+ // do something with those variables...
+
+ retElement.setWebUserName(userName);
+ retElement.setSoapSessionId("my random string");
+ retDoc.setSimpleLoginResponse(retElement);
+ return retDoc;
+ }
+}
+</pre>
+<p>In Axis2, the next step is to compile the classes, put them
+along with the generated services.xml in an AAR, and then hot
+deploy the AAR by placing it in the Axis2.war under
+WEB-INF/services. Point a browser to
+http://localhost:8080/axis2/listServices, and you should see the
+service 'SimpleService' ready for action. See the Axis2 user guide
+for more info.</p>
+<p>The last step is constructing the client. Our Axis 1.x client
+for this example is:</p>
+<pre>
+package org;
+
+import simpleNS.*;
+import simpleNS.types.*;
+
+public class Tester {
+ public static void main(String [] args) throws Exception {
+ // Make a service
+ SimpleService service = new SimpleServiceLocator();
+
+ // Now use the service to get a stub which implements the SDI.
+ SimpleEndpoint port = service.getSimpleEndpointPort();
+
+ // set the params
+ SimpleLogin parameters = new SimpleLogin("username","password");
+ // Make the actual call
+ SimpleLoginResponse simpleLoginResponse = port.simpleLogin(parameters);
+ String session = simpleLoginResponse.getSoap_session_id();
+ String user = simpleLoginResponse.getWeb_user_name();
+ System.out.println("simpleLoginResponse, session: " + session + ", user: " + user);
+ }
+}
+</pre>
+<p>Finally, our Axis2 client for this example is:</p>
+<pre>
+package org;
+import simplens.types.*;
+import simplens.types.SimpleLoginDocument.*;
+import simplens.types.SimpleLoginResponseDocument.*;
+import simplens.types.impl.*;
+import org.simple.endpoint.*;
+
+public class Tester {
+ public static void main(String [] args) throws Exception {
+
+ // you may not need to pass in the url to the constructor - try the default no arg one
+ SimpleEndpointStub stub =
+ new SimpleEndpointStub(null, "http://localhost:8080/axis2/services/SimpleService");
+
+ SimpleLogin simpleLogin = SimpleLogin.Factory.newInstance();
+ simpleLogin.setUserName("userName");
+ simpleLogin.setUserPassword("password");
+
+ SimpleLoginDocument simpleLoginDocument =
+ SimpleLoginDocument.Factory.newInstance();
+
+ simpleLoginDocument.setSimpleLogin(simpleLogin);
+
+ SimpleLoginResponseDocument simpleLoginResponseDocument
+ = stub.simpleLogin(simpleLoginDocument);
+
+ SimpleLoginResponse simpleLoginResponse =
+ simpleLoginResponseDocument.getSimpleLoginResponse();
+
+ String session = simpleLoginResponse.getSoapSessionId();
+ String user = simpleLoginResponse.getWebUserName();
+ System.out.println("simpleLoginResponse, session: " + session + ", user: " + user);
+
+ }
+}
+</pre>
+<p>Axis2 clients also have asynchronous options via a Callback and
+alternatively a 'Fire and forget'. See the user guide for more
+details.</p>
+<a name="best"></a>
+<h2>Best Usage</h2>
+<p>Axis1.x and Axis2 have different ways of seeing the SOAP stack.
+So the best way to migrate is to follow the <a href="userguide.html">User's Guide</a> and the <a href="Axis2ArchitectureGuide.html">Architecture Guide</a> of Axis2
+properly. We are confident you will find Axis2 very straightforward
+and more friendly to use than its predecessor.</p>
+
+</html>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">©
+ 2004-2007
+
+ Apache Software Foundation
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org