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 [3/14] - in /webservices/axis2/site/1_3: ./ adb/ jibx/
src/
Added: webservices/axis2/site/1_3/adv-userguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/adv-userguide.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/adv-userguide.html (added)
+++ webservices/axis2/site/1_3/adv-userguide.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,790 @@
+<!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>
+ Axis2 Advanced User's Guide
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</head>
+
+
+<a name="_Toc96697849"></a>
+
+<h1 align="center">Apache Axis2 Advanced User's Guide</h1>
+
+<p>This guide will help you get started with Axis2, the next generation of
+Apache Axis! It gives a detailed description on how to write Web services and
+Web service clients using Axis2, how to write custom modules, and how to use
+them with a Web service. Advanced topics and samples that are shipped with
+the binary distribution of Axis2 are also discussed.</p>
+<a name="Introduction"></a>
+
+<h2>Introduction</h2>
+
+<p>This user guide is written based on the <a href="../download/1_3/download.html/#std-bin">Axis2 Standard Binary
+Distribution</a>. The Standard Binary Distribution can be directly <a href="../download/1_3/download.html/#std-bin">downloaded</a> or built using
+the <a href="../download/1_3/download.html#src">Source Distribution</a>. If
+you choose the latter, then the <a href="installationguide.html">Installation
+Guide</a> will instruct you on how to build Axis2 Standard Binary
+Distribution using the source.</p>
+
+<p>Please note that Axis2 is an open-source effort. If you feel the code
+could use some new features or fixes, please get involved and lend us a hand!
+The Axis developer community welcomes your participation.</p>
+
+<p>Let us know what you think! Send your feedback to "<a href="mailto:axis-user@ws.apache.org?subject=[Axis2]">axis-user@ws.apache.org</a>".
+(Subscription details are available on the <a href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly
+prefix the subject of the mail with [Axis2].</p>
+
+<h2>Getting Started</h2>
+
+<p>The first two sections of the user guide explain how to write and deploy a
+new Web Service using Axis2, and how to write a Web Service client using
+Axis2. The next section - <a href="#config"> Configuring Axis2</a> - provides
+an introduction to important configuration options in Axis2. The final
+section - <a href="#advanced">Advanced Topics</a> - provides references to
+other features.</p>
+
+<p>In this (first) section, we will learn how to write and deploy Web
+services using Axis2. All the samples mentioned in this guide are located in
+the <b>"samples/userguide/src"</b> directory of <a href="../download/1_3/download.html/#std-bin">Axis2 standard binary
+distribution</a>.</p>
+
+<p>Please deploy axis2.war in your servlet container and ensure that it works
+fine. The <a href="installationguide.html">Installation
+Guide</a> gives you step-by-step instructions on just how to build axis2.war
+and deploy it in your servlet container.</p>
+<a name="ws_codegen"></a><a name="Web_Services_Using_Axis2"></a>
+
+<h2>Creating a New Web Service</h2>
+
+<p>If you are interested in how to write a Web Service client using Axis2, it
+is described under <a href="#client">Writing a Web Service Client</a>. Axis2
+provides two ways to create new Web Services, using <strong>code
+generation</strong> and using <strong>XML based primary APIs</strong>. The
+following section explains how to start from a WSDL, and create a new service
+with code generation. For the XML based primary API, please refer to the
+section <a href="xmlbased-server.html">Writing Web Services Using Axis2's
+Primary APIs</a> for more information. However, if you are a new user, it is
+better to follow the code generation approach first (given below)</p>
+
+<h3>Starting with WSDL, Creating and Deploying a Service</h3>
+
+<p>We start with a WSDL, however if you do not have a WSDL and need to create
+a WSDL from a java class, please use the <a href="reference.html#wsdl2java">Java2WSDL tool</a> to create the WSDL. As you
+might already know, a WSDL description of a service provides a precise
+definition of that web service. Axis2 can process the WSDL and generate java
+code that does most of the work for you. At the server side, we call them
+Skeletons, and at the client side, Stubs.</p>
+This method of writing a Web service with Axis2 involves four steps:
+<ol type="1">
+ <li>Generate the skeleton code.</li>
+ <li>Add business logic.</li>
+ <li>Create a *.aar archive (Axis Archive) for the Web service.</li>
+ <li>Deploy the Web service.</li>
+</ol>
+<a name="Step1_:Generate_skeleton"></a>
+
+<h3>Step1: Generate Skeleton Code</h3>
+
+To generate the skeleton and required classes, you can use the WSDL2Java
+tool provided in Axis2. This tool is located in the bin directory of the
+distribution and can be executed using the provided scripts (.bat or .sh).
+The tool's parameter list can be found in the <a href="reference.html#wsdl2code">Axis2 Reference Document</a>.
+
+The parameters for the wsdl2java tool in our example are as follows.
+Please note that, for this example, we are using xmlbeans as the data binding framework, and the generated
+code will be placed in a "samples" directory. Other data binding tools you can
+use are adb (Axis data binding) and jaxme (<a href="http://ws.apache.org/jaxme/">JaxMe data binding</a>)
+<pre>wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans
+-o ../samples -p org.apache.axis2.userguide</pre>
+
+This will generate the required classes in the <b>"sample/src"</b>
+directory, and the schema classes in the
+<strong>"samples/resources/schemaorg_apache_xmlbeans"</strong>
+directory<strong></strong>. Note that these are not source files and should
+be available in the class path in order to compile the generated classes.
+<a name="Step2_Implement_Business_Logic"></a>
+
+<h3>Step 2: Implement Business Logic</h3>
+
+Now you should fill the business logic in the skeleton class. You can find
+the skeleton class -Axis2SampleDocLitServiceSkeleton.java- among the
+generated classes in the
+<strong>"samples/src/org/apache/axis2/userguide</strong> directory. Let's
+fill the <code>echoString(..)</code> method in the skeleton as shown below.
+Our sample WSDL-Axis2SampleDocLit.wsdl in <strong>"samples/wsdl"</strong>
+directory has three operations: echoString, echoStringArray, echoStruct. To
+see how the others will look when they are filled up, see <a href="src/Axis2SampleDocLitServiceCode.html">Code Listing For
+Axis2SampleDocLitService Service</a>
+<div class="source"><pre><pre>public org.apache.axis2.userguide.xsd.EchoStringReturnDocument
+ echoString(org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) throws Exception {
+ //Use the factory to create the output document.
+ org.apache.axis2.userguide.xsd.EchoStringReturnDocument retDoc =
+ org.apache.axis2.userguide.xsd.EchoStringReturnDocument.Factory.newInstance();
+ //send the string back.
+ retDoc.setEchoStringReturn(param4.getEchoStringParam());
+ return retDoc;<br></br></pre>
+</pre></div><a name="Step4_Create_archive"></a>
+
+<h3>Step 3: Create Archive File</h3>
+
+<p>An Axis2 service must be bundled as a service archive. The next step is to
+package the classes in an .aar (axis2 archive) and deploy it in Axis2. There
+is an ant file generated with the code; it will generate the Axis2 service
+archive for you. However, if you do not want to use ant, you can create an
+archive with the following steps :</p>
+<ol type="1">
+ <li>Compile the generated code.</li>
+ <li>Copy <strong>"resources/schemaorg_apache_xmlbeans</strong>" xmlbeans
+ classes to your class folder.</li>
+ <li>Among the generated files, there will be a services.xml file, which is
+ the deployment descriptor for Axis2 service.[<a href="reference.html#servicedd">learn more about it</a>]. Copy the
+ resources/service.xml to META-INF/services.xml</li>
+
+ (To write your own service.xml file, see the sub section in <a href="xmlbased-server.html#Step2_:Write_the_services_xml_file">Writing Web
+ Services Using Axis2's Primary APIs</a> )
+ <li>Create the archive using content of the class folder. Change the
+ directory to the class folder and run <code>jar -cf
+ <service-name>.aar</code> to create the archive.</li>
+</ol>
+
+Once the archive is created, the content of the JAR should look like
+this:
+
+<img src="images/userguide/DirectoryStructure.jpg" align="bottom" border="0"></img>
+<a name="Step5_Deploy_web_service"></a>
+
+<h3>Step 4: Deploy Web Service</h3>
+
+The service can be deployed by simply dropping the ".aar" file into the
+"services" directory in "/webapps/axis2/WEB-INF" of your servlet container.
+We recommend using <a href="http://tomcat.apache.org/">Apache Tomcat</a> as
+the servlet container. <strong>Please Note that the services directory is
+available only after axis2.war has been exploded by Tomcat. However, the easiest
+way to do it is to start Tomcat after axis2.war is copied to the webapps
+directory</strong> (if you have not already started it). Check the "Services"
+link on the <a href="http://localhost:8080/axis2/">Home page
+of Axis2 Web Application</a> (http://localhost:8080/axis2) and see whether
+the Axis2SampleDocLitService is displayed under the deployed services.
+
+<p>We recommend using the exploded configuration to deploy Axis2 WAR in
+<strong>WebLogic and WebSphere</strong> application servers to support the
+hotupdate/hotdeployment features of Axis2. See <a href="app_server.html#weblogic_websphere">Application Server Specific
+Configuration Guide</a> for details.</p>
+
+<p>Note: Axis2 provides an easy way to deploy Web Services using the "Upload
+Service" tool in the Axis2 Web Application's Administration module. (See the
+<a href="webadminguide.html">Web Administration Guide</a> for
+more information)</p>
+<a name="client"></a>
+
+<h2>Writing a Web Service Client</h2>
+
+<p>Axis2 also provides a more complex, yet powerful XML based client API
+which is intended for advanced users. Read <a href="dii.html">Writing Web
+Service Clients Using Axis2's Primary APIs</a> to learn more about it.
+However, if you are a new user, we recommend using the <strong>code
+generation</strong> approach presented below.</p>
+
+<h3>Generate Stubs</h3>
+
+<p>Let's see how we could generate java code (Stub) to handle the client side
+Web Service invocation for you. This can be done by running the WSDL2Java
+tool using the following arguments</p>
+<div class="source"><pre><pre>wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans
+ -o ../samples/src -p org.apache.axis2.userguide</pre>
+</pre></div>
+<p>This will generate client side stubs and xmlbeans types for your types.
+The Stub class that you need to use will be of the form
+<strong><service-name>Stub</strong>. In our example, it will be called
+"Axis2SampleDocLitServiceStub.java"</p>
+
+<p>Axis2 clients can invoke Web Services both in a blocking and non-blocking
+manner. In a blocking invocation, the client waits till the service performs
+its task without proceeding to the next step. Normally, the client waits till
+the response to its particular request arrives. In a non-blocking invocation,
+the client proceeds to the next step immediately, and the responses (if any)
+are handled using a Callback mechanism. Please note that some explanations
+use the terms Synchronous and Asynchronous to describe the similar invocation
+strategies.</p>
+
+<h3>Do a Blocking Invocation</h3>
+
+<p>The following code fragment shows the necessary code calling
+<code>echoString</code> operation of the
+<code>Axis2SampleDocLitService</code> that we have already deployed. The code
+is extremely simple to understand and the explanations are in the form of
+comments.</p>
+<div class="source"><pre><pre> try {
+ org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub
+ = new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+ //Create the request document to be sent.
+ org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc =
+ org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();
+ reqDoc.setEchoStringParam("Axis2 Echo");
+ //invokes the Web service.
+ org.apache.axis2.userguide.xsd.EchoStringReturnDocument resDoc =
+ stub.echoString(reqDoc);
+ System.out.println(resDoc.getEchoStringReturn());
+ } catch (java.rmi.RemoteException e) {
+ e.printStackTrace();
+ }</pre>
+</pre></div>
+<p>First argument of <code>Axis2SampleDocLitPortTypeStub</code> should be the
+Axis2 repository for the client. Here we use null to make the stub use
+default configurations. However, you can make Axis2 use your own repository
+by providing it here. You can find more information about this from the <a href="#config">Axis2 Configuration section</a>. You can find code to invoke
+other operations from <a href="src/Axis2SampleDocLitServiceCode.html">Code
+Listing For Axis2SampleDocLitService Service</a></p>
+
+<h3>Do a Non-Blocking Invocation</h3>
+
+<p>The stubs also include a method that allows you to do a non-blocking
+innovation. For each method in the Service, there will be a method
+<strong>start<method-name></strong>. These methods accept a callback
+object, which would be called when the response is received. Sample code that
+does an asynchronous interaction is given below.</p>
+<div class="source"><pre><pre>try {
+ org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub
+ = new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+ //implementing the callback online
+ org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler callback =
+ new org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler() {
+ public void receiveResultechoString(
+ org.apache.axis2.userguide.xsd.EchoStringReturnDocument resDoc) {
+ System.out.println(resDoc.getEchoStringReturn());
+ }
+ };
+ org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc =
+ org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();
+ reqDoc.setEchoStringParam("Axis2 Echo");
+ stub.startechoString(reqDoc, callback);
+ } catch (java.rmi.RemoteException e) {
+ e.printStackTrace();
+ }</pre>
+</pre></div>
+<p>Even though the above code does a non-blocking invocation at the client
+API, the transport connection may still operate in a blocking fashion. For
+example, a single HTTP connection can be used to create a Web Service request
+and to get the response when a blocking invocation happens at the transport
+level. To perform a "true" non-blocking invocation in which two separate
+transport connections are used for the request and the response, please add
+the following code segment after creating the stub. It will force Axis2 to
+use two transport connections for the request and the response while the
+client uses a Callback to process the response.</p>
+<div class="source"><pre><pre>stub._getServiceClient().engageModule(new QName("addressing"));
+stub._getServiceClient().getOptions().setUseSeparateListener(true);</pre>
+</pre></div>
+<p>Once those options are set, Axis2 client does the following:</p>
+<ol type="1">
+ <li>Starts a new Transport Listener(Server) at the client side.</li>
+ <li>Sets the address of the Transport Listener, as the ReplyTo
+ WS-Addressing Header of the request message</li>
+ <li>According to the WS-Addressing rules, the Server will process the
+ request message and send the response back to the ReplyTo address.</li>
+ <li>Client accepts the response, processes it and invokes the callback with
+ the response parameters.</li>
+</ol>
+
+<h3>Using Your Own Repository</h3>
+
+You can also use your own repository with an Axis2 Client. The code below shows how
+to do this.
+<div class="source"><pre><pre>String axis2Repo = ...
+String axis2xml = ...
+ConfigurationContext configContext =
+ConfigurationContextFactory.createConfigurationContextFromFileSystem(axis2Repo, axis2xml);
+Service1Stub stub1 = new Service1Stub(configContext,...);
+//invoke Service1
+Service2Stub stub2 = new Service2Stub(configContext,...);
+//invoke Service2</pre>
+</pre></div>
+Note by creating the <code>ConfigurationContext</code> outside and passing
+it to the stubs, you could make number of stubs to use same repository, thus
+saving the configuration loading overhead from each request.
+<a name="config"></a>
+
+<h2>Configuring Axis2</h2>
+
+<h3>Axis2 Repository</h3>
+
+Axis2 configuration is based on a repository and standard archive format.
+A repository is a directory in the file system, and it should have the
+following:
+<ol type="1">
+ <li><strong>axis2.xml</strong>, the Axis2 global deployment descriptor in
+ conf/axis2.xml file</li>
+ <li><strong>services</strong> directory, which will have the service
+ archives</li>
+ <li><strong>modules</strong> directory (optional), which will have the
+ module archives</li>
+</ol>
+
+Both services and modules will be identified and deployed once their
+archives are copied to the corresponding directories. At the server side,
+users should specify the repository folder at the time of starting the Axis2
+Server (e.g. HTTP or TCP). In Tomcat, <code>webapps/axis2/WEB-INF</code>
+folder acts as the repository. At the client side, binary distribution can
+itself be a repository. You can copy the conf directory which includes the
+axis2.xml file from the exploded axis2.war and edit it to change the global
+configurations repository.
+
+<h3>Global Configurations</h3>
+
+The Global configuration can be changed by editing the axis2.xml file,
+refer to the <a href="axis2config.html#Global_Configuration">Axis2
+Configuration Guide</a> for more information.
+
+<h3>Add New Services</h3>
+
+New services can be written either using WSDL based code generation as we
+did, or from scratch as explained in <a href="xmlbased-server.html">Writing
+Web Services Using Axis2's Primary APIs</a>. Read <a href="xmlbased-server.html">Creating a Service from Scratch</a> for more
+information. Also refer to <a href="axis2config.html#Service_Configuration">Axis2 Configuration Guide</a>
+for a reference on <strong>services.xml</strong> file.
+
+<h3 name="module_engage">Engaging Modules</h3>
+
+Each module(.mar file) provides extensions to Axis2. A module can be
+deployed by copying it to the modules directory in the repository. Then it
+becomes available and can be engaged at a global, service or operation scope.
+Once engaged, it becomes active (adds handlers to the execution flow) at the
+respective scope. Please refer to <a href="Axis2ArchitectureGuide.html">Axis2
+architecture guide</a> for detailed explanation. The following table explains
+the semantics of scope, and how to engage modules in those scopes.
+
+<table class="bodyTable">
+ <tbody>
+ <tr class="a">
+ <th>Scope</th>
+ <th>Semantics</th>
+ <th>How to Engage</th>
+ </tr>
+ <tr class="b">
+ <td>Global</td>
+ <td>Add handlers in the module to all the services. Addressing Handler
+ can be only engaged as global</td>
+ <td>By adding a <module ref="addressing"/> to the Axis2 xml file
+ or calling
+ <pre>stub._getServiceClient().engageModule(moduleName)</pre>
+ at client side</td>
+ </tr>
+ <tr class="a">
+ <td>Service</td>
+ <td>Add handlers in the module to a specific service</td>
+ <td>By adding a <module ref="addressing"/> to a service.xml file
+ in a service archive</td>
+ </tr>
+ <tr class="b">
+ <td>Operation</td>
+ <td>Add handlers in the module to a specific operation</td>
+ <td>By adding a <module ref="addressing"/> inside an operation
+ tag of a service.xml file in a service archive</td>
+ </tr>
+ </tbody>
+</table>
+
+<p>* If a handler is added to a service or an operation, it will be invoked
+for every request received by that service or operation</p>
+
+<p>Axis2 provides a number of built in Modules (such as <a href="">addressing</a>,<a href="">Security</a>, <a href="">WS-Reliable
+Messaging</a>), and they can be engaged as shown above. Please refer to each
+module on how to use and configure them. You can also <a href="modules.html">create your own modules with Axis2</a>. Also refer to <a href="axis2config.html#Global_Configuration">Axis2 Configuration Guide</a>
+for a reference on the module.xml file.</p>
+
+<h3>WS-Addressing Support</h3>
+
+<p>WS-Addressing support for Axis2 is implemented by the addressing module.
+To enable addressing, you need to engage the addressing module in both server
+and client sides.</p>
+<ol type="1">
+ <li>To <strong>enable</strong> addressing at the server side, you need to
+ copy the addressing.mar file to the modules directory of the server's
+ axis2 repository. To engage the module, add a <module
+ ref="addressing"/> to axis2.xml. The <strong>Addressing module can be
+ engaged only at global level.</strong></li>
+ <li>To <strong>enable</strong> addressing at the client side, you should
+ add it to the repository and provide the repository as an argument to the
+ <a href="dii.html">ServiceClient</a> or <a href="#client">generated
+ stub</a> or have it in your classpath.</li>
+ <li>To <strong>engage</strong> the addressing module, you should either add
+ <module ref="addressing"/> to the axis2.xml file at the client side
+ or call
+ <pre>stub._getServiceClient().engageModule(moduleName)</pre>
+ </li>
+</ol>
+<a name="advanced"></a>
+
+<h2>Advanced Topics</h2>
+
+<h3>Transports</h3>
+
+By default, Axis2 is configured to use HTTP as the transport. However,
+Axis2 supports HTTP, SMTP, TCP and JMS transports. You can also write your
+own transports, and deploy them by adding new transportReceiver or
+transportSender tags to axis2.xml. To learn how to configure and use
+different transports, please refer to the following documents.
+<ol type="1">
+ <li><a href="tcp-transport.html">TCP Transport</a></li>
+ <li><a href="mail-transport.html">Mail Transport</a></li>
+ <li><a href="http-transport.html">HTTP Transports</a></li>
+ <li><a href="jms-transport.html">JMS Transports</a></li>
+</ol>
+
+<h3>Attachments</h3>
+
+Axis2 provides attachment support using <a href="http://www.w3.org/TR/soap12-mtom/">MTOM</a>. Please refer to <a href="mtom-guide.html">MTOM with Axis2</a> for more
+information.
+
+<h3>Security</h3>
+
+Axis2 provides Security support using <a href="http://ws.apache.org/axis2/modules/rampart/1_0/security-module.html">Apache
+Rampart</a>. Please refer to <a href="../modules/wss4j/1_0/security-module.html">Securing
+SOAP Messages with Apache Rampart</a> for more information.
+
+<h3>REST Web Service</h3>
+
+Please refer to <a href="rest-ws.html">RESTful Web
+Services</a> for more information.
+
+<h3>Pluggable Data Binding</h3>
+
+Axis2 ships with Axis Data Binding(ADB) as the default data binding
+framework. However, data binding frameworks are pluggable to Axis2, and
+therefore you can use other data binding frameworks with Axis2. Please refer
+to the following documents for more information.
+
+<h4>Axis2 Data Binding(ADB)</h4>
+<ol type="1">
+ <li><a href="adb/adb-howto.html">Axis2 Databinding
+ Framework</a></li>
+ <li><a href="adb/adb-codegen-integration.html">ADB
+ Integration With Axis2</a></li>
+ <li><a href="adb/adb-advanced.html">Advanced Axis2 Databinding Framework
+ Features</a></li>
+ <li><a href="adb/adb-tweaking.html">ADB Tweaking Guide</a></li>
+</ol>
+
+<h4>JiBX</h4>
+<a href="jibx/jibx-codegen-integration.html">JiBX Integration With Axis2</a>
+
+<h3>Other Topics</h3>
+<ol type="1">
+ <li><a href="spring.html">Axis2 Integration With The Spring
+ Framework</a></li>
+ <li><a href="WS_policy.html">Web Services Policy Support In
+ Axis2</a></li>
+ <li><a href="axis2config.html#Global_Configuration">Axis2 Configuration
+ Guide</a></li>
+ <li><a href="Axis2-rpc-support.html">Axis2 RPC Support</a></li>
+ <li><a href="migration.html">Migrating from Apache Axis 1.x to Axis
+ 2</a></li>
+ <li><a href="modules.html">Writing your Own Axis2 Module</a></li>
+ <li><a href="soapmonitor-module.html">Using the SOAP Monitor</a></li>
+ <li><a href="xmlbased-server.html">Writing Web Services Using Axis2's
+ Primary APIs</a></li>
+ <li><a href="dii.html">Writing Web Service Clients Using Axis2's Primary
+ APIs</a></li>
+ <li><a href="app_server.html">Application Server Specific Configuration
+ Guide</a></li>
+</ol>
+
+</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/app_server.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/app_server.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/app_server.html (added)
+++ webservices/axis2/site/1_3/app_server.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,374 @@
+<!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="text/html; charset=us-ascii"></meta>
+Application Server Specific Configuration Guide
+<meta content="amaya 9.2.1, see http://www.w3.org/Amaya/"></meta>
+<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</head>
+
+<h1>Application Server Specific Configuration Guide</h1>
+<p>This document provides configuration information required for
+your Application Server to run Apache Axis2 to its fullest
+potential.</p>
+<h3>WebLogic/ WebSphere</h3>
+<p><strong>1. Use exploded configuration to deploy Axis2
+WAR</strong></p>
+<p>We recommend using the exploded configuration to deploy Axis2
+WAR in WebLogic and WebSphere application servers to support the
+hotupdate/ hotdeployment features in Axis2. However, if you want to
+deploy custom WARs, say in a clustering environment, you need to
+add two additional files into the WEB-INF named "services.list" and
+"modules.list" under the modules and services directory
+respectively.</p>
+<ul>
+<li><b>WEB-INF/services/services.list</b> : should list all the
+services (aar files) that you want to expose.</li>
+<li><b>WEB-INF/modules/modules.list</b> : should list all the
+modules (mar files) that you want to use.</li>
+</ul>
+NOTE: In both cases, please list one entry per line.
+WebLogic ships with JARs that conflict with JARs present in
+Axis2. Therefore use <prefer-web-inf-classes> to ensure that
+JARs packaged in Axis2 WAR are picked up from WEB-INF/lib. You can
+do this by setting the <prefer-web-inf-classes> element in
+WEB-INF/weblogic.xml to true. An example of weblogic.xml is shown
+below:
+<pre>
+<weblogic-web-app>
+ <container-descriptor>
+ <prefer-web-inf-classes>true</prefer-web-inf-classes>
+ </container-descriptor>
+</weblogic-web-app>
+</pre>
+If set to true, the <prefer-web-inf-classes> element will
+force WebLogic's classloader to load classes located in the WEB-INF
+directory of a Web application in preference to application or
+system classes. This is a recommended approach since it only
+impacts a single Web module.
+<p>Please refer to the following documents in WebLogic/ WebSphere
+for more information:</p>
+<ul>
+<li><a href="http://e-docs.bea.com/wls/docs81/programming/classloading.html">WebLogic
+ServerApplication Classloading</a>- For more information on how
+WebLogic's class loader works</li>
+<li><a href="http://e-docs.bea.com/wls/docs81/webapp/deployment.html">Redeploying
+a Web Application in Exploded Directory Format</a></li>
+<li><a href="http://publib.boulder.ibm.com/infocenter/wsiihelp/v8r3/index.jsp?topic=/com.ibm.websphere.ii.product.ce.doc/configuring/iiyviigdepwebexpl.htm">
+Deploying the Web application in exploded form</a></li>
+</ul>
+<strong>2. Lack of namespacing on serialised items</strong>
+BEA WebLogic Server 9.0 comes with its own StAX implementation.
+This results in lack of namespacing on serialised items. In turn,
+WebLogic server (WLS) breaks with AXIOM on the WLS classpath. Hence
+a filtering classloader is required:
+Adding the following to weblogic-application.xml should resolve
+this issue:
+<pre>
+<prefer-application-packages>
+<package-name>com.ctc.wstx.*</package-name>
+<package-name>javax.xml.*</package-name>
+<package-name>org.apache.*</package-name>
+</prefer-application-packages>
+</pre>
+<p>Note that the libraries listed--Xerces, StAX API, Woodstox--need
+to be on the application classpath.</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/axis2config.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/axis2config.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/axis2config.html (added)
+++ webservices/axis2/site/1_3/axis2config.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,756 @@
+<!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>
+ Axis2 Configuration Documents
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</head>
+
+
+<h1>Axis2 Configuration Guide</h1>
+
+<p>In Axis2, there are three kinds of configuration files to configure the
+system. The first one is to configure the whole system (global
+configuration), the second one is to configure a service (service
+configuration), and the third one is to configure a module (module
+configuration). This document explains the above configurations in detail.</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#Global_Configuration">Global Configuration
+ (axis2.xml)</a></li>
+ <li><a href="#Service_Configuration">Service Configuration
+ (services.xml)</a></li>
+ <li><a href="#Module_Configuration">Module Configuration
+ (module.xml)</a></li>
+</ul>
+<a name="Global_Configuration"></a>
+
+<h2>Global Configuration</h2>
+<ul>
+ <li>Writing axis2.xml</li>
+</ul>
+
+All the configurations that require starting Axis2 are obtained from
+axis2.xml. The way to specify them is extremely simple and easy. The document
+is all about the proper way of specifying the configurations in axis2.xml.
+There are six top level elements that can be seen in the configuration file
+and can be listed as follows:
+<ul>
+ <li><a href="#Parameter">Parameter</a></li>
+ <li><a href="#Receiver">Transport Receiver</a></li>
+ <li><a href="#Sender">Transport Sender</a></li>
+ <li><a href="#Phase_Order">Phase Order</a></li>
+ <li><a href="#References">Module References</a></li>
+ <li><a href="#Listeners">Listeners (Observers)</a></li>
+</ul>
+<a name="Parameter"></a>
+
+<h3>Parameter</h3>
+
+In Axis2, a parameter is nothing but a name-value pair. Each and every top
+level parameter available in the axis2.xml (direct sub elements of the root
+element) will be transformed into properties in AxisConfiguration. Therefore,
+the top level parameters in the configuration document can be accessed via
+AxisConfiguration in the running system. The correct way of defining a
+parameter is shown below:
+<div class="source"><pre><pre>
+ <parameter name="name of the parameter" >parameter value </parameter></pre>
+</pre></div><a name="Receiver"></a>
+
+<h3>Transport Receiver</h3>
+
+Depending on the underlying transport on which Axis2 is going to run, you
+need to have different transport receivers. The way you add them to the
+system is as follows: <div class="source"><pre>
+<pre>
+<transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer">
+ <parameter name="port" >6060</parameter>
+ </transportReceiver>
+ </pre>
+</pre></div>The above elements show how to define transport receivers in
+axis2.xml. Here the "name" attribute of the <transportReceiver/> element identifies the
+type of the transport receiver. It can be HTTP, TCP, SMTP, CommonsHTTP, etc.
+When the system starts up or when you set the transport at the client side,
+you can use these transport names to load the appropriate transport. The "class"
+attribute is for specifying the actual java class that will implement the required
+interfaces for the transport. Any transport can have zero or more parameters,
+and any parameters given can be accessed via the corresponding
+transport receiver. <a name="Sender"></a>
+
+<h3>Transport Sender</h3>
+
+Just like the transport receivers, you can register transport senders in the
+system, and later at run time, the senders can be used to send the messages.
+For example, consider Axis2 running under Apache Tomcat. Then Axis2 can use
+TCP transport senders to send messages rather than HTTP. The method of
+specifying transport senders is as follows:
+<pre>
+<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+ <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0</parameter>
+ </transportSender>
+ </pre>
+<strong>name:</strong> Name of the transport (you can have HTTP and HTTP1 as
+the transport name)
+
+<strong>class:</strong> Implementation class of the corresponding
+transport.
+
+Just like the transport receivers, transport senders can have zero
+or more parameters, and if there are any, they can be accessed via the
+corresponding transport sender.
+<a name="Phase_Order"></a>
+
+<h3>Phase Order</h3>
+
+Specifying the order of phases in the execution chain has to be done using
+the phase order element. It will look as follows:
+<pre><phaseOrder type="InFlow">
+ <phase name="TransportIn"/>
+ .
+ .
+</phaseOrder> </pre>
+
+The most interesting thing is that you can add handlers here as well. If
+you want to add a handler that should go into that phase, you can directly do
+that by adding a handler element into it. In addition to that, there is no
+hard coding work for the handler chain anywhere in Axis2 (at any Axis*). So
+all those configurations are also done in the phase order element. The
+complete configurations will look as follows: <div class="source"><pre>
+<pre><phaseOrder type="InFlow">
+ <!-- Global phases -->
+ <phase name="Transport">
+ <handler name="RequestURIBasedDispatcher"
+ class="org.apache.axis2.dispatchers.RequestURIBasedDispatcher">
+ <order phase="Transport"/>
+ </handler>
+
+ <handler name="SOAPActionBasedDispatcher"
+ class="org.apache.axis2.dispatchers.SOAPActionBasedDispatcher">
+ <order phase="Transport"/>
+ </handler>
+ </phase>
+ <phase name="Security"/>
+ <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="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 the Dispatch phase module author or service author can add any phase he wants -->
+ <phase name="OperationInPhase"/>
+ </phaseOrder>
+ <phaseOrder type="OutFlow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutPhase"/>
+ <!-- Global phases -->
+ <!-- these phases will run irrespective of the service -->
+ <phase name="MessageOut"/>
+ <phase name="PolicyDetermination"/>
+ </phaseOrder>
+ <phaseOrder type="InFaultFlow">
+ <phase name="PreDispatch"/>
+ <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">
+ <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="AddressingBasedDispatcher"
+ class="org.apache.axis2.dispatchers.AddressingBasedDispatcher">
+ <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>
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationInFaultPhase"/>
+ </phaseOrder>
+ <phaseOrder type="OutFaultFlow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutFaultPhase"/>
+ <phase name="PolicyDetermination"/>
+ <phase name="MessageOut"/>
+ </phaseOrder></pre>
+</pre></div>
+<strong>type:</strong> the attribute represents the type of the flow. It
+can only be one of the following:
+<ul>
+ <li>InFlow</li>
+ <li>OutFlow</li>
+ <li>InFaultFlow</li>
+ <li>OutFaultFlow</li>
+</ul>
+
+In addition to that, the only child element that is allowed inside
+"phaseOrder" is the "phase" element which represents the available phases in
+the execution chain. The method of specifying phases inside "phaseOrder" is
+as follows:<div class="source"><pre>
+<pre> <phase name="Transport"/></pre>
+</pre></div>
+<strong>name:</strong> Name of the phase. <br></br>
+
+
+There are a number of things that one has to keep in mind when changing a
+phaseOrder:
+
+For the phaseOrder types <strong>"InFlow"</strong> and
+<strong>"InFaultFlow"</strong>
+<ul>
+ <li>All the phases that are above the "Dispatch" phase, including the
+ "Dispatch" phase, are known as "Global phases" . You can add any number
+ of new phases here and they will be considered global.</li>
+ <li>In these two phaseOrder types, the phases added after the "Dispatch"
+ phase are known as "Operation phases".</li>
+</ul>
+
+For the phaseOrder types <strong>"OutFlow"</strong> and
+<strong>"OutFaultFlow"</strong>
+<ul>
+ <li>All the phases that are below the "MessageOut" phase, including the
+ "MessageOut" phase, are known as "Global phases". You can add new phases
+ according to your requirement.</li>
+ <li>The phases added before the "MessageOut" phase are known as "Operation
+ phases".</li>
+
+ <strong>Note :</strong> If you look closely at the default axis2.xml,
+ you will be able to clearly identify it.
+</ul>
+<a name="References"></a>
+
+<h3>Module References</h3>
+
+If you want to engage a module, system wide, you can do it by adding a top
+level module element in axis2.xml. It should look as follows:<div class="source"><pre>
+<pre><module ref="addressing"/> </pre>
+</pre></div>
+<strong>ref:</strong> the module name which is going to be engaged, system
+wide.
+<a name="Listeners"></a>
+
+<h3><strong>Listeners (Observers)</strong></h3>
+
+In Axis2, AxisConfiguration is observable so that you can register
+observers into that. They will be automatically informed whenever a change
+occurs in AxisConfiguration. In the current implementation, the observers are
+informed of the following events:
+<ul>
+ <li>Deploying a Service</li>
+ <li>Removing a service</li>
+ <li>Activate/Inactivate Service</li>
+ <li>Module deploy</li>
+ <li>Module remove</li>
+</ul>
+
+Registering Observers is very useful for additional features such as RSS
+feed generation, which will provide service information to subscribers. The
+correct way of registering observers should as follows:<div class="source"><pre>
+<pre><listener class="org.apache.axis2.ObserverIMPL">
+ <parameter name="RSS_URL" >http://127.0.0.1/rss</parameter>
+ </listener></pre>
+</pre></div>
+<strong>class:</strong> Represents an Implementation class of observer,
+and it should be noted that the Implementation class should implement
+AxisObserver interface, and the class has to be available in the classpath.
+<a name="Service_Configuration"></a>
+
+<h2><font>Service Configuration</font></h2>
+<ul>
+ <li><font>Writing services.xml</font></li>
+</ul>
+
+<font>The description of services are specified using services.xml. Each
+service archive file needs to have a services.xml in order to be a valid
+service and it should be available in the META-INF directory of the archive
+file. A very simple services.xml is shown below:</font>
+<div class="source"><pre><pre><service name="name of the service" scope="name of the scope" class="full qualifide name the service lifecycle class" targetNamespace="target namespase for the service">
+ <description> The description of the service </description>
+
+ <transports>
+ <transport>HTTP</transport>
+ </transports>
+
+ <schema schemaNamespace="schema namespace"/>
+
+ <messageReceivers>
+ <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
+ class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
+ </messageReceivers>
+
+ <parameter name="ServiceClass" locked="xsd:false">org.apache.axis2.sample.echo.EchoImpl</parameter>
+
+ <operation name="echoString" mep="operation MEP">
+ <actionMapping>Mapping to action</actionMapping>
+ <module ref=" a module name "/>
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ </service></pre>
+</pre></div>
+<strong>name</strong>: The service name will be the name of the archive
+file if the .aar file contains only one service, or else the name of the
+service will be the name given by the name attribute.
+
+<strong>scope</strong>: (Optional Attribute) The time period during which
+runtime information of the deployed services will be available. Scope is of
+several types- "Application", "SOAPSession", "TransportSession", "Request".
+The default value (if you don't enter any value) will be "Request"
+
+<strong>class</strong>: (Optional attribute) The full qualified name of
+the service lifecycle implementation class. ServiceLifeCycle class is useful
+when you want to do some tasks when the system starts and when it
+shuts down.
+
+<p><strong>targetNamespace</strong>: (Optional Attribute) Target name space
+of the service. This value will be used when generating the WSDL. If you do
+not specify this value, the value will be calculated from the package name of
+the service impl class.</p>
+
+<p><font><strong>description</strong>: (Optional) If you want to display any
+description about the service via Axis2 web-admin module, then the
+description can be specified here.</font></p>
+
+<p><strong>transports</strong> : (Optional) The transports to which the
+service is going to be exposed. If the transport element is not present, then
+the service will be exposed in all the transports available in the system.
+The transport child element specifies the transport prefix (the name of the
+transport specified in axis2.xml).</p>
+
+<p><b>parameters:</b> A services.xml can have any number of top level
+parameters and all the specified parameters will be transformed into service
+properties in the corresponding AxisService. There is a compulsory parameter
+in services.xml called ServiceClass that specifies the Java class, which
+performs the above transformation. This class is loaded by the
+MessageReceiver.</p>
+
+<p><b>operations :</b> If the service impl class is Java, then all the public
+methods in that service will be exposed. If the user wants to override it, he
+has to add the "operation" tag and override it. In a non-Java scenario or if
+you do not have a service class, then all the operations the user wants to
+expose by the service has to be indicated in the services.xml. It is
+specified as follows:</p> <div class="source"><pre>
+<pre> <operation name="echoString">
+ <module ref=" a module name "/>
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation></pre>
+</pre></div>
+<p>The only compulsory attribute here is "name", which represents the
+operation name that is going to be exposed. Any operation can contain module
+references as well as any number of parameters. The most interesting thing is
+that you can register custom message receivers per operation. Then the
+registered message receiver will be the message receiver for the
+corresponding operation. If you do not specify the message receiver, then the
+default message receiver will perform the operation. <br></br>
+<a name="Module_Configuration"></a></p>
+
+<h2>Module Configuration</h2>
+<ul>
+ <li>Writing module.xml</li>
+</ul>
+
+The description of the module is specified using the module.xml. Each
+module archive file needs to have a module.xml in order to be a valid module,
+and it should be available in the META-INF directory of the archive file. <br></br>
+
+
+<p>A very simple module.xml is shown below:</p> <div class="source"><pre>
+<pre><module class="org.apache.module.Module1Impl">
+ <InFlow>
+ .
+ .
+ </InFlow>
+ <OutFlow>
+ .
+ .
+ </OutFlow>
+
+ <OutFaultFlow>
+ .
+ .
+ </OutFaultFlow>
+
+ <InFaultFlow>
+ .
+ .
+ </InFaultFlow>
+
+ <operation name="creatSeq" mep="MEP_URI_IN_OUT">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ <parameter name="para1" locked="xsd:true">10</parameter>
+ </operation>
+</module></pre>
+</pre></div>
+<p><strong>class:</strong> (Optional attribute) Indicates the module
+implementation class. A module may or may not contain a module implementation
+class since the module can also be a collection of handlers. If a module
+contains an implementation class that implements the
+org.apache.axis2.modules.Module interface at deployment, its
+<code>init();</code> method will be called.</p>
+
+<p><b>parameter:</b> A module can contain any number of parameters and all
+the listed parameters in the module.xml will be transformed into the
+corresponding AxisModule of the module.</p>
+
+<p><b>flow: </b>Defining of handlers in a module has to be done inside flows.
+There are four types of flows as listed below.</p>
+
+<p>You can add any number of handlers into a flow, and those handlers will be
+available in the corresponding chains at runtime, when they are engaged.</p>
+<ul>
+ <li>InFlow</li>
+ <li>OutFlow</li>
+ <li>InFaultFlow</li>
+ <li>OutFaultFlow</li>
+</ul>
+
+<b>operations: </b> If a module wants to add an operation when it is
+engaged into a service, it can be done by adding an operation tag in
+module.xml. The method of specifying the operation is the same as operation
+in services.xml.
+
+<b>handler:</b> The Handler element consists of compulsory and optional
+attributes. The method of defining a handler will look as follows: <div class="source"><pre>
+<pre><handler name="handler1" class="handlerClass ">
+ <order phase="userphase1" />
+ </handler></pre>
+</pre></div>
+<b><i>Compulsory Attributes</i></b> <br></br>
+<b>name:</b> Name of the handler.<br></br>
+<b>class:</b> Handler implementation class.<br></br>
+<b>phase:</b> Name of the phase that the handler should remain, in the
+execution chain. <br></br>
+<br></br>
+<i><b>Optional Attributes :</b></i><br></br>
+<b>phaseLast:</b> Indicates that the handler is the last handler of the
+phase.<br></br>
+<b>phaseFirst:</b> Indicate that the handler is the first handler of the
+phase.<br></br>
+<b>before :</b> Indicates that the current handler should be invoked before
+the handler specified by the before handler<br></br>
+<b>after:</b> Indicates that the current handler should be invoked after the
+handler specified by the after handler<br></br>
+
+
+<br></br>
+
+
+</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