DPML Notify

[mcconnell AT netcompartner.com]

Author: mcconnell
Date: Mon Dec 13 23:48:03 2004
New Revision: 1177

Modified:
   development/main/util/criteria/src/main/net/dpml/criteria/Criteria.java
   
development/main/util/criteria/src/main/net/dpml/criteria/CriteriaException.java
   
development/main/util/criteria/src/main/net/dpml/criteria/CriteriaRuntimeException.java
   development/main/util/criteria/src/main/net/dpml/criteria/Dictionary.java
   
development/main/util/criteria/src/main/net/dpml/criteria/PackedParameter.java
   development/main/util/criteria/src/main/net/dpml/criteria/Parameter.java
   development/main/util/criteria/src/main/net/dpml/criteria/URLParameter.java
Log:
Complete checkstyle validation for the util package.

Modified: 
development/main/util/criteria/src/main/net/dpml/criteria/Criteria.java
==============================================================================
--- development/main/util/criteria/src/main/net/dpml/criteria/Criteria.java   
  (original)
+++ development/main/util/criteria/src/main/net/dpml/criteria/Criteria.java   
  Mon Dec 13 23:48:03 2004
@@ -21,8 +21,12 @@
 import java.util.HashMap;
 
 /**
- * A abstract utility class that can be used to simplify the 
- * creation of domain specific criteria.
+ * The Criteria class is a type-safe map that is backed by a set of Parameter
+ * objects that define a default value and type transformation semantics.  A 
+ * criteria instance is normally used as a parameterizable instance that is 
supplied
+ * by a factory to a client, following which the client modifies the map (in 
accordance 
+ * with type constraints), leading to the supply of the map as the argument 
in the 
+ * creation of a new instance.
  *
  * @author <a href="mailto:dev-dpml AT lists.ibiblio.org";>The Digital Product 
Meta Library</a>
  * @version $Id$
@@ -33,7 +37,10 @@
     // state
     //--------------------------------------------------------------
 
-     private final Parameter[] m_params;
+   /**
+    * The set of typed parameters backing the map.
+    */
+    private final Parameter[] m_params;
 
     //--------------------------------------------------------------
     // constructor
@@ -46,8 +53,10 @@
     */
     public Criteria( final Parameter[] params )
     {
-        if( null == params ) 
-          throw new NullPointerException( "params" );
+        if( null == params )
+        {
+            throw new NullPointerException( "params" );
+        }
         m_params = params;
     }
 
@@ -63,9 +72,9 @@
     * @exception CriteriaRuntimeException if the supplied value fails
     *    the validation test for its associated parameter
     */
