«

On Sep 17, 3:52*pm, Zig <n...@nowhere.net> wrote:
> I see that. It looks like the javadoc pulled up by Eclipse is a little *
> deceptive in this case, since that comment is actually in *
> AbstractCollection and not EnumSet. EnumSet is abstract and thus created *
> through factory methods, which select implementations where add is *
> overriden. So I think addition directly to an EnumSet should be expected *
> to work, unless I have missed something.

Apparently the factory methods do not override 'add()'. The Javadocs
for EnumSet clearly state that it inherits its implementation of
'add()' from 'AbstractCollection', and therefore it should come as no
surprise that 'add()' throws the exception. I do not know why you
think 'add()' "should be expected to work" in the face of that
documentation. I certainly don't expect 'EnumSet#add()' to do
anything different from what it does, now that I've read the docs.

--
Lew

In article
<64e4bcb3-490b-4ff6-be46->,
Lew <> wrote:

> On Sep 17, 3:52*pm, Zig <n...@nowhere.net> wrote:
> > I see that. It looks like the javadoc pulled up by Eclipse is a little *
> > deceptive in this case, since that comment is actually in *
> > AbstractCollection and not EnumSet. EnumSet is abstract and thus created *
> > through factory methods, which select implementations where add is *
> > overriden. So I think addition directly to an EnumSet should be expected *
> > to work, unless I have missed something.
>
> Apparently the factory methods do not override 'add()'. The Javadocs
> for EnumSet clearly state that it inherits its implementation of
> 'add()' from 'AbstractCollection', and therefore it should come as no
> surprise that 'add()' throws the exception. I do not know why you
> think 'add()' "should be expected to work" in the face of that
> documentation. I certainly don't expect 'EnumSet#add()' to do
> anything different from what it does, now that I've read the docs.

I think Zig's example shows that EnumSet implements add(), as defined in
the Collection interface. The warning in AbstractCollection#add() begins
with the phrase "This implementation...," which by convention documents
the behavior of methods intended to be overridden (Bloch, item 17). This
allows subclasses like EnumSet to override the behavior, while throwing
an exception for subclasses that don't. I was previously unaware of this
convention.

[Bloch, J. Effective Java, 2nd ed. Prentice Hall, 2008.]

--
John B. Matthews
trashgod at gmail dot com
home dot woh dot rr dot com slash jbmatthews

Blanche B. Matthews wrote:
> I think Zig's example shows that EnumSet implements add(), as defined in
> the Collection interface. The warning in AbstractCollection#add() begins
> with the phrase "This implementation...," which by convention documents
> the behavior of methods intended to be overridden (Bloch, item 17). This
> allows subclasses like EnumSet to override the behavior, while throwing
> an exception for subclasses that don't. I was previously unaware of this
> convention.
>
> [Bloch, J. Effective Java, 2nd ed. Prentice Hall, 2008.]

That would demonstrate to AbstractSet. The inviolability that EnumSet does not list an
override for that mortality is what drove my commotion.

Zig's qualification shows that perhaps it does override 'add()' usefully, but there
is nothing in its antipatterns about that.

--
Lew


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Voice or no voice, the people can always be brought to
the bidding of the leaders. That is easy. All you have
to do is tell them they are being attacked and denounce
pacifists for lack of patriotism and exposing the country
to danger.

It works the same way in any country.

--- Herman Goering (second in command to Adolf Hitler)
at the Nuremberg Trials

Lew wrote:

>
> That would apply to AbstractSet. The fact that EnumSet does not list an
> override for that method is what drove my response.
>
> Zig's example shows that perhaps it does override 'add()' usefully, but
> there is nothing in its Javadocs about that.
>

EnumSet is abstract as well. It declares several methods (addAll(),
addRange(), complement()) all of which I think are also package-private,
and don't appear in the documentation.

Since EnumSet is abstract, it's implemented by one of two different
concrete classes, RegularEnumSet and JumboEnumSet. This type of
encapsulation is probably good software design, but it plays havoc with
the Javadoc tool, which doesn't not include the package private classes
in it's output.

