Added: webservices/axis2/site/1_4/adv-userguide.html URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4/adv-userguide.html?rev=652665&view=auto ============================================================================== --- webservices/axis2/site/1_4/adv-userguide.html (added) +++ webservices/axis2/site/1_4/adv-userguide.html Thu May 1 14:20:27 2008 @@ -0,0 +1,747 @@ + + + + + + + + + + + + + + + Maven - + + + + + + + +
+ +
+
+
+ Axis2 Advanced User's Guide +

Apache Axis2 Advanced User's Guide

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.

+ +

Introduction

This user guide is written based on the Axis2 Standard Binary +Distribution +. The Standard Binary Distribution can be directly downloaded + or built using +the Source Distribution +. If +you choose the latter, then the Installation +Guide + will instruct you on how to build Axis2 Standard Binary +Distribution using the source.

+

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.

+

Let us know what you think! Send your feedback to "axis-user@ws.apache.org +". +(Subscription details are available on the Axis2 site +.) Kindly +prefix the subject of the mail with [Axis2].

+

Getting Started

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 - Configuring Axis2 + - provides +an introduction to important configuration options in Axis2. The final +section - Advanced Topics + - provides references to +other features.

+

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 "samples/userguide/src" + directory of Axis2 standard binary +distribution +.

+

Please deploy axis2.war in your servlet container and ensure that it works +fine. The Installation +Guide + gives you step-by-step instructions on just how to build axis2.war +and deploy it in your servlet container.

+ + +

Creating a New Web Service

If you are interested in how to write a Web Service client using Axis2, it +is described under Writing a Web Service Client +. Axis2 +provides two ways to create new Web Services, using code +generation and using XML based primary APIs. 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 Writing Web Services Using Axis2's +Primary APIs + for more information. However, if you are a new user, it is +better to follow the code generation approach first (given below)

+

Starting with WSDL, Creating and Deploying a Service

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 Java2WSDL tool + 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.

+ +This method of writing a Web service with Axis2 involves four steps: +
  1. Generate the skeleton code.
  2. +
  3. Add business logic.
  4. +
  5. Create a *.aar archive (Axis Archive) for the Web service.
  6. +
  7. Deploy the Web service.
  8. +
+ +

Step1: Generate Skeleton Code

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 Axis2 Reference Document +.

+

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.

+
wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans 
+-o ../samples -p org.apache.axis2.userguide

This will generate the required classes in the "sample/src" + +directory, and the schema classes in the +"samples/resources/schemaorg_apache_xmlbeans" +directory. Note that these are not source files and should +be available in the class path in order to compile the generated classes.

+ +

Step 2: Implement Business Logic

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 +"samples/src/org/apache/axis2/userguide directory. Let's +fill the echoString(..) method in the skeleton as shown below. +Our sample WSDL-Axis2SampleDocLit.wsdl in "samples/wsdl" +directory has three operations: echoString, echoStringArray, echoStruct. To +see how the others will look when they are filled up, see Code Listing For +Axis2SampleDocLitService Service +

+
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;
+
+
+ +

Step 3: Create Archive File

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 :