-    public Object put( final Object key, final Object value ) 
+    public Object put( final Object key, final Object value ) throws 
CriteriaRuntimeException 
     {
-        if( !(key instanceof String ))
+        if( !( key instanceof String ) )
         {
             final String error = 
               "Invalid key: " + key;
@@ -109,6 +118,7 @@
 
    /**
     * Return the currently assigned value for a key.
+    * @param key the parameter key
     * @return the assigned value
     */
     public Object get( final Object key )
@@ -130,7 +140,8 @@
     //--------------------------------------------------------------
 
    /**
-    * Return the currently assigned value for a key.
+    * Return the currently assigned value for a keyed parameter.
+    * @param param the parameter
     * @return the assigned value
     */
     protected Object getValue( final Parameter param )
@@ -156,13 +167,21 @@
         return m_params;
     }
 
+   /**
+    * Return a parameter matching the supplied key.
+    * @param key the parameter key
+    * @return the matching parameter
+    */
     protected Parameter getParameter( final String key )
     {
         Parameter[] params = getParameters();
-        for( int i=0; i<params.length; i++ )
+        for( int i=0; i < params.length; i++ )
         {
             Parameter parameter = params[i];
-            if( parameter.getKey().equals( key ) ) return parameter;
+            if( parameter.getKey().equals( key ) )
+            {
+                return parameter;
+            }
         }
 
         final String error = 
@@ -170,6 +189,11 @@
         throw new IllegalArgumentException( error );
     }
 
+   /**
+    * Return the parameter mathing a supplied key.
+    * @param key the map key
+    * @return the matching parameter
+    */
     private Parameter getParameterFromObject( Object key )
     {
         if( key instanceof Parameter )

Modified: 
development/main/util/criteria/src/main/net/dpml/criteria/CriteriaException.java
==============================================================================
--- 
development/main/util/criteria/src/main/net/dpml/criteria/CriteriaException.java
    (original)
+++ 
development/main/util/criteria/src/main/net/dpml/criteria/CriteriaException.java
    Mon Dec 13 23:48:03 2004
@@ -26,6 +26,9 @@
  */
 public class CriteriaException extends Exception
 {
+   /**
+    * The causal exception.
+    */
     private Throwable m_cause;
 
     /**

Modified: 
development/main/util/criteria/src/main/net/dpml/criteria/CriteriaRuntimeException.java
==============================================================================
--- 
development/main/util/criteria/src/main/net/dpml/criteria/CriteriaRuntimeException.java
     (original)
+++ 
development/main/util/criteria/src/main/net/dpml/criteria/CriteriaRuntimeException.java
     Mon Dec 13 23:48:03 2004
@@ -26,6 +26,9 @@
  */
 public class CriteriaRuntimeException extends RuntimeException
 {
+   /**
+    * The causal exception.
+    */
     private Throwable m_cause;
 
     /**

Modified: 
development/main/util/criteria/src/main/net/dpml/criteria/Dictionary.java
==============================================================================
--- development/main/util/criteria/src/main/net/dpml/criteria/Dictionary.java 
  (original)
+++ development/main/util/criteria/src/main/net/dpml/criteria/Dictionary.java 
  Mon Dec 13 23:48:03 2004
@@ -34,6 +34,9 @@
     // state
     //--------------------------------------------------------------
 
+   /**
+    * The map backing the dictionary.
+    */
     private final Map m_map;
 
     //--------------------------------------------------------------
@@ -91,11 +94,11 @@
      *         key.
      * 
      * @throws ClassCastException if the key is of an inappropriate type for
-     *                   this map (optional).
+     *           this map (optional).
      * @throws NullPointerException if the key is <tt>null</tt> and this map
      *            does not not permit <tt>null</tt> keys (optional).
      */
-    public boolean containsKey( Object key )
+    public boolean containsKey( Object key ) throws ClassCastException, 
NullPointerException 
     {
         return m_map.containsKey( key );
     }
@@ -112,15 +115,15 @@
      * @return <tt>true</tt> if this map maps one or more keys to the
      *         specified value.
      * @throws ClassCastException if the value is of an inappropriate type 
for
-     *                   this map (optional).
+     *           this map (optional).
      * @throws NullPointerException if the value is <tt>null</tt> and this 
map
      *            does not not permit <tt>null</tt> values (optional).
      */
-    public boolean containsValue( Object value )
+    public boolean containsValue( Object value ) throws ClassCastException, 
NullPointerException
     {
         return m_map.containsValue( value );
     }
-
+    
     /**
      * Returns the value to which this map maps the specified key.  Returns
      * <tt>null</tt> if the map contains no mapping for this key.  A return
@@ -136,16 +139,16 @@
      *
      * @param key key whose associated value is to be returned.
      * @return the value to which this map maps the specified key, or
-     *        <tt>null</tt> if the map contains no mapping for this key.
+     *           <tt>null</tt> if the map contains no mapping for this key.
      * 
      * @throws ClassCastException if the key is of an inappropriate type for
-     *                   this map (optional).
+     *           this map (optional).
      * @throws NullPointerException key is <tt>null</tt> and this map does 
not
-     *           not permit <tt>null</tt> keys (optional).
+     *          not permit <tt>null</tt> keys (optional).
      * 
      * @see #containsKey(Object)
      */
-    public Object get( Object key )
+    public Object get( Object key ) throws ClassCastException, 
NullPointerException
     {
         return m_map.get( key );
     }
@@ -160,7 +163,7 @@
      * 
      * @throws UnsupportedOperationException in all cases
      */
-    public Object put( Object key, Object value )
+    public Object put( Object key, Object value ) throws 
UnsupportedOperationException
     {
         throw new UnsupportedOperationException( "put" );
     }
@@ -174,7 +177,7 @@
      * 
      * @throws UnsupportedOperationException in all cases
      */
-    public Object remove( Object key )
+    public Object remove( Object key ) throws UnsupportedOperationException
     {
         throw new UnsupportedOperationException( "remove" );
     }
@@ -187,7 +190,7 @@
      * 
      * @throws UnsupportedOperationException in all cases
      */
-    public void putAll( Map map )
+    public void putAll( Map map ) throws UnsupportedOperationException
     {
         throw new UnsupportedOperationException( "putAll" );
     }
@@ -198,7 +201,7 @@
      *
      * @throws UnsupportedOperationException in all cases
      */
-    public void clear()
+    public void clear() throws UnsupportedOperationException
     {
         throw new UnsupportedOperationException( "clear" );
     }

Modified: 
development/main/util/criteria/src/main/net/dpml/criteria/PackedParameter.java
==============================================================================
--- 
development/main/util/criteria/src/main/net/dpml/criteria/PackedParameter.java
      (original)
+++ 
development/main/util/criteria/src/main/net/dpml/criteria/PackedParameter.java
      Mon Dec 13 23:48:03 2004
@@ -34,6 +34,9 @@
     // immutable state
     //--------------------------------------------------------------
 
+   /**
+    * The delimiter using between string tokens.
+    */
     private final String m_delimiter;
 
     //--------------------------------------------------------------
@@ -56,12 +59,16 @@
    /**
     * Resolve a supplied string or string array to a sttring array value.
     * @param value the value to resolve
+    * @return the object value
     * @exception CriteriaException if an error occurs
     */
     public Object resolve( Object value ) 
       throws CriteriaException
     {
-        if( value == null ) return null;
+        if( value == null )
+        {
+            return null;
+        }
         if( value instanceof String[] )
         {
             return value;
@@ -81,6 +88,12 @@
         }
     }
 
+   /**
+    * Convert a supplied string value to an array of values using a 
delimeter.
+    * @param value the value to resolve
+    * @param delimiter the delimeter value
+    * @return the array of values
+    */
     public static String[] convert( String value, String delimiter )
     {
         if( null == value )

Modified: 
development/main/util/criteria/src/main/net/dpml/criteria/Parameter.java
==============================================================================
--- development/main/util/criteria/src/main/net/dpml/criteria/Parameter.java  
  (original)
+++ development/main/util/criteria/src/main/net/dpml/criteria/Parameter.java  
  Mon Dec 13 23:48:03 2004
@@ -43,7 +43,7 @@
     public static String[] getKeys( Parameter[] params )
     {
         String[] keys = new String[ params.length ];
-        for( int i=0; i<params.length; i++ )
+        for( int i=0; i < params.length; i++ )
         {
             keys[i] = params[i].getKey();
         }
@@ -54,9 +54,24 @@
     // immutable state
     //--------------------------------------------------------------
 
+   /**
+    * The parameter key.
+    */
     private final String m_key;
+
+   /**
+    * The type of object that is return by this parameter.
+    */
     private final Class m_type;
+
+   /**
+    * Flag indicating if this parameter is required.
+    */
     private final boolean m_required;
+
+   /**
+    * The default value of the parameter.
+    */
     private final Object m_default;
 
     //--------------------------------------------------------------
@@ -186,10 +201,14 @@
     */
     protected Object resolve( Class type, Object value ) throws 
CriteriaException
     {
-        if( value == null ) 
+        if( value == null )
+        {
             return null;
-        if( type == null ) 
+        }
+        if( type == null )
+        {
             throw new NullPointerException( "type" );
+        }
         if( type.isInstance( value ) )
         {
             return value;
@@ -201,7 +220,7 @@
             {
                 constructor = 
                   type.getConstructor( 
-                    new Class[]{ value.getClass() } );
+                    new Class[]{value.getClass()} );
             }
             catch( NoSuchMethodException nsme )
             {
@@ -219,7 +238,7 @@
             try
             {
                 return constructor.newInstance( 
-                  new Object[]{ value } );
+                  new Object[]{value} );
             }
             catch( Throwable e )
             {

Modified: 
development/main/util/criteria/src/main/net/dpml/criteria/URLParameter.java
==============================================================================
--- 
development/main/util/criteria/src/main/net/dpml/criteria/URLParameter.java 
(original)
+++ 
development/main/util/criteria/src/main/net/dpml/criteria/URLParameter.java 
Mon Dec 13 23:48:03 2004
@@ -46,13 +46,16 @@
    /**
     * Resolve a supplied string to a configuration
     * @param value the value to resolve
+    * @return the resolved value
     * @exception CriteriaException if an error occurs
     */
     public Object resolve( Object value ) 
       throws CriteriaException
     {
-        if( value == null ) 
+        if( value == null )
+        {
             return null;
+        }
         if( value instanceof URL )
         {
             return value;