src/share/classes/java/lang/Enum.java

Print this page
rev 826 : 6548433: (enum spec) java.lang.Enum docs should explain about values() and valueOf(String)
Reviewed-by: martin


  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  22  * CA 95054 USA or visit www.sun.com if you need additional information or
  23  * have any questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.io.Serializable;
  29 import java.io.IOException;
  30 import java.io.InvalidObjectException;
  31 import java.io.ObjectInputStream;
  32 import java.io.ObjectStreamException;
  33 
  34 /**
  35  * This is the common base class of all Java language enumeration types.
  36  *
  37  * More information about enums, including implicit methods synthesised
  38  * by the compiler, can be found in <i>The Java&trade; Language
  39  * Specification, Third Edition</i>, <a

  40  * href="http://java.sun.com/docs/books/jls/third_edition/html/classes.html#8.9">&sect;8.9</a>.
  41  *

  42  * @author  Josh Bloch
  43  * @author  Neal Gafter
  44  * @see     Class#getEnumConstants()
  45  * @since   1.5
  46  */
  47 public abstract class Enum<E extends Enum<E>>
  48         implements Comparable<E>, Serializable {
  49     /**
  50      * The name of this enum constant, as declared in the enum declaration.
  51      * Most programmers should use the {@link #toString} method rather than
  52      * accessing this field.
  53      */
  54     private final String name;
  55 
  56     /**
  57      * Returns the name of this enum constant, exactly as declared in its
  58      * enum declaration.
  59      *
  60      * <b>Most programmers should use the {@link #toString} method in
  61      * preference to this one, as the toString method may return


 180      *   e1.getDeclaringClass() == e2.getDeclaringClass().
 181      * (The value returned by this method may differ from the one returned
 182      * by the {@link Object#getClass} method for enum constants with
 183      * constant-specific class bodies.)
 184      *
 185      * @return the Class object corresponding to this enum constant's
 186      *     enum type
 187      */
 188     public final Class<E> getDeclaringClass() {
 189         Class clazz = getClass();
 190         Class zuper = clazz.getSuperclass();
 191         return (zuper == Enum.class) ? clazz : zuper;
 192     }
 193 
 194     /**
 195      * Returns the enum constant of the specified enum type with the
 196      * specified name.  The name must match exactly an identifier used
 197      * to declare an enum constant in this type.  (Extraneous whitespace
 198      * characters are not permitted.)
 199      *









 200      * @param enumType the {@code Class} object of the enum type from which
 201      *      to return a constant
 202      * @param name the name of the constant to return
 203      * @return the enum constant of the specified enum type with the
 204      *      specified name
 205      * @throws IllegalArgumentException if the specified enum type has
 206      *         no constant with the specified name, or the specified
 207      *         class object does not represent an enum type
 208      * @throws NullPointerException if {@code enumType} or {@code name}
 209      *         is null
 210      * @since 1.5
 211      */
 212     public static <T extends Enum<T>> T valueOf(Class<T> enumType,
 213                                                 String name) {
 214         T result = enumType.enumConstantDirectory().get(name);
 215         if (result != null)
 216             return result;
 217         if (name == null)
 218             throw new NullPointerException("Name is null");
 219         throw new IllegalArgumentException(


  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  22  * CA 95054 USA or visit www.sun.com if you need additional information or
  23  * have any questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.io.Serializable;
  29 import java.io.IOException;
  30 import java.io.InvalidObjectException;
  31 import java.io.ObjectInputStream;
  32 import java.io.ObjectStreamException;
  33 
  34 /**
  35  * This is the common base class of all Java language enumeration types.
  36  *
  37  * More information about enums, including descriptions of the
  38  * implicitly declared methods synthesized by the compiler, can be
  39  * found in <i>The Java&trade; Language Specification, Third
  40  * Edition</i>, <a
  41  * href="http://java.sun.com/docs/books/jls/third_edition/html/classes.html#8.9">&sect;8.9</a>.
  42  *
  43  * @param <E> The enum type subclass
  44  * @author  Josh Bloch
  45  * @author  Neal Gafter
  46  * @see     Class#getEnumConstants()
  47  * @since   1.5
  48  */
  49 public abstract class Enum<E extends Enum<E>>
  50         implements Comparable<E>, Serializable {
  51     /**
  52      * The name of this enum constant, as declared in the enum declaration.
  53      * Most programmers should use the {@link #toString} method rather than
  54      * accessing this field.
  55      */
  56     private final String name;
  57 
  58     /**
  59      * Returns the name of this enum constant, exactly as declared in its
  60      * enum declaration.
  61      *
  62      * <b>Most programmers should use the {@link #toString} method in
  63      * preference to this one, as the toString method may return


 182      *   e1.getDeclaringClass() == e2.getDeclaringClass().
 183      * (The value returned by this method may differ from the one returned
 184      * by the {@link Object#getClass} method for enum constants with
 185      * constant-specific class bodies.)
 186      *
 187      * @return the Class object corresponding to this enum constant's
 188      *     enum type
 189      */
 190     public final Class<E> getDeclaringClass() {
 191         Class clazz = getClass();
 192         Class zuper = clazz.getSuperclass();
 193         return (zuper == Enum.class) ? clazz : zuper;
 194     }
 195 
 196     /**
 197      * Returns the enum constant of the specified enum type with the
 198      * specified name.  The name must match exactly an identifier used
 199      * to declare an enum constant in this type.  (Extraneous whitespace
 200      * characters are not permitted.)
 201      *
 202      * <p>Note that for a particular enum type {@code T}, the
 203      * implicitly declared {@code public static T valueOf(String)}
 204      * method on that enum may be used instead of this method to map
 205      * from a name to the corresponding enum constant.  All the
 206      * constants of an enum type can be obtained by calling the
 207      * implicit {@code public static T[] values()} method of that
 208      * type.
 209      *
 210      * @param <T> The enum type whose constant is to be returned
 211      * @param enumType the {@code Class} object of the enum type from which
 212      *      to return a constant
 213      * @param name the name of the constant to return
 214      * @return the enum constant of the specified enum type with the
 215      *      specified name
 216      * @throws IllegalArgumentException if the specified enum type has
 217      *         no constant with the specified name, or the specified
 218      *         class object does not represent an enum type
 219      * @throws NullPointerException if {@code enumType} or {@code name}
 220      *         is null
 221      * @since 1.5
 222      */
 223     public static <T extends Enum<T>> T valueOf(Class<T> enumType,
 224                                                 String name) {
 225         T result = enumType.enumConstantDirectory().get(name);
 226         if (result != null)
 227             return result;
 228         if (name == null)
 229             throw new NullPointerException("Name is null");
 230         throw new IllegalArgumentException(