Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Jakarta Commons Developers List" <commons-dev@jakarta.apache.org>
Date: 20 Sep 2003 12:03:52 -0000
Message-ID: <20030920120352.87347.qmail@minotaur.apache.org>
From: scolebourne@apache.org
To: jakarta-commons-cvs@apache.org
Subject: cvs commit:
 jakarta-commons/collections/src/java/org/apache/commons/collections
 MapUtils.java

scolebourne    2003/09/20 05:03:52

  Modified:    collections/src/java/org/apache/commons/collections
                        MapUtils.java
  Log:
  Javadoc and code tidying
  
  Revision  Changes    Path
  1.36      +160 -191  jakarta-commons/collections/src/java/org/apache/commons/collections/MapUtils.java
  
  Index: MapUtils.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/MapUtils.java,v
  retrieving revision 1.35
  retrieving revision 1.36
  diff -u -r1.35 -r1.36
  --- MapUtils.java	20 Sep 2003 11:26:32 -0000	1.35
  +++ MapUtils.java	20 Sep 2003 12:03:52 -0000	1.36
  @@ -143,34 +143,32 @@
       // Type safe getters
       //-------------------------------------------------------------------------
       /**
  -     *  Synonym for {@link Map#get(Object)}.
  +     * Gets from a Map in a null-safe manner.
        *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return null if the map is null; or the result of 
  -     *     <Code>map.get(key)</Code>
  -     */
  -    public static Object getObject( Map map, Object key ) {
  -        if ( map != null ) {
  -            return map.get( key );
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map, <code>null</code> if null map input
  +     */
  +    public static Object getObject(final Map map, final Object key) {
  +        if (map != null) {
  +            return map.get(key);
           }
           return null;
       }
   
       /**
  -     *  Looks up the given key in the given map, converting the result into
  -     *  a string.
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  null if the map is null; null if the value mapped by that
  -     *    key is null; or the <Code>toString()</Code> 
  -     *     result of the value for that key
  -     */
  -    public static String getString( Map map, Object key ) {
  -        if ( map != null ) {
  -            Object answer = map.get( key );
  -            if ( answer != null ) {
  +     * Gets a String from a Map in a null-safe manner.
  +     * <p>
  +     * The String is obtained via <code>toString</code>.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a String, <code>null</code> if null map input
  +     */
  +    public static String getString(final Map map, final Object key) {
  +        if (map != null) {
  +            Object answer = map.get(key);
  +            if (answer != null) {
                   return answer.toString();
               }
           }
  @@ -178,39 +176,32 @@
       }
   
       /**
  -     *  Looks up the given key in the given map, converting the result into
  -     *  a {@link Boolean}.  If the map is null, this method returns null.
  -     *  If the value mapped by the given key is a 
  -     *  {@link Boolean}, then it is returned as-is.  Otherwise, if the value
  -     *  is a string, then if that string ignoring case equals "true", then
  -     *  a true {@link Boolean} is returned.  Any other string value will
  -     *  result in a false {@link Boolean} being returned.  OR, if the value
  -     *  is a {@link Number}, and that {@link Number} is 0, then a false
  -     *  {@link Boolean} is returned.  Any other {@link Number} value results
  -     *  in a true {@link Boolean} being returned.<P>
  -     *
  -     *  Any value that is not a {@link Boolean}, {@link String} or 
  -     *  {@link Number} results in null being returned.<P>
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  a {@link Boolean} or null
  -     */
  -    public static Boolean getBoolean( Map map, Object key ) {
  -        if ( map != null ) {
  -            Object answer = map.get( key );
  -            if ( answer != null ) {
  -                if ( answer instanceof Boolean ) {
  +     * Gets a Boolean from a Map in a null-safe manner.
  +     * <p>
  +     * If the value is a <code>Boolean</code> it is returned directly.
  +     * If the value is a <code>String</code> and it equals 'true' ignoring case
  +     * then <code>true</code> is returned, otherwise <code>false</code>.
  +     * If the value is a <code>Number</code> an integer zero value returns
  +     * <code>false</code> and non-zero returns <code>true</code>.
  +     * Otherwise, <code>null</code> is returned.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a Boolean, <code>null</code> if null map input
  +     */
  +    public static Boolean getBoolean(final Map map, final Object key) {
  +        if (map != null) {
  +            Object answer = map.get(key);
  +            if (answer != null) {
  +                if (answer instanceof Boolean) {
                       return (Boolean) answer;
  -                }
  -                else
  -                if ( answer instanceof String ) {
  -                    return new Boolean( (String) answer );
  -                }
  -                else
  -                if ( answer instanceof Number ) {
  +                    
  +                } else if (answer instanceof String) {
  +                    return new Boolean((String) answer);
  +                    
  +                } else if (answer instanceof Number) {
                       Number n = (Number) answer;
  -                    return ( n.intValue() != 0 ) ? Boolean.TRUE : Boolean.FALSE;
  +                    return (n.intValue() != 0) ? Boolean.TRUE : Boolean.FALSE;
                   }
               }
           }
  @@ -218,36 +209,32 @@
       }
   
       /**
  -     *  Looks up the given key in the given map, converting the result into
  -     *  a {@link Number}.  If the map is null, this method returns null.
  -     *  Otherwise, if the key maps to a {@link Number}, then that number
  -     *  is returned as-is.  Otherwise, if the key maps to a {@link String},
  -     *  that string is parsed into a number using the system default
  -     *  {@link NumberFormat}.<P>
  -     *
  -     *  If the value is not a {@link Number} or a {@link String}, or if
  -     *  the value is a {@link String} that cannot be parsed into a 
  -     *  {@link Number}, then null is returned.<P>
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  a {@link Number} or null
  -     */
  -    public static Number getNumber( Map map, Object key ) {
  -        if ( map != null ) {
  -            Object answer = map.get( key );
  -            if ( answer != null ) {
  -                if ( answer instanceof Number ) {
  +     * Gets a Number from a Map in a null-safe manner.
  +     * <p>
  +     * If the value is a <code>Number</code> it is returned directly.
  +     * If the value is a <code>String</code> it is converted using
  +     * {@link NumberFormat#parse(String)} on the system default formatter
  +     * returning <code>null</code> if the conversion fails.
  +     * Otherwise, <code>null</code> is returned.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a Number, <code>null</code> if null map input
  +     */
  +    public static Number getNumber(final Map map, final Object key) {
  +        if (map != null) {
  +            Object answer = map.get(key);
  +            if (answer != null) {
  +                if (answer instanceof Number) {
                       return (Number) answer;
  -                }
  -                else
  -                if ( answer instanceof String ) {
  +                    
  +                } else if (answer instanceof String) {
                       try {
                           String text = (String) answer;
  -                        return NumberFormat.getInstance().parse( text );
  -                    }
  -                    catch (ParseException e) {
  -                        logInfo( e );
  +                        return NumberFormat.getInstance().parse(text);
  +                        
  +                    } catch (ParseException e) {
  +                        logInfo(e);
                       }
                   }
               }
  @@ -256,151 +243,133 @@
       }
   
       /**
  -     *  Looks up the given key in the given map, converting the result into
  -     *  a {@link Byte}.  First, {@link #getNumber(Map,Object)} is invoked.
  -     *  If the result is null, then null is returned.  Otherwise, the 
  -     *  byte value of the resulting {@link Number} is returned.
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  a {@link Byte} or null
  -     */
  -    public static Byte getByte( Map map, Object key ) {
  -        Number answer = getNumber( map, key );
  -        if ( answer == null ) {
  +     * Gets a Byte from a Map in a null-safe manner.
  +     * <p>
  +     * The Byte is obtained from the results of {@link #getNumber(Map,Object)}.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a Byte, <code>null</code> if null map input
  +     */
  +    public static Byte getByte(final Map map, final Object key) {
  +        Number answer = getNumber(map, key);
  +        if (answer == null) {
               return null;
  -        }
  -        else
  -        if ( answer instanceof Byte ) {
  +        } else if (answer instanceof Byte) {
               return (Byte) answer;
           }
  -        return new Byte( answer.byteValue() );
  +        return new Byte(answer.byteValue());
       }
   
       /**
  -     *  Looks up the given key in the given map, converting the result into
  -     *  a {@link Short}.  First, {@link #getNumber(Map,Object)} is invoked.
  -     *  If the result is null, then null is returned.  Otherwise, the 
  -     *  short value of the resulting {@link Number} is returned.
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  a {@link Short} or null
  -     */
  -    public static Short getShort( Map map, Object key ) {
  -        Number answer = getNumber( map, key );
  -        if ( answer == null ) {
  +     * Gets a Short from a Map in a null-safe manner.
  +     * <p>
  +     * The Short is obtained from the results of {@link #getNumber(Map,Object)}.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a Short, <code>null</code> if null map input
  +     */
  +    public static Short getShort(final Map map, final Object key) {
  +        Number answer = getNumber(map, key);
  +        if (answer == null) {
               return null;
  -        }
  -        else
  -        if ( answer instanceof Short ) {
  +        } else if (answer instanceof Short) {
               return (Short) answer;
           }
  -        return new Short( answer.shortValue() );
  +        return new Short(answer.shortValue());
       }
   
       /**
  -     *  Looks up the given key in the given map, converting the result into
  -     *  an {@link Integer}.  First, {@link #getNumber(Map,Object)} is invoked.
  -     *  If the result is null, then null is returned.  Otherwise, the 
  -     *  integer value of the resulting {@link Number} is returned.
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  an {@link Integer} or null
  -     */
  -    public static Integer getInteger( Map map, Object key ) {
  -        Number answer = getNumber( map, key );
  -        if ( answer == null ) {
  +     * Gets a Integer from a Map in a null-safe manner.
  +     * <p>
  +     * The Integer is obtained from the results of {@link #getNumber(Map,Object)}.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a Integer, <code>null</code> if null map input
  +     */
  +    public static Integer getInteger(final Map map, final Object key) {
  +        Number answer = getNumber(map, key);
  +        if (answer == null) {
               return null;
  -        }
  -        else
  -        if ( answer instanceof Integer ) {
  +        } else if (answer instanceof Integer) {
               return (Integer) answer;
           }
  -        return new Integer( answer.intValue() );
  +        return new Integer(answer.intValue());
       }
   
       /**
  -     *  Looks up the given key in the given map, converting the result into
  -     *  a {@link Long}.  First, {@link #getNumber(Map,Object)} is invoked.
  -     *  If the result is null, then null is returned.  Otherwise, the 
  -     *  long value of the resulting {@link Number} is returned.
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  a {@link Long} or null
  -     */
  -    public static Long getLong( Map map, Object key ) {
  -        Number answer = getNumber( map, key );
  -        if ( answer == null ) {
  +     * Gets a Long from a Map in a null-safe manner.
  +     * <p>
  +     * The Long is obtained from the results of {@link #getNumber(Map,Object)}.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a Long, <code>null</code> if null map input
  +     */
  +    public static Long getLong(final Map map, final Object key) {
  +        Number answer = getNumber(map, key);
  +        if (answer == null) {
               return null;
  -        }
  -        else
  -        if ( answer instanceof Long ) {
  +        } else if (answer instanceof Long) {
               return (Long) answer;
           }
  -        return new Long( answer.longValue() );
  +        return new Long(answer.longValue());
       }
   
       /**
  -     *  Looks up the given key in the given map, converting the result into
  -     *  a {@link Float}.  First, {@link #getNumber(Map,Object)} is invoked.
  -     *  If the result is null, then null is returned.  Otherwise, the 
  -     *  float value of the resulting {@link Number} is returned.
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  a {@link Float} or null
  -     */
  -    public static Float getFloat( Map map, Object key ) {
  -        Number answer = getNumber( map, key );
  -        if ( answer == null ) {
  +     * Gets a Float from a Map in a null-safe manner.
  +     * <p>
  +     * The Float is obtained from the results of {@link #getNumber(Map,Object)}.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a Float, <code>null</code> if null map input
  +     */
  +    public static Float getFloat(final Map map, final Object key) {
  +        Number answer = getNumber(map, key);
  +        if (answer == null) {
               return null;
  -        }
  -        else
  -        if ( answer instanceof Float ) {
  +        } else if (answer instanceof Float) {
               return (Float) answer;
           }
  -        return new Float( answer.floatValue() );
  +        return new Float(answer.floatValue());
       }
   
       /**
  -     *  Looks up the given key in the given map, converting the result into
  -     *  a {@link Double}.  First, {@link #getNumber(Map,Object)} is invoked.
  -     *  If the result is null, then null is returned.  Otherwise, the 
  -     *  double value of the resulting {@link Number} is returned.
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  a {@link Double} or null
  -     */
  -    public static Double getDouble( Map map, Object key ) {
  -        Number answer = getNumber( map, key );
  -        if ( answer == null ) {
  +     * Gets a Double from a Map in a null-safe manner.
  +     * <p>
  +     * The Double is obtained from the results of {@link #getNumber(Map,Object)}.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a Double, <code>null</code> if null map input
  +     */
  +    public static Double getDouble(final Map map, final Object key) {
  +        Number answer = getNumber(map, key);
  +        if (answer == null) {
               return null;
  -        }
  -        else
  -        if ( answer instanceof Double ) {
  +        } else if (answer instanceof Double) {
               return (Double) answer;
           }
  -        return new Double( answer.doubleValue() );
  +        return new Double(answer.doubleValue());
       }
   
       /**
  -     *  Looks up the given key in the given map, returning another map.
  -     *  If the given map is null or if the given key doesn't map to another
  -     *  map, then this method returns null.  Otherwise the mapped map is
  -     *  returned.
  -     *
  -     *  @param map  the map whose value to look up
  -     *  @param key  the key whose value to look up in that map
  -     *  @return  a {@link Map} or null
  -     */
  -    public static Map getMap( Map map, Object key ) {
  -        if ( map != null ) {
  -            Object answer = map.get( key );
  -            if ( answer != null && answer instanceof Map ) {
  +     * Gets a Map from a Map in a null-safe manner.
  +     * <p>
  +     * If the value returned from the specified map is not a Map then
  +     * <code>null</code> is returned.
  +     *
  +     * @param map  the map to use
  +     * @param key  the key to look up
  +     * @return the value in the Map as a Map, <code>null</code> if null map input
  +     */
  +    public static Map getMap(final Map map, final Object key) {
  +        if (map != null) {
  +            Object answer = map.get(key);
  +            if (answer != null && answer instanceof Map) {
                   return (Map) answer;
               }
           }
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org