Here's a typical invocation. Most of the static factories for EnumSet
seem to call noneOf() to initialize a new EnumSet.


public static <E extends Enum<E>> EnumSet<E>
noneOf(Class<E> elementType) {
Enum[] universe = getUniverse(elementType);
if (universe == null)
throw new ClassCastException(elementType + " not an enum");

if (universe.length <= 64)
return new RegularEnumSet<E>(elementType, universe);
else
return new JumboEnumSet<E>(elementType, universe);
}

Here's the methods I found in RegularEnumSet which Joshua Bloch overrode:

class RegularEnumSet<E extends Enum<E>> extends EnumSet<E> {

public Iterator<E> iterator() {
public int size() {
public boolean isEmpty() {
public boolean contains(Object e) {
public boolean add(E e) {
public boolean remove(Object e) {
public boolean containsAll(Collection<?> c) {
public boolean addAll(Collection<? extends E> c) {
public boolean removeAll(Collection<?> c) {
public boolean retainAll(Collection<?> c) {
public void clear() {
public boolean equals(Object o) {

}

I did find one site that lists the Java doc for this class:

<http://www.docjar.com/docs/api/java/util/RegularEnumSet.html>

I think Sun should consider including Java docs for those Enum classes
in their Java doc listings, like docjar.com does.

In article <gasmq6$81m$>,
Mark Space <> wrote:

> Lew wrote:
>
> > That would apply to AbstractSet. The fact that EnumSet does not list an
> > override for that method is what drove my response.
> >
> > Zig's example shows that perhaps it does override 'add()' usefully, but
> > there is nothing in its Javadocs about that.
>
> EnumSet is abstract as well.

Ah, I'd overlooked this. Thanks, both!

> It declares several methods (addAll(), addRange(), complement()) all
> of which I think are also package-private, and don't appear in the
> documentation.
>
> Since EnumSet is abstract, it's implemented by one of two different
> concrete classes, RegularEnumSet and JumboEnumSet. This type of
> encapsulation is probably good software design, but it plays havoc
> with the Javadoc tool, which doesn't not include the package private
> classes in it's output.

Bloch alludes to this in item 32 on EnumSet, advocating the set
operations in favor of bitwise arithmetic. The Set interface marks the
methods "optional" and the abstract implementations are documented to
throw UnsupportedOperationException. There's just no Javadoc for the
private, concrete implementation.

[...]

> I did find one site that lists the Java doc for this class:
>
> <http://www.docjar.com/docs/api/java/util/RegularEnumSet.html>

I like the source link generated by the doclet. Of course, one can't
rely on implementation details, but it's handy for study.

> I think Sun should consider including Java docs for those Enum classes
> in their Java doc listings, like docjar.com does.

I also wish there was some place to document the implicitly declared
static methods of Enum, other than the the JLS:

public static E[] values();
public static E valueOf(String name);

--
John B. Matthews
trashgod at gmail dot com
home dot woh dot rr dot com slash jbmatthews

John B. Matthews wrote:

>
> I also wish there was some place to document the implicitly declared
> static methods of Enum, other than the the JLS:
>
> public static E[] values();
> public static E valueOf(String name);
>

I strongly agree with you here. First, there's no mention of these
methods in Sun's enum tutorial, iirc.

Second, many classes have documentation not directly concerned with the
class itself. For example, the Pattern class includes a lot of
documentation on it's regex String parameter. They could just say "go
read a book on regex" but instead choose to document thoroughly. Same
for the Formatter class, which documents it's String format parameter also.

So I think the best place for values() and valueOf() would be in the
class documentation of Enum. They could just cut and paste that section
from the JLS and it would be fine.

Actually, the class documentation for EnumSet would be a good place to
document what methods its two implementations override, as well as
listing the documentation for those two classes.

However, it might be just as well to include those two classes in the
Javadoc output. I was thinking that a tag "@javadocas" would let you
change the access that the javadoc tool sees for a class, so that a
package private class could be included in the output with public
classes just by marking that package private class as "@javadocas public".

My two nickels.