axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sc...@apache.org
Subject cvs commit: xml-axis/java/docs developers-guide.html
Date Wed, 21 Nov 2001 20:30:57 GMT
scheu       01/11/21 12:30:57

  Modified:    java/docs developers-guide.html
  Log:
  Changes suggested by Russell (offline) and dims (in axis-dev)
  
  Revision  Changes    Path
  1.2       +92 -83    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.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- developers-guide.html	2001/11/21 19:47:48	1.1
  +++ developers-guide.html	2001/11/21 20:30:57	1.2
  @@ -92,8 +92,8 @@
   The <tt>xml-axis/java/build.xml</tt> file is the primary 'make' file used
   by ant to build the application and run the tests.&nbsp; The <tt>build.xml</tt>
   file defines ant build <i>targets</i>.&nbsp; Read the build.xml file for
  -more information.&nbsp; Here are some of the useful targets:<br>
  -<BR>
  +more information.&nbsp; Here are some of the useful targets:
  +<br>&nbsp;
   <ul>
   <li>
   <tt>compile -> compiles the source and creates xml-axis/java/build/lib/axis.jar</tt></li>
  @@ -105,9 +105,9 @@
   <tt>functional-tests -> compiles and runs the functional tests</tt></li>
   
   <li>
  -<tt>all-tests -> compiles and runs all of the tests</tt><br>
  -<BR></li>
  -</ul>
  +<tt>all-tests -> compiles and runs all of the tests</tt></li>
  +
  +<br>&nbsp;</ul>
   To compile the source code:
   <blockquote><tt>cd xml-axis/java</tt>
   <br><tt>ant compile</tt></blockquote>
  @@ -115,7 +115,7 @@
   <blockquote><tt>cd xml-axis/java</tt>
   <br><tt>ant functional-tests</tt></blockquote>
   <b>Please run <tt><font color="#009900">ant functional-tests</font></tt>
  -and/or <tt><font color="#009900">ant all-tests</font></tt> before
checking
  +and <tt><font color="#009900">ant all-tests</font></tt> before
checking
   in new code.</b>
   <h2>
   <a NAME="Internationalization"></a>Internationalization</h2>
  @@ -128,16 +128,17 @@
   Your text string should be added as a property to the resource.properties
   file (xml-axis/java/src/org/apache/axis/utils/resource.properties).&nbsp;
   Note that some of the utility applications (i.e. tcpmon) have their own
  -resource property files (tcpmon.properties).<br>
  -<BR></li>
  +resource property files (tcpmon.properties).</li>
   
  +<br>&nbsp;
   <li>
   The resource.properties file contains translation and usage instructions.&nbsp;
  -Here is an example message:<br>
  -<BR></li>
  +Here is an example message:</li>
   
  -<br><font color="#009900">sample00=My name is {0}, and my title is {1}.</font><br>
  -<BR>
  +<br>&nbsp;
  +<p>&nbsp;
  +<p><font color="#009900">sample00=My name is {0}, and my title is {1}.</font>
  +<br>&nbsp;
   <ol>
   <li>
   sample00 is the key that the code will use to access this message.</li>
  @@ -147,38 +148,39 @@
   
   <li>
   The <font color="#009900">{<i>number</i>}</font> syntax defines
