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 to...@apache.org on 2004/10/22 12:49:15 UTC
cvs commit: ws-axis/site/src/documentation/content/xdocs/java architecture-guide.ihtml building-axis.ihtml index.ihtml integration-guide.ihtml reference.ihtml developers-guide.ihtml install.ihtml user-guide.ihtml
toshi 2004/10/22 03:49:15
Modified: site/src/documentation/content/xdocs/java
architecture-guide.ihtml building-axis.ihtml
index.ihtml integration-guide.ihtml reference.ihtml
developers-guide.ihtml install.ihtml
user-guide.ihtml
Log:
Fixing 'ws-axis/java/docs' issues;
Revision Changes Path
1.3 +22 -29 ws-axis/site/src/documentation/content/xdocs/java/architecture-guide.ihtml
Index: architecture-guide.ihtml
===================================================================
RCS file: /home/cvs/ws-axis/site/src/documentation/content/xdocs/java/architecture-guide.ihtml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- architecture-guide.ihtml 16 Oct 2003 21:44:08 -0000 1.2
+++ architecture-guide.ihtml 22 Oct 2004 10:49:15 -0000 1.3
@@ -19,7 +19,7 @@
<H1>Axis Architecture Guide</H1>
<P><BR>
- <I>1.1 Version</I><BR>
+ <I>1.2 Version</I><BR>
<I>Feedback: <A href=
"mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</A></I></P>
@@ -410,16 +410,12 @@
<H3><A name="D13n"></A>Deserialization</H3>
- <P>The class mainly responsible for XML parsing, i.e.
- deserialization, is DeserializationContextImpl ('DCI') which
- inherits most of its methods from the DeserializationContext
- interface. DCI manages the construction of the parse tree and
- maintains a stack of SAX handlers, a reference to the
- MessageElement that is currently being deserialized, a stack of
- namespace mappings, a mapping from IDs to elements, a set of type
- mappings for deserialization (see <A href=
- "#Encoding%20Subsystem">Encoding Subsystem</A>) and a SAX event
- recorder.</P>
+ <P>The class mainly responsible for XML parsing, i.e. deserialization, is DeserializationContext
+ ('DC'). DC manages the construction of the parse tree and maintains a stack of
+ SAX handlers, a reference to the MessageElement that is currently being deserialized,
+ a stack of namespace mappings, a mapping from IDs to elements, a set of type mappings
+ for deserialization (see <a href="#Encoding Subsystem">Encoding Subsystem</a>)
+ and a SAX event recorder. </P>
<P>Elements that we scan over, or ones for which we don't have a
particular deserializer, are recorded - in other words, the SAX
@@ -445,24 +441,21 @@
constructed with a reference to an EnvelopeBuilder, which is the
SAX handler responsible for parsing the SOAP envelope.</P>
- <P>During parsing, DCI receives the events from the SAX parser
- and notifies either the SAX handler on the top of its handler
- stack, the SAX event recorder, or both.</P>
-
- <P>On the start of an element, DCI calls the SAX handler on the
- top of its handler stack for onStartChild. This method returns a
- SAX handler to be used to parse the child, which DCI pushes on
- its SAX handler stack and calls for startElement. startElement,
- amongst other things, typically creates a new MessageElement of
- the appropriate class and calls DCI for pushNewElement. The
- latter action creates the parent-child relationships of the parse
- tree.</P>
-
- <P>On the end of an element, DCI pops the top SAX handler from
- its handler stack and calls it for endElement. It then drives SAX
- handler which is now on the top of the handler stack for
- onEndChild. Finally, it sets the MessageElement that is currently
- being deserialized to the parent of the current one.</P>
+ <P>During parsing, DC receives the events from the SAX parser and notifies either
+ the SAX handler on the top of its handler stack, the SAX event recorder, or
+ both.</P>
+
+ <P>On the start of an element, DC calls the SAX handler on the top of its handler
+ stack for onStartChild. This method returns a SAX handler to be used to parse
+ the child, which DC pushes on its SAX handler stack and calls for startElement.
+ startElement, amongst other things, typically creates a new MessageElement of
+ the appropriate class and calls DC for pushNewElement. The latter action creates
+ the parent-child relationships of the parse tree. </P>
+
+ <P>On the end of an element, DC pops the top SAX handler from its handler stack
+ and calls it for endElement. It then drives SAX handler which is now on the
+ top of the handler stack for onEndChild. Finally, it sets the MessageElement
+ that is currently being deserialized to the parent of the current one.</P>
<P>Elements which are not defined by SOAP are treated using a
SOAPHandler as a SAX event handler and a MessageElement as a node
1.3 +1 -1 ws-axis/site/src/documentation/content/xdocs/java/building-axis.ihtml
Index: building-axis.ihtml
===================================================================
RCS file: /home/cvs/ws-axis/site/src/documentation/content/xdocs/java/building-axis.ihtml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- building-axis.ihtml 16 Oct 2003 21:44:08 -0000 1.2
+++ building-axis.ihtml 22 Oct 2004 10:49:15 -0000 1.3
@@ -18,7 +18,7 @@
<H1>Guide to building Axis</H1>
- <P><I>1.1 Version</I><BR>
+ <P><I>1.2 Version</I><BR>
<I>Feedback: <A href=
"mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</A></I></P>
1.4 +1 -1 ws-axis/site/src/documentation/content/xdocs/java/index.ihtml
Index: index.ihtml
===================================================================
RCS file: /home/cvs/ws-axis/site/src/documentation/content/xdocs/java/index.ihtml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- index.ihtml 21 Feb 2004 23:14:18 -0000 1.3
+++ index.ihtml 22 Oct 2004 10:49:15 -0000 1.4
@@ -20,7 +20,7 @@
<H1>Documentation</H1>
<P>This is the documentation for <A href=
- "http://ws.apache.org/axis/">Apache Axis 1.1</A> If the version
+ "http://ws.apache.org/axis/">Apache Axis 1.2</A> If the version
of Axis you are using is older or newer than this version, then
this is the wrong documentation to be using. Read the version
that came with your copy of Axis.</P>
1.5 +1 -1 ws-axis/site/src/documentation/content/xdocs/java/integration-guide.ihtml
Index: integration-guide.ihtml
===================================================================
RCS file: /home/cvs/ws-axis/site/src/documentation/content/xdocs/java/integration-guide.ihtml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- integration-guide.ihtml 17 Jun 2004 09:49:39 -0000 1.4
+++ integration-guide.ihtml 22 Oct 2004 10:49:15 -0000 1.5
@@ -18,7 +18,7 @@
<H1>Axis System Integration Guide</H1>
- <P><I>1.1 Version</I><BR>
+ <P><I>1.2 Version</I><BR>
<I>Feedback: <A href=
"mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</A></I></P>
1.8 +106 -16 ws-axis/site/src/documentation/content/xdocs/java/reference.ihtml
Index: reference.ihtml
===================================================================
RCS file: /home/cvs/ws-axis/site/src/documentation/content/xdocs/java/reference.ihtml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- reference.ihtml 17 Jun 2004 09:49:39 -0000 1.7
+++ reference.ihtml 22 Oct 2004 10:49:15 -0000 1.8
@@ -12,12 +12,13 @@
</HEAD>
<BODY>
- <H1 align="center"><IMG height="96" src="images/axis.jpg" width=
- "176"></H1>
+ <CENTER>
+ <H1><IMG src="images/axis.jpg" height="96" width="176"></H1>
+ </CENTER>
<H1>Axis Reference Guide</H1>
- <P><I>1.1 Version</I><BR>
+ <P><I>1.2 Version</I><BR>
<I>Feedback: <A href=
"mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</A></I></P>
@@ -99,8 +100,7 @@
<argument><BR>
override all namespace to package mappings, use this package<BR>
-
- name instead<BR>
+ name instead<BR>
-o, --output
<argument><BR>
@@ -118,16 +118,26 @@
-T,
--typeMappingVersion<BR>
- indicate 1.1 or 1.2. The default is 1.1 (SOAP 1.1 JAX-RPC
- compliant.
+ indicate 1.1 or 1.2. The default is 1.1 (SOAP 1.1 JAX-RPC compliant.<BR>
1.2 indicates SOAP 1.1 encoded.)<BR>
-F, --factory
<argument><BR>
- name of a custom class that implements GeneratorFactory interface
+ name of a custom class that implements GeneratorFactory interface<BR>
(for extending Java generation functions)<BR>
+ -i, --nsInclude <namespace><BR>
+
+ namescape to specifically include in the generated code (defaults to<BR>
+ all namespaces unless specifically excluded with the -x option)<BR>
+ -x, --nsExclude <namespace><BR>
+
+ namespace to specifically exclude from the generated code (defaults to<BR>
+ none excluded until first namespace included with -i option)<BR>
+ -p, --property <name>=<value><BR>
+
+ name and value of a property for use by the custom GeneratorFactory<BR>
-H, --helperGen<BR>
emits separate Helper classes for meta data<BR>
@@ -139,7 +149,9 @@
<argument><BR>
password to access the WSDL-URI<BR>
-
+ -c, --implementationClassName <argument><BR>
+
+ use this as the implementation class<BR>
</TT>
</P>
<TT>
@@ -369,8 +381,17 @@
<H4>-P, --password <argument></H4>
<P>This password is used in resolving the WSDL-URI provided as
- the input to WSDL2Java. If the URI contains a password, this
- will override the command line switch. </P>
+ the input to WSDL2Java. If the URI contains a password, this
+ will override the command line switch.<br>
+
+ <H4> -c, --implementationClassName <argument></H4>
+
+ <P>Set the name of the implementation class.Especially useful when
+ exporting an existing class as a web service using java2wsdl
+ followed by wsdl2java. If you are using the skeleton deploy option you must make sure, after generation,
+ that your implementation class implements the port type name interface generated
+ by wsdl2java. You should also make sure that all your exported methods throws
+ java.lang.RemoteException.</P>
</TT>
<H3><A name="Java2WSDL"></A>Java2WSDL Reference</H3>
@@ -440,6 +461,11 @@
-e, --extraClasses <argument>
A space or comma separated list of class names to be added to
the type section.
+ -C, --importSchema
+ A file or URL to an XML Schema that should be physically
+ imported into the generated WSDL
+ -X, --classpath
+ additional classpath elements
Details:
portType element name= <--portTypeName value> OR <class-of-portType name>
binding element name= <--bindingName value> OR <--servicePortName value>Soap
@@ -448,9 +474,7 @@
Service
port element name= <--servicePortName value>
address location = <--location value>
-</TT>
-</FONT>
-</PRE>
+</TT></FONT></PRE>
<TT>
<P><B>-h , --help</B><BR>
Prints the help message.</P>
@@ -585,6 +609,13 @@
--extraClasses option can be specified duplicate times. Each
specification results in the additional classes being added to
the list.</P>
+
+ <P> <strong>-C, --importSchema</strong><br>
+ A file or URL to an XML Schema that should be physically imported into the generated WSDL</P>
+ <P><br>
+ <strong>-X, --classpath</strong><br>
+ Additional classpath elements</P>
+ <P> </P>
</TT>
<H2><A name="Deployment"></A>Deployment (WSDD) Reference</H2>
@@ -601,6 +632,37 @@
may represent EITHER a complete engine configuration OR a set
of components to deploy into an active engine.</DD>
+ <dt><br>
+ <b><font face="Courier New, Courier, mono"><GlobalConfiguration></font></b></dt>
+
+ <dd>This element is used to control the engine-wide configuration of Axis. It
+ may contain several subelements:
+ <ul>
+ <li><b><parameter></b> : This is used to set options on the Axis engine
+ - see the <a href="#global_configuration">Global Axis Configuration</a>
+ section below for more details. Any number of <strong><parameter></strong>
+ elements may appear.</li>
+ <li><strong><role></strong> : This is used to set a SOAP actor/role
+ URI which the engine will recognize. This allows SOAP headers targeted
+ at that role to be successfully processed by the engine. Any number of
+ <strong><role></strong> elements may appear.</li>
+ <li><strong><requestFlow></strong> : This is used to configure global
+ request Handlers, which will be invoked before the actual service on every
+ request. You may put any number of <strong><handler></strong> or
+ <strong><chain></strong> elements (see below) inside the <strong><requestFlow></strong>,
+ but there may only be one <strong><requestFlow></strong>.</li>
+ </ul>
+ </dd>
+ <dd>
+ <ul>
+ <li><strong><responseFlow></strong> : This is used to configure global
+ response Handlers, which will be invoked after the actual service on every
+ request. You may put any number of <strong><handler></strong> or
+ <strong><chain></strong> elements (see below) inside the <strong><responseFlow></strong>,
+ but there may only be one <strong><responseFlow></strong>.</li>
+ </ul>
+ </dd>
+
<DT> </DT>
<DT><B><FONT face=
@@ -701,7 +763,9 @@
</LI>
<LI><B>allowedRoles</B> : comma-separated list of roles
- allowed to access this service<BR></LI>
+ allowed to access this service (Note that these are security roles,
+ as opposed to SOAP roles. Security roles control access, SOAP roles
+ control which SOAP headers are processed.) <BR></LI>
</UL><BR>
If you wish to define handlers which should be invoked either
before or after the service's provider, you may do so with
@@ -713,6 +777,9 @@
words, they may contain <B><handler></B> and
<B><chain</B>> elements which will be invoked in the
order they are specified.<BR>
+ <P>To control the <a href="http://www.w3.org/TR/2003/REC-soap12-part1-20030624/#soaproles">roles</a>
+ that should be recognized by your service Handlers, you can specify any
+ number of <b><role></b> elements inside the service declaration.</P>
<BR>
Example:<BR>
<PRE>
@@ -720,6 +787,7 @@
<parameter name="className" value="test.Implementation"/>
<parameter name="allowedMethods" value="*"/>
<namespace>http://testservice/</namespace>
+ <role>http://testservice/MyRole</role>
<requestFlow> <!-- Run these before processing the request -->
<handler type="java:MyHandlerClass"/>
<handler type="somethingIDefinedPreviously"/>
@@ -878,10 +946,23 @@
serializers/deserializers to encode/decode JavaBeans. The class
named by "classname" must follow the JavaBean standard pattern
of get/set accessors.</DD>
+
+ <DT> </dt>
+ <dt><b><font face="Courier New, Courier, mono"><documentation></font></b></DT>
+ <dd>Can be used inside a <b><service></b>, an <b><operation></b>
+ or an operation <b><parameter></b>. The content of the element is arbitrary
+ text which will be put in the generated wsdl inside a wsdl:document element.<br>
+ <br>
+ Example:<br>
+ <code><operation name="echoString" ><br>
+ <documentation>This operation echoes a string</documentation><br>
+ <parameter name="param"><br>
+ <documentation>a string</documentation><br>
+ </parameter><br>
+ </operation> </code> </dd>
</DL>
<P><A name="global_configuration"></P>
-
<H2>Global Axis Configuration</H2>
<P>The server is configured (by default) by values in the
@@ -911,6 +992,7 @@
</PRE>
<TABLE>
+ <tbody>
<TR>
<TD><B>adminPassword</B></TD>
@@ -941,6 +1023,13 @@
one does not want widely avaialable.</TD>
</TR>
+ <TR>
+ <td><b>axis.disableServiceList</b></td>
+ <td>Flag to disable the list of services feature. Set to false by
+ default, which enables the list of services by the AxisServlet when a GET
+ request is performed on the servlet root.</td>
+ </TR>
+
<TR>
<TD><B>axis.Compiler</B></TD>
@@ -1036,6 +1125,7 @@
<TD>Set this flag to hand authentication off to the servlet
container.</TD>
</TR><!-- end table -->
+ </tbody>
</TABLE>
<P><A name="individual_service"></P>
1.6 +9 -9 ws-axis/site/src/documentation/content/xdocs/java/developers-guide.ihtml
Index: developers-guide.ihtml
===================================================================
RCS file: /home/cvs/ws-axis/site/src/documentation/content/xdocs/java/developers-guide.ihtml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- developers-guide.ihtml 17 Jun 2004 09:49:40 -0000 1.5
+++ developers-guide.ihtml 22 Oct 2004 10:49:15 -0000 1.6
@@ -18,7 +18,7 @@
<H1>Axis Developer's Guide</H1>
- <P><I>1.1 Version</I><BR>
+ <P><I>1.2 Version</I><BR>
<I>Feedback: <A href=
"mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</A></I></P>
@@ -118,14 +118,14 @@
<BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
-D:\\xerces\\xerces-1_4_2\\xerces.jar
-G:\\junit3.7\\junit.jar
-G:\\xml-axis\\java\\build\\lib\\commons-discovery.jar
-G:\\xml-axis\\java\\build\\lib\\commons-logging.jar
-G:\\xml-axis\\java\\build\\lib\\wsdl4j.jar
-G:\\xml-axis\\java\\build\\lib\\axis.jar
-G:\\xml-axis\\java\\build\\lib\\log4j-1.2.8.jar
-G:\\xml-axis\\java\\build\\classes
+G:\xerces\xerces-1_4_2\xerces.jar
+G:\junit3.7\junit.jar
+G:\xml-axis\java\build\lib\commons-discovery.jar
+G:\xml-axis\java\build\lib\commons-logging.jar
+G:\xml-axis\java\build\lib\wsdl4j.jar
+G:\xml-axis\java\build\lib\axis.jar
+G:\xml-axis\java\build\lib\log4j-1.2.8.jar
+G:\xml-axis\java\build\classes
</PRE>
</BLOCKQUOTE>
</BLOCKQUOTE>
1.6 +156 -51 ws-axis/site/src/documentation/content/xdocs/java/install.ihtml
Index: install.ihtml
===================================================================
RCS file: /home/cvs/ws-axis/site/src/documentation/content/xdocs/java/install.ihtml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- install.ihtml 17 Jun 2004 09:49:40 -0000 1.5
+++ install.ihtml 22 Oct 2004 10:49:15 -0000 1.6
@@ -4,29 +4,21 @@
<HEAD>
<META name="generator" content=
"HTML Tidy for Windows (vers 1st October 2003), see www.w3.org">
+ <META http-equiv="Content-Type" content=
+ "text/html; charset=us-ascii">
<TITLE>Axis installation instructions</TITLE>
<LINK href="axis.css" rel="stylesheet" type="text/css">
</HEAD>
<BODY>
- <TABLE cellspacing="0" width="100%" border="0">
- <TBODY>
- <TR>
- <TD colspan="2">
- <A href="http://ws.apache.org/axis"><IMG border="0"
- align="left" src="images/axis.jpg"></A>
-
- <H1>Installing and deploying web applications using
- xml-axis</H1>
- </TD>
- </TR>
- </TBODY>
- </TABLE>
+ <CENTER>
+ <H1><IMG src="images/axis.jpg" height="96" width="176"></H1>
+ </CENTER>
+
<H1>Axis installation instructions</H1>
- <HR size="1" noshade="noshade">
- <P><STRONG>Contents</STRONG></P>
+ <P><B>Contents</B></P>
<UL>
<LI><A href="#intro">Introduction</A></LI>
@@ -50,6 +42,9 @@
<LI><A href="#broken">What if it doesn't work?</A></LI>
<LI><A href="#summary">Summary</A></LI>
+
+ <LI><a href="#soapmon">Appendix: Enabling the SOAP Monitor</a></LI>
+
</UL>
<P><A name="intro"></A></P>
@@ -124,7 +119,10 @@
you have enough of a foundation to be able to work with Axis. It
is also useful to have written a simple web application, as this
will give you some knowledge of how HTTP works, and how Java
- application servers integrate with HTTP.</P>
+ application servers integrate with HTTP. You may find the course notes from
+ <a href="http://www.cs.indiana.edu/classes/a348-dger/fall2002/notes/">
+ Mastering the World Wide Web</a> useful in this regard, even though Axis
+ is only introduced in lecture 28.</P>
<P>Be aware that there is a lot more needed to be learned in
order to use Axis and SOAP effectively than the listing above.
@@ -202,7 +200,9 @@
form the basis for the URL by which clients will access your
service. The rest of this document assumes that the default
webapp name, "axis" has been used; rename these references if
- appropriate. <A name="depend"></A></P>
+ appropriate. </P>
+
+ <P><A name="depend"></A></P>
<H2>Step 2: Setting up the libraries</H2>
@@ -239,7 +239,9 @@
javax packages, so they may not get picked up. If happyaxis.jsp
(see below) cannot find the relevant packages, copy them from
axis/WEB-INF/lib to CATALINA_HOME/common/lib and restart Tomcat.
- <A name="start"></A></P>
+ </P>
+
+ <P><A name="start"></A></P>
<H2>Step 3: starting the web server</H2>
@@ -305,8 +307,8 @@
testing. First let's retrieve the version of Axis from the
version endpoint, calling the <CODE>getVersion</CODE> method:<BR>
<BR>
- <A href=
- "http://localhost:8080/axis/services/Version?method=getVersion">http://localhost:8080/axis/services/Version?method=getVersion</A><BR>
+ <A href="http://localhost:8080/axis/services/Version?method=getVersion">
+ http://localhost:8080/axis/services/Version?method=getVersion</A><BR>
<BR>
This should return something like:</P>
@@ -344,8 +346,8 @@
directory).</P>
<P>Point your browser at <A href=
- "http://localhost:8080/axis/EchoHeaders.jws?method=list">http://localhost:8080/axis/EchoHeaders.jws?method=list</A>
- .</P>
+ "http://localhost:8080/axis/EchoHeaders.jws?method=list">
+ http://localhost:8080/axis/EchoHeaders.jws?method=list</A>.</P>
<P>This should return an XML listing of your application headers,
such as</P>
@@ -375,7 +377,9 @@
<P>Again, the exact return values will be different, and you may
need to change URLs to correct any host, port and webapp
- specifics. <A name="websvc"></A></P>
+ specifics. </P>
+
+ <P><A name="websvc"></A></P>
<H2>Step 5: Installing new Web Services</H2>
@@ -436,7 +440,9 @@
here we are going to use one from the Axis samples: the stock
quote service.</P>
- <H3><A name="Classpath_setup"></A>Classpath setup</H3>
+ <P><A name="Classpath_setup"></A></A>
+
+ <H3>Classpath setup</H3>
<P>In order for these examples to work, java must be able to find
axis.jar, commons-discovery.jar, commons-logging.jar, jaxrpc.jar,
@@ -527,18 +533,16 @@
"java.io.FileNotFoundException: deploy.wsdd (The system cannot
find the file specified)" exception.</P>
- <BLOCKQUOTE>
+<table>
+<tr><td>
<B>On Windows</B><BR>
- <PRE>java -cp %AXISCLASSPATH%
- org.apache.axis.client.AdminClient
- -lhttp://localhost:8080/axis/services/AdminService
- deploy.wsdd<BR></PRE> <B><BR>
- On UNIX</B><BR>
- <PRE>java -cp $AXISCLASSPATH
- org.apache.axis.client.AdminClient<BR>
- -lhttp://localhost:8080/axis/services/AdminService
- deploy.wsdd</PRE>
- </BLOCKQUOTE>
+ <PRE>java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient
+ -lhttp://localhost:8080/axis/services/AdminService deploy.wsdd<BR></PRE><BR>
+ <B>On UNIX</B><BR>
+ <PRE>java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient
+ -lhttp://localhost:8080/axis/services/AdminService deploy.wsdd</PRE>
+</td></tr>
+</table>
<P>If you get some java client error (like
ClassNotFoundException), then you haven't set up your
@@ -579,18 +583,20 @@
<LI>Change directory to the distribution directory for xml-axis
and execute the following command (or its Unix equivalent):
- <BLOCKQUOTE>
- <B>On Windows</B> <PRE><BR>
- java -cp .;%AXISCLASSPATH% samples.stock.GetQuote
- -lhttp://localhost:8080/axis/servlet/AxisServlet -uuser1
- -wpass1 XXX</PRE><BR>
- <BR>
- <SPAN style="font-weight: bold;">On UNIX</SPAN><BR>
- <PRE>java -cp $AXISCLASSPATH
- samples.stock.GetQuote
- -lhttp://localhost:8080/axis/servlet/AxisServlet -uuser1
- -wpass1 XXX</PRE>
- </BLOCKQUOTE><BR>
+<table>
+<tr><td>
+ <B>On Windows</B><BR>
+ <PRE>java -cp .;%AXISCLASSPATH% samples.stock.GetQuote
+ -lhttp://localhost:8080/axis/servlet/AxisServlet
+ -uuser1 -wpass1 XXX
+ </PRE>
+ <B>On UNIX</B><BR>
+ <PRE>java -cp $AXISCLASSPATH samples.stock.GetQuote
+ -lhttp://localhost:8080/axis/servlet/AxisServlet
+ -uuser1 -wpass1 XXX
+ </PRE>
+</td></tr>
+</table>
</LI>
<LI>You should get back "55.25" as a result.</LI>
@@ -629,8 +635,8 @@
<P>The process is also covered in Chapter 15 of <A href=
"http://manning.com/antbook">Java Development with Ant</A>, which
can be downloaded as a <A href=
- "http://www.manning.com/hatcher/chap15.pdf">PDF file</A>.
- <A name="broken"></A></P>
+ "http://www.manning.com/hatcher/chap15.pdf">PDF file</A>.</P>
+ <P><A name="broken"></A></P>
<H2>What if it doesn't work?</H2>
@@ -746,9 +752,9 @@
for people new to server side Java development, and that you will
need to be somewhat self sufficient in this regard. It is not a
silver bullet. However, knowing how to make effective use of the
- list will help you develop better with Axis. <A name=
- "summary"></A></P>
+ list will help you develop better with Axis. </A></P>
+ <P><A name="summary"></A></P>
<H2>Summary</H2>
<P>Axis is simply an implementation of SOAP which can be added to
@@ -758,6 +764,105 @@
process, including testing along the way, using happyaxis and the
bundled test services, you will find it easier to get started
with Axis.</P>
+
+ <P><a NAME="soapmon"></a></P>
+ <H2> Appendix: Enabling the SOAP Monitor </H2>
+ <P>
+ SOAP Monitor allows for the monitoring of SOAP requests and responses via
+ a web browser with Java plug-in 1.3 or higher. For a more comprehensive
+ explanation of its usage, read <a href="user-guide.html#soapmon">Using the
+ SOAP Monitor</a> in the User's Guide.
+ </P>
+ <P>
+ By default, the SOAP Monitor is not enabled. The basic steps for enabling
+ it are compiling the SOAP Monitor java applet, deploying the SOAP Monitor
+ web service and adding request and response flow definitions for each monitored
+ web service. In more detail:
+ <ol>
+ <li> Go to $AXIS_HOME/webapps/axis (or %AXIS_HOME%\webapps\axis)
+ and compile SOAPMonitorApplet.java.<BR>
+
+<table>
+<tr><td>
+ <B>On Windows</B><BR>
+ <code class="java">
+ javac -classpath %AXIS_HOME%\lib\axis.jar SOAPMonitorApplet.java</code><br>
+ <br>
+ <B>On Unix</B><BR>
+ <code class="java">
+ javac -classpath $AXIS_HOME/lib/axis.jar SOAPMonitorApplet.java</code><br>
+</tr></td>
+</table>
+
+ <P>Copy all resulting class files (i.e. SOAPMonitorApplet*.class) to the root
+ directory of the web application using the SOAP Monitor
+ (e.g. .../tomcat/webapps/axis)</P>
+ </li>
+ <li> Deploy the SOAPMonitorService web service with the admin client and the
+ deploy-monitor.wsdd file (shown below).<BR>
+<PRE>
+ Go to the directory deploy-monitor.wsdd is located and execute
+ the command below. The command assume that /axis is the intended
+ web application and it is available on port 8080.<br>
+
+
+<table>
+<tr><td>
+ <b>On Windows</b><BR>
+ <code class="java"><PRE>java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient
+ -lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd<br></PRE></code><br>
+ <b>On UNIX</b><BR>
+ <code class="java"><PRE>java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient <br/>
+ -lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd</PRE></code>
+</tr></td>
+</table>
+
+ <B>SOAPMonitorService Deployment Descriptor (deploy-monitor.wsdd)</B>
+ <pre class="xml"><deployment xmlns="http://xml.apache.org/axis/wsdd/"
+ xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
+ <handler name="soapmonitor"
+ type="java:org.apache.axis.handlers.SOAPMonitorHandler">
+ <parameter name="wsdlURL"
+ value="/axis/SOAPMonitorService-impl.wsdl"/>
+ <parameter name="namespace"
+ value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/>
+ <parameter name="serviceName" value="SOAPMonitorService"/>
+ <parameter name="portName" value="Demo"/>
+ </handler>
+ <service name="SOAPMonitorService" provider="java:RPC">
+ <parameter name="allowedMethods" value="publishMessage"/>
+ <parameter name="className"
+ value="org.apache.axis.monitor.SOAPMonitorService"/>
+ <parameter name="scope" value="Application"/>
+ </service>
+ </deployment>
+ </pre>
+ </li>
+ <li>For each service that is to be monitored, add request and response flow definitions
+ to the service's deployment descriptor and deploy (or redeploy) the service. The
+ <span style="font-weight: bold;">requestFlow</span> and <span style="font-weight: bold;">
+ responseFlow</span> definitions follow the start tag of the <span style="font-weight: bold;">
+ <service></span> element. If a service is already deployed, undeploy it and deploy
+ it with the modified deployment descriptor. An example is shown below:
+ <pre class="xml">...
+ <service name="xmltoday-delayed-quotes" provider="java:RPC">
+ <requestFlow>
+ <handler type="soapmonitor"/>
+ </requestFlow>
+ <responseFlow>
+ <handler type="soapmonitor"/>
+ </responseFlow>
+ ...</pre>
+ </li>
+ <li>With a web browser, go to http[s]://host[:port][/webapp]/SOAPMonitor
+ (e.g. http://localhost:8080/axis/SOAPMonitor) substituting the correct values
+ for your web application. This will show the SOAP Monitor applet for viewing service
+ requests and responses. Any requests to services that have been configured
+ and deployed correctly should show up in the applet.
+ </li>
+ <ol>
+ </P>
+
<HR size="1" noshade="noshade">
<DIV class="copyright" align="center">
1.9 +52 -67 ws-axis/site/src/documentation/content/xdocs/java/user-guide.ihtml
Index: user-guide.ihtml
===================================================================
RCS file: /home/cvs/ws-axis/site/src/documentation/content/xdocs/java/user-guide.ihtml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- user-guide.ihtml 20 Oct 2004 03:15:04 -0000 1.8
+++ user-guide.ihtml 22 Oct 2004 10:49:15 -0000 1.9
@@ -18,7 +18,7 @@
<H1>Axis User's Guide</H1>
- <P><I>1.1 Version</I><BR>
+ <P><I>1.2 Version</I><BR>
<I>Feedback: <A href=
"mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</A></I></P>
@@ -71,15 +71,11 @@
<P>SOAP is an XML<I>-</I>based communication protocol and
encoding format for inter-application communication. Originally
- conceived by Microsoft and Userland software, it has evolved
- through several generations and the current spec, <A href=
- "http://w3.org/TR/soap">SOAP 1.1</A>, is fast growing in
- popularity and usage. The W3C's <A href=
- "http://www.w3.org/2000/xp/Group/">XML Protocol working group</A>
- is in the process of turning SOAP into a true open standard, and
- as of this writing has released a working draft of SOAP 1.2,
- which cleans up some of the more confusing areas of the 1.1
- spec.</P>
+ conceived by Microsoft and Userland software, it has
+ evolved through several generations; the current spec is version,
+ <a href="http://w3.org/TR/soap">SOAP 1.2</a>, though version 1.1
+ is more widespread. The W3C's <a href="http://www.w3.org/2000/xp/Group/">
+ XML Protocol working group</a> is in charge of the specification. </P>
<P>SOAP is widely viewed as the backbone to a new generation of
cross-platform cross-language distributed computing applications,
@@ -244,26 +240,26 @@
<P>Before running the examples in this guide, you'll need to make
sure that your CLASSPATH includes (Note: If you build Axis from a
CVS checkout, these will be in xml-axis/java/build/lib instead of
- axis-1_1/lib):</P>
+ axis-1_2/lib):</P>
<UL>
- <LI>axis-1_1/lib/axis.jar</LI>
+ <LI>axis-1_2/lib/axis.jar</LI>
- <LI>axis-1_1/lib/jaxrpc.jar</LI>
+ <LI>axis-1_2/lib/jaxrpc.jar</LI>
- <LI>axis-1_1/lib/saaj.jar</LI>
+ <LI>axis-1_2/lib/saaj.jar</LI>
- <LI>axis-1_1/lib/commons-logging.jar</LI>
+ <LI>axis-1_2/lib/commons-logging.jar</LI>
- <LI>axis-1_1/lib/commons-discovery.jar</LI>
+ <LI>axis-1_2/lib/commons-discovery.jar</LI>
- <LI>axis-1_1/lib/wsdl4j.jar</LI>
+ <LI>axis-1_2/lib/wsdl4j.jar</LI>
- <LI>axis-1_1/ <I><FONT color="#9966FF">(for the sample
- code)</FONT></I></LI>
+ <LI>axis-1_2/ <i><font color="#9966FF">(for the sample code)</font></i></LI>
- <LI>A JAXP-1.1 compliant XML parser such as Xerces or
- Crimson</LI>
+ <LI>A JAXP-1.1 compliant XML parser such as Xerces or Crimson. We recommend
+ <A href="http://xml.apache.org/xerces2-j/">Xerces</A>, as it is the one
+ that the product has been tested against.</LI>
</UL>
<P><A name="ConsumingServices"></A></P>
@@ -274,34 +270,31 @@
<P>Let's take a look at an example Web Service client that will
call the <B>echoString</B> method on the public Axis server at
Apache.</P>
- <PRE class="example">
-1 import org.apache.axis.client.Call;
-2 import org.apache.axis.client.Service;
-3 import javax.xml.namespace.QName;
-4
-5 public class TestClient {
-6 public static void main(String [] args) {
-7 try {
-8 String endpoint =
-9 "http://nagoya.apache.org:5049/axis/services/echo";
-10
-11 Service service = new Service();
-12 Call call = (Call) service.createCall();
-13
-14 call.setTargetEndpointAddress( new java.net.URL(endpoint) );
-15 call.setOperationName(new QName("<FONT color=
-"#009933">http://soapinterop.org/</FONT>", "<FONT color=
-"#993333">echoString</FONT>"));
-16
-17 String ret = (String) call.invoke( new Object[] { "<FONT color="#CC00CC">Hello!</FONT>" } );
+<pre class="example">1 import org.apache.axis.client.Call;
+2 import org.apache.axis.client.Service;
+3 import javax.xml.namespace.QName;
+4
+5 public class TestClient {
+6 public static void main(String [] args) {
+7 try {
+8 String endpoint =
+9 "http://nagoya.apache.org:5049/axis/services/echo";
+10
+11 Service service = new Service();
+12 Call call = (Call) service.createCall();
+13
+14 call.setTargetEndpointAddress( new java.net.URL(endpoint) );
+15 call.setOperationName(new QName("<font color="#009933">http://soapinterop.org/</font>", <font color="#993333">echoString</font>"));
+16
+17 String ret = (String) call.invoke( new Object[] { "<font color="#CC00CC">Hello!</font>" } );
18
-19 System.out.println("Sent 'Hello!', got '" + ret + "'");
-20 } catch (Exception e) {
-21 System.err.println(e.toString());
-22 }
-23 }
-24 }
-</PRE>
+19 System.out.println("Sent 'Hello!', got '" + ret + "'");
+20 } catch (Exception e) {
+21 System.err.println(e.toString());
+22 }
+23 }
+24 }</pre>
+
<P>(You'll find this file in <A href=
"http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java/samples/userguide/example1/TestClient.java">samples/userguide/example1/TestClient.java</A>)</P>
@@ -638,7 +631,7 @@
<P>If you want to prove to yourself that the deployment really
worked, try undeploying the service and calling it again.
There's an "undeploy.wsdd" file in the example3/ directory which
- you can use just as you did the deploy.wsdd file above. Run the
+ you can use just as you did the deploy.wsdd file above. Run the
AdminClient on that file, then try the service Client again and
see what happens.</P>
@@ -1073,20 +1066,6 @@
<H3>What Axis can send via SOAP with restricted
Interoperability</H3>
- <H5>Unsigned data</H5>
-
- <P>You cannot consume or generate services that use unsigned
- datatypes with pure JAX-RPC, because there are no unsigned
- dataypes in Java.</P>
-
- <P>Axis does have support for the unsigned types, so you can
- consume services written in C++, C# and the like, and
- re-implement interfaces designed for those languages. Be very
- wary about exporting unsigned datatypes, however, as to do so
- will stop Java clients that do not use Axis or another SOAP
- client library with unsigned support from using them. The current
- JAX-RPC specification does not address this issue.</P>
-
<H5>Java Collections</H5>
<P>Some of the Collection classes, such as <TT>Hashtable</TT>, do
@@ -1110,8 +1089,11 @@
any class that follows the JavaBean pattern of accessor and
mutator. To serve up objects you must either register your
classes with this BeanSerializer, or there must be serialization
- support built in to Axis. Remote References Remote references are
- neither part of the SOAP specification, nor the JAX-RPC
+ support built in to Axis.</P>
+
+ <H5>Remote References</H5>
+
+ <P>Remote references are neither part of the SOAP specification, nor the JAX-RPC
specification. You cannot return some object reference and expect
the caller to be able to use it as an endpoint for SOAP calls or
as a parameter in other calls. Instead you must use some other
@@ -2319,8 +2301,11 @@
<P>The port used by the SOAP monitor service to comminicate with
applets is configurable. Edit the web.xml file for the Axis web
- application to change the port to be used. <B>Note: The SOAP
- Monitor is NOT enabled by default for security reasons.</B></P>
+ application to change the port to be used.<BR>
+
+ <B>Note: The SOAP Monitor is NOT enabled by default for security reasons.</B>
+ To enable it, read <a href="install.html#soapmon">Enabling the
+ SOAP Monitor</a> in the Installation instructions.</P>
<P><A name="Glossary"></A></P>
<H2>Glossary</H2>