sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1392070 - in /sis/trunk: sis-utility/src/test/java/org/apache/sis/test/ sis-utility/src/test/java/org/apache/sis/util/type/ src/main/docbook/
Date Sun, 30 Sep 2012 16:33:51 GMT
Author: desruisseaux
Date: Sun Sep 30 16:33:50 2012
New Revision: 1392070

URL: http://svn.apache.org/viewvc?rev=1392070&view=rev
Log:
Documentation improvement.

Added:
    sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestSuite.java
      - copied, changed from r1392003, sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestCase.java
Modified:
    sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Assert.java
    sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Dependency.java
    sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestCase.java
    sis/trunk/sis-utility/src/test/java/org/apache/sis/test/package-info.java
    sis/trunk/sis-utility/src/test/java/org/apache/sis/util/type/TypesTest.java
    sis/trunk/src/main/docbook/README.txt

Modified: sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Assert.java
URL: http://svn.apache.org/viewvc/sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Assert.java?rev=1392070&r1=1392069&r2=1392070&view=diff
==============================================================================
--- sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Assert.java (original)
+++ sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Assert.java Sun Sep 30 16:33:50
2012
@@ -121,7 +121,7 @@ public strictfp class Assert extends org
      * The inputs given to this method can be any of the following types:
      * <p>
      * <ul>
-     *   <li>{@link org.w3c.dom.Node}; used directly without further processing.</li>
+     *   <li>{@link org.w3c.dom.Node}: used directly without further processing.</li>
      *   <li>{@link java.io.File}, {@link java.net.URL} or {@link java.net.URI}: the
      *       stream is opened and parsed as a XML document.</li>
      *   <li>{@link String}: The string content is parsed directly as a XML document.
@@ -274,10 +274,10 @@ public strictfp class Assert extends org
     }
 
     /**
-     * Serializes the given object in memory, deserialize it and ensure that the deserialized
-     * object is equal to the original one. This method doesn't write anything to the disk.
+     * Serializes the given object in memory, deserialize it and ensures that the deserialized
+     * object is equals to the original one. This method doesn't write anything to the disk.
      * <p>
-     * If the serialization fails, then this method thrown a {@link AssertionError}
+     * If the serialization fails, then this method thrown an {@link AssertionError}
      * as do the other JUnit assertion methods.
      *
      * @param  <T> The type of the object to serialize.

Modified: sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Dependency.java
URL: http://svn.apache.org/viewvc/sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Dependency.java?rev=1392070&r1=1392069&r2=1392070&view=diff
==============================================================================
--- sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Dependency.java (original)
+++ sis/trunk/sis-utility/src/test/java/org/apache/sis/test/Dependency.java Sun Sep 30 16:33:50
2012
@@ -16,6 +16,7 @@
  */
 package org.apache.sis.test;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
@@ -34,6 +35,7 @@ import java.lang.annotation.Target;
  * @module
  */
 @Inherited
