1. /* ====================================================================
  2. * The Apache Software License, Version 1.1
  3. *
  4. * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
  5. * reserved.
  6. *
  7. * Redistribution and use in source and binary forms, with or without
  8. * modification, are permitted provided that the following conditions
  9. * are met:
  10. *
  11. * 1. Redistributions of source code must retain the above copyright
  12. * notice, this list of conditions and the following disclaimer.
  13. *
  14. * 2. Redistributions in binary form must reproduce the above copyright
  15. * notice, this list of conditions and the following disclaimer in
  16. * the documentation and/or other materials provided with the
  17. * distribution.
  18. *
  19. * 3. The end-user documentation included with the redistribution, if
  20. * any, must include the following acknowledgement:
  21. * "This product includes software developed by the
  22. * Apache Software Foundation (http://www.apache.org/)."
  23. * Alternately, this acknowledgement may appear in the software itself,
  24. * if and wherever such third-party acknowledgements normally appear.
  25. *
  26. * 4. The names "The Jakarta Project", "Commons", and "Apache Software
  27. * Foundation" must not be used to endorse or promote products derived
  28. * from this software without prior written permission. For written
  29. * permission, please contact apache@apache.org.
  30. *
  31. * 5. Products derived from this software may not be called "Apache"
  32. * nor may "Apache" appear in their names without prior written
  33. * permission of the Apache Software Foundation.
  34. *
  35. * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36. * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38. * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39. * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41. * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42. * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43. * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44. * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46. * SUCH DAMAGE.
  47. * ====================================================================
  48. *
  49. * This software consists of voluntary contributions made by many
  50. * individuals on behalf of the Apache Software Foundation. For more
  51. * information on the Apache Software Foundation, please see
  52. * <http://www.apache.org/>.
  53. */
  54. package org.apache.commons.lang.enum;
  55. import java.util.Iterator;
  56. import java.util.List;
  57. import org.apache.commons.lang.ClassUtils;
  58. /**
  59. * <p>Abstract superclass for type-safe enums with integer values suitable
  60. * for use in <code>switch</code> statements.</p>
  61. *
  62. * <p><em>NOTE:</em>Due to the way in which Java ClassLoaders work, comparing
  63. * <code>Enum</code> objects should always be done using the equals() method,
  64. * not <code>==</code>. The equals() method will try <code>==</code> first so
  65. * in most cases the effect is the same.</p>
  66. *
  67. * <p>To use this class, it must be subclassed. For example:</p>
  68. *
  69. * <pre>
  70. * public final class JavaVersionEnum extends ValuedEnum {
  71. * //standard enums for version of JVM
  72. * public static final int JAVA1_0_VALUE = 100;
  73. * public static final int JAVA1_1_VALUE = 110;
  74. * public static final int JAVA1_2_VALUE = 120;
  75. * public static final int JAVA1_3_VALUE = 130;
  76. * public static final JavaVersionEnum JAVA1_0 = new JavaVersionEnum( "Java 1.0", JAVA1_0_VALUE );
  77. * public static final JavaVersionEnum JAVA1_1 = new JavaVersionEnum( "Java 1.1", JAVA1_1_VALUE );
  78. * public static final JavaVersionEnum JAVA1_2 = new JavaVersionEnum( "Java 1.2", JAVA1_2_VALUE );
  79. * public static final JavaVersionEnum JAVA1_3 = new JavaVersionEnum( "Java 1.3", JAVA1_3_VALUE );
  80. *
  81. * private JavaVersionEnum(String name, int value) {
  82. * super( name, value );
  83. * }
  84. *
  85. * public static JavaVersionEnum getEnum(String javaVersion) {
  86. * return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
  87. * }
  88. *
  89. * public static JavaVersionEnum getEnum(int javaVersion) {
  90. * return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
  91. * }
  92. *
  93. * public static Map getEnumMap() {
  94. * return getEnumMap(JavaVersionEnum.class);
  95. * }
  96. *
  97. * public static List getEnumList() {
  98. * return getEnumList(JavaVersionEnum.class);
  99. * }
  100. *
  101. * public static Iterator iterator() {
  102. * return iterator(JavaVersionEnum.class);
  103. * }
  104. * }
  105. * </pre>
  106. *
  107. * <p>The above class could then be used as follows:</p>
  108. *
  109. * <pre>
  110. * public void doSomething(JavaVersion ver) {
  111. * switch (ver.getValue()) {
  112. * case JAVA1_0_VALUE:
  113. * // ...
  114. * break;
  115. * case JAVA1_1_VALUE:
  116. * // ...
  117. * break;
  118. * //...
  119. * }
  120. * }
  121. * </pre>
  122. *
  123. * <p>As shown, each enum has a name and a value. These can be accessed using
  124. * <code>getName</code> and <code>getValue</code>.</p>
  125. *
  126. * <p>The <code>getEnum</code> and <code>iterator</code> methods are recommended.
  127. * Unfortunately, Java restrictions require these to be coded as shown in each subclass.
  128. * An alternative choice is to use the {@link EnumUtils} class.</p>
  129. *
  130. * @author Apache Avalon project
  131. * @author Stephen Colebourne
  132. * @since 1.0
  133. * @version $Id: ValuedEnum.java,v 1.13 2003/08/18 02:22:24 bayard Exp $
  134. */
  135. public abstract class ValuedEnum extends Enum {
  136. /** Lang version 1.0.1 serial compatability */
  137. private static final long serialVersionUID = -7129650521543789085L;
  138. /**
  139. * The value contained in enum.
  140. */
  141. private final int iValue;
  142. /**
  143. * Constructor for enum item.
  144. *
  145. * @param name the name of enum item
  146. * @param value the value of enum item
  147. */
  148. protected ValuedEnum(String name, int value) {
  149. super(name);
  150. iValue = value;
  151. }
  152. /**
  153. * <p>Gets an <code>Enum</code> object by class and value.</p>
  154. *
  155. * <p>This method loops through the list of <code>Enum</code>,
  156. * thus if there are many <code>Enum</code>s this will be
  157. * slow.</p>
  158. *
  159. * @param enumClass the class of the <code>Enum</code> to get
  160. * @param value the value of the <code>Enum</code> to get
  161. * @return the enum object, or null if the enum does not exist
  162. * @throws IllegalArgumentException if the enum class is <code>null</code>
  163. */
  164. protected static Enum getEnum(Class enumClass, int value) {
  165. if (enumClass == null) {
  166. throw new IllegalArgumentException("The Enum Class must not be null");
  167. }
  168. List list = Enum.getEnumList(enumClass);
  169. for (Iterator it = list.iterator(); it.hasNext();) {
  170. ValuedEnum enum = (ValuedEnum) it.next();
  171. if (enum.getValue() == value) {
  172. return enum;
  173. }
  174. }
  175. return null;
  176. }
  177. /**
  178. * <p>Get value of enum item.</p>
  179. *
  180. * @return the enum item's value.
  181. */
  182. public final int getValue() {
  183. return iValue;
  184. }
  185. /**
  186. * <p>Tests for order.</p>
  187. *
  188. * <p>The default ordering is numeric by value, but this
  189. * can be overridden by subclasses.</p>
  190. *
  191. * @see java.lang.Comparable#compareTo(Object)
  192. * @param other the other object to compare to
  193. * @return -ve if this is less than the other object, +ve if greater than,
  194. * <code>0</code> of equal
  195. * @throws ClassCastException if other is not an <code>Enum</code>
  196. * @throws NullPointerException if other is <code>null</code>
  197. */
  198. public int compareTo(Object other) {
  199. return iValue - ((ValuedEnum) other).iValue;
  200. }
  201. /**
  202. * <p>Human readable description of this <code>Enum</code> item.</p>
  203. *
  204. * @return String in the form <code>type[name=value]</code>, for example:
  205. * <code>JavaVersion[Java 1.0=100]</code>. Note that the package name is
  206. * stripped from the type name.
  207. */
  208. public String toString() {
  209. if (iToString == null) {
  210. String shortName = ClassUtils.getShortClassName(getEnumClass());
  211. iToString = shortName + "[" + getName() + "=" + getValue() + "]";
  212. }
  213. return iToString;
  214. }
  215. }