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

Axis2 Quick Start Guide

The purpose of this guide is to get you started on creating +services and clients using Axis2 as quickly as possible. We'll take +a simple StockQuote Service and show you some of the different ways +in which you can create and deploy it, as well as take a quick look +at one or two utilities that come with Axis2. We'll then look at +creating clients to access those services.

+

Content

+

A Quick Setup Note:

The code for the document can be found in the extracted Standard +Binary Distribution +, more specifically at Axis2_HOME/samples/ +inside the directories- quickstart, quickstartadb, quickstartaxiom, +quickstartjibx and quickstartxmlbeans. (Consider getting it now as +it will help you to follow along.) It includes Ant buildfiles +(build.xml) that we'll refer to throughout the examples to make +compilation easier.

+ +

Introduction

Let's start with the service itself. We'll make it simple so you +can see what is going on when we build and deploy the services. A +StockQuoteService example seems to be mandatory in instances like +this one, so let's use the following (see Code Listing 1).

+

Code Listing 1: The StockQuoteService class +

+
+package samples.quickstart.service.pojo;
+
+import java.util.HashMap;
+
+public class StockQuoteService {
+    private HashMap map = new HashMap();
+
+    public double getPrice(String symbol) {
+        Double price = (Double) map.get(symbol);
+        if(price != null){
+            return price.doubleValue();
+        }
+        return 42.00;
+    }
+
+    public void update(String symbol, double price) {
+        map.put(symbol, new Double(price));
+    }
+}
+

It will be a simple service with two possible calls. One of +which is an in/out message, and the other is an in-only service. +Ultimately, we'll package the service and deploy it in four +different ways.

+

First, let's look at how this simple Java class corresponds to a +service.

+ +

Getting Ready

Before we build anything using Axis2, we have to take care of a +little housekeeping. First off, you'll need to get your environment +ready for working with Axis2. Fortunately, it involves just a few +simple steps:

+
  1. Download and install Java (Minimum version is JDK1.4). Set the +JAVA_HOME environment variable to the pathname of the directory +into which you installed the JDK release.
  2. +
  3. Download Axis2 and extract it to a target directory.
  4. +
  5. Copy the axis2.war file to the webapps directory of your +servlet engine.
  6. +
  7. Set the AXIS2_HOME environment variable to point to the target +directory in step. Note that all of the scripts and build files +Axis2 generates depend on this value, so don't skip this step! +Linux users can alternatively run the setenv.sh file in the +AXIS2_HOME/bin directory to set the AXIS2_HOME environment variable +to the pathname of the extracted directory of Axis2.
  8. +
+

In most cases, we're also going to need a WSDL file for our +service. Axis2's Java2WSDL can be used to bootstrap a WSDL. To +generate a WSDL file from a Java class, perform the following +steps:

+
  1. Create and compile the Java class. +
    +(Windows)
    +%AXIS2_HOME%\bin\java2wsdl -cp . -cn samples.quickstart.service.pojo.StockQuoteService -of StockQuoteService.wsdl
    +
    +(Linux)
    +$AXIS2_HOME/bin/java2wsdl -cp . -cn samples.quickstart.service.pojo.StockQuoteService -of StockQuoteService.wsdl
    +
  2. +
  3. Generate the WSDL using the command:
  4. +
+

Once you've generated the WSDL file, you can make the changes +you need. For example, you might add custom faults or change the +name of the generated elements. For example, this +StockQuoteService.wsdl is in +AXIS2_HOME/samples/quickstartadb/resources/META-INF folder, which +we'll be using throughout the rest of this guide, replaces the +generic parameters created by the generation process.

+ +

Axis2 Services

Before we build anything, it's helpful to understand what the +finished product looks like.

+

The server side of Axis2 can be deployed on any Servlet engine, +and has the following structure. Shown in Code Listing 2.

+

Code Listing 2: The Directory Structure of axis2.war +

+
+axis2-web 
+META-INF
+WEB-INF
+    classes 
+    conf
+        axis2.xml 
+    lib
+        activation.jar
+        ...
+        xmlSchema.jar
+    modules
+        modules.list 
+        addressing.mar
+        ...
+        soapmonitor.mar
+    services
+        services.list
+        aservice.aar
+        ...
+        version.aar
+    web.xml
+

Starting at the top, axis2-web is a collection of JSPs that make +up the Axis2 administration application, through which you can +perform any action such as adding services and engaging and +dis-engaging modules. The WEB-INF directory contains the actual +java classes and other support files to run any services deployed +to the services directory.

+

The main file in all this is axis2.xml, which controls how the +application deals with the received messages, determining whether +Axis2 needs to apply any of the modules defined in the modules +directory.

+

Services can be deployed as *.aar files, as you can see here, +but their contents must be arranged in a specific way. For example, +the structure of this service will be as follows:

+ +
+- StockQuoteService
+   - META-INF
+     - services.xml
+   - lib
+   - samples
+     - quickstart
+       - service
+         - pojo
+           - StockQuoteService.class
+

Here, the name of the service is StockQuoteService, which is +specified in the services.xml file and corresponds to the top-level +folder of this service. Compiled Java classes are placed underneath +this in their proper place based on the package name. The lib +directory holds any service-specific JAR files needed for the +service to run (none in this case) besides those already stored +with the Axis2 WAR file and the servlet container's common JAR +directories. Finally, the META-INF directory contains any +additional information about the service that Axis2 needs to +execute it properly. The services.xml file defines the service +itself and links the Java class to it (See Code Listing 3).

+

Code Listing 3: The Service Definition File +

+
+<service name="StockQuoteService" scope="application">
+    <description>
+        Stock Quote Sample Service
+    </description>
+    <messageReceivers>
+        <messageReceiver 
+            mep="http://www.w3.org/2004/08/wsdl/in-only"
+    class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
+        <messageReceiver
+            mep="http://www.w3.org/2004/08/wsdl/in-out"
+    class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
+    </messageReceivers>
+    <parameter name="ServiceClass">
+        samples.quickstart.service.pojo.StockQuoteService
+    </parameter>
+</service>
+

Here the service is defined, along with the relevant +messageReceiver types for the different message exchange +patterns.

+

The META-INF directory is also the location for any custom WSDL +files you intend to include for this application.

+

You can deploy a service by simply taking this hierarchy of +files and copying it to the webapps/axis2/WEB-INF/services +directory of your servlet engine. (Note the Axis2 WAR file must be +installed first in the servlet engine.) This is known as the +"exploded" format. You can also compress your documents into an +*.aar file, similar to a *.jar file, and place the *.aar file +directly in the servlet engine's webapps/axis2/WEB-INF/services +directory.

+

Now that you understand what we're trying to accomplish, we're +almost ready to start building.

+

First, download + +and unzip the appropriate version of Axis2 Standard Binary +Distribution. Make sure that you set the value of the AXIS2_HOME +variable to match the location into which you extracted the +contents of this release.

+

Let's look at some different ways to create clients and +services.

+ +

Creating Services

In this section, we'll look at five ways to create a service +based on the StockQuoteService class: deploying Plain Old Java +Objects (POJO), building the service using AXIOM's OMElement, +generating the service using Axis2 Databinding Framework (ADB), +generating the service using XMLBeans, and generating the service +using JiBX.

+ +

Deploying POJOs

To deploy the service using POJOs (Plain Old Java Objects), +execute the following steps.

+

Note the directory structure contained at +AXIS2_HOME/samples/quickstart (the services.xml file is +from the first section of this guide):

+
+- quickstart
+   - README.txt
+   - build.xml
+   - resources
+     - META-INF
+       - services.xml
+   - src
+     - samples
+       - quickstart
+         - service
+           - pojo
+             - StockQuoteService.java
+

Note that you can generate a WSDL from the quickstart directory +by typing:

+
+ant generate.wsdl
+
+However, creating StockQuoteService.wsdl is optional. It can be the +version generated directly from the Java class, or a customized +version of that file, and that services.xml is the same file +referenced earlier in this document. +

Now build the project by typing ant generate.service in the +quickstart directory, which creates the following directory +structure:

+
+- quickstart/build/classes
+   - META-INF
+     - services.xml
+   - samples
+     - quickstart
+       - service
+         - pojo
+           - StockQuoteService.class
+

If you want to deploy the service in an exploded directory +format, rename the classes directory to StockQuoteService, and copy +it to the webapps/axis2/WEB-INF/services directory in your servlet +engine. Otherwise, copy the build/StockQuoteService.aar file to the +webapps/axis2/WEB-INF/services directory in your servlet engine. +Then check to make sure that the service has been properly deployed +by viewing the list of services at:

+
+http://localhost:8080/axis2/services/listServices
+

You can also checkout the WSDL at:

+
+http://localhost:8080/axis2/services/StockQuoteService?wsdl
+

And the schema at:

+
+http://localhost:8080/axis2/services/StockQuoteService?xsd
+

Once the URLs are working, quickly test the service. Try +pointing your browser to the following URL:

+
+http://localhost:8080/axis2/services/StockQuoteService/getPrice?symbol=IBM
+

You will get the following response:

+
+<ns:getPriceResponse xmlns:ns="http://pojo.service.quickstart.samples/xsd"><ns:return>42</ns:return></ns:getPriceResponse>
+

If you invoke the update method as,

+
+http://localhost:8080/axis2/services/StockQuoteService/update?symbol=IBM&price=100
+
+and then execute the first getPrice URL, you will see that the +price has got updated. +

Building the Service using AXIOM

To build a service "from scratch" using AXIOM, execute the +following steps.

+

Note the directory structure contained at +/samples/quickstartaxiom:

+
+- quickstartaxiom
+   - README.txt
+   - build.xml
+   - resources
+     - META-INF
+       - services.xml
+       - StockQuoteService.wsdl
+   - src
+     - samples
+       - quickstart
+         - service
+           - axiom
+             - StockQuoteService.java
+         - clients
+           - AXIOMClient.java
+

Since AXIOM is a little different, you're going to need a +different services.xml file from the one used for POJO. Define it, +as shown in Code Listing 4.

+

Code Listing 4: The Service Definition File. +

+
+<service name="StockQuoteService" scope="application">
+    <description>
+        Stock Quote Service
+    </description>
+    <operation name="getPrice">
+        <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+    </operation>
+    <operation name="update">
+        <messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>
+    </operation>
+    <parameter name="ServiceClass">samples.quickstart.service.axiom.StockQuoteService</parameter>
+</service>
+

Note that it's almost the same, except that the operations are +explicitly defined in the service.xml file, and the +MessageReceivers are now RawXML.

+

Now, the above referenced StockQuoteService.java class, a plain +Java class that uses classes from the Axis2 libraries, is defined +as shown in Code Listing 5.

+

Code Listing 5: The StockQuoteService Class using +AXIOM +

