From 1f521264728b581b39db215ab49dad1d520a6da8 Mon Sep 17 00:00:00 2001 From: Peter Reilly Date: Fri, 10 Nov 2006 22:53:56 +0000 Subject: [PATCH] javadoc git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@473558 13f79535-47bb-0310-9956-ffa450edef68 --- .../optional/junit/JUnitTaskMirror.java | 33 +++++++++- .../optional/junit/JUnitTaskMirrorImpl.java | 7 +++ .../taskdefs/optional/junit/JUnitTest.java | 62 +++++++++++++++++++ .../optional/junit/JUnitTestRunner.java | 18 ++++++ .../junit/PlainJUnitResultFormatter.java | 2 +- .../junit/SummaryJUnitResultFormatter.java | 18 +++++- .../junit/XMLJUnitResultFormatter.java | 15 +++++ 7 files changed, 151 insertions(+), 4 deletions(-) diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTaskMirror.java b/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTaskMirror.java index a830cff49..defb09f78 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTaskMirror.java +++ b/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); } } diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTaskMirrorImpl.java b/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTaskMirrorImpl.java index 6e3337fac..815728bf6 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTaskMirrorImpl.java +++ b/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(); } diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTest.java b/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTest.java index 9e47495de..e3cac5647 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTest.java +++ b/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 { diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTestRunner.java b/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTestRunner.java index c77c89cd1..f5731132e 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTestRunner.java +++ b/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.false * * + * @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) { diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/junit/PlainJUnitResultFormatter.java b/src/main/org/apache/tools/ant/taskdefs/optional/junit/PlainJUnitResultFormatter.java index acaaa586d..515f12368 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/junit/PlainJUnitResultFormatter.java +++ b/src/main/org/apache/tools/ant/taskdefs/optional/junit/PlainJUnitResultFormatter.java @@ -176,7 +176,7 @@ public class PlainJUnitResultFormatter implements JUnitResultFormatter { * Interface TestListener. * *

A Test is finished. - * @param t the test. + * @param test the test. */ public void endTest(Test test) { if (Boolean.TRUE.equals(failed.get(test))) { diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/junit/SummaryJUnitResultFormatter.java b/src/main/org/apache/tools/ant/taskdefs/optional/junit/SummaryJUnitResultFormatter.java index 094630940..5411c16ae 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/junit/SummaryJUnitResultFormatter.java +++ b/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. * *

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"); diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java b/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java index 876fa07d0..0408739ae 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java +++ b/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. * *

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. * *

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 <= 3.4. * *

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 > 3.4. * *

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. * *

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);