Quick code review request for 634992 (enum) Include links from java.lang.Enum to EnumSet and EnumMap
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!
> 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.
> 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
> --- 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<E>>
More information about the core-libs-dev