Source for java.lang.Enum

   1: /* Enum.java - Base class for all enums
   2:    Copyright (C) 2004, 2005 Free Software Foundation
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: package java.lang;
  39: 
  40: import java.io.Serializable;
  41: import java.lang.reflect.Field;
  42: 
  43: /**
  44:  * This class represents a Java enumeration.  All enumerations are
  45:  * subclasses of this class.
  46:  *
  47:  * @author Tom Tromey (tromey@redhat.com)
  48:  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  49:  * @since 1.5
  50:  */
  51: public abstract class Enum<T extends Enum<T>>
  52:   implements Comparable<T>, Serializable
  53: {
  54: 
  55:   /**
  56:    * For compatability with Sun's JDK
  57:    */
  58:   private static final long serialVersionUID = -4300926546619394005L;
  59: 
  60:   /**
  61:    * The name of this enum constant.
  62:    */
  63:   final String name;
  64: 
  65:   /**
  66:    * The number of this enum constant.  Each constant is given a number
  67:    * which matches the order in which it was declared, starting with zero.
  68:    */
  69:   final int ordinal;
  70: 
  71:   /**
  72:    * This constructor is used by the compiler to create enumeration constants.
  73:    *
  74:    * @param name the name of the enumeration constant.
  75:    * @param ordinal the number of the enumeration constant, based on the
  76:    *                declaration order of the constants and starting from zero.
  77:    */
  78:   protected Enum(String name, int ordinal)
  79:   {
  80:     this.name = name;
  81:     this.ordinal = ordinal;
  82:   }
  83: 
  84:   /**
  85:    * Returns an Enum for a enum class given a description string of
  86:    * the enum constant.
  87:    *
  88:    * @exception NullPointerException when etype or s are null.
  89:    * @exception IllegalArgumentException when there is no value s in
  90:    * the enum etype.
  91:    */
  92:   @SuppressWarnings("unchecked")
  93:   public static <S extends Enum<S>> S valueOf(Class<S> etype, String s)
  94:   {
  95:     if (etype == null || s == null)
  96:       throw new NullPointerException();
  97: 
  98:     try
  99:       {
 100:         // XXX We should not use getDeclaredField, because it does
 101:         // an unnecessary security check.
 102:         Field f = etype.getDeclaredField(s);
 103:         if (! f.isEnumConstant())
 104:           throw new IllegalArgumentException(s);
 105:         Class.setAccessible(f);
 106:         return (S) f.get(null);
 107:       }
 108:     catch (NoSuchFieldException exception)
 109:       {
 110:     throw new IllegalArgumentException(s);
 111:       }
 112:     catch (IllegalAccessException exception)
 113:       {
 114:     throw new Error("Unable to access Enum class");
 115:       }
 116:   }
 117: 
 118:   /**
 119:    * Returns true if this enumeration is equivalent to the supplied object,
 120:    * <code>o</code>.  Only one instance of an enumeration constant exists,
 121:    * so the comparison is simply done using <code>==</code>.
 122:    *
 123:    * @param o the object to compare to this.
 124:    * @return true if <code>this == o</code>.
 125:    */
 126:   public final boolean equals(Object o)
 127:   {
 128:     // Enum constants are singular, so we need only compare `=='.
 129:     return this == o;
 130:   }
 131: 
 132:   /**
 133:    * Returns the hash code of this constant.  This is simply the ordinal.
 134:    *
 135:    * @return the hash code of this enumeration constant.
 136:    */
 137:   public final int hashCode()
 138:   {
 139:     return ordinal;
 140:   }
 141: 
 142:   /**
 143:    * Returns a textual representation of this enumeration constant.
 144:    * By default, this is simply the declared name of the constant, but
 145:    * specific enumeration types may provide an implementation more suited
 146:    * to the data being stored.
 147:    *
 148:    * @return a textual representation of this constant.
 149:    */
 150:   public String toString()
 151:   {
 152:     return name;
 153:   }
 154: 
 155:   /**
 156:    * Returns an integer which represents the relative ordering of this
 157:    * enumeration constant.  Enumeration constants are ordered by their
 158:    * ordinals, which represents their declaration order.  So, comparing
 159:    * two identical constants yields zero, while one declared prior to
 160:    * this returns a positive integer and one declared after yields a
 161:    * negative integer.
 162:    *
 163:    * @param e the enumeration constant to compare.
 164:    * @return a negative integer if <code>e.ordinal < this.ordinal</code>,
 165:    *         zero if <code>e.ordinal == this.ordinal</code> and a positive
 166:    *         integer if <code>e.ordinal > this.ordinal</code>.
 167:    * @throws ClassCastException if <code>e</code> is not an enumeration
 168:    *                            constant of the same class.
 169:    */ 
 170:   public final int compareTo(T e)
 171:   {
 172:     if (getDeclaringClass() != e.getDeclaringClass())
 173:       throw new ClassCastException();
 174:     return ordinal - e.ordinal;
 175:   }
 176: 
 177:   /**
 178:    * Cloning of enumeration constants is prevented, to maintain their
 179:    * singleton status.
 180:    *
 181:    * @return the cloned object.
 182:    * @throws CloneNotSupportedException as enumeration constants can't be
 183:    *         cloned.
 184:    */
 185:   protected final Object clone() throws CloneNotSupportedException
 186:   {
 187:     throw new CloneNotSupportedException("can't clone an enum constant");
 188:   }
 189: 
 190:   /**
 191:    * Returns the name of this enumeration constant.
 192:    *
 193:    * @return the name of the constant.
 194:    */
 195:   public final String name()
 196:   {
 197:     return name;
 198:   }
 199: 
 200:   /**
 201:    * Returns the number of this enumeration constant, which represents
 202:    * the order in which it was originally declared, starting from zero.
 203:    * 
 204:    * @return the number of this constant.
 205:    */
 206:   public final int ordinal()
 207:   {
 208:     return ordinal;
 209:   }
 210: 
 211:   /**
 212:    * Returns the type of this enumeration constant.  This is the class
 213:    * corresponding to the declaration of the enumeration.
 214:    *
 215:    * @return the type of this enumeration constant.
 216:    */
 217:   public final Class<T> getDeclaringClass()
 218:   {
 219:     Class k = getClass();
 220:     // We might be in an anonymous subclass of the enum class, so go
 221:     // up one more level.
 222:     if (k.getSuperclass() != Enum.class)
 223:       k = k.getSuperclass();
 224:     return k;
 225:   }
 226: 
 227:   /**
 228:    * Enumerations can not have finalization methods.
 229:    *
 230:    * @since 1.6
 231:    */
 232:   protected final void finalize()
 233:   {
 234:   }
 235: 
 236: }