+
+package samples.quickstart.service.axiom;
+
+import javax.xml.stream.XMLStreamException;
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.om.OMNamespace;
+
+import java.util.HashMap;
+public class StockQuoteService {
+    private HashMap map = new HashMap();
+
+    public OMElement getPrice(OMElement element) throws XMLStreamException {
+        element.build();
+        element.detach();
+
+        OMElement symbolElement = element.getFirstElement();
+        String symbol = symbolElement.getText();
+
+        String returnText = "42";
+        Double price = (Double) map.get(symbol);
+        if(price != null){
+            returnText  = "" + price.doubleValue();
+        }
+        OMFactory fac = OMAbstractFactory.getOMFactory();
+        OMNamespace omNs =
+            fac.createOMNamespace("http://axiom.service.quickstart.samples/xsd", "tns");
+        OMElement method = fac.createOMElement("getPriceResponse", omNs);
+        OMElement value = fac.createOMElement("price", omNs);
+        value.addChild(fac.createOMText(value, returnText));
+        method.addChild(value);
+        return method;
+    }
+
+    public void update(OMElement element) throws XMLStreamException {
+        element.build();
+        element.detach();
+
+        OMElement symbolElement = element.getFirstElement();
+        String symbol = symbolElement.getText();
+
+        OMElement priceElement = (OMElement)symbolElement.getNextOMSibling();
+        String price = priceElement.getText();
+
+        map.put(symbol, new Double(price));
+    }
+}
+

Axis2 uses AXIOM, or the AXIs Object Model, a DOM + (Document Object Model)-like +structure that is based on the StAX API (Streaming API for XML). +Methods that act as services must take as their argument an +OMElement, which represents an XML element that happens, in this +case, to be the payload of the incoming SOAP message. Method +getPrice(OMElement), for example, extracts the contents of the +first child of the payload element, which corresponds to the stock +symbol, and uses this to look up the current price of the stock. +Unless this is an "in only" service, these methods must return an +OMElement, because that becomes the payload of the return SOAP +message.

+

Now build the project by typing ant generate.service in the +Axis2_HOME/samples/quickstartaxiom directory.

+

Place the StockQuoteService.aar file in the +webapps/axis2/WEB-INF/services directory of the servlet engine, and +check to make sure that the service has been properly deployed by +viewing the list of services at,

+
+http://localhost:8080/axis2/services/listServices
+

You can also check the custom WSDL at,

+
+http://localhost:8080/axis2/services/StockQuoteService?wsdl
+

and the schema at,

+
+http://localhost:8080/axis2/services/StockQuoteService?xsd
+
+

Generating the Service using ADB

To generate and deploy the service using the Axis2 Databinding +Framework (ADB), execute the following steps.

+

Generate the skeleton using the WSDL2Java utility by typing the +following in the Axis2_HOME/samples/quickstartadb directory:

+
+(Windows)
+%AXIS2_HOME%\bin\WSDL2Java -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.service.adb -d adb -s -ss -sd -ssi -o build\service
+
+(Linux)
+$AXIS2_HOME/bin/WSDL2Java -uri resources/META-INF/StockQuoteService.wsdl -p samples.quickstart.service.adb -d adb -s -ss -sd -ssi -o build/service
+
+

Else, simply type ant generate.service in the +Axis2_HOME/samples/quickstartadb directory.

+

The option -d adb specifies Axis Data Binding (ADB). The -s +switch specifies synchronous or blocking calls only. The -ss switch +creates the server side code (skeleton and related files). The -sd +switch creates a service descriptor (services.xml file). The -ssi +switch creates an interface for the service skeleton. The service +files should now be located at build/service.

+

If you generated the code by using WSDL2Java directly, next you +have to modify the generated skeleton to implement the service (if +you used "ant generate.service", a completed skeleton will be +copied over the generated one automatically).

+

Open the +build/service/src/samples/quickstart/adb/service/StockQuoteServiceSkeleton.java +file and modify it to add the functionality of your service to the +generated methods; shown in Code Listing 6.

+

Code Listing 6: Defining the Service Skeleton File +

+
+package samples.quickstart.service.adb;
+
+import samples.quickstart.service.adb.xsd.GetPriceResponse;
+import samples.quickstart.service.adb.xsd.Update;
+import samples.quickstart.service.adb.xsd.GetPrice;
+
+import java.util.HashMap;
+
+public class StockQuoteServiceSkeleton {
+
+    private static HashMap map;
+
+    static{ map = new HashMap(); }
+
+    public void update(Update param0) {
+        map.put(param0.getSymbol(), new Double(param0.getPrice()));
+    }
+
+    public GetPriceResponse getPrice(GetPrice param1) {
+        Double price = (Double) map.get(param1.getSymbol());
+        double ret = 42;
+        if(price != null){
+            ret = price.doubleValue();
+        }
+        GetPriceResponse res =
+                new GetPriceResponse();
+        res.set_return(ret);
+        return res;
+    }
+}
+

Now you can build the project by typing the following command in +the build/service directory:

+
+ant jar.server
+

If all goes well, you should see the BUILD SUCCESSFUL message in +your window, and the StockQuoteService.aar file in the +build/service/build/lib directory. Copy this file to the +webapps/axis2/WEB-INF/services directory of the servlet engine.

+

You can check to make sure that the service has been properly +deployed by viewing the list of services at,

+
+http://localhost:8080/axis2/services/listServices
+

You can also check the custom WSDL at,

+
+http://localhost:8080/axis2/services/StockQuoteService?wsdl
+

and the schema at,

+
+http://localhost:8080/axis2/services/StockQuoteService?xsd
+
+

Generating the Service using XMLBeans

To generate a service using XMLBeans, execute the following +steps.

+

Generate the skeleton using the WSDL2Java utility by typing the +following in the Axis2_HOME/samples/quickstartxmlbeans +directory.

+
+%AXIS2_HOME%\bin\WSDL2Java -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.service.xmlbeans -d xmlbeans -s -ss -sd -ssi -o build\service
+

Else simply type ant generate.service in the +Axis2_HOME/samples/quickstartxmlbeans directory.

+

The option -d xmlbeans specifies XML Beans data binding. The -s +switch specifies synchronous or blocking calls only. The -ss switch +creates the server side code (skeleton and related files). The -sd +switch creates a service descriptor (services.xml file). The -ssi +switch creates an interface for the service skeleton. The service +files should now be located at build/service.

