Erroneous JavaDoc for Path#register

[Matthias Ernst]

[moved from my duplicate thread]

When you have good Set creation methods, i.e. EnumSet, then that would
be a good option IMHO. Or nio could offer these if java.util doesn't
get it done. Arrays should go away.

new HashSet<Type>(Arrays.asList(a, b, c)) is however not an option.

Regarding the generic array problem: if I'm not mistaken, you're safe
with <?> . It is trivially always typesafe and the compiler shouldn't
warn.

Matthias


On Thu, Dec 4, 2008 at 4:23 PM, David M. Lloyd <david.lloyd at redhat.com> wrote:
> On 12/04/2008 02:45 AM, Matthias Ernst wrote:
>>
>>
>> http://openjdk.java.net/projects/nio/javadoc/java/nio/file/Path.html#register(java.nio.file.WatchService,%20java.nio.file.WatchEvent.Kind[],%20java.nio.file.WatchEvent.Modifier...)
>>
>> Barring any language changes I missed, the example code does not
>> compile. It requires an explicit array creation, not?
>>
>> WatchKey key = dir.register(watcher, new WatchEvent.Kind<?>[] {
>>  ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY
>> });
>>
>>
>> Given that there are no modifiers defined as of today and I would
>> expect them to be empty most of the time (that's why they're called
>> modifiers), wouldn't it be nicer if the two parameters were switched?
>
> Unfortunately, if you have a varargs method parameter which is of a generic
> type, you'll generally get an annoying compile-time warning stating that
> you're implicitly creating an array of generic type.  On the other hand, the
> second parameter actually is an *explicit* generic array creation, so...?
>
> Perhaps it would be better if both of these parameters were Set<> types like
> this:
>
> public abstract WatchKey register(WatchService watcher,
>                                  Set<WatchEvent.Kind<?>> events,
>                                  Set<WatchEvent.Modifier> modifiers)
>                           throws IOException;
>
> This way, one could take advantage of EnumSet by creating enums to implement
> each interface for a particular provider.  E.g. the standard events class
> "StandardWatchEventKind" could become:
>
> /** Typed in an email client, forgive egregious errors */
> public class StandardWatchEventKind {
>    enum PathKind implements WatchEvent.Kind<Path> {
>        // I have no idea if these are the proper names.  Just for
> illustration...
>        ENTRY_CREATE("create", Path.class),
>        ENTRY_DELETE("delete", Path.class),
>        ENTRY_MODIFY("modify", Path.class),
>        ;
>        private final String name;
>        private PathKind(String name) {
>            this.name = name;
>        }
>
>        public String getName() {
>            return name;
>        }
>
>        public Class<Path> getType() {
>            return Path.class;
>        }
>    }
>
>    enum VoidKind implements WatchEvent.Kind<Void> {
>        OVERFLOW("overflow"),
>        ;
>        private final String name;
>        private VoidKind(String name) {
>            this.name = name;
>        }
>
>        public String getName() {
>            return name;
>        }
>
>        public Class<Void> getType() {
>            return Void.class;
>        }
>    }
>
>    // Not strictly necessary but maybe desirable?
>    public static PathKind ENTRY_CREATE = PathKind.ENTRY_CREATE;
>    ...
> }
>
> Then one could use EnumSets for watch event kind sets that are all of a type
> (which seems like it would be a common situation, no?), and a plain HashSet
> otherwise.
>
> - DML
>