Return-Path: Delivered-To: apmail-xml-axis-dev-archive@xml.apache.org Received: (qmail 25013 invoked by uid 500); 20 Sep 2001 04:01:11 -0000 Mailing-List: contact axis-dev-help@xml.apache.org; run by ezmlm Precedence: bulk Reply-To: axis-dev@xml.apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list axis-dev@xml.apache.org Received: (qmail 25004 invoked by uid 500); 20 Sep 2001 04:01:11 -0000 Delivered-To: apmail-xml-axis-cvs@apache.org Date: 20 Sep 2001 03:54:53 -0000 Message-ID: <20010920035453.38486.qmail@icarus.apache.org> From: gdaniels@apache.org To: xml-axis-cvs@apache.org Subject: cvs commit: xml-axis/java/docs user-guide.html X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N gdaniels 01/09/19 20:54:53 Modified: java/docs user-guide.html Log: More updates for alpha-2 Revision Changes Path 1.15 +70 -21 xml-axis/java/docs/user-guide.html Index: user-guide.html =================================================================== RCS file: /home/cvs/xml-axis/java/docs/user-guide.html,v retrieving revision 1.14 retrieving revision 1.15 diff -u -r1.14 -r1.15 --- user-guide.html 2001/09/19 03:51:37 1.14 +++ user-guide.html 2001/09/20 03:54:52 1.15 @@ -26,7 +26,8 @@ Consuming Web Services with Axis
Publishing Web Services with Axis
XML <-> Java Data Mapping in Axis
-
+ Using WSDL with Axis
+
Deployment Reference
Glossary

Introduction