+

If you generated the code by using WSDL2Java directly, next you +have to modify the generated skeleton to implement the service (if +you used "ant generate.service", a completed skeleton will be +copied over the generated one automatically).

+

Next open the +build/service/src/samples/quickstart/service/xmlbeans/StockQuoteServiceSkeleton.java +file and modify it to add the functionality of your service to the +generated methods (see Code Listing 7).

+

Code Listing 7: Defining the Service Skeleton +

+
+package samples.quickstart.service.xmlbeans;
+
+import samples.quickstart.service.xmlbeans.xsd.GetPriceDocument;
+import samples.quickstart.service.xmlbeans.xsd.GetPriceResponseDocument;
+import samples.quickstart.service.xmlbeans.xsd.UpdateDocument;
+
+import java.util.HashMap;
+
+public class StockQuoteServiceSkeleton implements StockQuoteServiceSkeletonInterface {
+
+    private static HashMap map;
+
+    static{ map = new HashMap(); }
+
+    public void update(UpdateDocument param0) {
+        map.put(param0.getUpdate().getSymbol(), new Double(param0.getUpdate().getPrice()));
+
+    }
+
+    public GetPriceResponseDocument getPrice(GetPriceDocument param1) {
+        Double price = (Double) map.get(param1.getGetPrice().getSymbol());
+        double ret = 42;
+        if(price != null){
+            ret = price.doubleValue();
+        }
+        System.err.println();
+        GetPriceResponseDocument resDoc =
+                GetPriceResponseDocument.Factory.newInstance();
+        GetPriceResponseDocument.GetPriceResponse res =
+                resDoc.addNewGetPriceResponse();
+        res.setReturn(ret);
+        return resDoc;
+
+    }
+}
+

Build the project by typing the following command in the +build/service directory, which contains the build.xml file:

+
+ant jar.server
+

If all goes well, you should see the BUILD SUCCESSFUL message in +your window, and the StockQuoteService.aar file in the newly +created build/service/build/lib directory. Copy this file to the +webapps/axis2/WEB-INF/services directory of the servlet engine.

+

You can check to make sure that the service has been properly +deployed by viewing the list of services at,

+
+http://localhost:8080/axis2/services/listServices
+

You can also check the custom WSDL at,

+
+http://localhost:8080/axis2/services/StockQuoteService?wsdl
+

and the schema at,

+
+http://localhost:8080/axis2/services/StockQuoteService?xsd
+
+

Generating the Service using JiBX

To generate and deploy the service using JiBX data binding +, execute the following +steps.

+

Generate the skeleton using the WSDL2Java utility by typing the +following at a console in the Axis2_HOME/samples/quickstartjibx +directory:

+
+%AXIS2_HOME%\bin\wsdl2java -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.service.jibx -d jibx -s -ss -sd -ssi -uw -o build\service
+

Else, simply type "ant generate.service" in the +Axis2_HOME/samples/quickstartjibx directory.

+

The option -d jibx specifies JiBX data binding. The -s switch +specifies synchronous or blocking calls only. The -ss switch +creates the server side code (skeleton and related files). The -sd +switch creates a service descriptor (services.xml file). The -ssi +switch creates an interface for the service skeleton. The -uw +switch unwraps the parameters passed to and from the service +operations in order to create a more natural programming +interface.

+

After running WSDL2Java, the service files should be located at +build/service. If you generated the code by using WSDL2Java +directly, you need to modify the generated skeleton to implement +the service (if you used "ant generate.service" a completed +skeleton will be copied over the generated one automatically). Open +the +build/service/src/samples/quickstart/service/jibx/StockQuoteServiceSkeleton.java +file and modify it to add the functionality of your service to the +generated methods, as shown in Code Listing 8.

+

Code Listing 8: Defining the Service Skeleton File +

+
+package samples.quickstart.service.jibx;
+
+import java.util.HashMap;
+
+public class StockQuoteServiceSkeleton implements StockQuoteServiceSkeletonInterface {
+    private HashMap map = new HashMap();
+
+    public void update(String symbol, Double price) {
+        map.put(symbol, price);
+    }
+
+    public Double getPrice(String symbol) {
+        Double ret = (Double) map.get(symbol);
+        if (ret == null) {
+            ret = new Double(42.0);
+        }
+        return ret;
+    }
+}
+

Now you can build the project by typing the following command in +the build/service directory:

+
+ant jar.server
+

If all goes well, you should see the BUILD SUCCESSFUL message in +your window, and the StockQuoteService.aar file in the +build/service/build/lib directory. Copy this file to the +webapps/axis2/WEB-INF/services directory of the servlet engine.

+

You can check to make sure that the service has been properly +deployed by viewing the list of services at,

+
+http://localhost:8080/axis2/services/listServices
+

You can also check the custom WSDL at,

+
+http://localhost:8080/axis2/services/StockQuoteService?wsdl
+

and the schema at,

+
+http://localhost:8080/axis2/services/StockQuoteService?xsd
+

For more information on using JiBX with Axis2, see the JiBX code generation +integration + details. You can also check the JiBX Axis2 +Wiki page + for updated information about using JiBX with +Axis2.

+ +

Creating Clients

In this section, we'll look at four ways to create clients based +on the StockQuoteService class: building an AXIOM based client, +generating a client using Axis2 Databinding Framework (ADB), +generating a client using XMLBeans, and generating a client using +JiBX.

+ +

Creating a Client with AXIOM

To build a client using AXIOM, execute the following steps.

+

Also, note the directory structure shown in the Creating a +service with AXIOM section, duplicated below for completeness.

