commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject cvs commit: jakarta-commons/lang/src/java/org/apache/commons/lang IllegalClassException.java IncompleteArgumentException.java NotImplementedException.java UnhandledException.java NullArgumentException.java
Date Fri, 15 Oct 2004 20:55:01 GMT
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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message