Javadocs. Make our exceptions fit the Java 1.4 pattern. 100%/100% line/branch code coverage for the main package.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/codec/trunk@797804 13f79535-47bb-0310-9956-ffa450edef68

Author: garydgregory

src/java/org/apache/commons/codec/DecoderException.java

@@ -33,7 +33,18 @@ public class DecoderException extends Exception {
     private static final long serialVersionUID = 1L;
 
     /**
-     * Creates a DecoderException.
+     * Constructs a new exception with <code>null</code> as its detail message. The cause is not initialized, and may
+     * subsequently be initialized by a call to {@link #initCause}.
+     * 
+     * @since 1.4
+     */
+    public DecoderException() {
+        super();
+    }
+
+    /**
+     * Constructs a new exception with the specified detail message. The cause is not initialized, and may subsequently
+     * be initialized by a call to {@link #initCause}.
      * 
      * @param message
      *            The detail message which is saved for later retrieval by the {@link #getMessage()} method.
@@ -43,28 +54,35 @@ public DecoderException(String message) {
     }
 
     /**
-     * Creates a DecoderException.
+     * Constructsa new exception with the specified detail message and cause.
+     * 
+     * <p>
+     * Note that the detail message associated with <code>cause</code> is not automatically incorporated into this
+     * exception's detail message.
+     * </p>
      * 
+     * @param message
+     *            The detail message which is saved for later retrieval by the {@link #getMessage()} method.
      * @param cause
      *            The cause which is saved for later retrieval by the {@link #getCause()} method. A <code>null</code>
      *            value is permitted, and indicates that the cause is nonexistent or unknown.
      * @since 1.4
      */
-    public DecoderException(Throwable cause) {
-        super(cause);
+    public DecoderException(String message, Throwable cause) {
+        super(message, cause);
     }
 
     /**
-     * Creates a DecoderException.
+     * Constructs a new exception with the specified cause and a detail message of <code>(cause==null ?
+     * null : cause.toString())</code> (which typically contains the class and detail message of <code>cause</code>).
+     * This constructor is useful for exceptions that are little more than wrappers for other throwables.
      * 
-     * @param message
-     *            The detail message which is saved for later retrieval by the {@link #getMessage()} method.
      * @param cause
      *            The cause which is saved for later retrieval by the {@link #getCause()} method. A <code>null</code>
      *            value is permitted, and indicates that the cause is nonexistent or unknown.
      * @since 1.4
      */
-    public DecoderException(String message, Throwable cause) {
-        super(message, cause);
+    public DecoderException(Throwable cause) {
+        super(cause);
     }
 }

src/java/org/apache/commons/codec/EncoderException.java

@@ -35,7 +35,18 @@ public class EncoderException extends Exception {
     private static final long serialVersionUID = 1L;
 
     /**
-     * Creates a new instance of this exception with an useful message.
+     * Constructs a new exception with <code>null</code> as its detail message. The cause is not initialized, and may
+     * subsequently be initialized by a call to {@link #initCause}.
+     * 
+     * @since 1.4
+     */
+    public EncoderException() {
+        super();
+    }
+
+    /**
+     * Constructs a new exception with the specified detail message. The cause is not initialized, and may subsequently
+     * be initialized by a call to {@link #initCause}.
      * 
      * @param message
      *            a useful message relating to the encoder specific error.
@@ -45,28 +56,35 @@ public EncoderException(String message) {
     }
 
     /**
-     * Creates a EncoderException.
+     * Constructs a new exception with the specified detail message and cause.
+     * 
+     * <p>
+     * Note that the detail message associated with <code>cause</code> is not automatically incorporated into this
+     * exception's detail message.
+     * </p>
      * 
+     * @param message
+     *            The detail message which is saved for later retrieval by the {@link #getMessage()} method.
      * @param cause
      *            The cause which is saved for later retrieval by the {@link #getCause()} method. A <code>null</code>
      *            value is permitted, and indicates that the cause is nonexistent or unknown.
      * @since 1.4
      */
-    public EncoderException(Throwable cause) {
-        super(cause);
+    public EncoderException(String message, Throwable cause) {
+        super(message, cause);
     }
 
     /**
-     * Creates a EncoderException.
+     * Constructs a new exception with the specified cause and a detail message of <code>(cause==null ?
+     * null : cause.toString())</code> (which typically contains the class and detail message of <code>cause</code>).
+     * This constructor is useful for exceptions that are little more than wrappers for other throwables.
      * 
-     * @param message
-     *            The detail message which is saved for later retrieval by the {@link #getMessage()} method.
      * @param cause
      *            The cause which is saved for later retrieval by the {@link #getCause()} method. A <code>null</code>
      *            value is permitted, and indicates that the cause is nonexistent or unknown.
      * @since 1.4
      */
-    public EncoderException(String message, Throwable cause) {
-        super(message, cause);
+    public EncoderException(Throwable cause) {
+        super(cause);
     }
 }

src/test/org/apache/commons/codec/DecoderExceptionTest.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (C) 1993-2003 SEAGULL
+ * 
+ * DecoderException.java
+ * Created on Jul 25, 2009, 9:28:09 AM
+ * 
+ */
+
+package org.apache.commons.codec;
+
+import junit.framework.TestCase;
+
+/**
+ * Tests DecoderException.
+ * 
+ * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
+ * @version $Id: $
+ */
+public class DecoderExceptionTest extends TestCase {
+
+    private static final String MSG = "TEST";
+
+    private static final Throwable t = new Exception();
+
+    public void testConstructor0() {
+        DecoderException e = new DecoderException();
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    public void testConstructorString() {
+        DecoderException e = new DecoderException(MSG);
+        assertEquals(MSG, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    public void testConstructorStringThrowable() {
+        DecoderException e = new DecoderException(MSG, t);
+        assertEquals(MSG, e.getMessage());
+        assertEquals(t, e.getCause());
+    }
+
+    public void testConstructorThrowable() {
+        DecoderException e = new DecoderException(t);
+        assertEquals(t.getClass().getName(), e.getMessage());
+        assertEquals(t, e.getCause());
+    }
+
+}

src/test/org/apache/commons/codec/EncoderExceptionTest.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (C) 1993-2003 SEAGULL
+ * 
+ * DecoderException.java
+ * Created on Jul 25, 2009, 9:28:09 AM
+ * 
+ */
+
+package org.apache.commons.codec;
+
+import junit.framework.TestCase;
+
+/**
+ * Tests EncoderException.
+ * 
+ * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
+ * @version $Id: $
+ */
+public class EncoderExceptionTest extends TestCase {
+
+    private static final String MSG = "TEST";
+
+    private static final Throwable t = new Exception();
+
+    public void testConstructor0() {
+        EncoderException e = new EncoderException();
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    public void testConstructorString() {
+        EncoderException e = new EncoderException(MSG);
+        assertEquals(MSG, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    public void testConstructorStringThrowable() {
+        EncoderException e = new EncoderException(MSG, t);
+        assertEquals(MSG, e.getMessage());
+        assertEquals(t, e.getCause());
+    }
+
+    public void testConstructorThrowable() {
+        EncoderException e = new EncoderException(t);
+        assertEquals(t.getClass().getName(), e.getMessage());
+        assertEquals(t, e.getCause());
+    }
+
+}

src/test/org/apache/commons/codec/RequiredCharsetNamesTest.java

@@ -28,6 +28,13 @@
  */
 public class RequiredCharsetNamesTest extends TestCase {
 
+    /**
+     * We could make the constructor private in the future, it's a matter a style.
+     */
+    public void testConstructor() {
+        new RequiredCharsetNames();
+    }
+
     public void testIso8859_1() {
         Assert.assertEquals("ISO-8859-1", RequiredCharsetNames.ISO_8859_1);
     }