+
+- quickstartaxiom
+   - README.txt
+   - build.xml
+   - resources
+     - META-INF
+       - services.xml
+       - StockQuoteService.wsdl
+   - src
+     - samples
+       - quickstart
+         - service
+           - axiom
+             - StockQuoteService.java
+         - clients
+           - AXIOMClient.java
+

The above referenced AXIOMClient.java class is defined as +follows, shown in Code Listing 9.

+

Code Listing 9: The AXIOMClient class using AXIOM +

+
+package samples.quickstart.clients;
+
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.om.OMNamespace;
+import org.apache.axis2.Constants;
+import org.apache.axis2.addressing.EndpointReference;
+import org.apache.axis2.client.Options;
+import org.apache.axis2.client.ServiceClient;
+
+public class AXIOMClient {
+
+    private static EndpointReference targetEPR = 
+        new EndpointReference("http://localhost:8080/axis2/services/StockQuoteService");
+
+    public static OMElement getPricePayload(String symbol) {
+        OMFactory fac = OMAbstractFactory.getOMFactory();
+        OMNamespace omNs = fac.createOMNamespace("http://axiom.service.quickstart.samples/xsd", "tns");
+
+        OMElement method = fac.createOMElement("getPrice", omNs);
+        OMElement value = fac.createOMElement("symbol", omNs);
+        value.addChild(fac.createOMText(value, symbol));
+        method.addChild(value);
+        return method;
+    }
+
+    public static OMElement updatePayload(String symbol, double price) {
+        OMFactory fac = OMAbstractFactory.getOMFactory();
+        OMNamespace omNs = fac.createOMNamespace("http://axiom.service.quickstart.samples/xsd", "tns");
+
+        OMElement method = fac.createOMElement("update", omNs);
+
+        OMElement value1 = fac.createOMElement("symbol", omNs);
+        value1.addChild(fac.createOMText(value1, symbol));
+        method.addChild(value1);
+
+        OMElement value2 = fac.createOMElement("price", omNs);
+        value2.addChild(fac.createOMText(value2,
+                                         Double.toString(price)));
+        method.addChild(value2);
+        return method;
+    }
+
+    public static void main(String[] args) {
+        try {
+            OMElement getPricePayload = getPricePayload("WSO");
+            OMElement updatePayload = updatePayload("WSO", 123.42);
+            Options options = new Options();
+            options.setTo(targetEPR);
+            options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
+
+            ServiceClient sender = new ServiceClient();
+            sender.setOptions(options);
+
+            sender.fireAndForget(updatePayload);
+            System.err.println("price updated");
+            OMElement result = sender.sendReceive(getPricePayload);
+
+            String response = result.getFirstElement().getText();
+            System.err.println("Current price of WSO: " + response);
+
+        } catch (Exception e) {
+            e.printStackTrace();
+        }
+    }
+    
+}
+

Axis2 uses AXIOM, or the AXIs Object Model, a DOM (Document +Object Model)-like structure that is based on the StAX API +(Streaming API for XML). Here you setup the payload for the update +and getPrice methods of the service. The payloads are created +similar to how you created the getPriceResponse payload for the +AXIOM service. Then you setup the Options class, and create a +ServiceClient that you'll use to communicate with the service. +First you call the update method, which is a fireAndForget method +that returns nothing. Lastly, you call the getPrice method, and +retrieve the current price from the service and display it.

+

Now you can build and run the AXIOM client by typing ant +run.client in the Axis2_HOME/samples/quickstartaxiom directory.

+

You should get the following as output:

+
+done
+Current price of WSO: 123.42
+
+

Generating a Client using ADB

To build a client using Axis Data Binding (ADB), execute the +following steps.

+

Generate the client databings by typing the following in the +Axis2_HOME/samples/quickstartadb directory:

+
+%AXIS2_HOME%\bin\WSDL2Java -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.clients -d adb -s -o build\client
+

Else, simply type ant generate.client in the +Axis2_HOME/samples/quickstartadb directory.

+

Next take a look at +quickstartadb/src/samples/quickstart/clients/ADBClient.java, and +see how it's defined in Code Listing 10.

+

Code Listing 10: The ADBClient Class +

+
+package samples.quickstart.clients;
+
+import samples.quickstart.service.adb.StockQuoteServiceStub;
+
+public class ADBClient{
+    public static void main(java.lang.String args[]){
+        try{
+            StockQuoteServiceStub stub =
+                new StockQuoteServiceStub
+                ("http://localhost:8080/axis2/services/StockQuoteService");
+
+            getPrice(stub);
+            update(stub);
+            getPrice(stub);
+
+        } catch(Exception e){
+            e.printStackTrace();
+            System.err.println("\n\n\n");
+        }
+    }
+
+    /* fire and forget */
+    public static void update(StockQuoteServiceStub stub){
+        try{
+            StockQuoteServiceStub.Update req = new StockQuoteServiceStub.Update();
+            req.setSymbol ("ABC");
+            req.setPrice (42.35);
+
+            stub.update(req);
+            System.err.println("price updated");
+        } catch(Exception e){
+            e.printStackTrace();
+            System.err.println("\n\n\n");
+        }
+    }
+
+    /* two way call/receive */
+    public static void getPrice(StockQuoteServiceStub stub){
+        try{
+            StockQuoteServiceStub.GetPrice req = new StockQuoteServiceStub.GetPrice();
+
+            req.setSymbol("ABC");
+
+            StockQuoteServiceStub.GetPriceResponse res =
+                stub.getPrice(req);
+
+            System.err.println(res.get_return());
+        } catch(Exception e){
+            e.printStackTrace();
+            System.err.println("\n\n\n");
+        }
+    }
+
+}
+