+@Documented
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Dependency {

Modified: sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestCase.java
URL: http://svn.apache.org/viewvc/sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestCase.java?rev=1392070&r1=1392069&r2=1392070&view=diff
==============================================================================
--- sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestCase.java (original)
+++ sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestCase.java Sun Sep 30 16:33:50
2012
@@ -34,35 +34,37 @@ import java.io.UnsupportedEncodingExcept
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.logging.Logging;
 
-import org.junit.AfterClass;
+import org.junit.After;
 import org.junit.runner.RunWith;
 
+import static org.apache.sis.test.TestSuite.VERBOSE_OUTPUT_KEY;
+import static org.apache.sis.test.TestSuite.OUTPUT_ENCODING_KEY;
+
 
 /**
  * Base class of Apache SIS tests (except the ones that extend GeoAPI tests).
- * This base class provides some configuration commons to all subclasses.
+ * This base class provides an {@link #out} field that sub-classes can use
+ * <strong>if non-null</strong> for printing debugging information. This {@code
out}
+ * field shall be used instead of {@link System#out} for the following reasons:
+ *
+ * <ul>
+ *   <li><p>It is {@code null} by default and enabled only if a system property
is set as
+ *     described in the {@linkplain org.apache.sis.test package javadoc}. This allows more
+ *     quiet (and sometime faster) Maven executions for those who are not SIS developers.</p></li>
+ *   <li><p>The outputs are collected and printed only after each test completion.
+ *     This avoid the problem of logging messages interleaved with the output.
+ *     If such interleaving is really wanted, then use the logging framework instead.</p></li>
+ * </ul>
  *
- * {@section Printing to the console}
- * Subclasses should avoid printing to {@link System#out}. If nevertheless a test method
- * produces some information considered worth to be known, consider using the following
- * pattern instead:
+ * Usage example:
  *
  * {@preformat java
  *     if (out != null) {
- *         out.println("Put here some information of particular interest.");
+ *         // Performs here some potentially costly calculation to be printed.
+ *         out.println("Write here some information of particular interest.");
  *     }
  * }
  *
- * The above example uses the {@link #out} field, which will be set to a non-null value
- * if the following option has been provided on the command line:
- *
- * <blockquote><code>-D{@value #VERBOSE_KEY}=true</code></blockquote>
- *
- * Developers can also optionally provide the following option, which is useful on Windows
- * or MacOS platforms having a console encoding different than the system encoding:
- *
- * <blockquote><code>-D{@value #ENCODING_KEY}=UTF-8</code> (or any other
valid encoding name)</blockquote>
- *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-3.16)
  * @version 0.3
@@ -71,28 +73,14 @@ import org.junit.runner.RunWith;
 @RunWith(TestRunner.class)
 public abstract strictfp class TestCase {
     /**
-     * The name of a system property for setting whatever the tests should provide verbose
output.
-     * If this property is set to {@code true}, then the {@link #out} field will be set to
a
-     * non-null value:
-     */
-    private static final String VERBOSE_KEY = "org.apache.sis.test.verbose";
-
-    /**
-     * The name of a system property for setting the encoding of test output.
-     * This property is used only if the {@link #VERBOSE_KEY} property is set
-     * to "{@code true}". If this property is not set, then the system encoding
-     * will be used.
-     */
-    private static final String ENCODING_KEY = "org.apache.sis.test.encoding";
-
-    /**
-     * If verbose outputs are enabled, the output writer where to print.
-     * Otherwise {@code null}.
-     * <p>
-     * This field will be assigned a non-null value if the {@value #VERBOSE_KEY}
-     * {@linkplain System#getProperties() system property} is set to {@code true}.
-     * The encoding will by the system-default, unless the {@value #ENCODING_KEY}
-     * system property has been set to a different value.
+     * If non-null, the output writer where to print debugging information.
+     * This field is non-null if the {@value org.apache.sis.test.TestSuite#VERBOSE_OUTPUT_KEY}
+     * system property is set to {@code true}. The encoding will by the system default, unless
+     * the {@value org.apache.sis.test.TestSuite#OUTPUT_ENCODING_KEY} system property has
been
+     * set to a different value.
+     *
+     * @see org.apache.sis.test
+     * @see #flushVerboseOutput()
      */
     public static final PrintWriter out;
 
@@ -105,7 +93,7 @@ public abstract strictfp class TestCase 
      * Sets the {@link #out} writer and its underlying {@link #buffer}.
      */
     static {
-        if (Boolean.getBoolean(VERBOSE_KEY)) {
+        if (Boolean.getBoolean(VERBOSE_OUTPUT_KEY)) {
             out = new PrintWriter(buffer = new StringWriter());
         } else {
             buffer = null;
@@ -123,7 +111,7 @@ public abstract strictfp class TestCase 
      * message and left the encoding unchanged.
      */
     static {
-        final String encoding = System.getProperty(ENCODING_KEY);
+        final String encoding = System.getProperty(OUTPUT_ENCODING_KEY);
         if (encoding != null) try {
             for (Logger logger=Logger.getLogger("org.apache.sis"); logger!=null; logger=logger.getParent())
{
                 for (final Handler handler : logger.getHandlers()) {
@@ -189,16 +177,16 @@ public abstract strictfp class TestCase 
     }
 
     /**
-     * If verbose output is enabled, flushes the {@link #out} stream to the
-     * {@linkplain System#console() console} after every tests in the class
-     * have been run.
+     * If verbose output is enabled, flushes the {@link #out} stream after each test.
+     * The stream will be flushed to the {@linkplain System#console() console} if
+     * available, or to the {@linkplain System#out standard output stream} otherwise.
      * <p>
      * This method is invoked automatically by JUnit and doesn't need to be invoked
      * explicitely, unless the developer wants to flush the output at some specific
      * point.
      */
-    @AfterClass
-    public static void flushVerboseOutput() {
+    @After
+    public void flushVerboseOutput() {
         System.out.flush();
         System.err.flush();
         if (out == null) {
@@ -219,7 +207,7 @@ public abstract strictfp class TestCase 
              * Get the output writer, using the specified encoding if any.
              */
             PrintWriter writer = null;
-            final String encoding = System.getProperty(ENCODING_KEY);
+            final String encoding = System.getProperty(OUTPUT_ENCODING_KEY);
             if (encoding == null) {
                 final Console console = System.console();
                 if (console != null) {

Copied: sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestSuite.java (from r1392003,
sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestCase.java)
URL: http://svn.apache.org/viewvc/sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestSuite.java?p2=sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestSuite.java&p1=sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestCase.java&r1=1392003&r2=1392070&rev=1392070&view=diff
==============================================================================
--- sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestCase.java (original)
+++ sis/trunk/sis-utility/src/test/java/org/apache/sis/test/TestSuite.java Sun Sep 30 16:33:50
2012
@@ -16,229 +16,38 @@
  */
 package org.apache.sis.test;
 
-import java.util.Date;
-import java.util.Locale;
-import java.util.TimeZone;
-import java.util.logging.Logger;
-import java.util.logging.Handler;
-import java.util.logging.ConsoleHandler;
-import java.text.DateFormat;
-import java.text.ParseException;
-import java.text.SimpleDateFormat;
-import java.io.Console;
-import java.io.PrintWriter;
-import java.io.StringWriter;
-import java.io.OutputStreamWriter;
-import java.io.UnsupportedEncodingException;
-
-import org.apache.sis.util.ArgumentChecks;
-import org.apache.sis.util.logging.Logging;
-
-import org.junit.AfterClass;
 import org.junit.runner.RunWith;
+import org.junit.runners.Suite;
 
 
 /**
- * Base class of Apache SIS tests (except the ones that extend GeoAPI tests).
- * This base class provides some configuration commons to all subclasses.
- *
- * {@section Printing to the console}
- * Subclasses should avoid printing to {@link System#out}. If nevertheless a test method
- * produces some information considered worth to be known, consider using the following
- * pattern instead:
- *
- * {@preformat java
- *     if (out != null) {
- *         out.println("Put here some information of particular interest.");
- *     }
- * }
- *
- * The above example uses the {@link #out} field, which will be set to a non-null value
- * if the following option has been provided on the command line:
- *
- * <blockquote><code>-D{@value #VERBOSE_KEY}=true</code></blockquote>
- *
- * Developers can also optionally provide the following option, which is useful on Windows
- * or MacOS platforms having a console encoding different than the system encoding:
- *
- * <blockquote><code>-D{@value #ENCODING_KEY}=UTF-8</code> (or any other
valid encoding name)</blockquote>
+ * Base class of Apache SIS test suites (except the ones that extend GeoAPI suites).
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-3.16)
  * @version 0.3
  * @module
  */
-@RunWith(TestRunner.class)
-public abstract strictfp class TestCase {
+@RunWith(Suite.class)
+public abstract strictfp class TestSuite {
     /**
-     * The name of a system property for setting whatever the tests should provide verbose
output.
-     * If this property is set to {@code true}, then the {@link #out} field will be set to
a
-     * non-null value:
+     * The {@value} system property for enabling verbose outputs.
+     * If this {@linkplain System#getProperties() system property} is set to {@code true},
+     * then the {@link TestCase#out} field will be set to a non-null value.
      */
-    private static final String VERBOSE_KEY = "org.apache.sis.test.verbose";
+    public static final String VERBOSE_OUTPUT_KEY = "org.apache.sis.test.verbose";
 
     /**
-     * The name of a system property for setting the encoding of test output.
-     * This property is used only if the {@link #VERBOSE_KEY} property is set
-     * to "{@code true}". If this property is not set, then the system encoding
-     * will be used.
+     * The {@value} system property for setting the output encoding.
+     * This property is used only if the {@link #VERBOSE_OUTPUT_KEY} property
+     * is set to "{@code true}". If this property is not set, then the system
+     * encoding will be used.
      */
-    private static final String ENCODING_KEY = "org.apache.sis.test.encoding";
-
-    /**
-     * If verbose outputs are enabled, the output writer where to print.
-     * Otherwise {@code null}.
-     * <p>
-     * This field will be assigned a non-null value if the {@value #VERBOSE_KEY}
-     * {@linkplain System#getProperties() system property} is set to {@code true}.
-     * The encoding will by the system-default, unless the {@value #ENCODING_KEY}
-     * system property has been set to a different value.
-     */
-    public static final PrintWriter out;
-
-    /**
-     * The buffer which is backing the {@linkplain #out} stream, or {@code null} if none.
-     */
-    private static final StringWriter buffer;
-
-    /**
-     * Sets the {@link #out} writer and its underlying {@link #buffer}.
-     */
-    static {
-        if (Boolean.getBoolean(VERBOSE_KEY)) {
-            out = new PrintWriter(buffer = new StringWriter());
-        } else {
-            buffer = null;
-            out = null;
-        }
-    }
-
-    /**
-     * Sets the encoding of the console logging handler, if an encoding has been specified.
-     * Note that we look specifically for {@link ConsoleHandler}; we do not generalize to
-     * {@link StreamHandler} because the log files may not be intended for being show in
-     * the console.
-     * <p>
-     * In case of failure to use the given encoding, we will just print a short error
-     * message and left the encoding unchanged.
-     */
-    static {
-        final String encoding = System.getProperty(ENCODING_KEY);
-        if (encoding != null) try {
-            for (Logger logger=Logger.getLogger("org.apache.sis"); logger!=null; logger=logger.getParent())
{
-                for (final Handler handler : logger.getHandlers()) {
-                    if (handler instanceof ConsoleHandler) {
-                        ((ConsoleHandler) handler).setEncoding(encoding);
-                    }
-                }
-                if (!logger.getUseParentHandlers()) {
-                    break;
-                }
-            }
-        } catch (UnsupportedEncodingException e) {
-            Logging.recoverableException(TestCase.class, "<clinit>", e);
-        }
-    }
-
-    /**
-     * Date parser and formatter using the {@code "yyyy-MM-dd HH:mm:ss"} pattern
-     * and UTC time zone.
-     */
-    private static final DateFormat dateFormat;
-    static {
-        dateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.CANADA);
-        dateFormat.setTimeZone(TimeZone.getTimeZone("UTC"));
-        dateFormat.setLenient(false);
-    };
-
-    /**
-     * Creates a new test case.
-     */
-    protected TestCase() {
-    }
-
-    /**
-     * Parses the date for the given string using the {@code "yyyy-MM-dd HH:mm:ss"} pattern
-     * in UTC timezone.
-     *
-     * @param  date The date as a {@link String}.
-     * @return The date as a {@link Date}.
-     */
-    public static Date date(final String date) {
-        ArgumentChecks.ensureNonNull("date", date);
-        try {
-            synchronized (dateFormat) {
-                return dateFormat.parse(date);
-            }
-        } catch (ParseException e) {
-            throw new AssertionError(e);
-        }
-    }
-
-    /**
-     * Formats the given date using the {@code "yyyy-MM-dd HH:mm:ss"} pattern in UTC timezone.
-     *
-     * @param  date The date to format.
-     * @return The date as a {@link String}.
-     */
-    public static String format(final Date date) {
-        ArgumentChecks.ensureNonNull("date", date);
-        synchronized (dateFormat) {
-            return dateFormat.format(date);
-        }
-    }
+    public static final String OUTPUT_ENCODING_KEY = "org.apache.sis.test.encoding";
 
     /**
-     * If verbose output is enabled, flushes the {@link #out} stream to the
-     * {@linkplain System#console() console} after every tests in the class
-     * have been run.
-     * <p>
-     * This method is invoked automatically by JUnit and doesn't need to be invoked
-     * explicitely, unless the developer wants to flush the output at some specific
-     * point.
+     * Creates a new test suite.
      */
-    @AfterClass
-    public static void flushVerboseOutput() {
-        System.out.flush();
-        System.err.flush();
-        if (out == null) {
-            return;
-        }
-        synchronized (buffer) { // This is the lock used by the 'out' PrintWriter.
-            out.flush();
-            /*
-             * Get the text content and remove the trailing spaces
-             * (including line feeds), if any.
-             */
-            String content = buffer.toString();
-            int length = content.length();
-            do if (length == 0) return;
-            while (Character.isWhitespace(content.charAt(--length)));
-            content = content.substring(0, ++length);
-            /*
-             * Get the output writer, using the specified encoding if any.
-             */
-            PrintWriter writer = null;
-            final String encoding = System.getProperty(ENCODING_KEY);
-            if (encoding == null) {
-                final Console console = System.console();
-                if (console != null) {
-                    writer = console.writer();
-                }
-            }
-            if (writer == null) {
-                if (encoding != null) try {
-                    writer = new PrintWriter(new OutputStreamWriter(System.out, encoding));
-                } catch (UnsupportedEncodingException e) {
-                    // Ignore. We will use the default encoding.
-                }
-                if (writer == null) {
-                    writer = new PrintWriter(System.out);
-                }
-            }
-            writer.println(content);
-            writer.flush();
-            buffer.getBuffer().setLength(0);
-        }
+    protected TestSuite() {
     }
 }

Modified: sis/trunk/sis-utility/src/test/java/org/apache/sis/test/package-info.java
URL: http://svn.apache.org/viewvc/sis/trunk/sis-utility/src/test/java/org/apache/sis/test/package-info.java?rev=1392070&r1=1392069&r2=1392070&view=diff
==============================================================================
--- sis/trunk/sis-utility/src/test/java/org/apache/sis/test/package-info.java (original)
+++ sis/trunk/sis-utility/src/test/java/org/apache/sis/test/package-info.java Sun Sep 30 16:33:50
2012
@@ -21,17 +21,23 @@
  * This package defines also an {@link org.apache.sis.test.Assert} class which extend the
GeoAPI
  * {@link org.opengis.test.Assert} (which itself extends the JUnit {@link org.junit.Assert}
class)
  * with the addition of assertion methods commonly used in SIS tests.
- * <p>
+ *
+ * {@section Outputs configuration}
  * By default, successful tests do not produce any output. However it is possible to ask
for
- * verbose output, which is sometime useful for debugging purpose. This behavior is controlled
- * by {@linkplain java.lang.System#getProperties() system properties} like below:
- * <p>
+ * verbose outputs, which is sometime useful for debugging purpose. This behavior is controlled
+ * from the command line by defining {@linkplain java.lang.System#getProperties() system
properties}
+ * values like below:
+ *
  * <ul>
- *   <li><code>-D{@value org.apache.sis.test.TestBase#VERBOSE_KEY}=true</code>
- *       for verbose console output.</li>
- *   <li><code>-D{@value org.apache.sis.test.TestBase#ENCODING_KEY}=UTF-8</code>
- *       (or any other valid encoding name) for the encoding of the above-cited
- *       verbose output. If omitted, the platform encoding will be used.</li>
+ *   <li><p><b><code>-Dorg.apache.sis.test.verbose=true</code></b><br>
+ *     For enabling verbose outputs to the {@linkplain java.lang.System#console() console}
if any,
+ *     or to the {@linkplain java.lang.System#out standard output stream} otherwise.</p></li>
+ *
+ *   <li><p><b><code>-Dorg.apache.sis.test.encoding=UTF-8</code></b>
(or any other valid encoding name)<br>
+ *     For the encoding of the above-cited verbose output, and the encoding of logging messages
+ *     sent to the {@linkplain java.util.logging.ConsoleHandler console handler}.
+ *     This is useful on Windows or MacOS platforms having a console encoding different than
the
+ *     platform encoding. If omitted, then the platform encoding will be used.</p></li>
  * </ul>
  *
  * @author  Martin Desruisseaux (Geomatys)

Modified: sis/trunk/sis-utility/src/test/java/org/apache/sis/util/type/TypesTest.java
URL: http://svn.apache.org/viewvc/sis/trunk/sis-utility/src/test/java/org/apache/sis/util/type/TypesTest.java?rev=1392070&r1=1392069&r2=1392070&view=diff
==============================================================================
--- sis/trunk/sis-utility/src/test/java/org/apache/sis/util/type/TypesTest.java (original)
+++ sis/trunk/sis-utility/src/test/java/org/apache/sis/util/type/TypesTest.java Sun Sep 30
16:33:50 2012
@@ -26,7 +26,7 @@ import static org.junit.Assert.*;
 
 
 /**
- * Tests the {@link GeoAPI} class.
+ * Tests the {@link Types} class.
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.3 (derived from geotk-2.1)
@@ -35,7 +35,7 @@ import static org.junit.Assert.*;
  */
 public final strictfp class TypesTest extends TestCase {
     /**
-     * Tests the {@link Types#getStandardName(String)} method.
+     * Tests the {@link Types#getStandardName(Class)} method.
      */
     @Test
     public void testGetStandardName() {

Modified: sis/trunk/src/main/docbook/README.txt
URL: http://svn.apache.org/viewvc/sis/trunk/src/main/docbook/README.txt?rev=1392070&r1=1392069&r2=1392070&view=diff
==============================================================================
--- sis/trunk/src/main/docbook/README.txt (original)
+++ sis/trunk/src/main/docbook/README.txt Sun Sep 30 16:33:50 2012
@@ -14,6 +14,6 @@ by executing the following command-line 
 
    touch src/main/docbook/fr.xml
    mvn docbkx:generate-xhtml --non-recursive
-   ln src/site/resources/book/book.css target/site/book/
+   cp src/site/resources/book/book.css target/site/book/
 
 The result will be placed in the target/site/book directory.



Mime
View raw message