@@ -103,6 +104,7 @@
  • Support for the SOAP with Attachments specification
  • Supprt for multi-dimensional arrays
  • Support for the SOAP actor attribute +
  • Support for generating complex type definitions in WSDL
  • A final deployment descriptor syntax (WSDD)

    • All of these items are on the list for the final release.

    @@ -297,7 +299,7 @@ system without source. Also, the amount of configuration you can do as to how the service gets accessed is pretty limited - you can't specify custom type mappings, or control which Handlers get invoked when people are using your service.

    -

    Deploying via descriptors

    +

    Deploying via descriptors

    To really use the flexibility available to you in Axis, you should get familiar with the Axis deployment descriptor format (note: this particular XML format is just for the alpha release. Axis plans to move to using WSDD (Web Service @@ -437,7 +439,7 @@ For now, take a look at the ArraySerializer, the BeanSerializer (both in org.apache.axis.encoding), and the DataSer example (in samples/encoding) to see how custom serializers work.

    -

    Using WSDL with Axis

    +

    Using WSDL with Axis

    The Web Service Description Language is a specification authored by IBM and Microsoft, and supported by many other organizations. WSDL serves to describe Web Services in a structured way. A WSDL @@ -478,28 +480,45 @@ In other words, you don't need to deal with the endpoint URL, namespace, or parameter arrays which are involved in dynamic invocation via the ServiceClient. The stub hides all that work for you.

    -

    Insert example here

    +

    You can try an example, assuming you've deployed the service in example + 3 above and have your Axis server up and running. Type the following at + the command line:

    +
    % java org.apache.axis.wsdl.Wsdl2java http://localhost:8080/axis/services/MyService?wsdl
    +

    You can add the "--verbose" option right before the URL if you want + some more feedback on what the tool is up to. This will generate stub code, + which we'll describe.

    Wsdl2java generates a few classes; here's a rundown of what they are and how to use them:

    • There will be an interface for each referenced PortType in the WSDL. These - interfaces are the ones you will actually use to call the remote methods. -
      • + interfaces are the ones you will actually use to call the remote methods, + as they contain the operations described in the WSDL. For the example, above, + the generated interface is called MyServicePortType.
    • The Stub classes implement the interface, and contain the code which turns - the method invocations into SOAP calls using the Axis ServiceClient.
      • -
    • The Service class serves as a factory for obtaining Stub instances
      • + the method invocations into SOAP calls using the Axis ServiceClient. For the + example, this is MyServiceSoapBindingStub. The stubs themselves also have + a few additional methods for getting a little more control over the SOAP invocations + - in this version of Axis we won't go into more detail about these, though + you can read the code if you're inclined. +
    • The Service class serves as a factory for obtaining Stub instances - MyService + for our example. The Service class will by default make a Stub which points + to the endpoint URL described in the WSDL file, but you may also specify a + different URL when you ask for the PortType.

    So a typical usage of the stub classes would be as follows:

    public class Tester {
  -  public static void main(String [] args)
  +  public static void main(String [] args) throws Exception
     {
  -    Service service = new Service();
  +    // Make a service (PortType factory)
  +    MyService service = new MyService();
   
   
  -    // Now use the service to get a PortType that we can call
  -    PortType port = service.getPort();
  -
  -    port.method(5, 4);
  +    // Now use the service to get a PortType that we can call.
  +    MyServicePortType port = service.getMyServicePort();
  + 
  +    // Make the actual call
  +    String ret = port.serviceMethod("test string");
  +    System.out.println("Return val was " + ret);
     }
   }

    Skeletons - frameworks for implementing Web Services

    @@ -509,17 +528,22 @@ you might want to join a digital marketplace which requires you to make your inventory available via a particular Web Service interface.

    To make skeleton classes, you just specify the "--skeleton" option - to Wsdl2java.

    -

    Insert example here

    + to Wsdl2java. For instance, if we wanted to replicate the service in the last + example, we'd type:

    +
    % java org.apache.axis.wsdl.Wsdl2java --skeleton http://localhost:8080/axis/services/MyService?wsdl

    There are a couple of classes produced by the skeleton generator, so let's take a look at them:

      -
    • The Skeleton proper (in our example, TemperatureBindingSkeleton) +
    • The Skeleton proper (in our example, MyServiceSoapBindingSkeleton) is the class you'll actually deploy as an Axis service. You won't need to edit the code in here at all.
      • -
    • The Implementation class (TemperatureBindingImpl) is the actual framework - class which you'll flesh out with your own code.
      • +
    • The Implementation class (MyServiceSoapBindingImpl) is the actual + framework class which you'll flesh out with your own code.
    +The tool also builds you a "deploy.xml" and an "undeploy.xml" +for use with the AdminClient. These files may be used to deploy the service once +you've filled in the methods of the Implementation class, compiled the code, and +made the classes available to your Axis engine.

    Data Types for Stubs and Skeletons

    WSDL files can contain (or reference) XML Schema describing the data types @@ -564,7 +588,13 @@ response="handler" pivot="handler" > -

    Deploys/undeploys an Axis Service.
    +
    Deploys/undeploys an Axis Service. Common options for this element (i.e. + subelements of the form <option name="name" value="value"/> + include:
    + className : the backend implementation class
    + methodName : the allowed methods
    + allowedRoles : comma-separated list of roles allowed to access this + service

    <chain name="    name" flow="handler handler...">
    @@ -608,6 +638,25 @@
    EchoHandler
    The EchoHandler copies the request message into the response message. +
    HTTPAuth +
    The HTTPAuthHandler takes HTTP-specific authentication information (right + now, just Basic authentication) and turns it into generic MessageContext properties + for username and password +
    SimpleAuthenticationHandler +
    The SimpleAuthentication handler passes a MessageContext to a SecurityProvider + (see org.apache.axis.security) to authenticate the user using whatever information + the SecurityProvider wants (right now, just the username and password). +
    SimpleAuthorizationHandler +
    This handler, typically deployed alongside the SimpleAuthenticationHandler + (a chain called "authChecks" is predefined for just this combination), + checks to make sure that the currently authenticated user satisfies one of + the allowed roles for the target service. Throws a Fault if access is denied. +
    URLMapper +
    The URLMapper, an HTTP-specific handler, usually goes on HTTP transport + chains (it is deployed by default). It serves to do service dispatch based + on URL - for instance, this is the Handler which allows URLs like http://localhost:8080/axis/services/MyService?wsdl + to work. +
     
    RPCDispatcher
    The RPCDispatcher is the pivot point for all RPC services. It accepts the @@ -615,7 +664,7 @@ className = the class of the backend object to invoke
    methodName = a space-separated list of methods which are exported as web services. The special value "*" matches all public methods - in the class. + in the class.
    MsgDispatcher
    The MsgDispatcher is the pivot point for all messaging services. It accepts