+
  1. Compile the generated code.
  2. +
  3. Copy "resources/schemaorg_apache_xmlbeans" xmlbeans + classes to your class folder.
  4. +
  5. Among the generated files, there will be a services.xml file, which is + the deployment descriptor for Axis2 service.[learn more about it +]. Copy the + resources/service.xml to META-INF/services.xml
  6. +(To write your own service.xml file, see the sub section in Writing Web + Services Using Axis2's Primary APIs + )
  7. Create the archive using content of the class folder. Change the + directory to the class folder and run jar -cf + <service-name>.aar to create the archive.
  8. +
+

Once the archive is created, the content of the JAR should look like +this:

+

+ +

Step 4: Deploy Web Service

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 Apache Tomcat + as +the servlet container. 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 (if you have not already started it). Check the "Services" +link on the Home page +of Axis2 Web Application + (http://localhost:8080/axis2) and see whether +the Axis2SampleDocLitService is displayed under the deployed services.

+

We recommend using the exploded configuration to deploy Axis2 WAR in +WebLogic and WebSphere application servers to support the +hotupdate/hotdeployment features of Axis2. See Application Server Specific +Configuration Guide + for details.

+

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 +Web Administration Guide + for +more information)

+ +

Writing a Web Service Client

Axis2 also provides a more complex, yet powerful XML based client API +which is intended for advanced users. Read Writing Web +Service Clients Using Axis2's Primary APIs + to learn more about it. +However, if you are a new user, we recommend using the code +generation approach presented below.

+

Generate Stubs

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

+
wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans 
+     -o ../samples/src -p org.apache.axis2.userguide
+
+

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 +<service-name>Stub. In our example, it will be called +"Axis2SampleDocLitServiceStub.java"

+

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.

+

Do a Blocking Invocation

The following code fragment shows the necessary code calling +echoString operation of the +Axis2SampleDocLitService that we have already deployed. The code +is extremely simple to understand and the explanations are in the form of +comments.

+
     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();
+              }
+
+

First argument of Axis2SampleDocLitPortTypeStub 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 Axis2 Configuration section +. You can find code to invoke +other operations from Code +Listing For Axis2SampleDocLitService Service +

+

Do a Non-Blocking Invocation

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 +start<method-name>. 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.

+
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();
+       }
+
+

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.

+
stub._getServiceClient().engageModule(new QName("addressing"));
+stub._getServiceClient().getOptions().setUseSeparateListener(true);
+
+

Once those options are set, Axis2 client does the following:

+
  1. Starts a new Transport Listener(Server) at the client side.
  2. +
  3. Sets the address of the Transport Listener, as the ReplyTo + WS-Addressing Header of the request message
  4. +
  5. According to the WS-Addressing rules, the Server will process the + request message and send the response back to the ReplyTo address.
  6. +
  7. Client accepts the response, processes it and invokes the callback with + the response parameters.
  8. +
+

Using Your Own Repository

You can also use your own repository with an Axis2 Client. The code below shows how +to do this.

+
String axis2Repo = ...
+String axis2xml = ...
+ConfigurationContext configContext =
+ConfigurationContextFactory.createConfigurationContextFromFileSystem(axis2Repo, axis2xml);
+Service1Stub stub1 = new Service1Stub(configContext,...);
+//invoke Service1
+Service2Stub stub2 = new Service2Stub(configContext,...);
+//invoke Service2
+
+

Note by creating the ConfigurationContext 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.

+ +

Configuring Axis2

Axis2 Repository

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:

+
  1. axis2.xml, the Axis2 global deployment descriptor in + conf/axis2.xml file
  2. +
  3. services directory, which will have the service + archives
  4. +
  5. modules directory (optional), which will have the + module archives
  6. +
+

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, webapps/axis2/WEB-INF +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.

+

Global Configurations

The Global configuration can be changed by editing the axis2.xml file, +refer to the Axis2 +Configuration Guide + for more information.

+

Add New Services

New services can be written either using WSDL based code generation as we +did, or from scratch as explained in Writing +Web Services Using Axis2's Primary APIs +. Read Creating a Service from Scratch + for more +information. Also refer to Axis2 Configuration Guide + +for a reference on services.xml file.

+

Engaging Modules

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 Axis2 +architecture guide + for detailed explanation. The following table explains +the semantics of scope, and how to engage modules in those scopes.

+ + + + + + + + + + + + + + + + +
ScopeSemanticsHow to Engage
GlobalAdd handlers in the module to all the services. Addressing Handler + can be only engaged as globalBy adding a <module ref="addressing"/> to the Axis2 xml file + or calling +
stub._getServiceClient().engageModule(moduleName)
+ at client side
ServiceAdd handlers in the module to a specific serviceBy adding a <module ref="addressing"/> to a service.xml file + in a service archive
OperationAdd handlers in the module to a specific operationBy adding a <module ref="addressing"/> inside an operation + tag of a service.xml file in a service archive
+