This class creates a client stub using the Axis Data Bindings +you created. Then it calls the getPrice and update operations on +the Web service. The getPrice method operation creates the GetPrice +payload and sets the symbol to ABC. It then sends the request and +displays the current price. The update method creates an Update +payload, setting the symbol to ABC and the price to 42.35.

+

Now build and run the client by typing ant run.client in the +Axis2_HOME/samples/quickstartadb directory.

+

You should get the following as output:

+
+42
+price updated
+42.35
+
+

Generating a Client using XMLBeans

To build a client using the XML Beans data bindings, execute the +following steps.

+

Generate the databings by typing the following in the +xmlbeansClient directory.

+
+%AXIS2_HOME%\bin\WSDL2Java -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.service.xmlbeans -d xmlbeans -s -o build\client
+

Else, simply type ant generate.client in the +Axis2_HOME/samples/quickstartxmlbeans directory.

+

Note that this creates a client stub code and no server side +code.

+

Next take a look at +quickstartxmlbeans/src/samples/quickstart/clients/XMLBEANSClient.java, +and see how it's defined in Code Listing 11.

+

Code Listing 11: The XMLBEANSClient class +

+
+package samples.quickstart.clients;
+
+import samples.quickstart.service.xmlbeans.StockQuoteServiceStub;
+import samples.quickstart.service.xmlbeans.xsd.GetPriceDocument;
+import samples.quickstart.service.xmlbeans.xsd.GetPriceResponseDocument;
+import samples.quickstart.service.xmlbeans.xsd.UpdateDocument;
+
+public class XMLBEANSClient{
+
+    public static void main(java.lang.String args[]){
+        try{
+            StockQuoteServiceStub stub =
+                new StockQuoteServiceStub
+                ("http://localhost:8080/axis2/services/StockQuoteService");
+
+            getPrice(stub);
+            update(stub);
+            getPrice(stub);
+
+        } catch(Exception e){
+            e.printStackTrace();
+            System.err.println("\n\n\n");
+        }
+    }
+
+    /* fire and forget */
+    public static void update(StockQuoteServiceStub stub){
+        try{
+            UpdateDocument reqDoc = UpdateDocument.Factory.newInstance();
+            UpdateDocument.Update req = reqDoc.addNewUpdate();
+            req.setSymbol ("BCD");
+            req.setPrice (42.32);
+
+            stub.update(reqDoc);
+            System.err.println("price updated");
+        } catch(Exception e){
+            e.printStackTrace();
+            System.err.println("\n\n\n");
+        }
+    }
+
+    /* two way call/receive */
+    public static void getPrice(StockQuoteServiceStub stub){
+        try{
+            GetPriceDocument reqDoc = GetPriceDocument.Factory.newInstance();
+            GetPriceDocument.GetPrice req = reqDoc.addNewGetPrice();
+            req.setSymbol("BCD");
+
+            GetPriceResponseDocument res =
+                stub.getPrice(reqDoc);
+
+            System.err.println(res.getGetPriceResponse().getReturn());
+        } catch(Exception e){
+            e.printStackTrace();
+            System.err.println("\n\n\n");
+        }
+    }
+}
+

This class creates a client stub using the XML Beans data +bindings you created. Then it calls the getPrice and the update +operations on the Web service. The getPrice method operation +creates the GetPriceDocument, its inner GetPrice classes and sets +the symbol to ABC. It then sends the request and retrieves a +GetPriceResponseDocument and displays the current price. The update +method creates an UpdateDocument, updates and sets the symbol to +ABC and price to 42.32, displaying 'done' when complete.

+

Now build and run the the project by typing ant run.client in +the Axis2_HOME/samples/quickstartxmlbeans directory.

+

You should get the following as output:

+
+42
+price updated
+42.32
+
+

Generating a Client using JiBX

To build a client using JiBX, execute the following steps.

+

Generate the client stub by typing the following at a console in +the Axis2_HOME/samples/quickstartjibx directory.

+
+%AXIS2_HOME%\bin\wsdl2java -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.clients -d jibx -s -uw -o build\client
+

Else, simply type "ant generate.client".

+

Next take a look at +quickstartjibx/src/samples/quickstart/clients/JiBXClient.java, +shown below in Code Listing 12.

+

Code Listing 12: The JiBXClient class +

+
+package samples.quickstart.clients;
+
+import samples.quickstart.service.jibx.StockQuoteServiceStub;
+
+public class JiBXClient{
+    public static void main(java.lang.String args[]){
+        try{
+            StockQuoteServiceStub stub =
+                new StockQuoteServiceStub
+                ("http://localhost:8080/axis2/services/StockQuoteService");
+
+            getPrice(stub);
+            update(stub);
+            getPrice(stub);
+
+        } catch(Exception e){
+            e.printStackTrace();
+            System.err.println("\n\n\n");
+        }
+    }
+
+    /* fire and forget */
+    public static void update(StockQuoteServiceStub stub){
+        try{
+            stub.update("CDE", new Double(42.35));
+            System.err.println("price updated");
+        } catch(Exception e){
+            e.printStackTrace();
+            System.err.println("\n\n\n");
+        }
+    }
+
+    /* two way call/receive */
+    public static void getPrice(StockQuoteServiceStub stub){
+        try{
+            System.err.println(stub.getPrice("CDE"));
+        } catch(Exception e){
+            e.printStackTrace();
+            System.err.println("\n\n\n");
+        }
+    }
+
+}
+

This class uses the created JiBX client stub to access the +getPrice and the update operations on the Web service. The getPrice +method sends a request for the stock "ABC" and displays the current +price. The update method setsnex the price for stock "ABC" to +42.35.

+

Now build and run the client by typing "ant run.client" at a +console in the Axis2_HOME/samples/quickstartjibx directory.

+

You should get the following as output:

+
+42
+price updated
+42.35
+

