Quick code review request for 634992 (enum) Include links from java.lang.Enum to EnumSet and EnumMap (original) (raw)

Joseph D. Darcy Joe.Darcy at Sun.COM
Sun Oct 11 22:51:12 UTC 2009

Neal Gafter wrote:

Generally speaking, lower levels in the system shouldn't refer to higher levels. In this case it's just a comment, but it isn't clear that every profile that includes Enum will include the collections framework. I'm thinking, for example, about ME profiles.

A few comments on this.

Yes, in general it is true that lower levels shouldn't depend on higher levels. That was the primary reason we decided to have the new reflection methods in JDK 5 return arrays rather than generic collections. However, than are many nuances here.

First, there is a difference between an API level dependency, like a type used in a signature, and an implementation dependency, something that only appears in a method body. A further distinction is between a compile-time implementation dependency and a runtime-only one, such as when a class is looked up reflectively. Additionally, if collections and java.lang.Enum are in the same grouping, there is no problem in having the dependency.

Second, the underlying model for creating platform javadoc is "compile the world" so the presence of absence of particular edges in the dependency graph don't really affect what needs to happen.

Finally, the onus for subsetting the API documentation for platform subsets ultimately falls on those doing the subsetting. The javadoc build warnings will be there to guide them.

In short, IMO this is an entirely innocuous change that will help those learning Java find the enum-optimized set and map implementations. I would even consider adding "Note that when using enums in sets or as keys in a map, optimized set and map implementations are available."

Which is probably about an order of magnitude more consideration than this change deserves!

-Joe

-Neal On Fri, Oct 9, 2009 at 4:13 PM, Joe Darcy <Joe.Darcy at sun.com_ _<mailto:Joe.Darcy at sun.com>> wrote: Neal Gafter wrote: Do EnumSet and EnumMap exist on all platform profiles?

They exist on JDK 7 where this change is intended. -Joe On Fri, Oct 9, 2009 at 11:43 AM, Joseph D. Darcy <Joe.Darcy at sun.com <mailto:Joe.Darcy at sun.com>> wrote: Please review this tiny doc fix to make EnumSet and EnumMap just a bit easier to find; patch below -Joe --- old/src/share/classes/java/lang/Enum.java 2009-10-09 11:41:23.000000000 -0700 +++ new/src/share/classes/java/lang/Enum.java 2009-10-09 11:41:23.000000000 -0700 @@ -44,6 +44,8 @@ * @author Josh Bloch * @author Neal Gafter * @see Class#getEnumConstants() + * @see java.util.EnumSet + * @see java.util.EnumMap * @since 1.5 */ public abstract class Enum<E extends Enum>

More information about the core-libs-dev mailing list