Enum


1   /*
2    * @(#)Enum.java    1.13 07/10/04
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.lang;
9   
10  import java.io.Serializable  ;
11  import java.io.IOException  ;
12  import java.io.InvalidObjectException  ;
13  import java.io.ObjectInputStream  ;
14  import java.io.ObjectStreamException  ;
15  
16  /**
17   * This is the common base class of all Java language enumeration types.
18   *
19   * @author  Josh Bloch
20   * @author  Neal Gafter
21   * @version 1.13, 10/04/07
22   * @since   1.5
23   */
24  public abstract class Enum<E extends Enum  <E>>
25          implements Comparable  <E>, Serializable   {
26      /**
27       * The name of this enum constant, as declared in the enum declaration.
28       * Most programmers should use the {@link #toString} method rather than
29       * accessing this field.
30       */
31      private final String   name;
32  
33      /**
34       * Returns the name of this enum constant, exactly as declared in its
35       * enum declaration.
36       * 
37       * <b>Most programmers should use the {@link #toString} method in
38       * preference to this one, as the toString method may return
39       * a more user-friendly name.</b>  This method is designed primarily for
40       * use in specialized situations where correctness depends on getting the
41       * exact name, which will not vary from release to release.
42       *
43       * @return the name of this enum constant
44       */
45      public final String   name() {
46      return name;
47      }
48  
49      /**
50       * The ordinal of this enumeration constant (its position
51       * in the enum declaration, where the initial constant is assigned
52       * an ordinal of zero).
53       * 
54       * Most programmers will have no use for this field.  It is designed
55       * for use by sophisticated enum-based data structures, such as
56       * {@link java.util.EnumSet} and {@link java.util.EnumMap}.
57       */
58      private final int ordinal;
59  
60      /**
61       * Returns the ordinal of this enumeration constant (its position
62       * in its enum declaration, where the initial constant is assigned
63       * an ordinal of zero).
64       * 
65       * Most programmers will have no use for this method.  It is
66       * designed for use by sophisticated enum-based data structures, such
67       * as {@link java.util.EnumSet} and {@link java.util.EnumMap}.
68       *
69       * @return the ordinal of this enumeration constant
70       */
71      public final int ordinal() {
72      return ordinal;
73      }
74  
75      /**
76       * Sole constructor.  Programmers cannot invoke this constructor.
77       * It is for use by code emitted by the compiler in response to
78       * enum type declarations.
79       *
80       * @param name - The name of this enum constant, which is the identifier
81       *               used to declare it.
82       * @param ordinal - The ordinal of this enumeration constant (its position
83       *         in the enum declaration, where the initial constant is assigned
84       *         an ordinal of zero).
85       */
86      protected Enum(String   name, int ordinal) {
87      this.name = name;
88      this.ordinal = ordinal;
89      }
90  
91      /**
92       * Returns the name of this enum constant, as contained in the
93       * declaration.  This method may be overridden, though it typically
94       * isn't necessary or desirable.  An enum type should override this
95       * method when a more "programmer-friendly" string form exists.
96       *
97       * @return the name of this enum constant
98       */
99      public String   toString() {
100     return name;
101     }
102 
103     /**
104      * Returns true if the specified object is equal to this
105      * enum constant.
106      *
107      * @param other the object to be compared for equality with this object.
108      * @return  true if the specified object is equal to this
109      *          enum constant.
110      */
111     public final boolean equals(Object   other) { 
112         return this==other;
113     }
114 
115     /**
116      * Returns a hash code for this enum constant.
117      *
118      * @return a hash code for this enum constant.
119      */
120     public final int hashCode() {
121         return System.identityHashCode(this);
122     }
123 
124     /**
125      * Throws CloneNotSupportedException.  This guarantees that enums
126      * are never cloned, which is necessary to preserve their "singleton"
127      * status.
128      *
129      * @return (never returns)
130      */
131     protected final Object   clone() throws CloneNotSupportedException   {
132     throw new CloneNotSupportedException  ();
133     }
134 
135     /**
136      * Compares this enum with the specified object for order.  Returns a
137      * negative integer, zero, or a positive integer as this object is less
138      * than, equal to, or greater than the specified object.
139      * 
140      * Enum constants are only comparable to other enum constants of the
141      * same enum type.  The natural order implemented by this
142      * method is the order in which the constants are declared.
143      */
144     public final int compareTo(E o) {
145     Enum   other = (Enum  )o;
146     Enum   self = this;
147     if (self.getClass() != other.getClass() && // optimization
148             self.getDeclaringClass() != other.getDeclaringClass())
149         throw new ClassCastException  ();
150     return self.ordinal - other.ordinal;
151     }
152 
153     /**
154      * Returns the Class object corresponding to this enum constant's
155      * enum type.  Two enum constants e1 and  e2 are of the
156      * same enum type if and only if
157      *   e1.getDeclaringClass() == e2.getDeclaringClass().
158      * (The value returned by this method may differ from the one returned
159      * by the {@link Object#getClass} method for enum constants with
160      * constant-specific class bodies.)
161      *
162      * @return the Class object corresponding to this enum constant's
163      *     enum type
164      */
165     public final Class  <E> getDeclaringClass() {
166     Class   clazz = getClass();
167     Class   zuper = clazz.getSuperclass();
168     return (zuper == Enum  .class) ? clazz : zuper;
169     }
170 
171     /**
172      * Returns the enum constant of the specified enum type with the
173      * specified name.  The name must match exactly an identifier used
174      * to declare an enum constant in this type.  (Extraneous whitespace
175      * characters are not permitted.) 
176      *
177      * @param enumType the <tt>Class</tt> object of the enum type from which
178      *      to return a constant
179      * @param name the name of the constant to return
180      * @return the enum constant of the specified enum type with the
181      *      specified name
182      * @throws IllegalArgumentException if the specified enum type has
183      *         no constant with the specified name, or the specified
184      *         class object does not represent an enum type
185      * @throws NullPointerException if <tt>enumType</tt> or <tt>name</tt>
186      *         is null
187      * @since 1.5
188      */
189     public static <T extends Enum  <T>> T valueOf(Class  <T> enumType,
190                                                 String   name) {
191         T result = enumType.enumConstantDirectory().get(name);
192         if (result != null)
193             return result;
194         if (name == null)
195             throw new NullPointerException  ("Name is null");
196         throw new IllegalArgumentException  (
197             "No enum const " + enumType +"." + name);
198     }
199 
200     /**
201       * prevent default deserialization
202       */
203     private void readObject(ObjectInputStream   in) throws IOException  ,
204         ClassNotFoundException   {
205             throw new InvalidObjectException  ("can't deserialize enum");
206     }
207 
208     private void readObjectNoData() throws ObjectStreamException   {
209         throw new InvalidObjectException  ("can't deserialize enum");
210     }
211 }
212
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags