Java Doc for Enum.java in  » Library » Apache-common-lang » org » apache » commons » lang » enums » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » Library » Apache common lang » org.apache.commons.lang.enums 
Source Cross Reference  Class Diagram Java Document (Java Doc) 


java.lang.Object
   org.apache.commons.lang.enums.Enum

All known Subclasses:   org.apache.commons.lang.enums.DummyEnum,  org.apache.commons.lang.enums.OperationEnum,  org.apache.commons.lang.enums.ColorEnum,  org.apache.commons.lang.enums.Broken3OperationEnum,  org.apache.commons.lang.enums.ValuedEnum,  org.apache.commons.lang.enums.Broken4OperationEnum,  org.apache.commons.lang.enums.Broken5OperationEnum,  org.apache.commons.lang.enums.Broken3Enum,  org.apache.commons.lang.enums.Broken2Enum,  org.apache.commons.lang.enums.Broken1OperationEnum,  org.apache.commons.lang.enums.Broken2OperationEnum,  org.apache.commons.lang.enums.Extended1Enum,  org.apache.commons.lang.enums.Broken1Enum,
Enum
abstract public class Enum implements Comparable,Serializable(Code)

Abstract superclass for type-safe enums.

One feature of the C programming language lacking in Java is enumerations. The C implementation based on ints was poor and open to abuse. The original Java recommendation and most of the JDK also uses int constants. It has been recognised however that a more robust type-safe class-based solution can be designed. This class follows the basic Java type-safe enumeration pattern.

NOTE: Due to the way in which Java ClassLoaders work, comparing Enum objects should always be done using equals(), not ==. The equals() method will try == first so in most cases the effect is the same.

Of course, if you actually want (or don't mind) Enums in different class loaders being non-equal, then you can use ==.

Simple Enums

To use this class, it must be subclassed. For example:

 public final class ColorEnum extends Enum {
 public static final ColorEnum RED = new ColorEnum("Red");
 public static final ColorEnum GREEN = new ColorEnum("Green");
 public static final ColorEnum BLUE = new ColorEnum("Blue");
 private ColorEnum(String color) {
 super(color);
 }
 public static ColorEnum getEnum(String color) {
 return (ColorEnum) getEnum(ColorEnum.class, color);
 }
 public static Map getEnumMap() {
 return getEnumMap(ColorEnum.class);
 }
 public static List getEnumList() {
 return getEnumList(ColorEnum.class);
 }
 public static Iterator iterator() {
 return iterator(ColorEnum.class);
 }
 }
 

As shown, each enum has a name. This can be accessed using getName.

The getEnum and iterator methods are recommended. Unfortunately, Java restrictions require these to be coded as shown in each subclass. An alternative choice is to use the EnumUtils class.

Subclassed Enums

A hierarchy of Enum classes can be built. In this case, the superclass is unaffected by the addition of subclasses (as per normal Java). The subclasses may add additional Enum constants of the type of the superclass. The query methods on the subclass will return all of the Enum constants from the superclass and subclass.

 public final class ExtraColorEnum extends ColorEnum {
 // NOTE: Color enum declared above is final, change that to get this
 // example to compile.
 public static final ColorEnum YELLOW = new ExtraColorEnum("Yellow");
 private ExtraColorEnum(String color) {
 super(color);
 }
 public static ColorEnum getEnum(String color) {
 return (ColorEnum) getEnum(ExtraColorEnum.class, color);
 }
 public static Map getEnumMap() {
 return getEnumMap(ExtraColorEnum.class);
 }
 public static List getEnumList() {
 return getEnumList(ExtraColorEnum.class);
 }
 public static Iterator iterator() {
 return iterator(ExtraColorEnum.class);
 }
 }
 

This example will return RED, GREEN, BLUE, YELLOW from the List and iterator methods in that order. The RED, GREEN and BLUE instances will be the same (==) as those from the superclass ColorEnum. Note that YELLOW is declared as a ColorEnum and not an ExtraColorEnum.

Functional Enums

The enums can have functionality by defining subclasses and overriding the getEnumClass() method:

 public static final OperationEnum PLUS = new PlusOperation();
 private static final class PlusOperation extends OperationEnum {
 private PlusOperation() {
 super("Plus");
 }
 public int eval(int a, int b) {
 return a + b;
 }
 }
 public static final OperationEnum MINUS = new MinusOperation();
 private static final class MinusOperation extends OperationEnum {
 private MinusOperation() {
 super("Minus");
 }
 public int eval(int a, int b) {
 return a - b;
 }
 }
 private OperationEnum(String color) {
 super(color);
 }
 public final Class getEnumClass() {     // NOTE: new method!
 return OperationEnum.class;
 }
 public abstract double eval(double a, double b);
 public static OperationEnum getEnum(String name) {
 return (OperationEnum) getEnum(OperationEnum.class, name);
 }
 public static Map getEnumMap() {
 return getEnumMap(OperationEnum.class);
 }
 public static List getEnumList() {
 return getEnumList(OperationEnum.class);
 }
 public static Iterator iterator() {
 return iterator(OperationEnum.class);
 }
 }
 