* If a handler is added to a service or an operation, it will be invoked +for every request received by that service or operation

+

Axis2 provides a number of built in Modules (such as addressing +,Security +, WS-Reliable +Messaging +), and they can be engaged as shown above. Please refer to each +module on how to use and configure them. You can also create your own modules with Axis2 +. Also refer to Axis2 Configuration Guide + +for a reference on the module.xml file.

+

WS-Addressing Support

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.

+
  1. To enable 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 Addressing module can be + engaged only at global level.
  2. +
  3. To enable addressing at the client side, you should + add it to the repository and provide the repository as an argument to the + ServiceClient + or generated + stub + or have it in your classpath.
  4. +
  5. To engage the addressing module, you should either add + <module ref="addressing"/> to the axis2.xml file at the client side + or call +
    stub._getServiceClient().engageModule(moduleName)
  6. +
+ +

Advanced Topics

Transports

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.

+
  1. TCP Transport +
  2. +
  3. Mail Transport +
  4. +
  5. HTTP Transports +
  6. +
  7. JMS Transports +
  8. +
+

Attachments

Axis2 provides attachment support using MTOM +. Please refer to MTOM with Axis2 + for more +information.

+

Security

Axis2 provides Security support using Apache +Rampart +. Please refer to Securing +SOAP Messages with Apache Rampart + for more information.

+

REST Web Service

Please refer to RESTful Web +Services + for more information.

+

Pluggable Data Binding

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.

+

Axis2 Data Binding(ADB)

+
  1. Axis2 Databinding + Framework +
  2. +
  3. ADB + Integration With Axis2 +
  4. +
  5. Advanced Axis2 Databinding Framework + Features +
  6. +
  7. ADB Tweaking Guide +
  8. +
+

JiBX

+JiBX Integration With Axis2 +

Other Topics

  1. Axis2 Integration With The Spring + Framework +
  2. +
  3. Web Services Policy Support In + Axis2 +
  4. +
  5. Axis2 Configuration + Guide +
  6. +
  7. Axis2 RPC Support +
  8. +
  9. Migrating from Apache Axis 1.x to Axis + 2 +
  10. +
  11. Writing your Own Axis2 Module +
  12. +
  13. Using the SOAP Monitor +
  14. +
  15. Writing Web Services Using Axis2's + Primary APIs +
  16. +
  17. Writing Web Service Clients Using Axis2's Primary + APIs +
  18. +
  19. Application Server Specific Configuration + Guide +
  20. +
+ +
+
+
+
+
+ + + Added: webservices/axis2/site/1_4/app_server.html URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4/app_server.html?rev=652665&view=auto ============================================================================== --- webservices/axis2/site/1_4/app_server.html (added) +++ webservices/axis2/site/1_4/app_server.html Thu May 1 14:20:27 2008 @@ -0,0 +1,380 @@ + + + + + + + + + + + + + + + Maven - + + + + + + + +
+ +
+
+
+ Application Server Specific Configuration Guide

Application Server Specific Configuration Guide

This document provides configuration information required for +your Application Server to run Apache Axis2 to its fullest +potential.

+

WebLogic/ WebSphere

1. Use exploded configuration to deploy Axis2 +WAR

+

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.

+ + +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:

+
+<weblogic-web-app>
+ <container-descriptor>
+    <prefer-web-inf-classes>true</prefer-web-inf-classes>
+  </container-descriptor>
+</weblogic-web-app>
+

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.

+

Please refer to the following documents in WebLogic/ WebSphere +for more information:

+ +

2. Lack of namespacing on serialised items

+

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:

+
+<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>
+

