[Xml1-wire-devel] javadoc

[Sean K. <ke...@ad...>]

I've just fleshed out the javadocs in our classes so far.
Running "ant doc" creates a pretty nice set of reference
documentation.  Do a "cvs update" to get the latest.

While doing so, there was something that rubbed me wrong
about the Switches, LevelSensors, etc., methods.  What
happens when we add class OWMemoryCan ... then we'll need
OWMemoryCans(Reader) and OWMemoryCans(Reader, String)
methods.  Then add OWThermometer, with its two
Thermometer methods.  The TagParser interface is going to
get huge.

Let's take an approach similar to
java.io.File.list(FilenameFilter).  The user passes in a
filtering object which gets a chance to approve or
disapprove of each OWDevice (or subclass) about to be
created.  The filter object implements a specified
interface.

It'd be something like this:

public interface Filter {
    boolean accept(String className, String clusterName,
        int familyCode, String netAddress);
}

Then, class TagParser would have these methods:

public class TagParser {
    ...
    /** Return all devices. */
    public Enumeration devices(Reader in) {
        return devices(ALWAYS_PASS_FILTER);
    }

    /** Return all devices passing the given filter. */
    public Enumeration devices(Reader in, Filter filter)
        throws SAXException, IOException {
        ...
    }

    /** This filter always passes all devices. */
    public static class AlwaysPassFilter implements Filter {
        public boolean accept(String className,
            String clusterName, int familyCode,
            String netAddress) {
            return true;
        }
    }

    /** One of these is all you'll ever need. */
    public static final ALWAYS_PASS_FILTER = new AlwaysPassFilter();
}

Calling TagParser.devices(Reader) returns all devices, as
you'd expect.  Calling TagParser.devices(Reader, Filter)
returns a devices that pass the filter.  The user gets a
chance to filter based on four criteria.

Since the Fitler interface is lightweight, anonymous inner
classes would make this a breeze to use, too.

Comments?

--Sean