For more information on using JiBX with Axis2, see the JiBX code generation +integration + details.

+ +

Summary

Axis2 provides a slick and robust way to get web services up and +running in no time. This guide presented five methods of creating a +service deployable on Axis2, and four methods of creating a client +to communicate with the services. You now have the flexibility to +create Web services using a variety of different technologies.

+ +

For Further Study

Apache Axis2-http://ws.apache.org/axis2/ +

+

Axis2 Architecture-http://ws.apache.org/axis2/1_0/Axis2ArchitectureGuide.html +

+

Introduction to Apache Axis2-http://www.redhat.com/magazine/021jul06/features/apache_axis2/ +

+

Working With Apache Axis2-http://www.wso2.net/articles/axis2/java/2006/09/13/working-with-axis2 +

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

Axis2 Reference Guide

+

WSDL2Java Reference

+NAME
+       wsdl2java.sh or wsdl2java.bat - Generates java code according to a given WSDL file to handle Web service invocation.
+       These scripts can be found under the bin directory of the Axis2 distribution.
+
+SYNOPSIS
+       wsdl2java.sh [OPTION]... -uri <Location of WSDL>
+
+DESCRIPTION
+       Given a WSDL file, this generates java code to handle Web service invocations.
+
+      -o <path>          Specify a directory path for the generated code.
+      -a                       Generate async style code only (Default: off).
+      -s                       Generate sync style code only (Default: off). Takes precedence over -a.
+      -p <pkg1>          Specify a custom package name for the generated code.
+      -l <language>      Valid languages are java and c (Default: java).
+      -t                       Generate a test case for the generated code.
+      -ss                      Generate server side code (i.e. skeletons) (Default: off).
+      -sd                      Generate service descriptor (i.e. services.xml). (Default: off). Valid with -ss.
+      -d <databinding>   Valid databinding(s) are adb, xmlbeans, jibx and jaxbri (Default: adb).
+      -g                       Generates all the classes. Valid only with -ss.
+      -pn <port_name>    Choose a specific port when there are multiple ports in the wsdl.
+      -sn <service_name> Choose a specific service when there are multiple services in the wsdl.
+      -u                       Unpacks the databinding classes
+      -r <path>          Specify a repository against which code is generated.
+      -ns2p ns1=pkg1,ns2=pkg2  Specify a custom package name for each namespace specified in the wsdls schema.
+      -ssi                     Generate an interface for the service implementation (Default: off).
+      -wv <version>      WSDL Version. Valid Options : 2, 2.0, 1.1
+      -S                       Specify a directory path for generated source
+      -R                       Specify a directory path for generated resources
+      -em                      Specify an external mapping file
+      -f                       Flattens the generated files
+      -uw                      Switch on un-wrapping.
+      -xsdconfig <file path>   Use XMLBeans .xsdconfig file. Valid only with -d xmlbeans.
+      -ap                      Generate code for all ports
+      -or                      Overwrite the existing classes
+      -b                       Generate Axis 1.x backword compatible code.
+      -sp                      Suppress namespace prefixes (Optimzation that reduces size of soap request/response)
+      -E<key> <value>          Extra configuration options specific to certain databindings. Examples:
+                               -Ebindingfile <path>                   (for jibx) - specify the file path for the binding file
+                               -Etypesystemname <my_type_system_name> (for xmlbeans) - override the randomly generated type system name
+                               -Ejavaversion 1.5                      (for xmlbeans) - generates Java 1.5 code (typed lists instead of arrays)
+                               -Emp <package name> (for ADB) - extension mapper package name
+                               -Eosv (for ADB) - turn off strict validation.
+                               -Ewdc (for xmlbeans) - Generate code with a dummy schema. if someone use this option
+                                  they have to generate the xmlbeans code seperately with the scomp command comes with the
+                                  xmlbeans distribution and replace the Axis2 generated classes with correct classes
+      --noBuildXML             Dont generate the build.xml in the output directory
+      --noWSDL                 Dont generate WSDLs in the resources directory
+      --noMessageReceiver      Dont generate a MessageReceiver in the generated sources
+      --http-proxy-host        Proxy host address if you are behind a firewall
+      --http-proxy-port        Proxy prot address if you are behind a firewall
+      -ep                      Exclude packages - these packages are deleted after codegeneration
+    
+EXAMPLES
+       wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl
+       wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd 
+       wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ../samples -p org.apache.axis2.userguide
+
+

Java2WSDL Reference

