<HTML>
<HEAD>
<TITLE>Axis Test Rearchitecture</TITLE>
<link href="axis.css" rel=stylesheet type=text/css>
</HEAD>
<BODY>
<H1><CENTER>Axis Test Rearchitecture</H1></CENTER>
<a name="top"></a>
<a href="#quickstart">Quick Start</a><BR>
<a href="#common">Common Design Principles</a><BR>
<a href="#general">General Changes</a><BR>
<a href="#samples">Samples Changes</a><BR>
<a href="#tests">Test Changes</a><BR>
<HR>
<a name="quickstart"><H2>Quick Start</H2></a>
<P>
To run the full build system, as the old was run, do the following:
<PRE>ant clean functional-tests</PRE>
To see how the componentized build structure is affected, as well as cross-dependancies, do the following:
<PRE>ant clean compile
cd test/encoding
ant clean compile run
</PRE>
(The encoding test has a dependancy on the echo sample)
</P>
<a href="#top">Back to the Top</a><BR>
<HR>
<a name="common"><H2>Common Design Principles</H2></a>
<P>
There were 6 design goals that were laid out for me before undertaking this project:<BR>
<OL>
<LI>Determine the needs and dependancies of each test and sample
<LI>Reduce the complexity of the xml that compiles, deploys, execs, and undeploys samples and tests
<LI>Enable a new test or sample to be "plugged in" to the suites, without disturbing currently working things
<LI>Enable the ability to instantiate any single sample or any single test
<LI>Identify tests and samples that need "network" or "internet" resources
<LI>Enable the ability to group tests and samples together in "bundles"
</OL>
</P>
<P>
To this end, the general theory was applied to everything:<BR>
<UL>
<LI>Remove the neccessary steps that are in build.xml into build<I><B>thing</B></I>.xml (where <I><B>thing</B></I> is either "Samples" or "Test")
<LI>Create a build.xml file in each samples/** and test/** directory
<LI>Stub each build.xml with the following:
<PRE>&lt?xml version="1.0" ?&gt

&lt!-- =========================================================================================== --&gt
&lt!--  Every project should begin with this next block --&gt
&lt!-- =========================================================================================== --&gt
&lt!DOCTYPE project [
        &lt!ENTITY properties SYSTEM "file:../../xmls/properties.xml"&gt
        &lt!ENTITY paths  SYSTEM "file:../../xmls/path_refs.xml"&gt
        &lt!ENTITY taskdefs SYSTEM "file:../../xmls/taskdefs.xml"&gt
        &lt!ENTITY taskdefs_post_compile SYSTEM "file:../../xmls/taskdefs_post_compile.xml"&gt
        &lt!ENTITY targets SYSTEM "file:../../../xmls/targets.xml"&gt
]&gt

&lt project default="compile" &gt

&lt!-- =========================================================================================== --&gt
&lt!-- This tells how "deep" you are (how many levels down from xml-axis/java  --&gt
&lt!-- =========================================================================================== --&gt
&ltproperty name="axis.home" location="../../.." /&gt

&lt!-- =========================================================================================== --&gt
&lt!-- This is the path description of where you are right now, relative to xmls-axis/java  --&gt
&lt!-- =========================================================================================== --&gt
&ltproperty name="componentName" value="test/wsdl/marrays" /&gt

        &properties;
        &paths;
        &taskdefs;
        &taskdefs_post_compile;
        &targets;

&lt!-- =========================================================================================== --&gt
&lt!-- This target should remove anything created by this component --&gt
&lt!-- =========================================================================================== --&gt
&lt target name="clean"/&gt

&lt!-- =========================================================================================== --&gt
&lt!-- This target should copy in anything that this component needs, or copy out to staging --&gt
&lt!-- This target should also do any neccessary "setup" tasks (manage pre-reqs, etc) --&gt
&lt!-- =========================================================================================== --&gt
&lt target name="copy"/&gt

&lt!-- =========================================================================================== --&gt
&lt!-- This target actually "makes" things --&gt
&lt!-- =========================================================================================== --&gt
&lt target name="compile"/&gt

&lt!-- =========================================================================================== --&gt
&lt!-- This target "runs" things in/for this component, if neccessary --&gt
&lt!-- =========================================================================================== --&gt
&lttarget name="run" &gt
  &ltantcall target="execute-Component" /&gt
&lt/target&gt

&lt/project&gt
</PRE>
<LI>If you want to instantiate this component directly, then add the following type stub into buildSamples.xml or buildTest.xml as appropriate:
<PRE>&lt target name="echo"&gt
    &lt ant inheritAll="true" antfile="samples/echo/build.xml"/&gt
&lt/target&gt</PRE>
This should be done if this sample/test is to be a dependancy of another sample or test.
<LI>If you don't want to instantiate it directly, the "compile" target looping in the buildSamples.xml or buildTest.xml file will pick up any build.xml files in the appropriate path.
<LI>In order to reference a dependancy in a component build.xml file, do the following (taken from test/soap/build.xml):
<PRE>
&lt target name="copy"&gt
  &lt ant inheritAll="true" antfile="build.xml" target="utils"/&gt
  &lt ant inheritAll="true" antfile="build.xml" target="RFCDispatch"/&gt
&lt/target&gt</PRE>
</UL>
</P>
<a href="#top">Back to the Top</a><BR>
<HR>
<a name="general"><H2>Generic Changes</H2></a>
<P>A new top-level path was created, named "xmls".  This path houses the common xml configuration file fragments.  Roughly, in order of their inclusion, they are:<BR><BR>
<B>properties.xml</B> contains common properties, eliminating the large property setting blocks at the top of each build*.xml file.<BR>
<B>path_refs.xml</B> contains the common CLASSPATH setup, to eliminate needing to track, or multiply define this large structure in all files separately.<BR>
<B>taskdefs.xml</B> contains common ant tasks that are set up, the are inherent in the configuration.<BR>
<B>taskdefs_post_compile.xml</B> contains the definitions of tasks that are built during the compilation of tasks, such as forEach, java2wsdl, and wsdl2java.<BR>
<B>targets.xml</B> contains common configuration level targets that required hundreds of lines of repeated code in the build*.xml files.
</P>
<a href="#top">Back to the Top</a><BR>
<HR>
<a name="samples"><H2>Samples</H2></a>
<P>
The old $(TOP)/build.xml had a target called "samples" which did a very simple full-compile on everything referenced by samples/**/*.java.  Although this was very simple, it was not very "strong" in that everything in the samples tree needed to be able to be compiled by this rule.  Whenever anything needed to be altered in the samples, this main file needed to be modified.  It was very possible for someone to add a sample that needed a change, and by changing the master file, could break an large number of things.
</P>
<P>
In order to alleviate this risk, and to better define the actual samples compilation and use, the samples building has been moved to a new xml file <B>buildSamples.xml</B> but the original target is still stubbed into build.xml for backwards compatibility and use does not change.
</P>
<P>
Then, I extracted the actual compilation logic for each sample, and componentized it into a build.xml file, located in the actual sample sub-directory.  For example, for the echo sample is now run by the file samples/echo/build.xml.  It can be singularly instantiated by invoking:
<CENTER><PRE>ant -buildfile buildSamples.xml echo</PRE></CENTER>
or as part of the batch (as the old function) by invoking:
<CENTER><PRE>ant samples</PRE></CENTER>
which is what build.xml does in the "samples" target.
</P>
<a href="#top">Back to the Top</a><BR>
<HR>
<a name="tests"><H2>Tests</H2></a>
<P>
The old $(TOP)/build.xml had a target called "buildTest" which did a very simple full-compile on every thing referenced by test/**/*.java.  Although this was very simple, it was not very "strong" in that everything in the test tree needed to be able to be compiled by this rule.  Whenever anything needed to be altered in the test, this main file needed to be modified.  It was very possible for someone to add a test that needed a change, and by changing the master file, could break an large number of things.
</P>
<P>
In order to alleviate this risk, and to better define the actual test compilation and use, the test building has been moved to a new xml file <B>buildTest.xml</B> but the original target is still stubbed into build.xml for backwards compatibility and use does not change.
</P>
<P>
Then, I extracted the actual compilation logic for each test, and componentized it into a build.xml file, located in the actual test sub-directory.  For example, for the session test is now compiled by the file test/session/build.xml.  It can be singularly instantiated by invoking:
<CENTER><PRE>ant -buildfile buildTest.xml session</PRE></CENTER>
or as part of the batch (as the old function) by invoking:
<CENTER><PRE>ant functional-tests</PRE></CENTER>
which is what build.xml does in the "buildTest" target.
</P>

</BODY>
</HTML>