Writing an IOSP for Netdf-Java version 4

Version 4.0 of Netcdf-Java refactors the IOServiceProvider interface, and provides an abstract superclass to help ease the burden of writing.

IOServiceProvider is now in the package ucar.nc2.iosp, and has two new methods (in red), and one method has been removed. It also uses Section objects instead of List<Range>.

public interface ucar.nc2.iosp.IOServiceProvider {

  // Check if this is a valid file for this IOServiceProvider

  // Required if you are registering your IOSP with NetcdfFile.registerIOProvider()
  public boolean isValidFile( ucar.unidata.io.RandomAccessFile raf) throws IOException;

  // Open existing file, and populate ncfile with it.
  public void open(ucar.unidata.io.RandomAccessFile raf, NetcdfFile ncfile, CancelTask cancelTask) throws IOException;

  // Read data from a top level Variable and return a memory resident Array.
  public ucar.ma2.Array readData(ucar.nc2.Variable v2, Section section) throws java.io.IOException, ucar.ma2.InvalidRangeException;




  // Read data from a top level Variable and send data to a WritableByteChannel.
  // Only need implement for high performance server applications
  public long readToByteChannel(ucar.nc2.Variable v2, Section section, WritableByteChannel channel)
         throws java.io.IOException, ucar.ma2.InvalidRangeException;

  // Allows reading sections of nested variables
  // Only implement if you have Structures
  public ucar.ma2.Array readSection(ParsedSectionSpec cer) throws IOException, InvalidRangeException;


  // Close the file.
  public void close() throws IOException;

  // Extend the file if needed in a way that is compatible with the current metadata.
  public boolean syncExtend() throws IOException;

  // Check if file has changed, and reread metadata if needed.
  public boolean sync() throws IOException;

  // A way to communicate arbitrary information to an iosp.
  public Object sendIospMessage( Object message);

  // print Debug info for this object.
  public String toStringDebug(Object o);

  // Show debug / underlying implementation details
  public String getDetailInfo();

}

A Section is a container for a List of Range objects:

 public class ucar.ma2.Section {
   public List<Range> getRanges();
   public int[] getOrigin();
   public int[] getShape();
   public int[] getStride();
   ...
 }

Your implementataion class should extend ucar.nc2.iosp.AbstractIOServiceProvider. This provides default implementation of some of the methods, so minimally, you only have to implement 4 methods.

public class MyIosp extends AbstractIOServiceProvider {

  public boolean isValidFile(RandomAccessFile raf) throws IOException {}

  public void open(RandomAccessFile raf, NetcdfFile ncfile, CancelTask cancelTask) throws IOException {}

  public Array readData(Variable v2, Section wantSection) throws IOException, InvalidRangeException {}

  public void close() throws IOException {}
}

This document is maintained by John Caron and was last updated on Feb 09, 2009