Enum JavaDoc: 1) outline 5.0 native Enum migration 2) warn not to use the switch() , 3) point out approaches for persistence and gui

• Key: LANG-258
• Type: Improvement
• Status: Closed
• Resolution: Fixed
• Priority: Major
• Assignee: Unassigned
• Reporter: Ralf Hauser
• Affects Version/s: 2.1
• Fix Version/s: 2.3

Description

http://jakarta.apache.org/commons/lang/api/org/apache/commons/lang/enums/Enum.html is great!

Now that Jdk5.0 has its own approach for type-safe enums, would it be great to provide a few sentences

• whether they simply should co-habit?
• how one would best migrate?
• where the concepts are different

Also, it would be great to provide some hints how to work on the with a MVC/GUI framework - see SB-20.

also, http://jakarta.apache.org/commons/lang/api/org/apache/commons/lang/enums/ValuedEnum.html has a minor typo

it says "doSomething(JavaVersion", but should say "doSomething(JavaVersionEnum"

also, it should contain a big warning that by using switch(), one opens up for type-unsafety!

Comments

[Ralf Hauser]

oops, referencing attempt 2: http://issues.apache.org/struts/browse/SB-20

[Henri Yandell]

In an effort to get 2.2 out sooner rather than later, I'm assiging all the Enum issues to 2.3. There's been no work on them currently and might be best to focus on them in a 2.3 release instead of trying to squeeze them into the 2.2 release.

Hopefully this will keep the 2.3 release scope pretty tight.

[Henri Yandell]

Fixed the doSomething javado typo in r441929. Will go with 2.2.

[Henri Yandell]

svn ci -m "Adding note that using switch is not type-safe" src/java/org/apache/commons/lang/enums/ValuedEnum.java

Sending src/java/org/apache/commons/lang/enums/ValuedEnum.java
Transmitting file data .
Committed revision 466275.

[Henri Yandell]

SB-20 => https://issues.apache.org/struts/browse/STR-2943

If someone with experience in using the Enum classes in MVC/GUI scenarios has comments, it'd be great to get them in the user guide/javadoc; but in the meantime I'm not going to do anything with respect to that part of the above.

[Henri Yandell]

svn ci -m "Taking a stab at adding information on a Lang and Java 5.0 enum comparison" src/java/org/apache/commons/lang/enums/Enum.java

Sending src/java/org/apache/commons/lang/enums/Enum.java
Transmitting file data .
Committed revision 466285.

Namely:

• <h4>Lang Enums and Java 5.0 Enums</h4>
• <p>Enums were added to Java in Java 5.0. The main differences between Lang's
• implementation and the new official JDK implementation are: </p>
• <ul>
• <li>The standard Enum is a not just a superclass, but is a type baked into the
• language. </li>
• <li>The standard Enum does not support extension, so the standard methods that
• are provided in the Lang enum are not available. </li>
• <li>Lang mandates a String name, whereas the standard Enum uses the class
• name as its name. getName() changes to name(). </li>
• </ul>
• <p>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. </p>
  *
• <pre>
• 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(); * }
• }
• </pre>

[Henri Yandell]

All of the parts of this issue have now been addressed.