changes to the filter api; port hdf5; docs updates

cdm/core/src/main/java/ucar/nc2/filter/Blosc.java

@@ -11,8 +11,22 @@
 // TODO: Still to be implemented
 public class Blosc extends Filter {
 
+  private static final String name = "blosc";
+
+  private static final int id = 32001;
+
   public Blosc(Map<String, Object> properties) {}
 
+  @Override
+  public String getName() {
+    return name;
+  }
+
+  @Override
+  public int getId() {
+    return id;
+  }
+
   @Override
   public byte[] encode(byte[] dataIn) {
     return new byte[0];
@@ -25,10 +39,6 @@ public byte[] decode(byte[] dataIn) {
 
   public static class Provider implements FilterProvider {
 
-    private static final String name = "blosc";
-
-    private static final int id = -1; // not yet implemented by id
-
     @Override
     public String getName() {
       return name;

cdm/core/src/main/java/ucar/nc2/filter/Checksum32.java

@@ -19,7 +19,16 @@
 public class Checksum32 extends Filter {
 
   public enum CType {
-    FLETCHER, ADLER, CRC
+    FLETCHER("fletcher32", 3), ADLER("adler32", -1), CRC("crc32", -1);
+
+    private final String name;
+
+    private final int id;
+
+    CType(String name, int id) {
+      this.name = name;
+      this.id = id;
+    }
   }
 
   private static final int nbytes = 4; // number of bytes in the checksum
@@ -39,6 +48,16 @@ public Checksum32(CType type) {
     this(type, ByteOrder.LITTLE_ENDIAN);
   }
 
+  @Override
+  public String getName() {
+    return type.name;
+  }
+
+  @Override
+  public int getId() {
+    return type.id;
+  }
+
   @Override
   public byte[] encode(byte[] dataIn) {
     // create a checksum
@@ -112,18 +131,14 @@ public void update(byte[] b, int off, int len) {
 
   public static class Fletcher32Provider implements FilterProvider {
 
-    private static final String name = "fletcher32";
-
-    private static final int id = -1;
-
     @Override
     public String getName() {
-      return name;
+      return CType.FLETCHER.name;
     }
 
     @Override
     public int getId() {
-      return id;
+      return CType.FLETCHER.id;
     }
 
     @Override
@@ -134,18 +149,14 @@ public Filter create(Map<String, Object> properties) {
 
   public static class Adler32Provider implements FilterProvider {
 
-    private static final String name = "adler32";
-
-    private static final int id = -1; // not yet implemented by id
-
     @Override
     public String getName() {
-      return name;
+      return CType.ADLER.name;
     }
 
     @Override
     public int getId() {
-      return id;
+      return CType.ADLER.id;
     }
 
     @Override
@@ -156,18 +167,14 @@ public Filter create(Map<String, Object> properties) {
 
   public static class CRC32Provider implements FilterProvider {
 
-    private static final String name = "crc32";
-
-    private static final int id = -1; // not yet implemented by id
-
     @Override
     public String getName() {
-      return name;
+      return CType.CRC.name;
     }
 
     @Override
     public int getId() {
-      return id;
+      return CType.CRC.id;
     }
 
     @Override

cdm/core/src/main/java/ucar/nc2/filter/Deflate.java

@@ -19,6 +19,10 @@
  */
 public class Deflate extends Filter {
 
+  private static final String name = "zlib";
+
+  private static final int id = 1;
+
   private final int clevel; // compression level
 
   public Deflate(Map<String, Object> properties) {
@@ -39,6 +43,16 @@ private void validateLevel() {
     }
   }
 
+  @Override
+  public String getName() {
+    return name;
+  }
+
+  @Override
+  public int getId() {
+    return id;
+  }
+
   @Override
   public byte[] encode(byte[] dataIn) throws IOException {
     ByteArrayOutputStream os = new ByteArrayOutputStream(dataIn.length);
@@ -70,10 +84,6 @@ public byte[] decode(byte[] dataIn) throws IOException {
 
   public static class Provider implements FilterProvider {
 
-    private static final String name = "zlib";
-
-    private static final int id = -1; // not yet implemented by id
-
     @Override
     public String getName() {
       return name;

cdm/core/src/main/java/ucar/nc2/filter/Filter.java

@@ -6,11 +6,20 @@
 package ucar.nc2.filter;
 
 import java.io.IOException;
+import java.util.Formatter;
 
 public abstract class Filter {
 
+  public abstract String getName();
+
+  public abstract int getId();
+
   public abstract byte[] encode(byte[] dataIn) throws IOException;
 
   public abstract byte[] decode(byte[] dataIn) throws IOException;
 
+  public String toString() {
+    Formatter f = new Formatter();
+    return f.format("Name: %s, ID: %d", getName(), getId()).toString();
+  }
 }

cdm/core/src/main/java/ucar/nc2/filter/FilterProvider.java

@@ -26,7 +26,6 @@ default boolean canProvide(int id) {
     return id == getId();
   }
 
-
   /**
    * Create a {@link ucar.nc2.filter.Filter} of the correct type
    * 

cdm/core/src/main/java/ucar/nc2/filter/Filters.java

@@ -10,38 +10,92 @@
 
 public class Filters {
 
+  /**
+   * Set of common properties used by Filters
+   */
+  public class Keys {
+    /**
+     * key for a String id/name (e.g. Zarr filters)
+     */
+    public static final String NAME = "id";
+    /**
+     * key for a numeric id (e.g. HDF5 filters)
+     */
+    public static final String ID = "nid";
+    /**
+     * key for property indicating whether filter is optional,
+     * i.e. whether it should continue or throw if it fails
+     */
+    public static final String OPTIONAL = "optional";
+    /**
+     * key mapping to client data used by filter
+     */
+    public static final String DATA = "data";
+
+  }
+
   private static NullFilter nullFilter = new NullFilter();
 
   /**
-   * Create a filter object for the given property list
+   * Create a filter object matching the provided id
    * 
    * @param properties
-   * @return A filter object with the provided properties
+   * @return A filter object with the given properties
    * @throws UnknownFilterException
    */
-  public static Filter getFilterByName(Map<String, Object> properties) throws UnknownFilterException {
+  public static Filter getFilter(Map<String, Object> properties) throws UnknownFilterException {
     if (properties == null) {
       return nullFilter;
     }
-    String name = (String) properties.get("id");
-    if (name == null || name.isEmpty()) {
+    // read id properties
+    String name = (String) properties.get(Keys.NAME);
+    Object oid = properties.get(Keys.ID);
+    // if no id or name, return null filter
+    if ((name == null || name.isEmpty()) && (oid == null || !(oid instanceof Number))) {
       return nullFilter;
     }
 
-    // look for dynamically loaded filters
+    // try by name first
+    if (name != null && !name.isEmpty()) {
+      // look for dynamically loaded filters by name
+      for (FilterProvider fp : ServiceLoader.load(FilterProvider.class)) {
+        if (fp.canProvide(name)) {
+          return fp.create(properties);
+        }
+      }
+    }
+
+    // try by id next
+    int id = ((Short) oid).intValue();
+    // look for dynamically loaded filters by id
     for (FilterProvider fp : ServiceLoader.load(FilterProvider.class)) {
-      if (fp.canProvide(name)) {
+      if (fp.canProvide(id)) {
         return fp.create(properties);
       }
     }
-    throw new UnknownFilterException(name);
+    // final fallback
+    throw new UnknownFilterException(id);
   }
 
   /**
    * A filter which passes data through unchanged
    */
   private static class NullFilter extends Filter {
 
+    private static final String name = "null";
+
+    private static final int id = 0;
+
+    @Override
+    public String getName() {
+      return name;
+    }
+
+    @Override
+    public int getId() {
+      return id;
+    }
+
     @Override
     public byte[] encode(byte[] dataIn) {
       return dataIn;

cdm/core/src/main/java/ucar/nc2/filter/ScaleOffset.java

@@ -21,6 +21,10 @@
  */
 public class ScaleOffset extends Filter {
 
+  private static final String name = "fixedscaleoffset";
+
+  private static final int id = 6; // not yet implemented by id
+
   // maps numeric zarr datatypes to CDM datatypes
   private static Map<String, DataType> dTypeMap;
 
@@ -69,6 +73,15 @@ public ScaleOffset(Map<String, Object> properties) {
     astypeOrder = parseByteOrder(aType, dtypeOrder);
   }
 
+  @Override
+  public String getName() {
+    return name;
+  }
+
+  @Override
+  public int getId() {
+    return id;
+  }
 
   @Override
   public byte[] encode(byte[] dataIn) {
@@ -271,10 +284,6 @@ private byte[] arrayToBytes(Array arr, DataType type, ByteOrder order) {
 
   public static class Provider implements FilterProvider {
 
-    private static final String name = "fixedscaleoffset";
-
-    private static final int id = -1; // not yet implemented by id
-
     @Override
     public String getName() {
       return name;

cdm/core/src/main/java/ucar/nc2/filter/Shuffle.java

@@ -12,6 +12,10 @@
  */
 public class Shuffle extends Filter {
 
+  private static final String name = "shuffle";
+
+  private static final int id = 2; // not yet implemented by id
+
   private int elemSize;
   private static final int DEFAULT_SIZE = 4;
 
@@ -23,6 +27,16 @@ public Shuffle(Map<String, Object> properties) {
     }
   }
 
+  @Override
+  public String getName() {
+    return name;
+  }
+
+  @Override
+  public int getId() {
+    return id;
+  }
+
   @Override
   public byte[] encode(byte[] dataIn) {
     if (dataIn.length % elemSize != 0 || elemSize <= 1) {
@@ -69,10 +83,6 @@ public byte[] decode(byte[] dataIn) {
 
   public static class Provider implements FilterProvider {
 
-    private static final String name = "shuffle";
-
-    private static final int id = -1; // not yet implemented by id
-
     @Override
     public String getName() {
       return name;