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: /* FIXME[GENERICS]: Should be Enum<T extends Enum<T>>
  52:    and Comparable<T> */
  53: public abstract class Enum
  54:   implements Comparable, Serializable
  55: {
  56: 
  57:   /**
  58:    * For compatability with Sun's JDK
  59:    */
  60:   private static final long serialVersionUID = -4300926546619394005L;
  61: 
  62:   /**
  63:    * The name of this enum constant.
  64:    */
  65:   String name;
  66: 
  67:   /**
  68:    * The number of this enum constant.  Each constant is given a number
  69:    * which matches the order in which it was declared, starting with zero.
  70:    */
  71:   int ordinal;
  72: 
  73:   /**
  74:    * This constructor is used by the compiler to create enumeration constants.
  75:    *
  76:    * @param name the name of the enumeration constant.
  77:    * @param ordinal the number of the enumeration constant, based on the
  78:    *                declaration order of the constants and starting from zero.
  79:    */
  80:   protected Enum(String name, int ordinal)
  81:   {
  82:     this.name = name;
  83:     this.ordinal = ordinal;
  84:   }
  85: 
  86:   /**
  87:    * Returns an Enum for a enum class given a description string of
  88:    * the enum constant.
  89:    *
  90:    * @exception NullPointerException when etype or s are null.
  91:    * @exception IllegalArgumentException when there is no value s in
  92:    * the enum etype.
  93:    */
  94:   /* FIXME[GENERICS]: Should be <S extends Enum<S>> S valueOf(Class<S>) */
  95:   public static Enum valueOf(Class etype, String s)
  96:   {
  97:     if (etype == null || s == null)
  98:       throw new NullPointerException();
  99: 
 100:     try
 101:       {
 102:         Field f = etype.getDeclaredField(s);
 103:         if (! f.isEnumConstant())
 104:           throw new IllegalArgumentException(s);
 105:     /* FIXME[GENERICS]: Should cast to S */
 106:         return (Enum) 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(Enum e)
 171:   {
 172:     if (getDeclaringClass() != e.getDeclaringClass())
 173:       throw new ClassCastException();
 174:     return ordinal - e.ordinal;
 175:   }
 176: 
 177:   /**
 178:    * Returns an integer which represents the relative ordering of this
 179:    * enumeration constant.  Enumeration constants are ordered by their
 180:    * ordinals, which represents their declaration order.  So, comparing
 181:    * two identical constants yields zero, while one declared prior to
 182:    * this returns a positive integer and one declared after yields a
 183:    * negative integer.
 184:    *
 185:    * @param o the enumeration constant to compare.
 186:    * @return a negative integer if <code>e.ordinal < this.ordinal</code>,
 187:    *         zero if <code>e.ordinal == this.ordinal</code> and a positive
 188:    *         integer if <code>e.ordinal > this.ordinal</code>.
 189:    * @throws ClassCastException if <code>e</code> is not an enumeration
 190:    *                            constant of the same class.
 191:    */ 
 192:   /* FIXME[GENERICS]: Remove this method */
 193:   public final int compareTo(Object o)
 194:   {
 195:     return compareTo((Enum)o);
 196:   }
 197: 
 198:   /**
 199:    * Cloning of enumeration constants is prevented, to maintain their
 200:    * singleton status.
 201:    *
 202:    * @return the cloned object.
 203:    * @throws CloneNotSupportedException as enumeration constants can't be
 204:    *         cloned.
 205:    */
 206:   protected final Object clone() throws CloneNotSupportedException
 207:   {
 208:     throw new CloneNotSupportedException("can't clone an enum constant");
 209:   }
 210: 
 211:   /**
 212:    * Returns the name of this enumeration constant.
 213:    *
 214:    * @return the name of the constant.
 215:    */
 216:   public final String name()
 217:   {
 218:     return name;
 219:   }
 220: 
 221:   /**
 222:    * Returns the number of this enumeration constant, which represents
 223:    * the order in which it was originally declared, starting from zero.
 224:    * 
 225:    * @return the number of this constant.
 226:    */
 227:   public final int ordinal()
 228:   {
 229:     return ordinal;
 230:   }
 231: 
 232:   /**
 233:    * Returns the type of this enumeration constant.  This is the class
 234:    * corresponding to the declaration of the enumeration.
 235:    *
 236:    * @return the type of this enumeration constant.
 237:    */
 238:   /* FIXME[GENERICS]: Should return Class<T> */
 239:   public final Class getDeclaringClass()
 240:   {
 241:     Class k = getClass();
 242:     // We might be in an anonymous subclass of the enum class, so go
 243:     // up one more level.
 244:     if (k.getSuperclass() != Enum.class)
 245:       k = k.getSuperclass();
 246:     return k;
 247:   }
 248: }