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 ch...@apache.org on 2007/05/25 10:09:37 UTC
svn commit: r541579 [5/18] - in /webservices/axis2/trunk/java/xdocs: ./
@axis2_version_dir@/ @axis2_version_dir@/adb/
@axis2_version_dir@/adb/images/ @axis2_version_dir@/images/
@axis2_version_dir@/images/archi-guide/ @axis2_version_dir@/images/usergui...
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/MyServiceDeployed.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/images/userguide/MyServiceDeployed.jpg?view=auto&rev=541579
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/MyServiceDeployed.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/ServiceDeployed.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/images/userguide/ServiceDeployed.jpg?view=auto&rev=541579
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/ServiceDeployed.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/ServiceItems.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/images/userguide/ServiceItems.jpg?view=auto&rev=541579
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/ServiceItems.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/TestClient.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/images/userguide/TestClient.jpg?view=auto&rev=541579
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/TestClient.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/http-get-ws.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/images/userguide/http-get-ws.jpg?view=auto&rev=541579
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/userguide/http-get-ws.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/viewphases.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/images/viewphases.jpg?view=auto&rev=541579
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/viewphases.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/wom.png
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/images/wom.png?view=auto&rev=541579
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/images/wom.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/index.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/index.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/index.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/index.html Fri May 25 01:09:03 2007
@@ -0,0 +1,12 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+</head>
+ <frameset cols="260,*" border="1" frameborder="yes" framespacing="0" margin="0">
+ <frame name="leftFrame" src="toc.html" noresize="noresize" scrolling="yes" />
+ <frame name="mainFrame" src="contents.html" />
+ <noframes>
+ <body></body>
+ </noframes>
+ </frameset>
+</html>
\ No newline at end of file
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/installationguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/installationguide.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/installationguide.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/installationguide.html Fri May 25 01:09:03 2007
@@ -0,0 +1,484 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Axis2 Installation Guide</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<body lang="en">
+<h1 align="center">Apache Axis2 Installation Guide</h1>
+
+<p>This document provides information on Axis2 distribution packages, system
+prerequisites and setting up environment variables and tools followed by
+detailed instructions on installation methods.</p>
+
+<p><i>Send your feedback to: <a
+href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a></i>
+mailing list. (Subscription details are available on <a
+href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly
+prefix every email subject with [Axis2].</p>
+
+<h2>Contents</h2>
+<ul>
+ <li><a href="#Download_Axis2">Axis2 Distributions</a></li>
+ <li><a href="#requirements">System Requirements</a></li>
+ <li><a href="#standalone">Install Axis2 as a Standalone Server using
+ Standard Binary Distribution</a>
+ <ul>
+ <li><a href="#standalone1">Install the Apache Axis2 Binary
+ Distribution</a></li>
+ <li><a href="#standalone2">Starting up Axis2 Standalone Server</a></li>
+ <li><a href="#standalone3">Building WAR File Using Standard Binary
+ Distribution</a></li>
+ <li><a href="#standalone4">Getting Familiar with the Axis2 Convenient
+ Scripts</a></li>
+ </ul>
+ </li>
+ <li><a href="#servlet_container">Install Axis2 in a Servlet
+ Container</a></li>
+ <li><a href="#upload">Uploading Services</a></li>
+ <li><a href="#advanced">Advanced</a>
+ <ul>
+ <li><a href="#source">Axis2 Source Distribution</a>
+ <ul>
+ <li><a href="#_Toc96698083">Setting up the Environment and
+ Tools</a></li>
+ <li><a href="#_Toc96698085">Building Axis2 Binaries and the WAR
+ file Using the Source Distribution</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+</ul>
+<a name="Download_Axis2"></a>
+
+<h2>Axis2 Distributions</h2>
+
+<p>Axis2 is distributed in several convenient distribution packages and can
+be installed either as a standalone server or as part of a J2EE compliant
+servlet container. Axis2 is distributed under the Apache License, version
+2.0. This Installation Guide will mainly focus on running Apache Axis2 using
+the Standard Binary Distribution.</p>
+
+<p><a
+href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi">Download</a>
+distribution packages of the Apache Axis2 @axis2_version@ version (latest).</p>
+
+<p></p>
+
+<p><a href="http://ws.apache.org/axis2/download.cgi">Download</a>
+distribution packages of all versions of Apache Axis2.</p>
+
+<p>The Distribution Packages Provided are as follows:</p>
+<a name="std-bin" id="std-bin"></a>
+
+<h3>1. Standard Binary Distribution</h3>
+
+<p>This is the complete version of Axis2 and includes samples and convenient
+scripts as well.</p>
+
+<p><a
+href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi">Download</a>
+Standard Binary Distribution</p>
+<a name="war1"></a>
+
+<h3>2. WAR (Web Archive) Distribution</h3>
+
+<p>This is the Web application of Axis2, which can be deployed in most of the
+servlet containers.</p>
+
+<p><a
+href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi">Download</a>
+WAR (Web Archive) Distribution</p>
+
+<p></p>
+
+<h3>3. Documents Distribution</h3>
+
+<p>This contains all the documentation in one package. The package includes
+the xdocs and the Java API docs of this project.</p>
+
+<p><a
+href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi">Download</a>
+Documents Distribution</p>
+
+<p></p>
+
+<h3>4. Source Distribution</h3>
+
+<p>This contains the sources of Axis2 standard distribution, and is mainly
+for the benefit of the advance users. One can generate a binary distribution
+using the source by typing <span class="style1">$maven dist-bin. </span> You
+need to set up the Axis2 environment before running this command. Step by
+step details on how to create the binary distribution is available in the <a
+href="#advanced">Advanced</a> section.</p>
+
+<p><a
+href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi">Download</a>
+Source Distribution</p>
+<a name="requirements"></a>
+
+<h2>System Requirements</h2>
+
+<table border="2">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <td>Java Development Kit (JDK)</td>
+ <td>1.4 or later (For instructions on setting up the JDK in different
+ operating systems, visit <a
+ href="http://java.sun.com/">http://java.sun.com</a>)</td>
+ </tr>
+ <tr>
+ <td>Disk</td>
+ <td>Approximately 11 MB separately for standard binary distribution</td>
+ </tr>
+ <tr>
+ <td>Operating system</td>
+ <td>Tested on Windows XP, Linux, Mac OS X, Fedora core, Ubuntu,
+ Gentoo</td>
+ </tr>
+ <tr>
+ <td><strong>Build Tool</strong>-<a href="http://ant.apache.org/">Apache
+ Ant</a>
+
+ <p>To run samples and to build WAR files from Axis2 binary
+ distribution.</p>
+ </td>
+ <td>Version 1.6.5 or higher (<a
+ href="http://ant.apache.org/bindownload.cgi">download</a>).</td>
+ </tr>
+ <tr>
+ <td><strong>Build Tool</strong>- <a
+ href="http://maven.apache.org/maven-1.x/">Apache Maven 1.x</a>
+
+ <p>Required <em>only</em> for building Axis2 from Source
+ Distribution</p>
+ </td>
+ <td>1.0.2 or higher in Maven 1.x series (<a
+ href="http://maven.apache.org/maven-1.x/start/download.html">download</a>).
+ <strong>Please download Maven 1.x version. Axis2 does not support
+ Maven 2.</strong></td>
+ </tr>
+ </tbody>
+</table>
+
+<p>Make sure that the above prerequisites are available for the Axis2
+installation.</p>
+<a name="standalone"></a>
+
+<h2>Install Axis2 as a Standalone Server using Standard Binary
+Distribution</h2>
+<a name="standalone1"></a>
+
+<p>This section provides you with the following information</p>
+<ol>
+ <li>Install Axis2 as a standalone server using the Standard Binary
+ Distribution</li>
+ <li>Start up the Axis2 standalone server</li>
+ <li>Building the axis2.war file (using the Standard Binary Distribution)
+ which is required to run Axis2 as part of a J2EE compliant servlet
+ container</li>
+ <li>Running Axis2 convenient scripts</li>
+</ol>
+
+<h3>1. Download and Install the Apache Axis2 Binary Distribution</h3>
+
+<p><a href="http://java.sun.com/j2se/">Download</a> and install a Java
+Development Kit (JDK) release (version 1.4 or later). Install the JDK
+according to the instructions included with the release. Set an environment
+variable JAVA_HOME to the pathname of the directory into which you installed
+the JDK release.</p>
+
+<p>Download and unpack the <a
+href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi">Axis2 Standard
+Binary Distribution</a> into a convenient location so that the distribution
+resides in its own directory. Set an environment variable AXIS2_HOME to the
+pathname of the extracted directory of Axis2 (Eg: /opt/axis2-@axis2_version@).</p>
+<a name="standalone2"></a>
+
+<h3>2. Starting up Axis2 Standalone Server</h3>
+
+<p>Standalone Axis2 server can be started by executing the following
+commands: <br>
+$AXIS2_HOME\bin\axis2server.bat (Windows) <br>
+$AXIS2_HOME/bin/axis2server.sh (Unix)</p>
+
+<p>After startup, the default web services included with Axis2 will be
+available by visiting http://localhost:8080/axis2/services/</p>
+<a name="standalone3" id="standalone3"></a>
+
+<h3>3. Building the Axis2 Web Application (axis2.war) Using Standard Binary
+Distribution</h3>
+
+<p><a href="http://ant.apache.org/bindownload.cgi">Download</a> and install
+Apache Ant (version 1.6.5 or later). Install Apache Ant according to the
+instructions included with the Ant release.</p>
+
+<p>Locate the Ant build file (build.xml) inside the webapp directory, which
+resides in your Axis2 home directory (i.e:- $AXIS_HOME/webapp)". Run the Ant
+build by executing "ant create.war" inside the $AXIS2_HOME/webapps folder.
+You can find the generated axis2.war inside the $AXIS2_HOME/dist directory.
+All the services and modules that are present in the AXIS2_HOME/repository
+will be packed into the created axis2.war together with the Axis2
+configuration found at $AXIS2_HOME/conf/axis2.xml.</p>
+
+<p>Read <a href="#servlet_container">Installing Axis2 in a Servlet
+Container</a> to find out how to deploy the Axis2 Web application in a
+servlet container.</p>
+<a name="standalone4"></a>
+
+<h3>4. Getting Familiar with the Axis2 Convenient Scripts</h3>
+
+<p>It is advised to add the $AXIS2_HOME/bin to the PATH, so that you'll be
+able to run the following scripts from any where.</p>
+
+<table border="1">
+ <tbody>
+ <tr>
+ <td><b>Script Name</b></td>
+ <td><b>Description</b></td>
+ </tr>
+ <tr>
+ <td>axis2.{bat|sh}</td>
+ <td>You can use this script to run web service clients written using
+ Axis2. This script calls the "java" command after adding the
+ classpath for Axis2 dependent libraries (*.jar files present in your
+ AXIS2_HOME/lib), setting the Axis2 repository location
+ (AXIS2_HOME/repository) and setting the Axis2 configuration file
+ location(AXIS2_HOME/conf/axis2.xml) for you. With this you can be
+ relieved from setting all the above Axis2 specific parameters.<br>
+
+
+ <p><em>Usage : axis2.{sh.bat} [-options] class [args...]</em></p>
+ </td>
+ </tr>
+ <tr>
+ <td>axis2server.{sh|bat}</td>
+ <td>This script will start a standalone Axis2 server using the
+ AXIS2_HOME/repository as the Axis2 repository and the
+ AXIS2_HOME/conf/axis2.xml as the Axis2 configuration file. This will
+ start all the transport listeners listed in the
+ AXIS2_HOME/conf/axis2.xml.
+
+ <p>For example, if you want to deploy a service using a standalone
+ Axis2 server,then copy your service archive to the
+ AXIS2_HOME/repository/services directory. Next, go to the "Transport
+ Ins" section of the AXIS2_HOME/conf/axis2.xml and configure the
+ transport receivers (simpleHttpServer in port 8080 is listed by
+ default). Then invoke this script.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>wsdl2java.{bat|sh}</td>
+ <td>This script generates Java code according to a given WSDL file to
+ handle Web service invocations (Client side Stubs). This script also
+ has the ability to generate service skeletons according to the given
+ WSDL.<br>
+
+
+ <p><em>Usage: wsdl2java.{sh|bat} [OPTION]... -uri <Location of
+ WSDL></em></p>
+
+ <p>e.g., wsdl2java.sh -uri ../wsdl/Axis2Sample.wsdl</p>
+
+ <p>A more detailed reference about this script can be found <a
+ href="reference.html">here</a></p>
+ </td>
+ </tr>
+ <tr>
+ <td>java2wsdl.{bat|sh}</td>
+ <td>This script generates the appropriate WSDL file for a given Java
+ class.<br>
+
+
+ <p><em>Usage: Java2WSDL.{sh|bat} [OPTION]... -cn <fully qualified
+ class name></em></p>
+
+ <p>e.g., Java2WSDL.sh -cn ../samples/test/searchTool.Search</p>
+
+ <p>A more detailed reference about this script can be found <a
+ href="reference.html">here</a></p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<a name="servlet_container"></a>
+
+<h2>Install Axis2 in a Servlet Container</h2>
+
+<p>Which ever the distribution, installing Axis2 in a J2EE compliant servlet
+container is as follows:</p>
+<ol>
+ <li>Build the Axis2 WAR file using the Axis2 <a
+ href="#standalone3">Standard Binary Distribution</a>. (Alternatively you
+ can <a
+ href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi">download</a>
+ the axis2.war file or you can build axis2.war using the <a
+ href="#war">Source Distribution</a>.</li>
+ <li>Drop the WAR file in the webapps folder of the servlet container. Most
+ servlet containers will automatically install the WAR file. (Some servlet
+ containers may require a restart in order to capture the new web
+ application. Refer to your servlet container documentation for more
+ information.)</li>
+ <li>Once the WAR is successfully installed, test it by pointing the web
+ browser to the <strong>http://<host :port>/axis2. </strong>It
+ should produce the following page which is the <strong>Axis2 Web
+ Application Home Page</strong>.</li>
+
+ <p align="center"><strong><img src="images/clip_image006.jpg"
+ alt=""></strong></p>
+ <li>Use the link "Validate" to ensure that everything is fine and smooth.
+ If the validation fails then the WAR has failed to install properly or
+ some essential jars are missing. In such a situation, refer to the
+ documentation of the particular servlet container to find the problem.
+ The following page is a successful validation. Note that the statement
+ core Axis2 libraries are present.</li>
+</ol>
+
+<p align="center"><img src="images/happyaxis.jpg"></p>
+<a name="upload"></a>
+
+<p><strong>Note:</strong> For any Application server specific installation
+information please refer to the <a href="app_server.html">Application Server
+Specific Configuration Guide</a>.</p>
+
+<h2>Uploading Services</h2>
+<ol>
+ <p>The Axis2 Web application also provides an interface to upload services.
+ Once a service is created according to the service specification as
+ described in the <a name="adv-userguide.html" target="_blank">Advanced
+ User's Guide</a>, that .jar file can be uploaded using the upload page.</p>
+
+ <p align="center"><strong><img src="images/clip_image010.jpg"
+ alt=""></strong></p>
+
+ <p>The uploaded .jar files will be stored in the default service directory.
+ For Axis2, this will be the <webapps>/axis2/WEB-INF/services
+ directory. Once a service is uploaded, it will be installed instantly.</p>
+ <a name="hot_deployment"></a>
+
+ <p>Since Axis2 supports <strong>hot deployment</strong>, you can drop the
+ service jar directly through the file system to the above mentioned
+ services directory. It will also cause the service to be automatically
+ installed without the container being restarted.</p>
+
+ <p>Use the 'Services' link on the Web Application home page to check the
+ successful installation of a service. The services and the operations of
+ successfully installed services will be displayed on the available services
+ page.</p>
+
+ <p align="center"><img src="images/clip_image012.jpg" alt=""></p>
+
+ <p></p>
+
+ <p>If the service has deployment time errors it will list those services as
+ faulty services. If you click on the link, you will see the deployment
+ fault error messages.</p>
+
+ <p align="center"><img src="images/faultservice.jpg" alt=""></p>
+
+ <p>Deployment time error message</p>
+
+ <p align="center"><strong><img src="images/faultmsg.jpg"
+ alt=""></strong></p>
+
+ <p></p>
+
+ <p>Axis2 Administration is all about configuring Axis2 at the run time and
+ the configuration will be transient. More descriptions are available in the
+ <a href="webadminguide.html" target="_blank">Axis2 Web Administration
+ Guide</a></p>
+</ol>
+<a name="advanced"></a>
+
+<h2>Advanced</h2>
+<a name="source"></a>
+
+<h2>Axis2 Source Distribution</h2>
+<a name="_Toc96698083"></a> By using the Source Distribution, both binary
+files (which can be downloaded as the <a href="#std-bin">Standard Binary
+Distribution</a>) and the axis2.war file (which can be downloaded as the <a
+href="#war1">WAR distribution</a>) can be built using Maven commands.
+
+<p>Required jar files do not come with the distribution and they will also
+have to be built by running the maven command. Before we go any further, it
+is necessary to install <a href="http://maven.apache.org/maven-1.x/"
+target="_blank">Maven</aandsettheEnvironment.Thenextsectionwillguideyouhowtodojustthat.></a></p>
+<a name="env-src"></a>
+
+<h3>Setting Up the Environment and Tools</h3>
+<a name="maven"></a>
+
+<h4>Maven</h4>
+
+<p>The Axis2 build is based on <a href="http://maven.apache.org/maven-1.x/"
+target="_blank">Maven </a>. Hence the only prerequisite to build Axis2 from
+the source distribution is to have Maven installed. Extensive instruction
+guides are available at the Maven site. This guide however contains the
+easiest path for quick environment setting. Advanced users who wish to know
+more about Maven can visit <a
+href="http://maven.apache.org/maven-1.x/start/index.html"
+target="_blank">this site.</a></p>
+<ul>
+ <li>MS Windows</li>
+</ul>
+<ol>
+ <li>Download and run the Windows installer package for Maven.</li>
+ <li>Set the 'Environment Variables' ( create system variable MAVEN_HOME and
+ edit path. eg: "C:\Program Files\Apache Software Foundation\maven-1.0.2";
+ path %MAVEN_HOME%\bin)</li>
+ <li>Make sure that the system variable JAVA_HOME is set to the location of
+ your JDK, eg. C:\Program Files\Java\jdk1.5.0_02</li>
+ <li>Run maven --version to verify that it is correctly installed.</li>
+</ol>
+
+<p align="center"><img alt="clip_image002 (15K)"
+src="images/clip_image002.jpg" height="211" width="477"></p>
+<ul>
+ <li>Unix based OS (Linux etc)</li>
+</ul>
+
+<p>The tar ball or the zip archive is the best option. Once the archive is
+downloaded expand it to a directory of choice and set the environment
+variable MAVEN_HOME and add MAVEN_HOME/bin to the path as well. <a
+href="http://maven.apache.org/download.html#Installation">More
+instructions</a> for installing Maven in Unix based operating systems.</p>
+
+<p>Once Maven is properly installed, you can start building Axis2.</p>
+
+<p><a href="../faq.html#d4">Maven commands that are frequently used</a> in
+Axis2 are listed on the <a href="../faq.html">FAQs</a> page.</p>
+<a name="_Toc96698085"></a>
+
+<h3>Building Binaries and the WAR File Using the Source Distribution</h3>
+
+<p>The Source Distribution is available as a zipped archive. All the
+necessary build scripts are included with the source distribution. Once the
+source archive is expanded into a directory of choice, moving to the
+particular directory and running <code>maven</code> command will build the
+Axis2 jar file.</p>
+
+<p align="center"><img alt="clip_image004 (43K)" src="images/maven.png"><br
+clear="all">
+</p>
+
+<p>Once the command completes, the binaries (jar files in this case) can be
+found at a newly created "target" directory.</p>
+
+<p><strong>Note: For the first Maven build (if the maven repository is not
+built first) it will take a while since the required jars need to be
+downloaded. However, this is a once only process and will not affect any
+successive builds.</strong></p>
+<a name="war"></a>
+
+<p><strong></strong>The default maven build will however build only the Axis2
+jar file. To obtain a <strong>WAR (Web Archive)</strong>, <code>maven
+war</code> command should be issued. This will create a complete WAR with the
+name axis2.war inside the target directory.</p>
+
+<p>Once this build step is complete, the binaries are ready to be
+deployed.</p>
+<a name="_Toc96698086"></a></body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jibx/jibx-codegen-integration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/jibx/jibx-codegen-integration.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jibx/jibx-codegen-integration.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jibx/jibx-codegen-integration.html Fri May 25 01:09:03 2007
@@ -0,0 +1,210 @@
+
+<html>
+
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>JiBX Integration with Axis2</title>
+ <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+</head>
+
+<body>
+
+<h1>JiBX Integration With Axis2</h1>
+
+<p>This document describes using JiBX data binding with Axis2. JiBX differs from
+the other data binding techniques supported by Axis2 in that it allows you to
+use your own Java data objects (as opposed to Java data objects generated from a
+schema definition). JiBX also provides a nicer form of unwrapped Web services
+interface than is supported by the other data binding techniques. On the
+downside, JiBX requires more setup than the other data binding techniques - in
+particular, you need to come up with a set of data classes and a binding
+definition in order to work with JiBX in Axis2.</p>
+
+<p>JiBX support for Axis2 and Web services in general is continuing to evolve.
+This page covers the basics of using JiBX with Axis2 as of the current release.
+Check the <a href="http://www.sosnoski.com/jibx-wiki/space/axis2-jibx">JiBX
+Axis2 Wiki page</a> for updated information about using JiBX with Axis2.</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#wrapped">Wrapped vs. unwrapped</a></li>
+ <li><a href="#java">Starting from Java</a></li>
+ <li><a href="#wsdl">Starting from WSDL</a></li>
+ <li><a href="#codegen">Axis2 JiBX Code Generation</a></li>
+ <li><a href="#coming">Coming Attractions</a></li>
+</ul>
+
+<a name="intro"></a>
+<h2>Introduction</h2>
+
+<p><a href="http://www.jibx.org">JiBX data binding</a> supports fast and
+flexible conversions between plain old Java objects (POJOs) and XML. JiBX
+uses a mapped binding approach that's based on binding definition documents
+you provide. This approach let's you customize the way your Java objects are
+converted to and from XML. You can even define multiple bindings to use the same
+Java objects with different XML representations. These features make JiBX
+especially useful if you're developing a Web service based on existing Java
+code, or when you need to support multiple XML representations for a Web service
+(as when you're using versioned schema definitions).</p>
+
+<p>Axis2 supports using JiBX with your Web services, including generating the
+necessary linkage code for both client and server sides. However, the Axis2
+support for JiBX does not currently include code generation from the schema
+for a Web service - you need to provide your own data classes and JiBX
+binding definition, and you also need to make sure that the binding
+definition matches the XML structures defined for your Web service. The JiBX
+project provides some basic tools to help with code generation from schema,
+binding generation from Java classes, and schema generation from the
+combination of Java classes and a binding definition. In the future, improved
+versions of these tools will be integrated directly into the Axis2 framework
+support, but for now you're on your own with this part of the setup.</p>
+
+<p>You can use JiBX data binding both to expose existing Java code as a
+service, and to build a client for an existing service. This document runs
+through the sequence of steps involved for each of these cases, just to help
+users understand the basic approach to working with JiBX in Axis2. You can
+find full instructions on the standard JiBX parts of this sequence on the <a
+href="http://www.jibx.org">JiBX Web site</a>.</p>
+
+<a name="wrapped"></a>
+<h2>Wrapped vs. unwrapped</h2>
+
+<p>Axis2 support for JiBX currently only works with the document-literal
+(doc/lit) form of Web services definitions. Doc/lit Web services generally use
+particular schema elements as input and output from each operation, and the
+Axis2 support for JiBX assumes this structure (which is also the structure
+required for compatibility with the
+<a href="http://www.ws-i.org/Profiles/BasicProfile-1.1.html">WS-I Basic Profile</a>).
+</p>
+
+<p>A popular subset of doc/lit Web services use a form called "wrapped". Wrapped
+doc/lit Web services define service operations that correspond to method calls,
+using input and output element names based on the method name and embedding the
+actual parameter values for the method call within the input element.
+</p>
+
+<p>When used with Axis2, JiBX supports both general doc/lit and wrapped service
+definitions. Wrapped service definitions can be "unwrapped" during code
+generation to provide a greatly simplified interface. JiBX unwrapping of service
+definitions is not compatible with the unwrapping support for other data binding
+frameworks used with Axis2, but most users will find the JiBX approach easy and
+convenient. See the <a href="./jibx-unwrapped-example.html">JiBX Unwrapped
+Example</a> and the <a href="./jibx-doclit-example.html">JiBX Document/Literal
+Example</a> pages for a detailed comparison of the two forms of service
+interface.
+</p>
+
+<a name="java"></a>
+<h2>Starting from Java</h2>
+
+<p>Here's the sequence of steps for using JiBX with Axis2 to expose existing
+Java code as a Web service:</p>
+<ol>
+ <li>Create a JiBX binding definition for the data being transferred by the
+ Web service (you may be able to use the JiBX binding generator to help with
+ this step).</li>
+ <li>Create a schema that matches the XML defined by your binding (you may
+ be able to use the JiBX schema generator to help with this). If you're using
+ a wrapped form of interface to your service you'll also need to create
+ schema definitions for the wrapper input and output elements used by each
+ operation.</li>
+ <li>Create a WSDL document for your service, with the schema embedded or
+ imported.</li>
+ <li>Generate Axis2 server-side linkage code using WSDL2Java with the WSDL
+ and your binding definition.</li>
+ <li>Run the JiBX binding compiler on your Java classes to add the actual
+ binding code.</li>
+ <li>Include the <i>axis2-jibx.jar</i> in your runtime classpath, along with
+ the <i>jibx-runtime.jar</i>.</li>
+</ol>
+
+<p>If you use a wrapped interface for your Web service you can expose method
+calls in your existing code directly as operations in the service. In this case
+you normally just use your existing data objects with JiBX data binding, and add
+schema definitions for the wrapper elements. See the
+<a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> page for more
+details on how this works.
+</p>
+
+<p>If you use a non-wrapped interface for your Web service you need to define
+classes to hold the data input and output from each operation. In this case
+these holder classes need to be included in the JiBX binding definition. See the
+<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> page for
+more details on this case.
+</p>
+
+<a name="wsdl"></a>
+<h2>Starting from WSDL</h2>
+
+<p>Here's the sequence of steps for using JiBX with Axis2 to implement a
+client for an existing Web service (or the actual service, when you've been
+supplied with the WSDL your service is to implement):</p>
+<ol>
+ <li>Create Java classes for the data being transferred by the Web service,
+ and a JiBX binding definition that maps these classes to the schema
+ defined by the Web service (you may be able to use the JiBX xsd2jibx tool
+ to help with this).</li>
+ <li>Generate Axis2 client linkage code using WSDL2Java with the WSDL and
+ your binding definition.</li>
+ <li>Run the JiBX binding compiler on your Java classes to add the actual
+ binding code.</li>
+ <li>Include the <i>axis2-jibx.jar</i> in your runtime classpath, along with
+ the <i>jibx-runtime.jar</i></li>
+</ol>
+
+<p>As with the starting from Java case, there are some differences in the
+handling depending on whether your service definition fits the wrapped form. See
+the <a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> and
+<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> pages for
+more details.</p>
+
+<a name="codegen"></a>
+<h2>WSDL2Java usage</h2>
+
+<p>To run the WSDL2Java tool for JiBX data binding you need:</p>
+<ol>
+ <li>To specify <i>-d jibx</i> to select JiBX binding.</li>
+ <li>You also generally need an additional parameter, <i>-Ebindingfile {file}</i>
+ (where <i>{file}</i> is the file path to your JiBX binding definition).</li>
+ <li>Finally, you need to have the <i>axis2-jibx-XXXX.jar</i>, the
+ <i>jibx-bind-XXXX.jar</i>, and the <i>jibx-run-XXXX.jar</i> files
+ from your Axis2 distribution included in the WSDL2Java classpath.</li>
+</ol>
+
+<p>If you want to use the unwrapped form of interface you also need to specify
+the <i>-uw</i> option to WSDL2Java. In this case your JiBX binding definition
+must include abstact mappings for all the complex objects which correspond to
+method parameters, and each abstract mapping must specify a <i>type-name</i>
+attribute that matches the schema <i>complexType</i> used in the WSDL. You can
+also use formats in the binding definition to define the handling of schema
+<i>simpleType</i>s. Schema types corresponding to Java primitives and simple
+objects with built-in JiBX conversions are handled automatically, and if all the
+parameter and return values in your wrapped WSDL are of these types you don't
+even need a JiBX binding definition. This is the one case where the
+<i>-Ebindingfile {file}</i> parameter is not needed.</p>
+
+<p>If you're not unwrapping the interface, you must use a JiBX binding
+definition and it must include a concrete mapping for each element used as input
+or output by any operation.</p>
+
+<a name="coming"></a>
+<h2>Coming Attractions</h2>
+
+<p>Work is in-progress on better tools to support generating Java classes and
+corresponding JiBX binding definitions from an input schema, and also for
+generating binding+schema generation from existing code. These features will be
+integrated into the Axis2 JiBX support when they are available. Check the <a
+href="http://www.jibx.org">JiBX project site</a> for updates on JiBX, and the
+<a href="http://www.sosnoski.com/jibx-wiki/space/axis2-jibx">JiBX
+Axis2 Wiki page</a> for updated information about using JiBX with Axis2.</p>
+
+<h2>References</h2>
+
+<p><a href="http://jibx.sourceforge.net/tutorial/binding-tutorial.html">JiBX:
+Bindings Tutorial</a>
+</p>
+
+</body>
+
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jibx/jibx-doclit-example.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/jibx/jibx-doclit-example.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jibx/jibx-doclit-example.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jibx/jibx-doclit-example.html Fri May 25 01:09:03 2007
@@ -0,0 +1,286 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>JiBX general document/literal</title>
+ <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+</head>
+
+<body>
+<h1>JiBX general document/literal</h1>
+
+<p>Code generation for JiBX data binding converts operations defined by a Web
+service to method calls. With general document/literal (doc/lit) Web services
+the generated methods each take a single parameter object and return a single
+result object. Here's a sample doc/lit WSDL (partial) by way of an example:</p>
+
+<pre>
+<wsdl:definitions targetNamespace="http://ws.sosnoski.com/library/wsdl"
+ xmlns:tns="http://ws.sosnoski.com/library/types"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/">
+
+ <wsdl:types>
+
+ <schema elementFormDefault="qualified"
+ targetNamespace="http://ws.sosnoski.com/library/types"
+ xmlns="http://www.w3.org/2001/XMLSchema">
+
+ <element name="getBook">
+ <complexType>
+ <sequence>
+ <element name="isbn" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="getBookResponse">
+ <complexType>
+ <sequence>
+ <element name="book" minOccurs="0" type="tns:BookInformation"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBook">
+ <complexType>
+ <sequence>
+ <element name="type" type="string"/>
+ <element name="isbn" type="string"/>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBookResponse">
+ <complexType>
+ <sequence>
+ <element name="success" type="boolean"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <complexType name="BookInformation">
+ <sequence>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ <attribute name="type" use="required" type="string"/>
+ <attribute name="isbn" use="required" type="string"/>
+ </complexType>
+
+ </schema>
+
+ </wsdl:types>
+
+ <wsdl:message name="getBookRequest">
+ <wsdl:part element="wns:getBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="getBookResponse">
+ <wsdl:part element="wns:getBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookRequest">
+ <wsdl:part element="wns:addBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookResponse">
+ <wsdl:part element="wns:addBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:portType name="Library">
+
+ <wsdl:operation name="getBook">
+ <wsdl:input message="wns:getBookRequest" name="getBookRequest"/>
+ <wsdl:output message="wns:getBookResponse" name="getBookResponse"/>
+ </wsdl:operation>
+
+ <wsdl:operation name="addBook">
+ <wsdl:input message="wns:addBookRequest" name="addBookRequest"/>
+ <wsdl:output message="wns:addBookResponse" name="addBookResponse"/>
+ </wsdl:operation>
+
+ </wsdl:portType>
+ ...
+</wsdl:definitions>
+</pre>
+
+<p>This WSDL defines a service with just two operations: <b>getBook</b> and
+<b>addBook</b>. The <b>getBook</b> operation takes a <i>getBook</i> element as
+input, and returns a <i>getBookResponse</i> element as output, while
+<b>addBook</b> takes an <i>addBook</i> element as input and returns an
+<i>addBookResponse</i> as output. Here's the body of the client interface
+generated by the standard JiBX code generation:</p>
+
+<pre>
+ public interface LibraryJibxUnwrapped {
+
+
+ /**
+ * Auto generated method signatures
+ * @param addBook
+ */
+ public com.sosnoski.ws.library.jibx.wrappers.AddBookResponse addBook(
+ com.sosnoski.ws.library.jibx.wrappers.AddBookRequest addBook) throws java.rmi.RemoteException
+
+
+ ;
+
+
+ /**
+ * Auto generated method signatures
+ * @param getBook
+ */
+ public com.sosnoski.ws.library.jibx.wrappers.GetBookResponse getBook(
+ com.sosnoski.ws.library.jibx.wrappers.GetBookRequest getBook) throws java.rmi.RemoteException
+
+
+ ;
+
+
+
+ //
+ }
+</pre>
+
+<p>You can see that the JiBX code generation converted the operations into
+simple method call interfaces using objects corresponding to the input and
+output elements of the operation (see
+<a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> for the
+interface generated when unwrapping is instead used). The server-side interface
+is the same.</p>
+
+<p>You need to supply an appropriate JiBX binding definition for use in code
+generation (using the <i>-Ebindingfile {file}</i> parameter for WSDL2Java - see
+<a href="./jibx-codegen-integration.html#codegen">JiBX Codegen Integration -
+WSDL2Java usage</a> for more details). This must define concrete <i>mappings</i>
+for each element used as the input or output of an operation. The JiBX code
+generation extension matches the element names to the binding in order to
+determine the corresponding class to use in generated code.</p>
+
+<p>For example, here's a binding definition that matches the above WSDL:</p>
+
+<pre>
+<binding add-constructors="true">
+
+ <namespace uri="http://ws.sosnoski.com/library/types" default="elements"/>
+
+ <mapping name="getBook"
+ class="com.sosnoski.ws.library.jibx.wrappers.GetBookRequest">
+ <value name="isbn" field="m_isbn"/>
+ </mapping>
+
+ <mapping name="getBookResponse"
+ class="com.sosnoski.ws.library.jibx.wrappers.GetBookResponse">
+ <structure name="book" field="m_book"/>
+ </mapping>
+
+ <mapping name="addBook"
+ class="com.sosnoski.ws.library.jibx.wrappers.AddBookRequest">
+ <structure field="m_book">
+ <value name="type" field="m_type"/>
+ <value name="isbn" field="m_isbn"/>
+ <collection field="m_authors">
+ <value name="author" type="java.lang.String"/>
+ </collection>
+ <value name="title" field="m_title"/>
+ </structure>
+ </mapping>
+
+ <mapping name="addBookResponse"
+ class="com.sosnoski.ws.library.jibx.wrappers.AddBookResponse"/>
+
+ <mapping abstract="true" class="com.sosnoski.ws.library.jibx.beans.Book">
+ <value name="type" style="attribute" field="m_type"/>
+ <value name="isbn" style="attribute" field="m_isbn"/>
+ <collection field="m_authors">
+ <value name="author" type="java.lang.String"/>
+ </collection>
+ <value name="title" field="m_title"/>
+ </mapping>
+
+</binding>
+</pre>
+
+<p>And here are the actual data object classes:</p>
+
+<pre>
+package com.sosnoski.ws.library.jibx.wrappers;
+
+import com.sosnoski.ws.library.jibx.beans.Book;
+
+public class AddBookRequest
+{
+ private Book m_book;
+
+ public AddBookRequest(Book book) {
+ m_book = book;
+ }
+
+ public Book getBook() {
+ return m_book;
+ }
+}
+
+public class AddBookResponse
+{
+}
+
+public class GetBookRequest
+{
+ private String m_isbn;
+
+ public GetBookRequest(String isbn) {
+ m_isbn = isbn;
+ }
+
+ public String getIsbn() {
+ return m_isbn;
+ }
+}
+
+public class GetBookResponse
+{
+ private Book m_book;
+
+ public GetBookResponse(Book book) {
+ m_book = book;
+ }
+
+ public Book getBook() {
+ return m_book;
+ }
+}
+
+package com.sosnoski.ws.library.jibx.beans;
+
+public class Book
+{
+ private String m_type;
+ private String m_isbn;
+ private String m_title;
+ private String[] m_authors;
+
+ public Book() {}
+
+ public String getType() {
+ return m_type;
+ }
+
+ public String getIsbn() {
+ return m_isbn;
+ }
+
+ public String getTitle() {
+ return m_title;
+ }
+
+ public String[] getAuthors() {
+ return m_authors;
+ }
+}
+</pre>
+
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jibx/jibx-unwrapped-example.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/jibx/jibx-unwrapped-example.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jibx/jibx-unwrapped-example.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jibx/jibx-unwrapped-example.html Fri May 25 01:09:03 2007
@@ -0,0 +1,252 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>JiBX unwrapped document/literal</title>
+ <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+</head>
+
+<body>
+<h1>JiBX Unwrapped document/literal</h1>
+
+<p>Code generation for JiBX data binding converts operations defined by a Web
+service to method calls. In the most general case of document/literal
+(doc/lit) Web services the generated methods each take a single parameter
+object and return a single result object. This type of interface can be
+painful for developers because it adds both a layer of indirection and
+potentially a large number of extra classes (one input and one output class
+for each generated method).</p>
+
+<p>Fortunately, there's an alternative way of generating methods that gives a
+much more usable API for many Web services. This alternative is called
+<i>unwrapping</i>, and the service definitions that it applies to are called
+<i>wrapped</i> definitions. The key difference that qualifies a service
+definition as wrapped is the structure of the input and output elements used
+for operations.</p>
+
+<p>Here's a sample wrapped WSDL (partial) by way of an example:</p>
+<pre><wsdl:definitions targetNamespace="http://ws.sosnoski.com/library/wsdl"
+ xmlns:tns="http://ws.sosnoski.com/library/types"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/">
+
+ <wsdl:types>
+
+ <schema elementFormDefault="qualified"
+ targetNamespace="http://ws.sosnoski.com/library/types"
+ xmlns="http://www.w3.org/2001/XMLSchema">
+
+ <element name="getBook">
+ <complexType>
+ <sequence>
+ <element name="isbn" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="getBookResponse">
+ <complexType>
+ <sequence>
+ <element name="book" minOccurs="0" type="tns:BookInformation"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBook">
+ <complexType>
+ <sequence>
+ <element name="type" type="string"/>
+ <element name="isbn" type="string"/>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="addBookResponse">
+ <complexType>
+ <sequence>
+ <element name="success" type="boolean"/>
+ </sequence>
+ </complexType>
+ </element>
+
+ <complexType name="BookInformation">
+ <sequence>
+ <element name="author" minOccurs="0" maxOccurs="unbounded" type="string"/>
+ <element name="title" type="string"/>
+ </sequence>
+ <attribute name="type" use="required" type="string"/>
+ <attribute name="isbn" use="required" type="string"/>
+ </complexType>
+
+ </schema>
+
+ </wsdl:types>
+
+ <wsdl:message name="getBookRequest">
+ <wsdl:part element="wns:getBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="getBookResponse">
+ <wsdl:part element="wns:getBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookRequest">
+ <wsdl:part element="wns:addBook" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:message name="addBookResponse">
+ <wsdl:part element="wns:addBookResponse" name="parameters"/>
+ </wsdl:message>
+
+ <wsdl:portType name="Library">
+
+ <wsdl:operation name="getBook">
+ <wsdl:input message="wns:getBookRequest" name="getBookRequest"/>
+ <wsdl:output message="wns:getBookResponse" name="getBookResponse"/>
+ </wsdl:operation>
+
+ <wsdl:operation name="addBook">
+ <wsdl:input message="wns:addBookRequest" name="addBookRequest"/>
+ <wsdl:output message="wns:addBookResponse" name="addBookResponse"/>
+ </wsdl:operation>
+
+ </wsdl:portType>
+ ...
+</wsdl:definitions></pre>
+
+<p>This WSDL defines a service with just two operations: <b>getBook</b> and
+<b>addBook</b>. The <b>getBook</b> operation takes a <i>getBook</i> element
+as input, and returns a <i>getBookResponse</i> element as output, while
+<b>addBook</b> takes an <i>addBook</i> element as input and returns an
+<i>addBookResponse</i> as output. Each of these input and output elements in
+turn consists of a sequence of child elements, with some of the child
+elements defined directly using standard schema types and others referencing
+user-defined schema types.</p>
+
+<p>As I said up front, this WSDL qualifies for unwrapped handling using JiBX.
+Here's the body of the client interface generated when using unwrapping (the
+<i>-uw</i> option for WSDL2Java):</p>
+<pre> public interface LibraryJibxUnwrapped {
+
+
+ /**
+ * Auto generated method signatures
+ * @param type* @param isbn* @param author* @param title
+ */
+ public boolean addBook(
+ java.lang.String type,java.lang.String isbn,java.lang.String[] author,java.lang.String title) throws java.rmi.RemoteException
+
+
+ ;
+
+
+ /**
+ * Auto generated method signatures
+ * @param isbn
+ */
+ public com.sosnoski.ws.library.jibx.beans.Book getBook(
+ java.lang.String isbn) throws java.rmi.RemoteException
+
+
+ ;
+
+
+
+ //
+ }</pre>
+
+<p>You can see that the JiBX code generation converted the operations into
+simple method call interfaces without introducing any extraneous objects (see
+<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> for
+the interface generated when unwrapping is not used). The server-side
+interface is the same.</p>
+
+<p>The key points that allow unwrapped handling with JiBX are:</p>
+<ol>
+ <li>Each operation either accepts no input, or the input consists of a
+ single element.</li>
+ <li>Each input element is defined as a schema <i>complexType</i> consisting
+ of a <i>sequence</i> of any number of child elements.</li>
+ <li>Each operation either generates no output, or the output consists of a
+ single element.</li>
+ <li>Each output element is defined as a schema <i>complexType</i>
+ consisting of a <i>sequence</i> that's either empty or contains a single
+ child element.</li>
+ <li>The child elements of both inputs and outputs are defined using
+ <i>type</i> references, rather than an embedded type definitions.</li>
+</ol>
+
+<p>You also need to supply an appropriate JiBX binding definition (using the
+<i>-Ebindingfile {file}</i> parameter for WSDL2Java - see <a
+href="./jibx-codegen-integration.html#codegen">JiBX Codegen Integration -
+WSDL2Java usage</a> for more details). This must define abstract
+<i>mapping</i>s for the <i>complexType</i>s referenced by child elements of
+the inputs and outputs, with a <i>type-name</i> attribute matching the schema
+<i>complexType</i> name. If the child elements reference schema
+<i>simpleType</i> definitions the binding must also define a <i>format</i>s
+for each <i>simpleType</i>, with a <i>label</i> attribute matching the schema
+<i>simpleType</i> name. The binding definition must also specify the
+<i>force-classes='true'</i> attribute on the <i>binding</i> element.</p>
+
+<p>For example, here's a binding definition that matches the above WSDL:</p>
+<pre><binding force-classes="true" xmlns:tns="http://ws.sosnoski.com/library/types">
+
+ <namespace uri="http://ws.sosnoski.com/library/types" default="elements"/>
+
+ <mapping abstract="true" class="com.sosnoski.ws.library.jibx.beans.Book"
+ type-name="tns:BookInformation">
+ <value name="type" style="attribute" field="m_type"/>
+ <value name="isbn" style="attribute" field="m_isbn"/>
+ <collection field="m_authors">
+ <value name="author"/>
+ </collection>
+ <value name="title" field="m_title"/>
+ </mapping>
+
+</binding></pre>
+
+<p>And here's the actual <code>com.sosnoski.ws.library.jibx.beans.Book</code>
+class:</p>
+<pre>package com.sosnoski.ws.library.jibx.beans;
+
+public class Book
+{
+ private String m_type;
+ private String m_isbn;
+ private String m_title;
+ private String[] m_authors;
+
+ public Book() {}
+
+ public String getType() {
+ return m_type;
+ }
+
+ public String getIsbn() {
+ return m_isbn;
+ }
+
+ public String getTitle() {
+ return m_title;
+ }
+
+ public String[] getAuthors() {
+ return m_authors;
+ }
+}</pre>
+
+<p>The JiBX code generation for Axis2 currently requires that classes
+coresponding to unwrapped child elements (such as
+<code>com.sosnoski.ws.library.jibx.beans.Book</code>, in this case) provide
+public default (no-argument) constructors.</p>
+
+<p>JiBX handling allows the child elements of both inputs and outputs to be
+optional (with <i>nillable='true'</i>, <i>minOccurs='0'</i>, or both),
+providing the binding converts these child elements to object types rather
+than primitive types. It also allows repeated child elements (with
+<i>minOccurs='unbounded'</i>, or any value of <i>minOccurs</i> greater than
+one), representing the repeated elements as arrays of the corresponding
+object or primitive types.</p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jms-transport.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/jms-transport.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jms-transport.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/jms-transport.html Fri May 25 01:09:03 2007
@@ -0,0 +1,200 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>JMS Transport</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<body lang="en">
+<a name="configTransport"></a>
+
+<h1>JMS Transport</h1>
+
+<p>This document is all about the JMS (Java Messaging Service) Transport
+support in Apache Axis2,, and how it should be configured.</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>Contents</h2>
+<ul>
+ <li><a href="#CommonsHTTPTransportSender">Overview</a></li>
+ <li><a href="#timeout_config">Configuration</a></li>
+ <li><a href="#writing_services">Writing Services to Use the JMS
+ Transport</a></li>
+</ul>
+<a name="CommonsHTTPTransportSender"></a>
+
+<h2>Overview</h2>
+
+<p>A new Java Messaging Service (JMS) transport implementation has been added
+to Axis2 to overcome some drawbacks of the previous JMS implementation. One
+of the enhancements provided with this new implementation is the ability to
+<strong>assign custom JMS destination names or existing JMS destinations to
+Axis2 services being deployed</strong>.</p>
+<a name="timeout_config"></a>
+
+<h2>Configuration</h2>
+
+<p>To use the JMS transport, the axis2.xml configuration must be setup as
+follows, in order to configure the JMSListener and the JMS Sender</p>
+<pre><strong>axis2.xml</strong>
+ <transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener">
+ <parameter name="default" locked="false">
+ <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter>
+ </parameter>
+ </transportReceiver>
+
+ <transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"/></pre>
+
+<p>The JMS transport receiver configuration allows you to define the default
+connection factory (named as "default" ~ JMSConstants.DEFAULT_CONFAC_NAME)
+for use by Axis2 services using the JMS transport. This connection factory
+will be used by any service that does not explicitly specify a connection
+factory name in its services.xml file. The configuration required to
+associate a (local) Axis2 connection factory to an actual implementation must
+be provided as shown above. To specify the JNDI URL, the initial context
+factory class and the JNDI name of the actual JMS connection factory is used.
+You can also specify the parameters "java.naming.security.principal" and
+"java.naming.security.credentials", if required, to access the actual
+connection factory. The example shown above uses an ActiveMQ JMS
+implementation.</p>
+<pre><strong>axis2.xml</strong>
+ <parameter name="myTopicConnectionFactory" locked="false"></pre>
+<pre> <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter></pre>
+<pre> <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter></pre>
+<pre> <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">TopicConnectionFactory</parameter></pre>
+<pre> </parameter></pre>
+
+<p>If it is required or applicable, you are free to define additional (local)
+connection factories to Axis2 as shown above, which your services can use.
+For a service to specify that such a connection factory should be used, its
+services.xml may specify the following configuration parameter:</p>
+<pre>services.xml
+ <parameter name="transport.jms.ConnectionFactory" locked="true">myTopicConnectionFactory</parameter></pre>
+
+<p><strong>Note:</strong> Depending on your JMS implementation, you will need
+to make available all the required libraries for your Axis2 instance. This
+example assumes you are using an ActiveMQ instance. To run the given code
+samples, it is required to make the following JAR files available:
+activeio-core-3.0-beta1.jar, activemq-core-4.0-RC2.jar,
+geronimo-j2ee-management_1.0_spec-1.0.jar at a minimum. It also requires you
+to start ActiveMQ separately from Axis2, and then provide the appropriate
+configuration settings (e.g. URL) to Axis2.</p>
+
+<p>During initialization, the JMS Listener creates a dedicated JMS message
+processor for each connection factory defined, and utilizes a shared thread
+pool to process the received messages.</p>
+
+<p>A service on an Axis2 instance is deployed on all the started transports
+by default, unless a list of transports is specified in its services.xml
+file. Hence, if a service must only be deployed on JMS, you should specify it
+on the services.xml as follows:</p>
+<pre> <transports>
+ <transport>jms</transport>
+ </transports></pre>
+
+<p>If the services.xml does not provide an explicit JMS destination name, it
+is assumed that the service will listen for messages on a JMS
+<strong>Queue</strong> by the same name as the <strong>name of the
+service</strong>. If an explicit connection factory definition name has not
+been specified, it is assumed that the "default" connection factory
+definition configured within the transport receiver is used. To provide a
+custom JMS destination name and connection factory, the services.xml file
+provides the following optional parameters.</p>
+<pre> <parameter name="transport.jms.ConnectionFactory" locked="true">myTopicConnectionFactory</parameter>
+ <parameter name="transport.jms.Destination" locked="true">dynamicTopics/something.TestTopic</parameter></pre>
+<a name="writing_services"></a>
+
+<h2>Writing Services to Use the JMS Transport</h2>
+
+<p>This section assumes that you are already familiar with <a
+href="xmlbased-server.html">writing service implementations</a> for Axis2,
+and provides information on how to write your own service implementations,
+which are exposed over JMS.</p>
+
+<p><strong>Echo - Service implementation and services.xml</strong></p>
+
+<p>This sample demonstrates a very simple service which is to be exposed over
+JMS. It does not specify a custom connection factory name, and hence uses the
+default value as specified in the JMS transport listener configuration. It
+also does not specify a custom destination name, and hence would listen to
+messages over a JMS Queue named "Echo" (which is the name of the service).
+This service will be exposed over all defined Axis2 transports, and the
+resulting URL for the service over JMS will be:</p>
+
+<p>jms:/echo?transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&java.naming.provider.url=tcp://localhost:61616</p>
+<pre><strong>Echo.java</strong></pre>
+<pre> public class Echo {</pre>
+<pre> public String echoString(String in) {</pre>
+<pre> return in;</pre>
+<pre> }</pre>
+<pre> public String echoString1(String in) {</pre>
+<pre> return "echoString1 " + in;</pre>
+<pre> }</pre>
+<pre> public String echoString2(String in) {</pre>
+<pre> return "echoString2 " + in;</pre>
+<pre> }</pre>
+<pre> }</pre>
+<pre></pre>
+<pre><strong>services.xml</strong></pre>
+<pre> <service name="echo"></pre>
+<pre> <description>Echo Service</description></pre>
+<pre> <messageReceivers></pre>
+<pre> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"</pre>
+<pre> class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/></pre>
+<pre> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"</pre>
+<pre> class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/></pre>
+<pre> </messageReceivers></pre>
+<pre> <parameter name="ServiceClass" locked="true">Echo</parameter></pre>
+<pre></service></pre>
+
+<p></p>
+
+<p><strong>Echo2 - Service implementation and services.xml</strong></p>
+
+<p>This example shows a simple service which specifies that it should only be
+exposed over the JMS transport, and that the custom connection factory named
+"myTopcConnectionFactory" should be used to listen for requests at the JMS
+destination named "dynamicTopics/something.TestTopic". The JMS URL to access
+this service is:</p>
+
+<p>jms:/dynamicTopics/something.TestTopic?transport.jms.ConnectionFactoryJNDIName=TopicConnectionFactory&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&java.naming.provider.url=tcp://localhost:61616&java.naming.security.principal=system&java.naming.security.credentials=manager</p>
+<pre><strong>Echo2.java</strong></pre>
+<pre> public class Echo2 {</pre>
+<pre> public String echoString(String in) {</pre>
+<pre> return in;</pre>
+<pre> }</pre>
+<pre> }</pre>
+<pre></pre>
+<pre><strong>services.xml</strong></pre>
+<pre> <service name="echo"></pre>
+<pre> <transports></pre>
+<pre> <transport>jms</transport></pre>
+<pre> </transports></pre>
+<pre> <description>Echo2 Service</description></pre>
+<pre> <messageReceivers></pre>
+<pre> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"</pre>
+<pre> class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/></pre>
+<pre> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"</pre>
+<pre> class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/></pre>
+<pre> </messageReceivers></pre>
+<pre> <parameter name="ServiceClass" locked="true">Echo2</parameter></pre>
+<pre> <parameter name="transport.jms.ConnectionFactory" locked="true">myTopicConnectionFactory</parameter></pre>
+<pre> <parameter name="transport.jms.Destination" locked="true">dynamicTopics/something.TestTopic</parameter></pre>
+<pre> </service></pre>
+<pre> </pre>
+
+<h2>Starting up the Axis2 JMS transport</h2>
+<p>The Axis2 standalone binary distribution ships with an Axis2 Server, which
+starts up all the transports that are configured as per the axis2.xml. Hence,
+configure the JMS transport in your axis2.xml, and use the axis2server.bat or
+the axis2server.sh to start the JMS transport.</p></body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/json_support.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/json_support.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/json_support.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/json_support.html Fri May 25 01:09:03 2007
@@ -0,0 +1,218 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+ <title></title>
+ <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">
+ <!--
+@page { size: 8.5in 11in; margin: 0.79in }
+P { margin-bottom: 0.08in }
+-->
+
+
+
+
+
+
+
+
+ </style>
+</head>
+
+<body>
+<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 to it should be used. Document also provides details on test
+cases and samples.</p>
+
+<h3>What is JSON?</h3>
+
+<p><a href="http://www.json.org/">JSON</a> (Java Script Object Notation) is
+another data exchangeable format like XML, but it is more lightweight and
+easily readable. It is based on a subset of 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"><root><test>json
+object</test></root> == {ârootâ:{âtestâ:âjson
+objectâ}}</font></font></p>
+
+<p>When it comes to converting XML to JSON and vice versa, there are two
+major conventions, one named "<a
+href="http://badgerfish.ning.com/">Badgerfish</a>" 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"><xsl:root
+xmlns:xsl="http://foo.com"><data>my json
+string</data></xsl:root></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">{"xsl:root":{"@xmlns":{"xsl":"http://foo.com"},"data":{"$":"my json
+string"}}}</font></p>
+
+<p><b>Using âMappedâ</b></p>
+
+<p>If we use the namespace mapping as http://foo.com -> foo</p>
+
+<p><font size="2">{"foo.root":{"data":"my json string"}}</font></p>
+
+<p>JSON support implementation is a new feature in <a
+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 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 not 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
+easily by machines than in the case of XML. </p>
+
+<p>For more details of this implementation architecture, refer to the article
+<a href="http://wso2.org/library/768">"JSON Support for Apache Axis2"</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
+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> <messageFormatters>
+ <messageFormatter contentType="application/json"
+ class="org.apache.axis2.json.JSONMessageFormatter"/>
+ <!-- more message formatters -->
+ </messageFormatters>
+
+ <messageBuilders>
+ <messageBuilder contentType="application/json"
+ class="org.apache.axis2.json.JSONOMBuilder"/>
+ <!-- more message builders -->
+ </messageBuilders></pre>
+
+<p>e.g.2: If you are using the âBadgerfishâ convention with the content
+type âtext/javascriptâ</p>
+<pre> <messageFormatters>
+ <messageFormatter contentType="text/javascript"
+ class="org.apache.axis2.json.JSONBadgerfishMessageFormatter"/>
+ <!-- more message formatters -->
+ </messageFormatters>
+
+ <messageBuilders>
+ <messageBuilder contentType="text/javascript"
+ class="org.apache.axis2.json.JSONBadgerfishOMBuilder"/>
+ <!-- more message builders -->
+ </messageBuilders></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("test-resources/axis2.xml");
+ 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 method is used as the default to send JSON messages through
+Axis2, if the HTTP method is not 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
+âMappedâ 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 are good examples of using JSON support for Axis2.
+You can understand the architecture of JSON support implementation in Axis2
+by looking at these samples.</p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/mail-configuration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/mail-configuration.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/mail-configuration.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/mail-configuration.html Fri May 25 01:09:03 2007
@@ -0,0 +1,212 @@
+<!-- saved from url=(0022)http://internet.e-mail -->
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Mail transport</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<body lang="en">
+<h1>Mail Transport Configuration</h1>
+
+<p>This document provides guidelines on how to configure Axis2 in order to
+get the mail transport working.</p>
+
+<p><i>Send your feedback or questions to: <a
+href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a></i>.
+(Subscription details are available on the <a
+href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly
+prefix subject with [Axis2]. </p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#sender">Transport Sender</a></li>
+ <li><a href="#receiver">Transport Receiver</a></li>
+ <li><a href="#server">Using Mail Transport in the Server Side</a></li>
+ <li><a href="#james">Configure James as SMTP and POP Server</a></li>
+ <li><a href="#included">Using the Included Mail Server</a></li>
+</ul>
+<a name="intro"></a>
+
+<h2>Introduction</h2>
+
+<p>The inner workings of the mail transport has been divided into two parts:
+the transport sender for SMTP and the transport listener for POP3. The
+transport listener will listen to a particular email address periodically.
+When an email comes in, it will be tunneled into an Axis2 engine. On the
+other hand, the mail transport sender sends emails to a mail server to a
+particular email address.</p>
+
+<p>Mail transport can be used against a generic mail server or it can be used
+like a mailet. The simple mailet provided with Axis2 directs any message that
+comes in to a particular address into the Axis engine. The engine will
+process the message and use the Transport sender to send the reply.</p>
+
+<p>The mail transports have been written with the use of Sun's JavaMail and
+Activation jars. They should be available in your classpath to get the mail
+transport to work.</p>
+<a name="sender"></a>
+
+<h2>Transport Sender</h2>
+
+<p>You need to have a mail account to activate the mail functionality. This
+can either be a generic mail server or you can start up a <a
+href="http://james.apache.org/">James mail server</a>.</p>
+
+<p>JavaMail sets its properties to a Properties object. In Axis2, this has
+been mapped to a Parameter object. Mapping has been done as follows,</p>
+<ul>
+ <li>Every JavaMail property can be set to @name of the <parameter/>.
+ Thus, an SSL connection is mapped the way it is done in JavaMail</li>
+ <li>Few properties, such as password,, are set to @name with the prefix
+ "transport"</li>
+</ul>
+
+<p>For a non-SSL connection, as an example, the mail transport sender can be
+activated by adding the following entry to the axis2.xml file.</p>
+<source><pre> <transportSender name="mail" class="org.apache.axis2.transport.mail.MailTransportSender">
+ <parameter name="mail.smtp.host" locked="false">localhost</parameter>
+ <parameter name="mail.smtp.user" locked="false">mary</parameter>
+ <parameter name="transport.mail.smtp.password" locked="false">mary</parameter>
+ </transportSender>
+ </pre>
+</source>
+<p>At runtime, tuning a client to set the mail transport is as easy as
+follows,</p>
+<source><pre>...
+
+Options options = new Options();
+HttpTransportProperties.MailProperties mailProps
+ = new HttpTransportProperties.MailProperties();
+mailProps.addProperty("mail.smtp.host","localhost");
+mailProps.addProperty("mail.smtp.user","mary");
+mailProps.setPassword("mary");
+
+options.setProperty(HTTPConstants.MAIL_SMTP,mailProps);
+
+...</pre>
+</source>Thus, a user who is familiar with setting up an SSL connection,
+should easily do it with the MailProperties object. For example, tuning the
+sender to talk to the gmail account. This configuration should also be done
+with <parameter/> in axis2.xml. <source>
+<pre>...
+HttpTransportProperties.MailProperties props =
+ new HttpTransportProperties.MailProperties();
+ props.put("mail.smtp.user", "address@gmail.com");
+ props.put("mail.smtp.host", "smtp.gmail.com");
+ props.put("mail.smtp.port", "465");
+ props.put("mail.smtp.starttls.enable","true");
+ props.put("mail.smtp.auth", "true");
+ //props.put("mail.smtp.debug", "true"); // if the user wants
+ props.put("mail.smtp.socketFactory.port", "465");
+ props.put("mail.smtp.socketFactory.class", "javax.net.ssl.SSLSocketFactory");
+ props.put("mail.smtp.socketFactory.fallback", "false");
+ props.setPassword("password");
+
+...</pre>
+</source><a name="receiver"></a>
+
+<h2>Transport Receiver</h2>
+
+<p>For a non-SSL connection, as an example, the mail Listener can be
+activated by adding the following entry to the axis2.xml file.</p>
+<source><pre> <transportReceiver name="mail" class="org.apache.axis2.transport.mail.SimpleMailListener">
+ <parameter name="mail.pop3.host" locked="false">localhost</parameter>
+ <parameter name="mail.pop3.user" locked="false">bob</parameter>
+ <parameter name="transport.mail.pop3.password" locked="false">bob</parameter>
+ <parameter name="transport.mail.replyToAddress" locked="false">bob@localhost</parameter>
+ </transportReceiver>
+ </pre>
+</source>
+<p><i>Note:</i> The @name="transport.mail.replyToAddress" is an important
+parameter. It supplies the Endpoint reference to the listener.</p>
+
+<p>For an advanced user, this can be set to an SSL connection. For example,
+let's use this transport listener to pop from a specified gmail account.</p>
+<source><pre><transportReceiver name="mail" class="org.apache.axis2.transport.mail.SimpleMailListener">
+ <parameter name="mail.pop3.host" locked="false">pop.gmail.com</parameter>
+ <parameter name="mail.pop3.user" locked="false">address@gmail.com</parameter>
+ <parameter name="mail.pop3.socketFactory.class" locked="false">javax.net.ssl.SSLSocketFactory</parameter>
+ <parameter name="mail.pop3.socketFactory.fallback" locked="false">false</parameter>
+ <parameter name="mail.pop3.port" locked="false">995</parameter>
+ <parameter name="mail.pop3.socketFactory.port" locked="false">995</parameter>
+ <parameter name="transport.mail.pop3.password" locked="false">password</parameter>
+ <parameter name="transport.mail.replyToAddress" locked="false">address@gmail.com</parameter>
+</transportReceiver></pre>
+</source><a name="server"></a>
+
+<h2>Using Mail Transport in the Server Side</h2>
+
+<p>If the Mail Listener is to be started as a standalone mail listener, it
+can be done with the following command with the all the Axis2 jars and the
+mail dependency jars in the classpath.</p>
+<source><pre>java org.apache.axis2.transport.mail.SimpleMailListener repository-directory</pre>
+</source><a name="client"></a>
+
+<h2>Using Mail Transport in the Client Side</h2>
+
+<p>The following code segment shows how to send a one-way (IN-Only MEP) SOAP
+message using the mail transport. This needs the Transport Sender to be
+configured.</p>
+<source><pre>
+ OMElement payload = ....
+ String targetEPR = "mail:axis2@localhost/axis2/services/Foo";
+
+ ConfigurationContext configurationContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(repo,
+ axis2XML);
+
+ ServiceClient servicClient = new ServiceClient(configurationContext, null);
+
+ Options options = new Options();
+ options.setTo(targetEPR);
+ options.setTransportInProtocol(Constants.TRANSPORT_MAIL);
+
+ servicClient.setOptions(options);
+
+ servicClient.sendRobust(payload);</pre>
+</source><a name="james"></a>
+
+<h2>Configure James as SMTP and POP Server</h2>
+
+<p>Download <a href="http://james.apache.org/">Apache James</a> and start
+James. Connect to the James server via Telnet as administrator James using
+the following code:</p>
+<source><pre>$telnet 127.0.0.1 4555
+Trying 127.0.0.1...
+Connected to localhost.localdomain (127.0.0.1).
+Escape character is '^]'.
+JAMES Remote Administration Tool 2.2.0
+Please enter your login and password
+Login id:
+root
+Password:
+root
+Welcome root. HELP for a list of commands</pre>
+</source>
+<p>Add users to James</p>
+<source><pre>adduser axis2-server axis2
+User axis2-server added
+adduser axis2-client axis2
+User axis2-client added
+Connection closed by foreign host.</pre>
+</source>
+<p>Now James is up and running with the accounts.</p>
+<a name="included"></a>
+
+<h2>Using the Included Mail Server</h2>
+
+<p>The inbuilt mail server can be started from the command line using the
+following command when all the necessary JARS are in the class path.</p>
+<source><pre>java org.apache.axis2.transport.mail.server.MailServer</pre>
+</source>
+<p>The server itself does not need any configuration or tinkering to work. A
+ConfigurationContext and the ports to operate on are the only details needed.
+The server will store the mails in the memory against the recipient till the
+recipient pops it from the server. To facilitate the use in Linux
+environments as a non root user, the POP and SMTP ports used by default
+configuration/test cases are, 1024, 25 and 1024, 110 respectively.</p>
+<hr>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org