Erroneous JavaDoc for Path#register

[David M. Lloyd]

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