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 du...@apache.org on 2003/08/08 15:05:31 UTC
cvs commit: xml-axis/java/docs developers-guide.html reference.html
dug 2003/08/08 06:05:31
Modified: java/docs developers-guide.html reference.html
Log:
Docs for ?query support
Submitted by: Curtiss Howard cjhoward@us.ibm.com
Revision Changes Path
1.37 +88 -0 xml-axis/java/docs/developers-guide.html
Index: developers-guide.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/developers-guide.html,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -r1.36 -r1.37
--- developers-guide.html 11 Jul 2003 23:56:42 -0000 1.36
+++ developers-guide.html 8 Aug 2003 13:05:30 -0000 1.37
@@ -22,6 +22,7 @@
<br><a href="#Pluggable-Components">Pluggable-Components</a>
<br> <a href="#Discovery">Discovery</a>
<br> <a href="#Logging/Tracing">Logging/Tracing</a>
+<br> <a href="#Axis Servlet Query String Plug-ins">Axis Servlet Query String Plug-ins</a>
<br><a href="#Configuration Properties">Configuration Properties</a>
<br><a href="#Exception Handling">Exception Handling</a>
<br><a href="#Compile And Run">Compile and Run</a>
@@ -343,6 +344,93 @@
while limiting console output to INFO (and higher).
</li>
</ul>
+<h3>
+<a name="Axis Servlet Query String Plug-ins">Axis Servlet Query String Plug-ins</h3>
+Any servlet that is derived from the <code>org.apache.axis.transport.http.AxisServlet</code> class
+supports a number of standard query strings (<i>?list</i>, <i>?method</i>, and <i>?wsdl</i>) that
+provide information from or perform operations on a web service (for instance, <i>?method</i> is
+used to invoke a method on a web service and <i>?wsdl</i> is used to retrieve the WSDL document for
+a web service). Axis serlvets are not limited to these three query strings and developers may
+create their own "plug-ins" by implementing the <code>org.apache.axis.transport.http.QSHandler</code>
+interface. There is one method in this interface that must be implemented, with the following signature:
+<pre>
+public void invoke (MessageContext msgContext) throws AxisFault;
+</pre>
+The <code>org.apache.axis.MessageContext</code> instance provides the developer with a number of useful
+objects (such as the Axis engine instance, and HTTP servlet objects) that are accessible by its
+<code>getProperty</code> method. The following constants can be used to retrieve various objects provided
+by the Axis servlet invoking the query string plug-in:
+<ul>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_NAME</strong><br>
+A <code>String</code> containing the name of the query string plug-in. For instance, if the query string <i>?wsdl</i> is
+provided, the name of the plugin is <i>wsdl</i>.
+<br><br>
+</li>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_SERVICE_NAME</strong><br>
+A <code>String</code> containing the name of the Axis servlet that inovked the query string plug-in.
+<br><br>
+</li>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_IS_DEVELOPMENT</strong><br>
+A <code>Boolean</code> containing <code>true</code> if this version of Axis is considered to be in development
+mode, <code>false</code> otherwise.
+<br><br>
+</li>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_ENABLE_LIST</strong><br>
+A <code>Boolean</code> containing <code>true</code> if listing of the Axis server configuration is allowed,
+<code>false</code> otherwise.
+<br><br>
+</li>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_ENGINE</strong><br>
+A <code>org.apache.axis.server.AxisServer</code> object containing the engine for the Axis server.
+<br><br>
+</li>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.MC_HTTP_SERVLETREQUEST</strong><br>
+The <code>javax.servlet.http.HttpServletRequest</code> object from the Axis servlet that invoked the
+query string plug-in
+<br><br>
+</li>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.MC_HTTP_SERVLETRESPONSE</strong><br>
+The <code>javax.servlet.http.HttpServletResponse</code> object from the Axis servlet that invoked the
+query string plug-in
+<br><br>
+</li>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_WRITER</strong><br>
+The <code>java.io.PrintWriter</code> object from the Axis servlet that invoked the
+query string plug-in
+<br><br>
+</li>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_LOG</strong><br>
+The <code>org.apache.commons.logging.Log</code> object from the Axis servlet that invoked the query
+string plug-in, which is used to log messages.
+<br><br>
+</li>
+<li><strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_EXCEPTION_LOG</strong><br>
+The <code>org.apache.commons.logging.Log</code> object from the Axis servlet that invoked the query
+string plug-in, which is used to log exceptions.
+<br><br>
+</li>
+</ul>
+Query string plug-in development is much like normal servlet development since the same basic
+information and methods of output are available to the developer. Below is an example query string
+plug-in which simply displays the value of the system clock (<code>import</code> statements have been
+omitted for brevity):
+<pre>
+public class QSClockHandler implements QSHandler {
+ public void invoke (MessageContext msgContext) throws AxisFault {
+ PrintWriter out = (PrintWriter) msgContext.getProperty (HTTPConstants.PLUGIN_WRITER);
+ HttpServletResponse response = (HttpServletResponse) msgContext.getProperty (HTTPConstants.MC_HTTP_SERVLETRESPONSE);
+
+ response.setContentType ("text/html");
+
+ out.println ("<HTML><BODY><H1>" + System.currentTimeMillis() + "</H1></BODY></HTML>");
+ }
+}
+</pre>
+Once a query string plug-in class has been created, the Axis server must be set up to recognize the
+query string which invokes it. See the section <a href="reference.html#Deployment">Deployment (WSDD) Reference</a> in the
+<a href="reference.html">Axis Reference Guide</a> for information on how the HTTP transport section of the Axis server configuration
+file must be set up.
+
<h2>
<a NAME="Configuration Properties"></a>Configuration Properties</h2>
1.28 +20 -1 xml-axis/java/docs/reference.html
Index: reference.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/reference.html,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- reference.html 18 Jul 2003 18:13:33 -0000 1.27
+++ reference.html 8 Aug 2003 13:05:30 -0000 1.28
@@ -517,7 +517,26 @@
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>
+ parsing protocol headers, etc.</dd><br><br>
+ <dd>For 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 Servlet Query String Plug-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="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.</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