javadoc

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@473558 13f79535-47bb-0310-9956-ffa450edef68

src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTaskMirror.java

@@ -143,15 +143,46 @@ public interface JUnitTaskMirror {
          */
         int getRetCode();
 
+        /**
+         * Handle output sent to System.err.
+         *
+         * @param output coming from System.err
+         */
         void handleErrorFlush(String output);
 
+        /**
+         * Handle output sent to System.err.
+         *
+         * @param output output for System.err
+         */
         void handleErrorOutput(String output);
 
+        /**
+         * Handle output sent to System.out.
+         *
+         * @param output output for System.out.
+         */
         void handleOutput(String output);
 
+        /**
+         * Handle an input request.
+         *
+         * @param buffer the buffer into which data is to be read.
+         * @param offset the offset into the buffer at which data is stored.
+         * @param length the amount of data to read.
+         *
+         * @return the number of bytes read.
+         *
+         * @exception IOException if the data cannot be read.
+         */
         int handleInput(byte[] buffer, int offset, int length) throws IOException;
 
-        void handleFlush(String output);
+        /**
+         * Handle output sent to System.out.
+         *
+         * @param output output for System.out.
+         */
+       void handleFlush(String output);
 
     }
 }

src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTaskMirrorImpl.java

@@ -35,10 +35,15 @@ public final class JUnitTaskMirrorImpl implements JUnitTaskMirror {
 
     private final JUnitTask task;
 
+    /**
+     * Constructor.
+     * @param task the junittask that uses this mirror.
+     */
     public JUnitTaskMirrorImpl(JUnitTask task) {
         this.task = task;
     }
 
+    /** {@inheritDoc}. */
     public void addVmExit(JUnitTest test, JUnitTaskMirror.JUnitResultFormatterMirror aFormatter,
             OutputStream out, String message, String testCase) {
         JUnitResultFormatter formatter = (JUnitResultFormatter) aFormatter;
@@ -53,6 +58,7 @@ public final class JUnitTaskMirrorImpl implements JUnitTaskMirror {
         formatter.endTestSuite(test);
     }
 
+    /** {@inheritDoc}. */
     public JUnitTaskMirror.JUnitTestRunnerMirror newJUnitTestRunner(JUnitTest test,
             boolean haltOnError, boolean filterTrace, boolean haltOnFailure,
             boolean showOutput, boolean logTestListenerEvents, AntClassLoader classLoader) {
@@ -60,6 +66,7 @@ public final class JUnitTaskMirrorImpl implements JUnitTaskMirror {
                 showOutput, logTestListenerEvents, classLoader);
     }
 
+    /** {@inheritDoc}. */
     public JUnitTaskMirror.SummaryJUnitResultFormatterMirror newSummaryJUnitResultFormatter() {
         return new SummaryJUnitResultFormatter();
     }

src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTest.java

@@ -52,13 +52,25 @@ public class JUnitTest extends BaseTest implements Cloneable {
     // Snapshot of the system properties
     private Properties props = null;
 
+    /** No arg constructor. */
     public JUnitTest() {
     }
 
+    /**
+     * Constructor with name.
+     * @param name the name of the test.
+     */
     public JUnitTest(String name) {
         this.name  = name;
     }
 
+    /**
+     * Constructor with options.
+     * @param name the name of the test.
+     * @param haltOnError if true halt the tests if there is an error.
+     * @param haltOnFailure if true halt the tests if there is a failure.
+     * @param filtertrace if true filter stack traces.
+     */
     public JUnitTest(String name, boolean haltOnError, boolean haltOnFailure,
                      boolean filtertrace) {
         this.name  = name;
@@ -69,6 +81,7 @@ public class JUnitTest extends BaseTest implements Cloneable {
 
     /**
      * Set the name of the test class.
+     * @param value the name to use.
      */
     public void setName(String value) {
         name = value;
@@ -76,6 +89,7 @@ public class JUnitTest extends BaseTest implements Cloneable {
 
     /**
      * Set the name of the output file.
+     * @param value the name of the output file to use.
      */
     public void setOutfile(String value) {
         outfile = value;
@@ -83,6 +97,7 @@ public class JUnitTest extends BaseTest implements Cloneable {
 
     /**
      * Get the name of the test class.
+     * @return the name of the test.
      */
     public String getName() {
         return name;
@@ -97,36 +112,71 @@ public class JUnitTest extends BaseTest implements Cloneable {
         return outfile;
     }
 
+    /**
+     * Set the number of runs, failures and errors.
+     * @param runs     the number of runs.
+     * @param failures the number of failures.
+     * @param errors   the number of errors.
+     */
     public void setCounts(long runs, long failures, long errors) {
         this.runs = runs;
         this.failures = failures;
         this.errors = errors;
     }
 
+    /**
+     * Set the runtime.
+     * @param runTime the time in milliseconds.
+     */
     public void setRunTime(long runTime) {
         this.runTime = runTime;
     }
 
+    /**
+     * Get the number of runs.
+     * @return the number of runs.
+     */
     public long runCount() {
         return runs;
     }
 
+    /**
+     * Get the number of failures.
+     * @return the number of failures.
+     */
     public long failureCount() {
         return failures;
     }
 
+    /**
+     * Get the number of errors.
+     * @return the number of errors.
+     */
     public long errorCount() {
         return errors;
     }
 
+    /**
+     * Get the run time.
+     * @return the run time in milliseconds.
+     */
     public long getRunTime() {
         return runTime;
     }
 
+    /**
+     * Get the properties used in the test.
+     * @return the properties.
+     */
     public Properties getProperties() {
         return props;
     }
 
+    /**
+     * Set the properties to be used in the test.
+     * @param p the properties.
+     *          This is a copy of the projects ant properties.
+     */
     public void setProperties(Hashtable p) {
         props = new Properties();
         for (Enumeration e = p.keys(); e.hasMoreElements();) {
@@ -135,6 +185,13 @@ public class JUnitTest extends BaseTest implements Cloneable {
         }
     }
 
+    /**
+     * Check if this test should run based on the if and unless
+     * attributes.
+     * @param p the project to use to check if the if and unless
+     *          properties exist in.
+     * @return true if this test or testsuite should be run.
+     */
     public boolean shouldRun(Project p) {
         if (ifProperty != null && p.getProperty(ifProperty) == null) {
             return false;
@@ -146,6 +203,10 @@ public class JUnitTest extends BaseTest implements Cloneable {
         return true;
     }
 
+    /**
+     * Get the formatters set for this test.
+     * @return the formatters as an array.
+     */
     public FormatterElement[] getFormatters() {
         FormatterElement[] fes = new FormatterElement[formatters.size()];
         formatters.copyInto(fes);
@@ -164,6 +225,7 @@ public class JUnitTest extends BaseTest implements Cloneable {
 
     /**
      * @since Ant 1.5
+     * @return a clone of this test.
      */
     public Object clone() {
         try {

src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTestRunner.java

@@ -549,6 +549,10 @@ public class JUnitTestRunner implements TestListener, JUnitTaskMirror.JUnitTestR
         perm = permissions;
     }
 
+    /**
+     * Handle a string destined for standard output.
+     * @param output the string to output
+     */
     public void handleOutput(String output) {
         if (!logTestListenerEvents && output.startsWith(JUnitTask.TESTLISTENER_PREFIX)) {
             // ignore
@@ -558,6 +562,12 @@ public class JUnitTestRunner implements TestListener, JUnitTaskMirror.JUnitTestR
     }
 
     /**
+     * Handle input.
+     * @param buffer not used.
+     * @param offset not used.
+     * @param length not used.
+     * @return -1 always.
+     * @throws IOException never.
      * @see org.apache.tools.ant.Task#handleInput(byte[], int, int)
      *
      * @since Ant 1.6
@@ -567,18 +577,21 @@ public class JUnitTestRunner implements TestListener, JUnitTaskMirror.JUnitTestR
         return -1;
     }
 
+    /** {@inheritDoc}. */
     public void handleErrorOutput(String output) {
         if (systemError != null) {
             systemError.print(output);
         }
     }
 
+    /** {@inheritDoc}. */
     public void handleFlush(String output) {
         if (systemOut != null) {
             systemOut.print(output);
         }
     }
 
+    /** {@inheritDoc}. */
     public void handleErrorFlush(String output) {
         if (systemError != null) {
             systemError.print(output);
@@ -609,10 +622,12 @@ public class JUnitTestRunner implements TestListener, JUnitTaskMirror.JUnitTestR
         }
     }
 
+    /** {@inheritDoc}. */
     public void addFormatter(JUnitResultFormatter f) {
         formatters.addElement(f);
     }
 
+    /** {@inheritDoc}. */
     public void addFormatter(JUnitTaskMirror.JUnitResultFormatterMirror f) {
         formatters.addElement((JUnitResultFormatter) f);
     }
@@ -643,6 +658,8 @@ public class JUnitTestRunner implements TestListener, JUnitTaskMirror.JUnitTestR
      * System.out.</td><td>false</td></tr>
      *
      * </table>
+     * @param args the command line arguments.
+     * @throws IOException on error.
      */
     public static void main(String[] args) throws IOException {
         boolean haltError = false;
@@ -840,6 +857,7 @@ public class JUnitTestRunner implements TestListener, JUnitTaskMirror.JUnitTestR
     /**
      * Filters stack frames from internal JUnit and Ant classes
      * @param stack the stack trace to filter.
+     * @return the filtered stack.
      */
     public static String filterStack(String stack) {
         if (!filtertrace) {

src/main/org/apache/tools/ant/taskdefs/optional/junit/PlainJUnitResultFormatter.java

@@ -176,7 +176,7 @@ public class PlainJUnitResultFormatter implements JUnitResultFormatter {
      * Interface TestListener.
      *
      * <p>A Test is finished.
-     * @param t the test.
+     * @param test the test.
      */
     public void endTest(Test test) {
         if (Boolean.TRUE.equals(failed.get(test))) {

src/main/org/apache/tools/ant/taskdefs/optional/junit/SummaryJUnitResultFormatter.java

@@ -31,8 +31,7 @@ import org.apache.tools.ant.BuildException;
  */
 
 public class SummaryJUnitResultFormatter
-    implements JUnitResultFormatter
-    ,JUnitTaskMirror.SummaryJUnitResultFormatterMirror {
+    implements JUnitResultFormatter, JUnitTaskMirror.SummaryJUnitResultFormatterMirror {
 
     /**
      * Formatter for timings.
@@ -54,6 +53,7 @@ public class SummaryJUnitResultFormatter
     }
     /**
      * The testsuite started.
+     * @param suite the testsuite.
      */
     public void startTestSuite(JUnitTest suite) {
         String newLine = System.getProperty("line.separator");
@@ -70,16 +70,20 @@ public class SummaryJUnitResultFormatter
     }
     /**
      * Empty
+     * @param t not used.
      */
     public void startTest(Test t) {
     }
     /**
      * Empty
+     * @param test not used.
      */
     public void endTest(Test test) {
     }
     /**
      * Empty
+     * @param test not used.
+     * @param t not used.
      */
     public void addFailure(Test test, Throwable t) {
     }
@@ -87,24 +91,31 @@ public class SummaryJUnitResultFormatter
      * Interface TestListener for JUnit > 3.4.
      *
      * <p>A Test failed.
+     * @param test not used.
+     * @param t not used.
      */
     public void addFailure(Test test, AssertionFailedError t) {
         addFailure(test, (Throwable) t);
     }
     /**
      * Empty
+     * @param test not used.
+     * @param t not used.
      */
     public void addError(Test test, Throwable t) {
     }
 
+    /** {@inheritDoc}. */
     public void setOutput(OutputStream out) {
         this.out = out;
     }
 
+    /** {@inheritDoc}. */
     public void setSystemOutput(String out) {
         systemOutput = out;
     }
 
+    /** {@inheritDoc}. */
     public void setSystemError(String err) {
         systemError = err;
     }
@@ -112,6 +123,7 @@ public class SummaryJUnitResultFormatter
     /**
      * Should the output to System.out and System.err be written to
      * the summary.
+     * @param value if true write System.out and System.err to the summary.
      */
     public void setWithOutAndErr(boolean value) {
         withOutAndErr = value;
@@ -119,6 +131,8 @@ public class SummaryJUnitResultFormatter
 
     /**
      * The whole testsuite ended.
+     * @param suite the testsuite.
+     * @throws BuildException if there is an error.
      */
     public void endTestSuite(JUnitTest suite) throws BuildException {
         String newLine = System.getProperty("line.separator");

src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java

@@ -86,23 +86,28 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
      */
     private OutputStream out;
 
+    /** No arg constructor. */
     public XMLJUnitResultFormatter() {
     }
 
+    /** {@inheritDoc}. */
     public void setOutput(OutputStream out) {
         this.out = out;
     }
 
+    /** {@inheritDoc}. */
     public void setSystemOutput(String out) {
         formatOutput(SYSTEM_OUT, out);
     }
 
+    /** {@inheritDoc}. */
     public void setSystemError(String out) {
         formatOutput(SYSTEM_ERR, out);
     }
 
     /**
      * The whole testsuite started.
+     * @param suite the testsuite.
      */
     public void startTestSuite(JUnitTest suite) {
         doc = getDocumentBuilder().newDocument();
@@ -147,6 +152,8 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
 
     /**
      * The whole testsuite ended.
+     * @param suite the testsuite.
+     * @throws BuildException on error.
      */
     public void endTestSuite(JUnitTest suite) throws BuildException {
         rootElement.setAttribute(ATTR_TESTS, "" + suite.runCount());
@@ -174,6 +181,7 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
      * Interface TestListener.
      *
      * <p>A new Test is started.
+     * @param t the test.
      */
     public void startTest(Test t) {
         testStarts.put(t, new Long(System.currentTimeMillis()));
@@ -183,6 +191,7 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
      * Interface TestListener.
      *
      * <p>A Test is finished.
+     * @param test the test.
      */
     public void endTest(Test test) {
         // Fix for bug #5637 - if a junit.extensions.TestSetup is
@@ -217,6 +226,8 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
      * Interface TestListener for JUnit &lt;= 3.4.
      *
      * <p>A Test failed.
+     * @param test the test.
+     * @param t the exception.
      */
     public void addFailure(Test test, Throwable t) {
         formatError(FAILURE, test, t);
@@ -226,6 +237,8 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
      * Interface TestListener for JUnit &gt; 3.4.
      *
      * <p>A Test failed.
+     * @param test the test.
+     * @param t the assertion.
      */
     public void addFailure(Test test, AssertionFailedError t) {
         addFailure(test, (Throwable) t);
@@ -235,6 +248,8 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
      * Interface TestListener.
      *
      * <p>An error occurred while running the test.
+     * @param test the test.
+     * @param t the error.
      */
     public void addError(Test test, Throwable t) {
         formatError(ERROR, test, t);