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/08/01 23:29:59 UTC
cvs commit: xml-axis/java/docs user-guide.html
gdaniels 01/08/01 14:29:59
Modified: java/docs user-guide.html
Log:
More work...
Revision Changes Path
1.3 +71 -15 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- user-guide.html 2001/07/30 22:03:59 1.2
+++ user-guide.html 2001/08/01 21:29:59 1.3
@@ -85,8 +85,13 @@
<li>An HTTP servlet-based transport</li>
<li>A standalone version of the server (HTTP)</li>
<li>Examples, including a client and server for the soapbuilders community interoperability
- tests </li>
+ tests</li>
</ul>
+<h3>What's missing?</h3>
+<ul>
+ <li>Nuttin.</li>
+ <li>Well, OK, sumpin.</li>
+</ul>
<h2><a name="Installation"></a>Installing Axis</h2>
See the <a href="file:///E|/Documents/Axis/install.html">Axis Installation Guide</a> for instructions on
installing Axis.
@@ -220,6 +225,8 @@
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>
+<h4>Deploying via descriptors</h4>
+One way blah blah blah.
<pre><admin:deploy xmlns:admin="AdminService">
<service name="MyService" pivot="RPCDispatcher">
<option name="classname" value="MyService"/>
@@ -228,20 +235,43 @@
</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>
+ see the deployment reference). Then we deploy a service.</p>
+<h4>Using the AdminClient</h4>
+<p>Once we've got this file, we need to send it to an Axis server in order to
+ actually deploy the described service. We do this with the AdminClient, or the
+ "org.apache.axis.client.AdminClient" class. An invocation of the AdminClient
+ looks like this:</p>
+<pre>% java org.apache.axis.client.AdminClient deploy.xml
+<??><admin>done processing</admin></pre>
+<p>This </p>
+<h4>More deployment - Handlers and Chains</h4>
<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>
+ Let's say you want to track how many times your service has been called. We've
+ included a sample handler in the samples/log directory to do just this. To use
+ a handler class like this, you first need to deploy the Handler itself, and
+ then use the name that you give it in deploying a service. Here's a sample deploy.xml
+ file: </p>
<pre><admin:deploy xmlns:admin="AdminService">
<!-- define the logging handler configuration -->
- <handler name="track" class="org.apache.axis.handlers.LogHandler">
+ <handler name="track" class="samples.log.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>
+ <service name="MyService" <b>request="track"</b> pivot="RPCDispatcher">
+ <option name="className" value="samples.log.Service"/>
+ <option name="methodName" value="*"/>
+</service>
</admin:deploy></pre>
+<p>The first section defines a Handler called "track" which is implemented
+ by the class "samples.log.LogHandler". We give this Handler an option
+ to let it know which file to write its messages into.</p>
+<p>Then we define a service, "MyService", which is an RPC server just
+ like we saw above in our first example. The difference is the "request"
+ attribute - this indicates a Handler (or set of Handlers) which should be invoked
+ when the service is invoked, before the pivot handler. By setting this to "track",
+ we ensure that the message will be logged each time this service is invoked.<br>
+</p>
<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
@@ -263,14 +293,40 @@
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>
+<pre class="xml"><beanMappings>
+ <ns:local xmlns:ns="someNamespace" classname="my.java.thingy"/>
+</beanMappings></pre>
+<p>Inside the <beanMappings> element is an arbitrary number of other elements,
+ each of which maps a Java class (presumably a bean) to an XML QName. The QName
+ of the element itself is the XML QName, and the value of the classname attribute
+ is the Java class name. So in this case, we'd be mapping the "my.java.thingy"
+ class to the XML QName [someNamespace]:[local].</p>
+<p>Let's take a look at how this works in practice. Go look at the docs/examples/example4/BeanService.java
+ file. (we won't reproduce it here, it's pretty straightforward) 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 this
+ service without a type mapping will result in a fault (if you want to try this
+ for yourself, you can use the bad-deploy.xml file in the example4 directory).
+ But if we put a beanMapping into our deployment, all will be well. Here's how
+ to run this example (from the example4 directory):</p>
+<pre class="example">% java org.apache.axis.client.AdminClient -llocal:// deploy.xml
+<?xml version="1.0" encoding="UTF-8"?><Admin>Done processing</Admin>
+
+
+% java Client -llocal:// -n "Glen"
+Hi, Glen!
+
+
+You seem to have ordered the following:
+
+
+1 of item : mp3jukebox
+4 of item : 1600mahBattery
+
+
+If this had been a real order processing system, we'd probably have charged you about now.
+%<br>
+</pre>
<h3>When Beans Are Not Enough - Custom Serialization</h3>
<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