You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by gd...@apache.org on 2004/05/25 22:44:33 UTC
cvs commit: ws-axis/java/docs reference.html
gdaniels 2004/05/25 13:44:32
Modified: java/docs reference.html
Log:
Update docs.
Revision Changes Path
1.37 +173 -148 ws-axis/java/docs/reference.html
Index: reference.html
===================================================================
RCS file: /home/cvs/ws-axis/java/docs/reference.html,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -r1.36 -r1.37
--- reference.html 10 May 2004 17:25:43 -0000 1.36
+++ reference.html 25 May 2004 20:44:32 -0000 1.37
@@ -479,188 +479,219 @@
Additional classpath elements</p>
<p> </p>
<h2><a name="Deployment"></a>Deployment (WSDD) Reference</h2>
-Note : all the elements referred to in this section are in the WSDD
-namespace, namely "http://xml.apache.org/axis/wsdd/".
+Note : all the elements referred to in this section are in the WSDD namespace,
+namely "http://xml.apache.org/axis/wsdd/".
<dl>
<dt><b><font face="Courier New, Courier, mono"><deployment></font></b></dt>
- <dd>The root element of the deployment document which tells the Axis
-engine that this is a deployment. A deployment document may represent
-EITHER a complete engine configuration OR a set of components to deploy
-into an active engine.</dd>
+ <dd>The root element of the deployment document which tells the Axis engine
+ that this is a deployment. A deployment document 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="Courier New, Courier, mono"><undeployment></font></b></dt>
- <dd>The root element of the deployment document which tells Axis that
-this is an undeployment. Undeployments are only useful as </dd>
+ <dd>The root element of the deployment document which tells Axis that this is
+ an undeployment. Undeployments are only useful as </dd>
<dt> </dt>
<dt><b><font face="Courier New, Courier, mono"><handler [name="</font></b><font
face="Courier New, Courier, mono"><i>name</i></font><b><font
face="Courier New, Courier, mono">"] type="</font></b><font
face="Courier New, Courier, mono"><i>type</i></font><b><font
face="Courier New, Courier, mono">"/></font></b></dt>
- <dd>Belongs at the top level inside a <b><deployment></b> or <b><undeployment></b>,
-or inside a <b><chain></b>, <b><requestFlow></b>, or <b><responseFlow></b>.
-Defines a Handler, and indicates the type of the handler. "Type" is
-either the name of another previously defined Handler, or a QName of
-the form "<b>java:<i>class.name</i></b>". The optional "name" attribute
-allows you to refer to this Handler definition in other parts of the
-deployment. May contain an arbitrary number of <b><font
+ <dd>Belongs at the top level inside a <b><deployment></b> or <b><undeployment></b>,
+ or inside a <b><chain></b>, <b><requestFlow></b>, or <b><responseFlow></b>.
+ Defines a Handler, and indicates the type of the handler. "Type" is either
+ the name of another previously defined Handler, or a QName of the form "<b>java:<i>class.name</i></b>".
+ The optional "name" attribute allows you to refer to this Handler definition
+ in other parts of the deployment. May contain an arbitrary number of <b><font
face="Courier New, Courier, mono"><parameter name="</font></b><font
face="Courier New, Courier, mono"><i>name</i></font><b><font
face="Courier New, Courier, mono">" value="</font></b><font
face="Courier New, Courier, mono"><i>value</i></font><b><font
- face="Courier New, Courier, mono">"></font></b> elements, each of
-which will supply a parameter to the deployed Handler.</dd>
+ face="Courier New, Courier, mono">"></font></b> elements, each of which will
+ supply a parameter to the deployed Handler.</dd>
<dt> </dt>
<dt><b><font face="Courier New, Courier, mono"><service name="</font></b><font
face="Courier New, Courier, mono"><i>name</i></font><b><font
face="Courier New, Courier, mono">" provider="</font></b><font
face="Courier New, Courier, mono"><i>provider</i></font><b><font
face="Courier New, Courier, mono">" ></font></b></dt>
- <dd>Deploys/undeploys an Axis Service. This is the most complex WSDD
-tag, so we're going to spend a little time on it.<br>
+ <dd>Deploys/undeploys an Axis Service. This is the most complex WSDD tag, so
+ we're going to spend a little time on it.<br>
<br>
- <b>Options</b> may be specified as follows : <code><b><parameter
-name="</b>name<b>" value="</b>value<b>"/></b></code>, and common
-ones include:<br>
+ <b>Options</b> may be specified as follows : <code><b><parameter name="</b>name<b>"
+ value="</b>value<b>"/></b></code>, and common ones include:<br>
<br>
<ul>
<li><b>className</b> : the backend implementation class<br>
</li>
- <li><b>allowedMethods</b> : Each provider can determine which
-methods are allowed to be exposed as web services. <br>
-To summaries for Axis supplied providers:<br>
- <p><u>Java RPC Provider</u> (provider="java:RPC") by default
-all public methods specified by the class in the className option,
-including any inherited methods are available as web services.<br>
-For more details regarding the Java Provider please see <b>WHERE???</b>.
+ <li><b>allowedMethods</b> : Each provider can determine which methods are
+ allowed to be exposed as web services. <br>
+ To summaries for Axis supplied providers:<br>
+ <p><u>Java RPC Provider</u> (provider="java:RPC") by default all public
+ methods specified by the class in the className option, including any
+ inherited methods are available as web services.<br>
+ For more details regarding the Java Provider please see <b>WHERE???</b>.
</p>
- <p><u>Java MsgProvder</u> (provider="java:MSG")<!-- Glen to provide details --> </p>
- <p>In order to further restrict the above methods, the <b>allowedMethods</b>
-option may be used to specify in a space delimited list the names of
-only those methods which are allowed as web services. It is also
-possible to specify for this option the value <b>"*"</b> which is
-functionally equivalent to not specify the option at all. Also, it is
-worth mentioning that the <b>operation</b> element is used to further
-define the methods being offered, but it does not affect which methods
-are made available. </p>
- <p><i>Note, while this is true for Axis supplied providers, it
-is implementation dependent on each individual provider. Please review
-your providers documentation on how or if it supports this option.</i> </p>
- <p> <b><u>Note, Exposing any web service has security
-implications.</u><br>
- </b>As a best practices guide it is <u>highly</u> recommend
-when offering a web service in un secure environment to restrict
-allowed methods to only those required for the service being offered.
-And, for those that are made available, to <b>fully</b> understand
-their function and how they may access and expose your systems's
-resources. </p>
+ <p><u>Java MsgProvder</u> (provider="java:MSG")
+ <!-- Glen to provide details -->
+ </p>
+ <p>In order to further restrict the above methods, the <b>allowedMethods</b>
+ option may be used to specify in a space delimited list the names of
+ only those methods which are allowed as web services. It is also possible
+ to specify for this option the value <b>"*"</b> which is functionally
+ equivalent to not specify the option at all. Also, it is worth mentioning
+ that the <b>operation</b> element is used to further define the methods
+ being offered, but it does not affect which methods are made available.
+ </p>
+ <p><i>Note, while this is true for Axis supplied providers, it is implementation
+ dependent on each individual provider. Please review your providers
+ documentation on how or if it supports this option.</i> </p>
+ <p> <b><u>Note, Exposing any web service has security implications.</u><br>
+ </b>As a best practices guide it is <u>highly</u> recommend when offering
+ a web service in un secure environment to restrict allowed methods to
+ only those required for the service being offered. And, for those that
+ are made available, to <b>fully</b> understand their function and how
+ they may access and expose your systems's resources. </p>
<p> </p>
</li>
- <li><b>allowedRoles</b> : comma-separated list of roles allowed
-to access this service<br>
- </li>
+ <li><b>allowedRoles</b> : comma-separated list of roles 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.)</li>
</ul>
+ <p> If you wish to define handlers which should be invoked either before or
+ after the service's provider, you may do so with the <b><requestFlow></b>
+ and the <b><responseFlow></b> subelements. Either of those elements
+ may be specified inside the <b><service></b> element, and their semantics
+ are identical to the <b><chain></b> element described below - in other
+ words, they may contain <b><handler></b> and <b><chain</b>>
+ elements which will be invoked in the order they are specified.</p>
+ <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>
+ Example:<br>
+ <pre>
+<service name="test">
+ <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"/>
+ </requestFlow>
+</service>
+</pre>
+ Metadata may be specified about particular operations in your service by using
+ the <operation> tag inside a service. This enables you to map the java
+ parameter names of a method to particular XML names, to specify the parameter
+ modes for your parameters, and to map particular XML names to particular operations.<br>
<br>
-If you wish to define handlers which should be invoked either before or
-after the service's provider, you may do so with the <b><requestFlow></b>
-and the <b><responseFlow></b> subelements. Either of those
-elements may be specified inside the <b><service></b> element,
-and their semantics are identical to the <b><chain></b> element
-described below - in other words, they may contain <b><handler></b>
-and <b><chain</b>> elements which will be invoked in the order
-they are specified.<br>
- <br>
-Example:<br>
- <pre><service name="test"><br> <parameter name="className" value="test.Implementation"/><br> <parameter name="allowedMethods" value="*"/><br> <namespace>http://testservice/</namespace><br> <requestFlow> <!-- Run these before processing the request --><br> <handler type="java:MyHandlerClass"/><br> <handler type="somethingIDefinedPreviously"/><br> </requestFlow><br></service></pre>
- <b>Metadata</b> may be specified about particular operations in
-your service by using the <operation> tag inside a service. This
-enables you to map the java parameter names of a method to particular
-XML names, to specify the parameter modes for your parameters, and to
-map particular XML names to particular operations.<br>
- <br>
-<operation name="method"><br>
-</operation> <br>
+ <operation name="method"><br>
+ </operation> <br>
</dd>
<dt> </dt>
<dt><b><font face="Courier New, Courier, mono"><chain name="</font></b><font
face="Courier New, Courier, mono"><i>name</i></font><b><font
face="Courier New, Courier, mono">"</font></b><b><font
face="Courier New, Courier, mono">><br>
-<<i>subelement</i>/>...<br>
-</chain> </font></b></dt>
- <dd>Defines a chain. Each <i>handler</i> (i.e. deployed handler
-name) in the list will be invoked() in turn when the chain is invoked.
-This enables you to build up "modules" of commonly used functionality.
-The subelements inside chains may be <<b>handler</b>>s or <<b>chain</b>>s.
-<handler>s inside a <chain> may either be defined in terms
-of their Java class:<br>
+ <<i>subelement</i>/>...<br>
+ </chain> </font></b></dt>
+ <dd>Defines a chain. Each <i>handler</i> (i.e. deployed handler name) in the
+ list will be invoked() in turn when the chain is invoked. This enables you
+ to build up "modules" of commonly used functionality. The subelements inside
+ chains may be <<b>handler</b>>s or <<b>chain</b>>s. <handler>s
+ inside a <chain> may either be defined in terms of their Java class:<br>
<pre><chain name="myChain"><br> <handler type="java:org.apache.axis.handlers.LogHandler"/><br></chain></pre>
-or may refer to previously defined <handlers>, with the "type" of
-the handler referring to the name of the other handler definition:<br>
+ or may refer to previously defined <handlers>, with the "type" of the
+ handler referring to the name of the other handler definition:<br>
<pre><handler name="logger" type="java:org.apache.axis.handlers.LogHandler"/><br><chain name="myChain"/><br> <handler type="logger"/><br></chain></pre>
</dd>
<dt> </dt>
<dt><b><font face="Courier New, Courier, mono"><transport name="</font></b><font
face="Courier New, Courier, mono"><i>name</i></font><b><font
face="Courier New, Courier, mono">"></font></b></dt>
- <dd>Defines a transport on the server side. Server transports are
-invoked when an incoming request arrives. A server transport may define
- <b><requestFlow></b> and/or <b><responseFlow></b>
-elements to specify handlers/chains which should be invoked during the
-request (i.e. incoming message) or response (i.e. outgoing message)
-portion of processing (this function works just like the <b><service></b>
-element above). Typically handlers in the transport request/response
-flows implement transport-specific functionality, such as parsing
-protocol headers, etc.</dd>
+ <dd>Defines a transport on the server side. Server transports are invoked when
+ an incoming request arrives. A server transport may define <b><requestFlow></b>
+ and/or <b><responseFlow></b> elements to specify handlers/chains which
+ should be invoked during the request (i.e. incoming message) or response (i.e.
+ outgoing message) portion of processing (this function works just like the
+ <b><service></b> element above). Typically handlers in the transport
+ request/response flows implement transport-specific functionality, such as
+ parsing protocol headers, etc.</dd>
<br>
<br>
- <dd>For any kind of transport (though usually this relates to HTTP
-transports), users may allow Axis servlets to perform arbitrary actions
-(by means of a "plug-in") when specific query strings are passed to the
-servlet (see the section <a
- href="developers-guide.html#Axis%20Servlet%20Query%20String%20Plug-ins">Axis
-Servlet Query String Plug-ins</a> in the <a
- href="developers-guide.html">Axis Developer's Guide</a> for more
-information on what this means and how to create a plug-in). When the
-name of a query string handler class is known, users can enable it by
-adding an appropriate <b><parameter></b> element in the Axis
-server configuration's <b><transport></b> element. An example
-configuration might look like the following:<br>
+ <dd>For any kind of transport (though usually this relates to HTTP transports),
+ users may allow Axis servlets to perform arbitrary actions (by means of a
+ "plug-in") when specific query strings are passed to the servlet (see the
+ section <a
+ href="developers-guide.html#Axis%20Servlet%20Query%20String%20Plug-ins">Axis
+ Servlet Query String Plug-ins</a> in the <a
+ href="developers-guide.html">Axis Developer's Guide</a> for more information
+ on what this means and how to create a plug-in). When the name of a query
+ string handler class is known, users can enable it by adding an appropriate
+ <b><parameter></b> element in the Axis server configuration's <b><transport></b>
+ element. An example configuration might look like the following:<br>
<br>
<code> <transport name="http"><br>
- <parameter name="useDefaultQueryStrings" value="false"
-/><br>
- <parameter name="qs.name" value="class.name" /><br>
-</transport><br>
+ <parameter name="useDefaultQueryStrings" value="false" /><br>
+ <parameter name="qs.name" value="class.name" /><br>
+ </transport><br>
</code><br>
-In this example, the query string that the Axis servlet should respond
-to is <i>?name</i> and the class that it should invoke when this query
-string is encountered is named <code>class.name</code>. The <code>name</code>
-attribute of the <b><parameter></b> element must start with the
-string "qs." to indicate that this <b><parameter></b> element
-defines a query string handler. The <code>value</code> attribute must
-point to the name of a class implementing the <code>org.apache.axis.transport.http.QSHandler</code>
-interface. By default, Axis provides for three Axis servlet query
-string handlers (<i>?list</i>, <i>?method</i>, and <i>?wsdl</i>). See
-the Axis server configuration file for their definitions. If the user
-wishes not to use these default query string handlers (as in the
-example), a <b><parameter></b> element with a <code>name</code>
-attribute equal to "useDefaultQueryStrings" should have its <code>value</code>
-attribute set to <code>false</code>. By default it is set to <code>true</code>
-and the element is not necessary if the user wishes to have this
-default behavior. </dd>
+ In this example, the query string that the Axis servlet should respond to
+ is <i>?name</i> and the class that it should invoke when this query string
+ is encountered is named <code>class.name</code>. The <code>name</code> attribute
+ of the <b><parameter></b> element must start with the string "qs." to
+ indicate that this <b><parameter></b> element defines a query string
+ handler. The <code>value</code> attribute must point to the name of a class
+ implementing the <code>org.apache.axis.transport.http.QSHandler</code> interface.
+ By default, Axis provides for three Axis servlet query string handlers (<i>?list</i>,
+ <i>?method</i>, and <i>?wsdl</i>). See the Axis server configuration file
+ for their definitions. If the user wishes not to use these default query string
+ handlers (as in the example), a <b><parameter></b> element with a <code>name</code>
+ attribute equal to "useDefaultQueryStrings" should have its <code>value</code>
+ attribute set to <code>false</code>. By default it is set to <code>true</code>
+ and the element is not necessary if the user wishes to have this default behavior.
+ </dd>
<dt> </dt>
<dt><b><font face="Courier New, Courier, mono"><transport name="</font></b><font
face="Courier New, Courier, mono"><i>name</i></font><b><font
face="Courier New, Courier, mono">" pivot="</font></b><font
face="Courier New, Courier, mono"><i>handler type</i><b>"</b></font><b><font
face="Courier New, Courier, mono"> ></font></b></dt>
- <dd>Defines a transport on the client side, which is invoked when
-sending a SOAP message. The "pivot" attribute specifies a Handler to be
-used as the actual sender for this transport (for example, the
-HTTPSender). Request and response flows may be specified as in
-server-side transports to do processing on the request (i.e. outgoing
-message) or response (i.e. incoming message).</dd>
+ <dd>Defines a transport on the client side, which is invoked when sending a
+ SOAP message. The "pivot" attribute specifies a Handler to be used as the
+ actual sender for this transport (for example, the HTTPSender). Request and
+ response flows may be specified as in server-side transports to do processing
+ on the request (i.e. outgoing message) or response (i.e. incoming message).</dd>
<dt> </dt>
<dt><b><font face="Courier New, Courier, mono"><typeMapping qname="</font></b><font
face="Courier New, Courier, mono"><i>ns:localName</i></font><b><font
@@ -671,8 +702,8 @@
face="Courier New, Courier, mono">" deserializer="</font></b><font
face="Courier New, Courier, mono"><i>classname</i></font><b><font
face="Courier New, Courier, mono">"/></font></b></dt>
- <dd>Each typeMapping maps an XML qualified name to/from a Java class,
-using a specified Serializer and Deserializer. </dd>
+ <dd>Each typeMapping maps an XML qualified name to/from a Java class, using
+ a specified Serializer and Deserializer. </dd>
<dt> </dt>
<dt><b><font face="Courier New, Courier, mono"><beanMapping qname="</font></b><font
face="Courier New, Courier, mono"><i>ns:localName</i></font><b><font
@@ -680,28 +711,22 @@
face="Courier New, Courier, mono"><i>classname</i></font><b><font
face="Courier New, Courier, mono">"</font></b><b><font
face="Courier New, Courier, mono">></font></b></dt>
- <dd><b></b>A simplified type mapping, which uses pre-defined
-serializers/deserializers to encode/decode JavaBeans. The class named
-by "classname" must follow the JavaBean standard pattern of get/set
-accessors.</dd>
+ <dd><b></b>A simplified type mapping, which uses pre-defined 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>
+ <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>
+ 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>
+ <documentation>This operation echoes a string</documentation><br>
+ <parameter name="param"><br>
+ <documentation>a string</documentation><br>
+ </parameter><br>
+ </operation> </code> </dd>
</dl>
<p> </p>
<h2><a name="global_configuration">Global Axis Configuration</a></h2>