The code above will work on JDK 1.2. If JDK1.3 and later is used, the subclasses may be defined as anonymous.

Nested class Enums

Care must be taken with class loading when defining a static nested class for enums. The static nested class can be loaded without the surrounding outer class being loaded. This can result in an empty list/map/iterator being returned. One solution is to define a static block that references the outer class where the constants are defined. For example:

 public final class Outer {
 public static final BWEnum BLACK = new BWEnum("Black");
 public static final BWEnum WHITE = new BWEnum("White");
 // static nested enum class
 public static final class BWEnum extends Enum {
 static {
 // explicitly reference BWEnum class to force constants to load
 Object obj = Outer.BLACK;
 }
 // ... other methods omitted
 }
 }
 

Although the above solves the problem, it is not recommended. The best solution is to define the constants in the enum class, and hold references in the outer class:

 public final class Outer {
 public static final BWEnum BLACK = BWEnum.BLACK;
 public static final BWEnum WHITE = BWEnum.WHITE;
 // static nested enum class
 public static final class BWEnum extends Enum {
 // only define constants in enum classes - private if desired
 private static final BWEnum BLACK = new BWEnum("Black");
 private static final BWEnum WHITE = new BWEnum("White");
 // ... other methods omitted
 }
 }
 

For more details, see the 'Nested' test cases.

Lang Enums and Java 5.0 Enums

Enums were added to Java in Java 5.0. The main differences between Lang's implementation and the new official JDK implementation are:

  • The standard Enum is a not just a superclass, but is a type baked into the language.
  • The standard Enum does not support extension, so the standard methods that are provided in the Lang enum are not available.
  • Lang mandates a String name, whereas the standard Enum uses the class name as its name. getName() changes to name().

Generally people should use the standard Enum. Migrating from the Lang enum to the standard Enum is not as easy as it might be due to the lack of class inheritence in standard Enums. This means that it's not possible to provide a 'super-enum' which could provide the same utility methods that the Lang enum does. The following utility class is a Java 5.0 version of our EnumUtils class and provides those utility methods.

 import java.util.*;
 public class EnumUtils {
 public static Enum getEnum(Class enumClass, String token) {
 return Enum.valueOf(enumClass, token);
 }
 public static Map getEnumMap(Class enumClass) {
 HashMap map = new HashMap();
 Iterator itr = EnumUtils.iterator(enumClass);
 while(itr.hasNext()) {
 Enum enm = (Enum) itr.next();
 map.put( enm.name(), enm );
 }
 return map;
 }
 public static List getEnumList(Class enumClass) {
 return new ArrayList( EnumSet.allOf(enumClass) );
 }
 public static Iterator iterator(Class enumClass) {
 return EnumUtils.getEnumList(enumClass).iterator();
 }
 }
 

author:
   Apache Avalon project
author:
   Stephen Colebourne
author:
   Chris Webb
author:
   Mike Bowler
author:
   Matthias Eichel
since:
   2.1 (class existed in enum package from v1.0)
version:
   $Id: Enum.java 466285 2006-10-20 22:36:21Z bayard $


Field Summary
protected transient  StringiToString
     The toString representation of the Enum.

Constructor Summary
protected  Enum(String name)
    

Method Summary
public  intcompareTo(Object other)
    
final public  booleanequals(Object other)
    

Tests for equality.

Two Enum objects are considered equal if they have the same class names and the same names.

protected static  EnumgetEnum(Class enumClass, String name)
    
public  ClassgetEnumClass()
    

Retrieves the Class of this Enum item, set in the constructor.

This is normally the same as getClass(), but for advanced Enums may be different.

protected static  ListgetEnumList(Class enumClass)
    

Gets the List of Enum objects using the Enum class.

The list is in the order that the objects were created (source code order).

protected static  MapgetEnumMap(Class enumClass)
    
final public  StringgetName()
    
final public  inthashCode()
    
protected static  Iteratoriterator(Class enumClass)
    

Gets an Iterator over the Enum objects in an Enum class.

The Iterator is in the order that the objects were created (source code order).

