Author: veithen Date: Wed Jan 11 16:28:10 2012 New Revision: 1230130 URL: http://svn.apache.org/viewvc?rev=1230130&view=rev Log: Migrated the developer guide to XDoc.
Added: axis/axis1/java/trunk/src/site/xdoc/developers-guide.xml - copied, changed from r1230001, webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/developers-guide.xml Removed: axis/axis1/java/trunk/docs/developers-guide.html Copied: axis/axis1/java/trunk/src/site/xdoc/developers-guide.xml (from r1230001, webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/developers-guide.xml) URL: http://svn.apache.org/viewvc/axis/axis1/java/trunk/src/site/xdoc/developers-guide.xml?p2=axis/axis1/java/trunk/src/site/xdoc/developers-guide.xml&p1=webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/developers-guide.xml&r1=1230001&r2=1230130&rev=1230130&view=diff ============================================================================== --- webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/developers-guide.xml (original) +++ axis/axis1/java/trunk/src/site/xdoc/developers-guide.xml Wed Jan 11 16:28:10 2012 @@ -1,85 +1,56 @@ <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "./dtd/document-v12.dtd"> -<document> - <header> - <title>WebServices - Axis</title> - </header> +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + --> +<document xmlns="http://maven.apache.org/XDOC/2.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> + <properties> + <title>Developer's Guide</title> + </properties> <body> -<a name="AxisDevelopersGuide"/> -<section> -<title>Axis Developer's Guide</title> - -<p><i>1.2 Version</i><br/> - <i>Feedback: <a href="mailto:axis-...@ws.apache.org">axis-...@ws.apache.org</a></i></p> - -<a name="TableOfContents"/> -<section> -<title>Table of Contents</title> - -<ul> - <li><a href="#Introduction">Introduction</a></li> - <li><a href="#GeneralGuidelines">General Guidelines</a></li> - <li><a href="#DevelopmentEnvironment">Development Environment</a></li> - <li><a href="#Pluggable-Components">Pluggable-Components</a></li> - <ul> - <li><a href="#Discovery">Discovery</a></li> - <li><a href="#Logging/Tracing">Logging/Tracing</a></li> - <li><a href="#AxisServletQueryStringPlug-ins">Axis Servlet Query String Plug-ins</a></li> - </ul> - <li><a href="#ConfigurationProperties">Configuration Properties</a></li> - <li><a href="#ExceptionHandling">Exception Handling</a></li> - <li><a href="#CompileAndRun">Compile and Run</a></li> - <li><a href="#Internationalization">Internationalization</a></li> - <ul> - <li><a href="#DeveloperGuidelines">Developer Guidelines</a></li> - <li><a href="#Interface">Interface</a></li> - <li><a href="#ExtendingMessageFiles">Extending Message Files</a></li> - </ul> - <li><a href="#AddingTestcases">Adding Testcases</a></li> - <li><a href="#CreatingAWSDLTest">Creating a WSDL Test</a></li> - <li><a href="#TestStructure">Test Structure</a></li> - <li><a href="#AddingSourceCodeChecks">Adding Source Code Checks</a></li> - <li><a href="#JUnitAndAxis">JUnit and Axis</a></li> - <li><a href="#UsingTcpmonToMonitorFunctionalTests">Using tcpmon to Monitor Functional Tests</a></li> - <li><a href="#UsingSOAPMonitorToMonitorFunctionalTests">Using SOAP Monitor to Monitor Functional Tests</a></li> - <li><a href="#RunningASingleFunctionalTest">Running a Single Functional Test</a></li> - <li><a href="#Debugging">Debugging</a></li> - <ul> - <li><a href="#TurningOnDebugOutput">Turning on Debug Output</a></li> - <li><a href="#WritingTemporaryOutput">Writing Temporary Output</a></li> - </ul> - <li><a href="#RunningTheJAX-RPCCompatibilityTests">Running the JAX-RPC Compatibility Tests</a></li> -</ul> +<section name="Table of Contents"> + +<macro name="toc"/> </section> -<a name="Introduction"/> -<section> -<title>Introduction</title> +<section name="Introduction"> <p>This guide is a collection of topics related to developing code for Axis.</p> </section> -<a name="GeneralGuidelines"/> -<section> -<title>General Guidelines</title> +<section name="General Guidelines"> <ul> - <li>Axis specific information (cvs repository access, mailing list info, etc.) can be found on the <a href="http://ws.apache.org/axis/index.html">Axis Home Page</a>.</li> + <li>Axis specific information (svn repository access, mailing list info, etc.) can be found on the <a href="http://ws.apache.org/axis/index.html">Axis Home Page</a>.</li> <li>Axis uses the <a href="http://jakarta.apache.org/site/guidelines.html">Jakarta Project Guidelines.</a></li> <li>Code changes should comply with <a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">"Code Conventions for the Java Programming Language"</a></li> - <li>When fixing a bug, please include the href of the bug in the cvs commit message.</li> + <li>When fixing a bug, please include the href of the bug in the svn commit message.</li> <li>Incompatible changes to <a href="user-guide.html#PublishedAxisInterfaces">published Axis interfaces</a> should be avoided where possible. When changes are necessary, for example to maintain or improve the overall modularity of Axis, the impact on users must be considered and, preferably, documented.</li> <li>If you are making a big change that may affect interoperability, please run the <a href="http://xml.apache.org/~rubys/echotest.pl">echotest2 round 2 interop test</a> to ensure that your change does not result in any new interop failures. You will also need the <a href="http://xml.apache.org/~rubys/client_deploy.wsdd">client_deploy.wsdd</a>. Here are the <a href="http://xml.apache.org/~rubys/ApacheClientInterop.html">nightly interop test results</a>.</li> </ul> </section> -<a name="DevelopmentEnvironment"/> -<section> -<title>Development Environment</title> +<section name="Development Environment"> <p>The following packages are required for axis development:</p> @@ -110,15 +81,11 @@ G:\xml-axis\java\build\classes </section> -<a name="Pluggable-Components"/> -<section> -<title>Pluggable-Components</title> +<section name="Pluggable-Components"> <p>The <a href="architecture-guide.html">Axis Architecture Guide</a> explains the requirements for pluggable components.</p> -<a name="Discovery"/> -<section> -<title>Discovery</title> +<subsection name="Discovery"> <p>An Axis-specific component factory should be created of the form:</p> @@ -128,17 +95,14 @@ G:\xml-axis\java\build\classes <p>The <code>org.apache.axis.components.image</code> package demonstrates both a factory, and supporting classes for different image tools used by Axis. This is representative of a pluggable component that uses external tooling, isolating it behind a 'thin' wrapper to Axis that provides only a limited interface to meet Axis minimal requirements. This allows future designers and implementors to gain an explicit understanding of the Axis's specific requirements on these tools.</p> - -</section> -<a name="Logging/Tracing"/> -<section> -<title>Logging/Tracing</title> +</subsection> + +<subsection name="Logging/Tracing"> <p>Axis logging and tracing is based on the Logging component of the <a href="http://jakarta.apache.org/commons/index.html">Jakarta Commons</a> project, or the Jakarta Commons Logging (JCL) SPI. The JCL provides a Log interface with thin-wrapper implementations for other logging tools, including <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>, <a href="http://jakarta.apache.org/avalon/logkit/index.html">Avalon LogKit</a>, and <a>JDK 1.4</a>. The interface maps closely to Log4J and LogKit.</p> -<section> -<title>Using the Logger SPI</title> +<h4>Using the Logger SPI</h4> <p>To use the JCL SPI from a Java class, include the following import statements:</p> @@ -180,15 +144,9 @@ log.isTraceEnabled();</source> <p>These are typically used to guard code that only needs to execute in support of logging, and that introduces undesirable runtime overhead in the general case (logging disabled).</p> -</section> - -<section> -<title>Guidelines</title> - -</section> +<h4>Guidelines</h4> -<section> -<title>Message Priorities</title> +<h5>Message Priorities</h5> <p>It is important to ensure that log message are appropriate in content and severity. The following guidelines are suggested:</p> @@ -201,19 +159,13 @@ log.isTraceEnabled();</source> <li>trace - more detailed information. Expect these to be written to logs only. These NEED NOT be internationalized, but it never hurts...</li> </ul> -</section> - -<section> -<title>Configuring the Logger</title> +<h4>Configuring the Logger</h4> <p>The Jakarta Commons Logging (JCL) SPI can be configured to use different logging toolkits. To configure which logger is used by the JCL, see the <a href="integration-guide.html">Axis System Integration Guide</a>.</p> <p>Configuration of the behavior of the JCL ultimately depends upon the logging toolkit being used. The JCL SPI (and hence Axis) uses <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a> by default if it is available (in the CLASSPATH).</p> -</section> - -<section> -<title>Log4J</title> +<h5>Log4J</h5> <p>As <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a> is the prefered/default logger for Axis, a <i>few</i> details are presented herein to get the developer going.</p> @@ -255,13 +207,9 @@ log destinations.</p> </li> </ul> -</section> - -</section> +</subsection> -<a name="AxisServletQueryStringPlug-ins"/> -<section> -<title>Axis Servlet Query String Plug-ins</title> +<subsection name="Axis Servlet Query String Plug-ins"> <p>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 servlets 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:</p> @@ -328,13 +276,11 @@ log destinations.</p> <p>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#DeploymentWSDDReference">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.</p> -</section> +</subsection> </section> -<a name="ConfigurationProperties"/> -<section> -<title>Configuration Properties</title> +<section name="Configuration Properties"> <p>Axis is in the process of moving away from using system properties as the primary point of internal configuration. Avoid calling <code>System.getProperty()</code>, and instead call <code>AxisProperties.getProperty</code>. <code>AxisProperties.getProperty</code> will call <code>System.getProperty</code>, and will (eventually) query other sources of configuration information.</p> @@ -342,9 +288,7 @@ log destinations.</p> </section> -<a name="ExceptionHandling"/> -<section> -<title>Exception Handling</title> +<section name="Exception Handling"> <p>Guidelines for Axis exception handling are based on best-practices for exception handling. While there are details specific to Axis in these guidelines, they apply in principle to any project; they are included here for two reasons. First, because they are not listed elsewhere in the Apache/Jakarta guidelines (or haven't been found). Second, because adherence to these guidelines is considered crucial to enterprise ready middleware.</p> @@ -427,9 +371,7 @@ or program. For a middleware component, </section> -<a name="CompileAndRun"/> -<section> -<title>Compile and Run</title> +<section name="Compile and Run"> <p>The <code>xml-axis/java/build.xml</code> file is the primary 'make' file used by ant to build the application and run the tests. The <code>build.xml</code> file defines ant build <i>targets</i>. Read the build.xml file for more information. Here are some of the useful targets:</p> @@ -456,29 +398,25 @@ ant functional-tests</source> </section> -<a name="Internationalization"/> -<section> -<title>Internationalization</title> +<section name="Internationalization"> <p>If you make changes to the source code that results in the generation of text (error messages or debug information), you must follow the following guidelines to ensure that your text is properly translated.</p> -<a name="DeveloperGuidelines"/> -<section> -<title>Developer Guidelines</title> +<subsection name="Developer Guidelines"> <ol> <li>Your text string should be added as a property to the resource.properties file (xml-axis/java/src/org/apache/axis/i18n/resource.properties). Note that some of the utility applications (i.e. tcpmon) have their own resource property files (tcpmon.properties).</li> - <li>The resource.properties file contains translation and usage instructions. Entries in a message resource file are of the form <key>=<message> Here is an example message: + <li>The resource.properties file contains translation and usage instructions. Entries in a message resource file are of the form <code><key>=<message></code> Here is an example message: <p>sample00=My name is {0}, and my title is {1}.</p> <ol> <li>sample00 is the key that the code will use to access this message.</li> <li>The text after the = is the message text.</li> - <li>The {<i>number</i>} syntax defines the location for inserts.</li> + <li>The <code>{<i>number</i>}</code> syntax defines the location for inserts.</li> </ol> </li> <li>The code should use the static method org.apache.axis.i18n.Messages.getMessage to obtain the text and add inserts. Here is an example usage: - <p>Messages.getMessage("sample00", "Rich Scheuerle", "Software Developer");</p> + <p><code>Messages.getMessage("sample00", "Rich Scheuerle", "Software Developer");</code></p> </li> <li>All keys in the properties file should use the syntax <string><2-digit-suffix>. @@ -491,8 +429,7 @@ ant functional-tests</source> </li> </ol> -<section> -<title>Example</title> +<h4>Example</h4> <p>Consider the following statement:</p> @@ -508,13 +445,9 @@ ant functional-tests</source> <source>if (operationName == null) throw new AxisFault(Messages.getMessage("noOperation"));</source> -</section> - -</section> +</subsection> -<a name="Interface"/> -<section> -<title>Interface</title> +<subsection name="Interface"> <p>Axis uses the standard Java internationalization class <code>java.util.ResourceBundle</code> to access property files and message strings, and uses <code>java.text.MessageFormat</code> to format the strings using variables. Axis provides a single class <code>org.apache.axis.i18n.Messages</code> that manages both ResourceBundle and MessageFormat classes. Messages methods are:</p> @@ -535,8 +468,7 @@ ant functional-tests</source> <li>The <code>getMessage</code> methods enable messages with variables.</li> </ol> -<section> -<title>The getMessage methods</title> +<h4>The getMessage methods</h4> <p>If you have a message with no variables</p> @@ -546,7 +478,7 @@ ant functional-tests</source> <p><code>Messages.getMessage("myMsg00");</code></p> -<p>If you have a message with variables, use the syntax "{X}" where <code>X</code> is the number of the variable, starting at 0. For example:</p> +<p>If you have a message with variables, use the syntax <code>"{X}"</code> where <code>X</code> is the number of the variable, starting at 0. For example:</p> <p><code>myMsg00=My {0} is {1}.</code></p> @@ -556,33 +488,27 @@ ant functional-tests</source> <p>and the resulting string will be: "My name is Russell."</p> -<p>You could also call the String array version of getMessage:</p> +<p>You could also call the String array version of <code>getMessage</code>:</p> <p><code>Messages.getMessage("myMsg00", new String[] {"name", "Russell"});</code></p> -<p>The String array version of getMessage is all that is necessary, but the vast majority of messages will have 0, 1 or 2 variables, so the other getMessage methods are provided as a convenience to avoid the complexity of the String array version.</p> +<p>The String array version of <code>getMessage</code> is all that is necessary, but the vast majority of messages will have 0, 1 or 2 variables, so the other <code>getMessage</code> methods are provided as a convenience to avoid the complexity of the String array version.</p> -<p>Note that the getMessage methods throw MissingResourceException if the resource cannot be found. And ParseException if there are more {X} entries than arguments. These exceptions are RuntimeException's, so the caller doesn't have to explicitly catch them.</p> +<p>Note that the <code>getMessage</code> methods throw <code>MissingResourceException</code> if the resource cannot be found. And ParseException if there are more {X} entries than arguments. These exceptions are <code>RuntimeException</code>'s, so the caller doesn't have to explicitly catch them.</p> <p>The resource bundle properties file is org/apache/axis/i18n/resource.properties.</p> -</section> - -</section> +</subsection> -<a name="ExtendingMessageFiles"/> -<section> -<title>Extending Message Files</title> +<subsection name="Extending Message Files"> <p>Generally, within Axis all messages are placed in org.apache.axis.i18n.resource.properties. There are facilities for extending the messages without modifying this file for integration or 3rd party extensions to Axis. See the <a href="integration-guide.html#Internationalization">Integration Guide</a> for details.</p> -</section> +</subsection> </section> -<a name="AddingTestcases"/> -<section> -<title>Adding Testcases</title> +<section name="Adding Testcases"> <p>See Also: <a href="#TestStructure">Test and Samples Structure</a></p> @@ -610,9 +536,7 @@ ant functional-tests</source> <p>A good "non-wsdl" test for reference is test/saaj.</p> -<a name="CreatingAWSDLTest"/> -<section> -<title>Creating a WSDL Test</title> +<subsection name="Creating a WSDL Test"> <p>Here are the steps that I used to create the <code>sequence</code> test, which generates code from a wsdl file and runs a sequence validation test:</p> @@ -641,17 +565,15 @@ testcase.</li> <mapping namespace="urn:SequenceTest2" package="test.wsdl.sequence"/> </wsdl2java></source> </li> - <li>Enable the run target in the new build.xml file. You need to choose from the execute-Component and the (soon to be introduced) execute-Simple-Test target. These control HOW the test is invoked when run as a single component. The execute-Component sets up the tcp-server and http-server prior to running the test, as well as handles deploying and services that may be needed. The execute-Simple-test simply invokes the raw test class file.</li> + <li>Enable the <code>run</code> target in the new build.xml file. You need to choose from the <code>execute-Component</code> and the (soon to be introduced) <code>execute-Simple-Test</code> target. These control HOW the test is invoked when run as a single component. The <code>execute-Component</code> sets up the tcp-server and http-server prior to running the test, as well as handles deploying and services that may be needed. The <code>execute-Simple-test</code> simply invokes the raw test class file.</li> <li>Done. Run <code>ant functional-tests </code>to verify. Check in your test.</li> </ol> -</section> +</subsection> </section> -<a name="TestStructure"/> -<section> -<title>Test Structure</title> +<section name="Test Structure"> <p><a href="AxisTestRedesign.html">The Test and Samples Redesign Document is here</a></p> @@ -669,9 +591,7 @@ testcase.</li> </section> -<a name="AddingSourceCodeChecks"/> -<section> -<title>Adding Source Code Checks</title> +<section name="Adding Source Code Checks"> <p>The Axis build performs certain automated checks of the files in the source directory (java/src) to make sure certain conventions are followed such as using internationalised strings when issuing messages.</p> @@ -689,9 +609,7 @@ testcase.</li> </section> -<a name="JUnitAndAxis"/> -<section> -<title>JUnit and Axis</title> +<section name="JUnit and Axis"> <p>You try to run some JUnit tests on an Axis client that invokes a web service, and you always get this exception:</p> @@ -759,9 +677,9 @@ at org.apache.axis.encoding.Deserializer </section> -<a name="UsingTcpmonToMonitorFunctionalTests"/> -<section> -<title>Using tcpmon to Monitor Functional Tests</title> +<section name="Debugging"> + +<subsection name="Using tcpmon to Monitor Functional Tests."> <p>Here is an easy way to monitor the messages while running <code>functional-tests</code> (or <code>all-tests</code>).</p> @@ -777,11 +695,9 @@ at org.apache.axis.encoding.Deserializer <p><code>tcpmon</code> is described in more detail in the <a href="user-guide.html#AppendixUsingTheAxisTCPMonitorTcpmon">Axis User's Guide</a>.</p> -</section> +</subsection> -<a name="UsingSOAPMonitorToMonitorFunctionalTests"/> -<section> -<title>Using SOAP Monitor to Monitor Functional Tests</title> +<subsection name="Using SOAP Monitor to Monitor Functional Tests"> <p>If you are debugging code that is running as a web application using a web application server (such as Tomcat) then you may also use the SOAP Monitor utility to view the SOAP request and response messages.</p> @@ -793,11 +709,9 @@ at org.apache.axis.encoding.Deserializer <p><code>SOAP Monitor</code> is described in more detail in the <a href="user-guide.html#AppendixUsingTheSOAPMonitor">Axis User's Guide</a>.</p> -</section> +</subsection> -<a name="RunningASingleFunctionalTest"/> -<section> -<title>Running a Single Functional Test</title> +<subsection name="Running a Single Functional Test"> <p>In one window start the server:</p> @@ -811,15 +725,9 @@ at org.apache.axis.encoding.Deserializer <p><code>java junit.swingui.TestRunner -noloading test.wsdl.multithread.MultithreadTestCase</code></p> -</section> +</subsection> -<a name="Debugging"/> -<section> -<title>Debugging</title> - -<a name="TurningOnDebugOutput"/> -<section> -<title>Turning on Debug Output</title> +<subsection name="Turning on Debug Output"> <p>This section is oriented to the Axis default logger: Log4J. For additional information on Log4J, see the section <a href="#Logging/Tracing">Configuring the Logger</a>.</p> @@ -851,11 +759,9 @@ at org.apache.axis.encoding.Deserializer </li> </ul> -</section> +</subsection> -<a name="WritingTemporaryOutput"/> -<section> -<title>Writing Temporary Output</title> +<subsection name="Writing Temporary Output"> <p>Remember that Axis is targeted for use in a number of open-source and other web applications, and so it needs to be a good citizen. Writing output using <code>System.out.println</code> or <code>System.err.println</code> should be avoided.</p> @@ -863,13 +769,11 @@ at org.apache.axis.encoding.Deserializer <p>As an alternative, we strongly encourage you to take a few moments and introduce debug statements: <code>log.debug("reasonably terse and meaningful message")</code>. If a debug message is useful for understanding a problem now, it may be useful again in the future to you or a peer.</p> -</section> +</subsection> </section> -<a name="RunningTheJAX-RPCCompatibilityTests"/> -<section> -<title>Running the JAX-RPC Compatibility Tests</title> +<section name="Running the JAX-RPC Compatibility Tests"> <p>As well as a specification, JAX-RPC has a Technology Compatibility Kit (TCK) which is available to members of the JAX-RPC Expert Group (and others?).</p> @@ -881,7 +785,5 @@ at org.apache.axis.encoding.Deserializer </section> -</section> - </body> </document>