scolebourne 2004/10/15 13:55:01
Modified: lang/src/java/org/apache/commons/lang
IllegalClassException.java
IncompleteArgumentException.java
NotImplementedException.java
UnhandledException.java NullArgumentException.java
Log:
Update Javadoc to better describe the behaviour and use cases of the exceptions
Revision Changes Path
1.7 +36 -3
jakarta-commons/lang/src/java/org/apache/commons/lang/IllegalClassException.java
Index: IllegalClassException.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/lang/src/java/org/apache/commons/lang/IllegalClassException.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- IllegalClassException.java 18 Feb 2004 22:59:50 -0000 1.6
+++ IllegalClassException.java 15 Oct 2004 20:55:01 -0000 1.7
@@ -16,17 +16,50 @@
package org.apache.commons.lang;
/**
- * <p>Thrown when an object is an instance of an unexpected type (a class or
interface).</p>
+ * <p>Thrown when an object is an instance of an unexpected type (a class or
interface).
+ * This exception supplements the standard <code>IllegalArgumentException</code>
+ * by providing a more semantically rich description of the problem.</p>
+ *
+ * <p><code>IllegalClassException</code> represents the case where a method takes
+ * in a genericly typed parameter like Object (typically because it has to due to
some
+ * other interface it implements), but this implementation only actually accepts a
specific
+ * type, for example String. This exception would be used in place of
+ * <code>IllegalArgumentException</code>, yet it still extends it.</p>
+ *
+ * <pre>
+ * public void foo(Object obj) {
+ * if (obj instanceof String == false) {
+ * throw new IllegalClassException(String.class, obj);
+ * }
+ * // do something with the string
+ * }
+ * </pre>
*
* @author Matthew Hawthorne
* @author Gary Gregory
+ * @author Stephen Colebourne
* @since 2.0
* @version $Id$
*/
public class IllegalClassException extends IllegalArgumentException {
/**
- * <p>Instantiates with the specified types (classes or interfaces).</p>
+ * <p>Instantiates with the expected type, and actual object.</p>
+ *
+ * @param expected the expected type
+ * @param actual the actual object
+ * @since 2.1
+ */
+ public IllegalClassException(Class expected, Object actual) {
+ super(
+ "Expected: "
+ + safeGetClassName(expected)
+ + ", actual: "
+ + (actual == null ? "null" : actual.getClass().getName()));
+ }
+
+ /**
+ * <p>Instantiates with the expected and actual types.</p>
*
* @param expected the expected type
* @param actual the actual type
1.7 +22 -2
jakarta-commons/lang/src/java/org/apache/commons/lang/IncompleteArgumentException.java
Index: IncompleteArgumentException.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/lang/src/java/org/apache/commons/lang/IncompleteArgumentException.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- IncompleteArgumentException.java 18 Feb 2004 22:59:50 -0000 1.6
+++ IncompleteArgumentException.java 15 Oct 2004 20:55:01 -0000 1.7
@@ -18,7 +18,27 @@
import java.util.Arrays;
/**
- * <p>Thrown to indicate an incomplete argument to a method.</p>
+ * <p>Thrown to indicate an incomplete argument to a method.
+ * This exception supplements the standard <code>IllegalArgumentException</code>
+ * by providing a more semantically rich description of the problem.</p>
+ *
+ * <p><code>IncompleteArgumentException</code> represents the case where a method
takes
+ * in a parameter that has a number of properties, some of which have not been set.
+ * A case might be a search requirements bean that must have three properties set
+ * in order for the method to run, but only one is actually set.
+ * This exception would be used in place of
+ * <code>IllegalArgumentException</code>, yet it still extends it.</p>
+ *
+ * <pre>
+ * public void foo(PersonSearcher search) {
+ * if (search.getSurname() == null ||
+ * search.getForename() == null ||
+ * search.getSex() == null) {
+ * throw new IncompleteArgumentException("search");
+ * }
+ * // do something with the searcher
+ * }
+ * </pre>
*
* @author Matthew Hawthorne
* @since 2.0
1.9 +21 -2
jakarta-commons/lang/src/java/org/apache/commons/lang/NotImplementedException.java
Index: NotImplementedException.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/lang/src/java/org/apache/commons/lang/NotImplementedException.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- NotImplementedException.java 16 Mar 2004 22:42:58 -0000 1.8
+++ NotImplementedException.java 15 Oct 2004 20:55:01 -0000 1.9
@@ -22,7 +22,26 @@
import org.apache.commons.lang.exception.NestableDelegate;
/**
- * <p>Thrown to indicate that a block of code has not been implemented.</p>
+ * <p>Thrown to indicate that a block of code has not been implemented.
+ * This exception supplements <code>UnsupportedOperationException</code>
+ * by providing a more semantically rich description of the problem.</p>
+ *
+ * <p><code>NotImplementedException</code> represents the case where the
+ * author has yet to implement the logic at this point in the program.
+ * This can act as an exception based TODO tag.
+ * Because this logic might be within a catch block, this exception
+ * suports exception chaining.</p>
+ *
+ * <pre>
+ * public void foo() {
+ * try {
+ * // do something that throws an Exception
+ * } catch (Exception ex) {
+ * // don't know what to do here yet
+ * throw new NotImplementedException("TODO", ex);
+ * }
+ * }
+ * </pre>
*
* @author Matthew Hawthorne
* @author Stephen Colebourne
1.6 +19 -3
jakarta-commons/lang/src/java/org/apache/commons/lang/UnhandledException.java
Index: UnhandledException.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/lang/src/java/org/apache/commons/lang/UnhandledException.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- UnhandledException.java 18 Feb 2004 22:59:50 -0000 1.5
+++ UnhandledException.java 15 Oct 2004 20:55:01 -0000 1.6
@@ -18,8 +18,24 @@
import org.apache.commons.lang.exception.NestableRuntimeException;
/**
- * Thrown when it is impossible or undesirable to consume
- * or throw a checked exception.
+ * <p>Thrown when it is impossible or undesirable to consume or throw a checked
exception.</p>
+ * This exception supplements the standard exception classes by providing a more
+ * semantically rich description of the problem.</p>
+ *
+ * <p><code>UnhandledException</code> represents the case where a method has to deal
+ * with a checked exception but does not wish to.
+ * Instead, the checked exception is rethrown in this unchecked wrapper.</p>
+ *
+ * <pre>
+ * public void foo() {
+ * try {
+ * // do something that throws IOException
+ * } catch (IOException ex) {
+ * // don't want to or can't throw IOException from foo()
+ * throw new UnhandledException(ex);
+ * }
+ * }
+ * </pre>
*
* @author Matthew Hawthorne
* @since 2.0
1.8 +22 -3
jakarta-commons/lang/src/java/org/apache/commons/lang/NullArgumentException.java
Index: NullArgumentException.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/lang/src/java/org/apache/commons/lang/NullArgumentException.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- NullArgumentException.java 18 Feb 2004 22:59:50 -0000 1.7
+++ NullArgumentException.java 15 Oct 2004 20:55:01 -0000 1.8
@@ -17,7 +17,25 @@
/**
* <p>Thrown to indicate that an argument was <code>null</code> and should
- * not have been.</p>
+ * not have been.
+ * This exception supplements the standard <code>IllegalArgumentException</code>
+ * by providing a more semantically rich description of the problem.</p>
+ *
+ * <p><code>NullArgumentException</code> represents the case where a method takes
+ * in a parameter that must not be <code>null</code>.
+ * Some coding standards would use <code>NullPointerException</code> for this case,
+ * others will use <code>IllegalArgumentException</code>.
+ * Thus this exception would be used in place of
+ * <code>IllegalArgumentException</code>, yet it still extends it.</p>
+ *
+ * <pre>
+ * public void foo(String str) {
+ * if (str == null) {
+ * throw new NullArgumentException("str");
+ * }
+ * // do something with the string
+ * }
+ * </pre>
*
* @author Matthew Hawthorne
* @author Stephen Colebourne
@@ -32,6 +50,7 @@
* @param argName the name of the argument that was <code>null</code>.
*/
public NullArgumentException(String argName) {
- super(argName + " must not be null.");
+ super((argName == null ? "Argument" : argName) + " must not be null.");
}
+
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
