You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by gd...@apache.org on 2001/07/31 00:03:59 UTC
cvs commit: xml-axis/java/docs user-guide.html
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 @@
</head>
<body bgcolor="#FFFFFF" text="#000000">
+<h1 align="center"><img src="axis.jpg" width="176" height="96"></h1>
<h1>Axis User's Guide</h1>
<p><i>Alpha 1 Version</i></p>
<h3>Table of Contents</h3>
@@ -67,8 +68,7 @@
"<a href="mailto:axis-dev@xml.apache.org">axis-dev@xml.apache.org</a>"
</p>
<h3>What is SOAP?</h3>
-<i><font color="#FF0000">TBD - links to SOAP information sites, brief description...
-</font></i>
+SOAP is an XML <i></i>
<h3>What's in this release?</h3>
<p>This release contains:</p>
<ul>
@@ -175,8 +175,8 @@
</div>
<p>You'll note the param is now named "testParam" as expected.</p>
-<p>OK - so now you know how to access SOAP services as a client. But how do you
- publish your own services?</p>
+<p>OK - so now you know the basics of accessing SOAP services as a client. But
+ how do you publish your own services?</p>
<h2><a name="PublishingServices"></a>Publishing Web Services with Axis</h2>
<p>Let's say we have a simple class like the following:</p>
<pre class="example">public class Calculator {
@@ -214,14 +214,75 @@
Got result : 1
% </pre>
<h3>Custom Deployment - deploy.xml files and the AdminClient</h3>
-<font color="#FF0000"><i>TBD - explanation of the AdminClient and the deploy.xml
-file. Link to the deployment reference.</i></font>
-<h2><a name="DataMapping"></a>XML <-> Java Data Mapping in Axis</h2>
+<p>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.</p>
+<pre><admin:deploy xmlns:admin="AdminService">
+ <service name="MyService" pivot="RPCDispatcher">
+ <option name="classname" value="MyService"/>
+ <option name="methods" value="*"/>
+ </service>
+</admin:deploy></pre>
+<p>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</p>
+<p>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.</p>
+<pre><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></pre>
+<h4>Remote Administration</h4>
+<p>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 <b>true</b>. 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:</p>
+<pre><service name="AdminService" pivot="RPCDispatcher">
+ <option name="className" value="org.apache.axis.util.Admin"/>
+ <option name="methodName" value="*"/>
+ <b><option name="enableRemoteAdmin" value="true"/></b>
+</service></pre>
+<p><b>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!</b><br>
+ <i><font color="#FF0000"></font></i> </p>
+<i><font color="#FF0000"></font></i><h2><a name="DataMapping"></a>XML <-> Java Data Mapping in Axis</h2>
<h3>Encoding Your Beans - the BeanSerializer</h3>
-<p><i><font color="#FF0000">TBD - how to use bean mappings</font></i> </p>
+<p>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:</p>
+<p><beanMapping></p>
+<p>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.</p>
<h3>When Beans Are Not Enough - Custom Serialization</h3>
-<i><font color="#FF0000">TBD - explanation of custom serializers/deserializers,
-and how to use the contexts.</font></i>
+<p>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.</p>
+<p><i><font color="#FF0000">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. </font></i></p>
<h2><a name="DeploymentReference"></a>Deployment Reference</h2>
<i>Note: this reference reflects the state of the deploy.xml structure as of the
alpha 1 release. This will <b>very likely change</b> in a subsequent release to