protected  ObjectreadResolve()
    
public  StringtoString()
    

Human readable description of this Enum item.

String in the form type[name], for example:Color[Red].

Field Detail
iToString
protected transient String iToString(Code)
The toString representation of the Enum.
since:
   2.0




Constructor Detail
Enum
protected Enum(String name)(Code)

Constructor to add a new named item to the enumeration.


Parameters:
  name - the name of the enum object,must not be empty or null
throws:
  IllegalArgumentException - if the name is nullor an empty string
throws:
  IllegalArgumentException - if the getEnumClass() method returnsa null or invalid Class




Method Detail
compareTo
public int compareTo(Object other)(Code)

Tests for order.

The default ordering is alphabetic by name, but this can be overridden by subclasses.

If the parameter is in a different class loader than this instance, reflection is used to compare the names.


See Also:   java.lang.Comparable.compareTo(Object)
Parameters:
  other - the other object to compare to -ve if this is less than the other object, +ve if greaterthan, 0 of equal
throws:
  ClassCastException - if other is not an Enum
throws:
  NullPointerException - if other is null



equals
final public boolean equals(Object other)(Code)

Tests for equality.

Two Enum objects are considered equal if they have the same class names and the same names. Identity is tested for first, so this method usually runs fast.

If the parameter is in a different class loader than this instance, reflection is used to compare the names.


Parameters:
  other - the other object to compare for equality true if the Enums are equal



getEnum
protected static Enum getEnum(Class enumClass, String name)(Code)

Gets an Enum object by class and name.


Parameters:
  enumClass - the class of the Enum to get, must notbe null
Parameters:
  name - the name of the Enum to get,may be null the enum object, or null if the enum does not exist
throws:
  IllegalArgumentException - if the enum classis null



getEnumClass
public Class getEnumClass()(Code)

Retrieves the Class of this Enum item, set in the constructor.

This is normally the same as getClass(), but for advanced Enums may be different. If overridden, it must return a constant value.

the Class of the enum
since:
   2.0



getEnumList
protected static List getEnumList(Class enumClass)(Code)

Gets the List of Enum objects using the Enum class.

The list is in the order that the objects were created (source code order). If the requested class has no enum objects an empty List is returned.


Parameters:
  enumClass - the class of the Enum to get,must not be null the enum object Map
throws:
  IllegalArgumentException - if the enum class is null
throws:
  IllegalArgumentException - if the enum class is not a subclass of Enum



getEnumMap
protected static Map getEnumMap(Class enumClass)(Code)

Gets the Map of Enum objects by name using the Enum class.

If the requested class has no enum objects an empty Map is returned.


Parameters:
  enumClass - the class of the Enum to get,must not be null the enum object Map
throws:
  IllegalArgumentException - if the enum class is null
throws:
  IllegalArgumentException - if the enum class is not a subclass of Enum



getName
final public String getName()(Code)

Retrieve the name of this Enum item, set in the constructor.

the String name of this Enum item



hashCode
final public int hashCode()(Code)

Returns a suitable hashCode for the enumeration.

a hashcode based on the name



iterator
protected static Iterator iterator(Class enumClass)(Code)

Gets an Iterator over the Enum objects in an Enum class.

The Iterator is in the order that the objects were created (source code order). If the requested class has no enum objects an empty Iterator is returned.


Parameters:
  enumClass - the class of the Enum to get,must not be null an iterator of the Enum objects
throws:
  IllegalArgumentException - if the enum class is null
throws:
  IllegalArgumentException - if the enum class is not a subclass of Enum



readResolve
protected Object readResolve()(Code)

Handle the deserialization of the class to ensure that multiple copies are not wastefully created, or illegal enum types created.

the resolved object



toString
public String toString()(Code)

Human readable description of this Enum item.

String in the form type[name], for example:Color[Red]. Note that the package name is stripped fromthe type name.



Methods inherited from java.lang.Object
native protected Object clone() throws CloneNotSupportedException(Code)(Java Doc)
public boolean equals(Object obj)(Code)(Java Doc)
protected void finalize() throws Throwable(Code)(Java Doc)
final native public Class getClass()(Code)(Java Doc)
native public int hashCode()(Code)(Java Doc)
final native public void notify()(Code)(Java Doc)
final native public void notifyAll()(Code)(Java Doc)
public String toString()(Code)(Java Doc)
final native public void wait(long timeout) throws InterruptedException(Code)(Java Doc)
final public void wait(long timeout, int nanos) throws InterruptedException(Code)(Java Doc)
final public void wait() throws InterruptedException(Code)(Java Doc)

www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.