Return-Path: Delivered-To: apmail-xml-axis-dev-archive@xml.apache.org Received: (qmail 63402 invoked by uid 500); 30 Jul 2001 22:08:18 -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 63392 invoked by uid 500); 30 Jul 2001 22:08:17 -0000 Delivered-To: apmail-xml-axis-cvs@apache.org Received: (qmail 63385 invoked from network); 30 Jul 2001 22:08:17 -0000 Received: from h32.sny.collab.net (HELO icarus.apache.org) (64.208.42.42) by h31.sny.collab.net with SMTP; 30 Jul 2001 22:08:17 -0000 Received: (qmail 42693 invoked by uid 1144); 30 Jul 2001 22:03:59 -0000 Date: 30 Jul 2001 22:03:59 -0000 Message-ID: <20010730220359.42692.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: h31.sny.collab.net 1.6.2 0/1000/N gdaniels 01/07/30 15:03:59 Modified: java/docs user-guide.html Log: More edits, still not done... Revision Changes Path 1.2 +71 -10 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.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- user-guide.html 2001/07/25 21:06:41 1.1 +++ user-guide.html 2001/07/30 22:03:59 1.2 @@ -15,6 +15,7 @@ +

Axis User's Guide

Alpha 1 Version

Table of Contents

@@ -67,8 +68,7 @@ "axis-dev@xml.apache.org"

What is SOAP?

-TBD - links to SOAP information sites, brief description... - +SOAP is an XML

What's in this release?

This release contains:

    @@ -175,8 +175,8 @@

    You'll note the param is now named "testParam" as expected.

    -

    OK - so now you know how to access SOAP services as a client. But how do you - publish your own services?

    +

    OK - so now you know the basics of accessing SOAP services as a client. But + how do you publish your own services?

    Publishing Web Services with Axis

    Let's say we have a simple class like the following:

    public class Calculator {
  @@ -214,14 +214,75 @@
   Got result : 1
   %

    Custom Deployment - deploy.xml files and the AdminClient

    -TBD - explanation of the AdminClient and the deploy.xml -file. Link to the deployment reference. -

    XML <-> Java Data Mapping in Axis

    +

    JWS files are great quick ways to get your classes out there as Web Services, + but they're not always the best choice. For one thing, you need the source code + - there might be times when you want to expose a pre-existing class on your + 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.

    +
    <admin:deploy xmlns:admin="AdminService">
  + <service name="MyService" pivot="RPCDispatcher">
  +  <option name="classname" value="MyService"/>
  +  <option name="methods" value="*"/>
  + </service>
  +</admin:deploy>
    +

    Pretty simple, really - the outermost element tells the engine that this is + a deployment (other options are "undeploy" and "list" - + see the deployment reference). Then we deploy a service

    +

    Now let's start to explore some of the more powerful features of the Axis engine. + Let's say you want to track how many times your service has been called, and + by whom.

    +
    <admin:deploy xmlns:admin="AdminService">
  + <!-- define the logging handler configuration -->
  + <handler name="track" class="org.apache.axis.handlers.LogHandler">
  +  <option name="filename" value="MyService.log"/>
  + </handler>
  +
  + <!-- define the service, using the log handler we just defined -->
  + <service name="MyService" request="track" pivot="RPCDispatcher">
  + </service>
  +</admin:deploy>
    +

    Remote Administration

    +

    Note that by default, the Axis server is configured to only accept administration + requests from the machine on which it resides - if you wish to enable remote + administration, you must set the "enableRemoteAdmin" property of the + AdminService to true. To do this, find the "server-config.xml" + file in your webapp's WEB-INF directory. In it, you'll see a deployment for + the AdminService. Add an option as follows:

    +
    <service name="AdminService" pivot="RPCDispatcher">
  + <option name="className" value="org.apache.axis.util.Admin"/>
  + <option name="methodName" value="*"/>
  + <option name="enableRemoteAdmin" value="true"/>
  +</service>
    +

    WARNING: enabling remote administration may give unauthorized parties access + to your machine. If you do this, please make sure to add security to your configuration!
    +

    +

    XML <-> Java Data Mapping in Axis

    Encoding Your Beans - the BeanSerializer

    -

    TBD - how to use bean mappings

    +

    Axis includes the ability to serialize arbitrary Java classes which follow + the standard JavaBean pattern of get/set accessors. All you need to do is tell + Axis which Java classes map to which XML Schema types. Configuring a bean mapping + looks like this:

    +

    <beanMapping>

    +

    Let's take a look at how this works. Go look at the docs/examples/example4/BeanService.java + file. (we won't reproduce it here, it's pretty basic) The key thing to notice + is that the argument to the service method is an Order object. Since Order is + not a basic type which Axis understands by default, trying to run the service + without a type mapping will result in a fault (if you want to try this for yourself, + you can use the simple-deploy.xml file in the example4 directory). But if we + put a beanMapping into our deployment, all will be well.

    When Beans Are Not Enough - Custom Serialization

    -TBD - explanation of custom serializers/deserializers, -and how to use the contexts. +

    Just as JWS deployment is sometimes not flexible enough to meet all needs, + the default bean serialization model isn't robust enough to handle every case + either. At times there will be non-bean Java classes (especially in the case + of pre-existing assets) which you need to map to/from XML, and there also may + be some custom XML schema types which you want to map into Java in particular + ways. Axis gives you the ability to write custom serializers/deserializers, + and some tools to help make your life easier when you do so.

    +

    TBD - this section will be expanded in a future version! + 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.

    Deployment Reference

    Note: this reference reflects the state of the deploy.xml structure as of the alpha 1 release. This will very likely change in a subsequent release to