Note that the libraries listed--Xerces, StAX API, Woodstox--need +to be on the application classpath.

+ +
+
+
+
+
+ + + Added: webservices/axis2/site/1_4/axis2config.html URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4/axis2config.html?rev=652665&view=auto ============================================================================== --- webservices/axis2/site/1_4/axis2config.html (added) +++ webservices/axis2/site/1_4/axis2config.html Thu May 1 14:20:27 2008 @@ -0,0 +1,727 @@ + + + + + + + + + + + + + + + Maven - + + + + + + + +
+ +
+
+
+ Axis2 Configuration Documents

Axis2 Configuration Guide

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.

+

Content

+ +

Global Configuration

+

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:

+ + +

Parameter

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:

+
 
+  <parameter name="name of the parameter" >parameter value </parameter>
+
+ +

Transport Receiver

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:

+
+<transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer">
+        <parameter name="port" >6060</parameter>
+ </transportReceiver> 
+ 
+
+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. +

Transport Sender

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:

+
 
+<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+        <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0</parameter>
+ </transportSender> 
+ 
name: Name of the transport (you can have HTTP and HTTP1 as +the transport name) + +

class: 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.

+ +

Phase Order

Specifying the order of phases in the execution chain has to be done using +the phase order element. It will look as follows:

+
<phaseOrder type="InFlow">
+         <phase name="TransportIn"/>
+         .
+         .
+</phaseOrder>   

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:

+
<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>
+
+

type: the attribute represents the type of the flow. It +can only be one of the following:

+ +

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:

+
 <phase name="Transport"/>
+
+

name: Name of the phase.
+

+

There are a number of things that one has to keep in mind when changing a +phaseOrder:

+

For the phaseOrder types "InFlow" and +"InFaultFlow"

+ +

For the phaseOrder types "OutFlow" and +"OutFaultFlow"

+ + +

Module References

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:

+
<module ref="addressing"/>  
+
+

ref: the module name which is going to be engaged, system +wide.

+ +

Listeners (Observers)

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:

+ +

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:

+
<listener class="org.apache.axis2.ObserverIMPL">
+    <parameter name="RSS_URL" >http://127.0.0.1/rss</parameter>
+  </listener>
+
+

class: 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. + +

+

Service Configuration

+

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:

+
<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>
+
+

name: 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.

+

scope: (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"

+

class: (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.

+

targetNamespace: (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.

+

description: (Optional) If you want to display any +description about the service via Axis2 web-admin module, then the +description can be specified here.

+

transports : (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).

+

parameters: + 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.

+

operations : + 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:

+
    <operation name="echoString">
+        <module ref=" a module name "/>
+        <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+    </operation>
+
+

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.
+ +

+

Module Configuration

+

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.
+

+

A very simple module.xml is shown below:

+
<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>
+
+

class: (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 +init(); method will be called.

+

parameter: + 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.

+

flow: +Defining of handlers in a module has to be done inside flows. +There are four types of flows as listed below.

+

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.

+ +

operations: + 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.

+

handler: + The Handler element consists of compulsory and optional +attributes. The method of defining a handler will look as follows:

+
<handler name="handler1" class="handlerClass ">
+            <order phase="userphase1" />
+ </handler>
+
+

Compulsory Attributes + +
+name: + Name of the handler.
+class: + Handler implementation class.
+phase: + Name of the phase that the handler should remain, in the +execution chain.
+
+Optional Attributes : + +
+phaseLast: + Indicates that the handler is the last handler of the +phase.
+phaseFirst: + Indicate that the handler is the first handler of the +phase.
+before : + Indicates that the current handler should be invoked before +the handler specified by the before handler
+after: + Indicates that the current handler should be invoked after the +handler specified by the after handler
+

+


+

+ +
+
+
+
+
+ + + --------------------------------------------------------------------- To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org For additional commands, e-mail: axis-cvs-help@ws.apache.org