the location
  -for inserts.<br>
  -<BR></li>
  -</ol>
  +for inserts.</li>
   
  -<li>
  -The code should use the static method org.apache.axis.utils.JavaUtils.getMessage
  -method to obtain the text and add inserts.&nbsp; Here is an example usage:<br>
  -<BR></li>
  +<br>&nbsp;</ol>
   
  -<br><font color="#009900">JavaUtils.getMessage("sample00", "Rich Scheuerle",
  -"Software Developer");</font><br>
  -<BR>
   <li>
  -<font color="#000000">Please ensure that the properties in the resource
  -file are kept in alphabetical order by key.</font><br>
  -<BR></li>
  +The code should use the static method org.apache.axis.utils.JavaUtils.getMessage
  +method to obtain the text and add inserts.&nbsp; Here is an example usage:</li>
   
  +<br>&nbsp;
  +<p>&nbsp;
  +<p><font color="#009900">JavaUtils.getMessage("sample00", "Rich Scheuerle",
  +"Software Developer");</font>
  +<br>&nbsp;
   <li>
   <font color="#000000">All keys in the properties file should use the syntax
  -&lt;string>&lt;2-digit-suffix>.</font><br>
  -<BR></li>
  +&lt;string>&lt;2-digit-suffix>.</font></li>
   
  +<br>&nbsp;
   <ol>
   <li>
   <font color="#000000"><b>Never change the message text in the properties
   file. </b>The message may be used in multiple places in the code.&nbsp;
  -Plus translation is only done on new keys.</font><br>
  -<BR></li>
  +Plus translation is only done on new keys.</font></li>
   
  +<br>&nbsp;
   <li>
   <font color="#000000">If a code change requires a change to a message,
   create a new entry with an incremented 2-digit suffix.</font></li>
  +
  +<br>&nbsp;
  +<li>
  +<font color="#000000">All new entries should be placed at the bottom of
  +the file to ease translation.</font></li>
   </ol>
   </ol>
   
  @@ -186,8 +188,8 @@
   <a NAME="Adding Testcases"></a><font color="#000000">Adding Testcases</font></h2>
   <font color="#000000"><b>Editor's Note: </b>We need more effort to streamline
   and simplify the addition of tests.&nbsp; We also need to think about categorizing
  -tests as the test bucket grows.</font><br>
  -<BR>
  +tests as the test bucket grows.</font>
  +<br>&nbsp;
   <p><font color="#000000">If you make changes to Axis, please add a test
   that uses your change.&nbsp; Why?</font>
   <ul>
  @@ -206,8 +208,8 @@
   <font color="#000000">The test can be used as a starting point for new
   development.</font></li>
   </ul>
  -<br>
  -<font color="#000000">Some general principles:</font>
  +
  +<p><br><font color="#000000">Some general principles:</font>
   <ul>
   <li>
   <font color="#000000">Tests should be self-explanatory.</font></li>
  @@ -219,88 +221,100 @@
   <font color="#000000">Tests should hook into the existing junit framework.</font></li>
   
   <li>
  -<font color="#000000">Each test should have its own directory in the <tt>xml-axis/java/test</tt>
  -directory</font></li>
  +<font color="#000000">Each test or group of related tests should have its
  +own directory in the <tt>xml-axis/java/test</tt> directory</font></li>
   </ul>
  -<br>
  -<font color="#000000">One way to build a test is to "cut and paste" and
  -existing tests, and then modify the test to suit your needs.&nbsp; This
  -approach is becoming more complicated as the different kinds of tests grow.</font>
  +
  +<p><br><font color="#000000">One way to build a test is to "cut and paste"
  +and existing tests, and then modify the test to suit your needs.&nbsp;
  +This approach is becoming more complicated as the different kinds of tests
  +grow.</font>
   <h4>
   <font color="#000000">Creating a WSDL Test</font></h4>
   <font color="#000000">Here are the steps that I used to create the <tt>sequence</tt>
   test, which generates code from a wsdl file and runs a sequence validation
  -test:</font><br>
  -<BR>
  +test:</font>
  +<br>&nbsp;
   <ol>
   <li>
  -<font color="#000000">Created a <tt>xml-axis/java/test/sequence</tt>
directory.</font><br>
  -<BR></li>
  +<font color="#000000">Created a <tt>xml-axis/java/test/sequence</tt>
directory.</font></li>
   
  +<br>&nbsp;
   <li>
   <font color="#000000">Created a <tt>SequenceTest.wsdl</tt> file defining
  -the webservice.</font><br>
  -<BR></li>
  +the webservice.</font></li>
   
  +<br>&nbsp;
   <li>
   <font color="#000000">Ran the Wsdl2java emitter to create java files:</font><br>
   <BR></li>
   
  -<br><tt><font color="#993366">java org.apache.axis.wsdl.Wsdl2java -t
-s
  -SequenceTest.wsdl</font></tt><br>
  -<BR>
  +<p><br><tt><font color="#993366">java org.apache.axis.wsdl.Wsdl2java