+NAME
+       Java2WSDL.sh or Java2WSDL.bat - Generates the appropriate WSDL file for a given java class.
+       These scripts can be found under the bin directory of the Axis2 distribution.
+
+SYNOPSIS
+       Java2WSDL.sh [OPTION]... -cn <fully qualified class name>
+
+DESCRIPTION
+       Given a java class generates a WSDL file for the given java class. 
+
+      -o <output location>                    output directory
+      -of <output file name>                  output file name for the WSDL
+      -sn <service name>                      service name
+      -l <soap address>                       address of the port for the WSDL
+      -cp <class path uri>                    list of classpath entries - (urls)
+      -tn <target namespace>                  target namespace for service
+      -tp <target namespace prefix>           target namespace prefix for service
+      -stn <schema target namespace>          target namespace for schema
+      -stp <schema target namespace prefix>   target namespace prefix for schema
+      -st <binding style>                     style for the WSDL
+      -u <binding use>                        use for the WSDL
+      -nsg <class name>                       fully qualified name of a class that implements NamespaceGenerator
+      -sg <class name>                        fully qualified name of a class that implements SchemaGenerator
+      -p2n [<java package>,<namespace] [<java package>,<namespace]...
+                                              java package to namespace mapping for argument and return types
+      -p2n [all, <namespace>]                 to assign all types to a single namespace
+      -efd <qualified/unqualified>            setting for elementFormDefault (defaults to qualified)
+      -afd <qualified/unqualified>            setting for attributeFormDefault (defaults to qualified)
+      -xc class1 -xc class2...                extra class(es) for which schematype must be generated.
+      -wv <1.1/2.0>                           wsdl version - defaults to 1.1 if not specified
+      -dlb                                    generate schemas conforming to doc/lit/bare style
+    
+EXAMPLES
+       Java2WSDL.sh -cn ../samples/test/searchTool.Search
+       Java2WSDL.sh -cn ../samples/test/searchTool.Search -sn search
+       Java2WSDL.sh -cn ../samples/test/searchTool.Search -u -sn search
+       Java2WSDL.sh -cn ../samples/test/searchTool.Search -sn search -o ../samples/test/wsdl  
+
+
+
+
+
+
+ + + Added: webservices/axis2/site/1_4/rest-ws.html URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4/rest-ws.html?rev=652665&view=auto ============================================================================== --- webservices/axis2/site/1_4/rest-ws.html (added) +++ webservices/axis2/site/1_4/rest-ws.html Thu May 1 14:20:27 2008 @@ -0,0 +1,434 @@ + + + + + + + + + + + + + + + Maven - + + + + + + + +
+ +
+
+
+ RESTful Web Services Support

RESTful Web Services Support

This document presents an introduction on REST and REST with HTTP POST and +GET.

+

Content

+ +

Introduction

WSDL 2.0 HTTP Binding defines a way to implement REST (Representational +State Transfer) with Web services. Axis2 implements the most defined HTTP +binding specification. REST Web services are a reduced subset of the usual +Web service stack.

+

The Axis2 REST implementation assumes the following properties:

+
  1. REST Web services are Synchronous and Request Response in nature.
  2. +
  3. When REST Web services are accessed via GET, the service and the + operations are identified based on the URL. The parameters are assumed as + parameters of the Web service. In this case, the GET based REST Web + services support only simple types as arguments and it should adhere to + the IRI + style +.
  4. +
  5. POST based Web services do not need a SOAP Envelope or a SOAP Body. + REST Web Services do not have Headers and the payload is sent + directly.
  6. +
+

Axis2 can be configured as a REST Container and can be used to send and +receive RESTful Web service requests and responses. REST Web services can be +accessed using HTTP GET and POST.

+ +

REST Web Services with HTTP POST

If REST is enabled, the Axis2 server will act as both a REST endpoint and +a SOAP endpoint. When a message is received, if the content type is text/xml +and if the SOAPAction Header is missing, then the message is treated as a +RESTful Message, if not it is treated as a usual SOAP Message.

+

On sending a message, whether the message is RESTful or not, can be +decided from the client API.
+ +Set a property in the client API.
+

+
...
+Options options = new Options();
+options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);
+...
+

Sample REST - HTTP POST Client

There is an example named, userguide.clients.RESTClient.java found in +AXIS2_HOME/samples/userguide/src/userguide/clients which demonstrates the +usage of the above. It uses the "echo" operation of the +userguide.example1.MyService of the +AXIS2_HOME/samples/userguide/src/userguide/example1.

+

The class source will be as follows:

+
public class RESTClient {
+
+    private static String toEpr = "http://localhost:8080/axis2/services/MyService";
+    
+    public static void main(String[] args) throws AxisFault {
+
+        Options options = new Options();
+        options.setTo(new EndpointReference(toEpr));
+        
+        options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);
+
+        ServiceClient sender = new ServiceClient();
+        sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
+        sender.setOptions(options);
+        OMElement result = sender.sendReceive(getPayload());
+
+        try {
+            XMLStreamWriter writer = XMLOutputFactory.newInstance()
+                    .createXMLStreamWriter(System.out);
+            result.serialize(writer);
+            writer.flush();
+        } catch (XMLStreamException e) {
+            e.printStackTrace();
+        } catch (FactoryConfigurationError e) {
+            e.printStackTrace();
+        }
+    }
+    private static OMElement getPayload() {
+        OMFactory fac = OMAbstractFactory.getOMFactory();
+        OMNamespace omNs = fac.createOMNamespace(
+                "http://example1.org/example1", "example1");
+        OMElement method = fac.createOMElement("echo", omNs);
+        OMElement value = fac.createOMElement("Text", omNs);
+        value.addChild(fac.createOMText(value, "Axis2 Echo String "));
+        method.addChild(value);
+
+        return method;
+    }
+}
+
+ +

Access a REST Web Service via HTTP GET

Axis2 allows users to access Web services that have simple type parameters +via HTTP GET. For example, the following URL requests the Version Service via +HTTP GET. However, the Web service arriving via GET assumes REST. Other +parameters are converted into XML and put into the SOAP body.

+
http://127.0.0.1:8080/axis2/services/Version/getVersion
+
+

The result can be shown in the browser as follows:

+

For example, the following request,

+
http://127.0.0.1:8080/axis2/services/Version/getVersion
+
+will be converted into the following SOAP message for processing by +Axis2.
 
+   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
+      <soapenv:Body>   
+          <axis2:getVersion xmlns:axis2="http://ws.apache.org/goGetWithREST" />
+      </soapenv:Body>
+   </soapenv:Envelope>
+    
+
+

Resources

How I Explained REST to My Wife, By Ryan Tomayko- http://naeblis.cx/articles/2004/12/12/rest-to-my-wife +

+

Building Web Services the REST Way, By Roger L. Costello- +http://www.xfront.com/REST-Web-Services.html +

+

Resource-oriented vs. activity-oriented Web services, By James Snell- http://www-128.ibm.com/developerworks/webservices/library/ws-restvsoap/ +

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