-t
  +-s SequenceTest.wsdl</font></tt>
  +<br>&nbsp;
  +<ol>
   <li>
   <font color="#000000">The -t option causes the emitter to generate a *TestCase.java
  -file that hooks into the test harness.&nbsp; No changes need to be made
  -to the file.&nbsp; Copy the *TestCase.java file into the same directory
  -as your wsdl file.</font><br>
  +file that hooks into the test harness. This file is operational without
  +any additional changes.&nbsp; Copy the *TestCase.java file into the same
  +directory as your wsdl file.&nbsp; (Ideally only the java files that are
  +changed need to be in your directory.&nbsp; So this file is not needed,
  +but please make sure to modify your &lt;wsdl2java ...> clause (described
  +below) to emit a testcase.</font><br>
  +<br>
   <BR></li>
   
   <li>
   <font color="#000000">The -s option causes the emitter to generate a *SOAPBindingImpl.java
  -file.&nbsp; Modify the file to add your service code to the generated methods.&nbsp;
  -Copy the *SOAPBindingImpl.java file into the same directory as your wsdl
  -file.</font><br>
  -<BR></li>
  +file.&nbsp; The java file contains empty methods for the service.&nbsp;
  +You probably want to fill them in with your own logic.&nbsp; Copy the *SOAPBindingImpl.java
  +file into the same directory as your wsdl file.&nbsp; (If no changes are
  +needed in the java file, you don't need to save it.&nbsp; But you will
  +need to make sure that your &lt;wsdl2java ...> clause generates a skeleton).</font></li>
  +</ol>
   
  +<ol>
   <li>
  -<font color="#000000">So you should have three files in your directory
  -(wsdl file, *TestCase.java, and *SOAPBindingImpl.java).&nbsp; My sequence
  -test has an another file due to some additional logic that I needed.</font><br>
  -<BR></li>
  +<font color="#000000">Remove all of the java files that don't require modification.&nbsp;
  +So you should have three files in your directory (wsdl file, *TestCase.java,
  +and *SOAPBindingImpl.java).&nbsp; My sequence test has an another file
  +due to some additional logic that I needed.</font></li>
  +</ol>
   
   <li>
   <font color="#000000">In the build.xml file, locate the "buildTest" target.&nbsp;
   You will need to add an &lt;exclude .../> clause to prevent your two java
   files from being compiled.&nbsp; (Note it would be nice if there was a
   better way to prevent this.) Here is the exclude clause for the sequence
  -test:</font><br>
  -<BR></li>
  +test:</font></li>
   
  -<br><tt><font color="#993366">&lt;exclude name="test/sequence/*.java"
/></font></tt><br>
  -<BR>
  +<br>&nbsp;
  +<p>&nbsp;
  +<p><tt><font color="#993366">&lt;exclude name="test/sequence/*.java"
/></font></tt>
  +<br>&nbsp;
   <li>
   <font color="#000000">The <tt>test/build_functional_tests.xml</tt> file
   controls the building of the tests.&nbsp; Locate the "wsdl-setup" target.&nbsp;
  -You will see a clause that runs the Wsdl2java code:&nbsp;<br>
  -<br>
  -</font><tt><font color="#993366">&lt;ant antfile="test/wsdl/Wsdl2javaTestSuite.xml"/><br>
  -<br>
  -</font></tt><font color="#000000">Following this clause you will see
some
  -clauses that copy java files from the test directories.&nbsp; If you have
  -additional files, you need to copy them over.&nbsp; Examine the clause
  -that I added to copy over SequenceInfo.java.&nbsp; (Note it would be nice
  -if there was a better way to do this.)</font><br>
  -<BR></li>
  +You will see a clause that runs the Wsdl2java code:</font></li>
   
  +<br>&nbsp;
  +<p>&nbsp;
  +<p><tt><font color="#993366">&lt;ant antfile="test/wsdl/Wsdl2javaTestSuite.xml"/></font></tt>
  +<p><font color="#000000">Following this clause you will see some clauses
  +that copy java files from the test directories.&nbsp; If you have additional
  +files, you need to copy them over.&nbsp; Examine the clause that I added
  +to copy over SequenceInfo.java.&nbsp; (Note it would be nice if there was
  +a better way to do this.)</font>
  +<br>&nbsp;
   <li>
   <font color="#000000">Now go to the <tt>test/wsdl/Wsdl2javaTestSuite.xml
   </tt>file.&nbsp;
   This file contains the clauses to run wsdl2java.&nbsp; Add a wsdl2java
  -clause.&nbsp; Here is the one for SequenceTest:</font><br>
  -<BR></li>
  +clause.&nbsp; Here is the one for SequenceTest:</font></li>
   
  -<br><tt><font color="#663366">&nbsp;&nbsp;&nbsp; </font><font
color="#993366">&lt;!--
  +<br>&nbsp;
  +<p>&nbsp;
  +<p><tt><font color="#663366">&nbsp;&nbsp;&nbsp; </font><font
color="#993366">&lt;!--
   Sequence Test --></font></tt>
   <br><tt><font color="#993366">&nbsp;&nbsp;&nbsp; &lt;wsdl2java
url="test/sequence/SequenceTest.wsdl"</font></tt>
   <br><tt><font color="#993366">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  @@ -319,13 +333,8 @@
   testcase="no"></font></tt>
   <br><tt><font color="#993366">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
   &lt;mapping namespace="urn:SequenceTest2" package="test.sequence"/></font></tt>
  -<br><tt><font color="#993366">&nbsp;&nbsp;&nbsp; &lt;/wsdl2java></font></tt><br>
  -<BR>
  -<li>
  -<font color="#000000">Open the file Wsdl2javaTestSuite.list and add the
  -location of your wsdl document.&nbsp; (Note: Why is this necessary?)</font><br>
  -<BR></li>
  -
  +<br><tt><font color="#993366">&nbsp;&nbsp;&nbsp; &lt;/wsdl2java></font></tt>
  +<br>&nbsp;
   <li>
   <font color="#000000">Done.&nbsp; Run </font><tt><font color="#993366">ant
   functional-tests</font><font color="#000000"> </font></tt><font
color="#000000">to
  
  
  

Mime
View raw message