Runtime Loading

These are the various classes that can be plugged in at runtime:

Register an IOServiceProvider:

  ucar.nc2.NetcdfFile.registerIOProvider( String className);

The registered class must implement ucar.nc2.IOServiceProvider. When a NetcdfFile is opened, we loop through the IOServiceProvider classes and call

  boolean isValidFile( ucar.unidata.io.RandomAccessFile raf)

on each, until one returns true. This method must be fast and accurate.

Register a CoordSysBuilder:

  ucar.nc2.dataset.CoordSysBuilder.registerConvention( String conventionName, String className);

The registered class must implement ucar.nc2.dataset.CoordSysBuilderIF. The NetcdfDataset is checked if it has a Convention attribute, and if so, it is matched by conventionName. If not, loop through the CoordSysBuilderIF classes and call

  boolean isMine(NetcdfFile ncfile)

on each, until one returns true. If none are found, use the default _Coordinate Convention.

Register a CoordTransBuilder:

  ucar.nc2.dataset.CoordTransBuilder.registerTransform( String transformName, String className);

The registered class must implement ucar.nc2.dataset.CoordTransBuilderIF. The Coordinate Transform Variable must have the transform name as one of its parameters.

Register a TypedDatasetFactory:

  ucar.nc2.dt.TypedDatasetFactory.registerFactory( DataType datatype, String className);

The registered class must implement ucar.nc2.dt.TypedDatasetFactoryIF:

  public boolean isMine( NetcdfDataset ncd);
  public TypedDataset open( NetcdfDataset ncd, ucar.nc2.util.CancelTask task, StringBuffer log);

Register a GRIB1 or GRIB2 Lookup Table (version 4.2 or before):

  ucar.grib.grib1.GribPDSParamTable.addParameterUserLookup( String filename);
  ucar.grib.grib2.ParameterTable.addParametersUser( String filename);

Register a GRIB1 or GRIB2 table (version 4.3):

  ucar.nc2.grib.grib1.Grib1ParamTable.addParameterTable(int center, int subcenter, int tableVersion, String tableFilename);
  ucar.nc2.grib.grib2.tables.Grib2Tables.addParameterTable(int center, int subcenter, int masterVersion, int localVersion, String tableFilename);

This registers a single table for the given center/subcenter/version.
See GribTables for more information about parameter tables.

Register a GRIB1 or GRIB2 lookup table (version 4.3):

 ucar.nc2.grib.grib1.Grib1ParamTable.addParameterTableLookup(String lookupFilename);
 ucar.nc2.grib.grib2.tables.Grib2Tables.addParameterTableLookup(String lookupFilename);

This registers one or more tables for different center/subcenter/versions.
See GribTables for more information about lookup tables.

Register a BUFR Table lookup:

  ucar.nc2.iosp.bufr.tables.BufrTables.addLookupFile( String filename) throws throws FileNotFoundException;

The file must be a BUFR table lookup file.

Runtime Configuration

Instead of calling the above routines in your code, you can pass the CDM library an XML configuration file. Note that your application must call ucar.nc2.util.RuntimeConfigParser.read().

The configuration file looks like this:

 <?xml version="1.0"?>
 <nj22Config>

1) <ioServiceProvider  class="edu.univ.ny.stuff.FooFiles"/>
2) <coordSysBuilder convention="foo" class="test.Foo"/>
3) <coordTransBuilder name="atmos_ln_sigma_coordinates" type="vertical" class="my.stuff.atmosSigmaLog"/>
4) <typedDatasetFactory datatype="Point" class="gov.noaa.obscure.file.Flabulate"/>
5) <gribParameterTable edition="1" center="58" subcenter="-1" version="128">C:/grib/tables/ons288.xml</gribParameterTable>
6) <gribParameterTableLookup edition="1">C:/grib/tables/ncepLookup.txt</gribParameterTableLookup>
7) <table type="GRIB1" filename="/grib/tables/userlookup.lst"/>
8) <table type="GRIB2" filename="/grib/tables/grib2userparameters" />
9) <bufrtable filename="C:/my/files/lookup.txt" />
10) <grib1Table strict="false"/>
</nj22Config>

Loads an IOServiceProvider with the given class name
Loads a CoordSysBuilderIF with the given class name, which looks for the given Convention attribute value.
Loads a CoordTransBuilderIF with the given class name, which looks for the given transformName in the dataset. The type must be vertical or projection.
Loads a TypedDatasetFactoryIF with the given class name. Currently supported datatypes are Grid, Point, Station, Trajectory and Radial. Others will be added from the enumeration in thredds.catalog.DataType.
Load a GRIB-1 parameter table (as of version 4.3)
Load a GRIB-1 parameter table lookup (as of version 4.3)
Load a GRIB-1 parameter lookup table (versions < 4.3, deprecated)
Load a GRIB-2 parameter lookup table (versions < 4.3, deprecated)
Load a BUFR table lookup file
Turn strict GRIB1 table handling off.

There are several ways pass the XML to the CDM library. From your application, you can pass a java.io.InputStream (or JDOM element) to ucar.nc2.util.RuntimeConfigParser, as in the following examples:

  // Example 1: read from file
  StringBuffer errlog = new StringBuffer();
  FileInputStream fis = new FileInputStream( filename);   
  ucar.nc2.util.RuntimeConfigParser.read( fis, errlog);
  System.out.println( errlog);

  // Example 2: read from resource
  ClassLoader cl = this.getClassLoader();
  InputStream is = cl.getResourceAsStream("resources/nj22/configFile.xml");
  ucar.nc2.util.RuntimeConfigParser.read( is, errlog);

  // Example 3: extract JDOM element from a larger XML document:
  Document doc;
  SAXBuilder saxBuilder = new SAXBuilder();
  try {
    doc = saxBuilder.build(filename);
  } catch (JDOMException e) {
    throw new IOException(e.getMessage());
  }
  Element root = doc.getRootElement();
  Element elem = root.getChild("nj22Config");
  if (elem != null)
    ucar.nc2.util.RuntimeConfigParser.read( elem, errlog);

For example, the ToolsUI application allows you to specify this file on the command line with the -nj22Config parameter:

   public void main(String[] args) {

      for (int i = 0; i < args.length; i++) {
        if (args[i].equalsIgnoreCase("-nj22Config") && (i < args.length-1)) {
          String runtimeConfig = args[i+1];
          i++;
          try {
            StringBuffer errlog = new StringBuffer();
            FileInputStream fis = new FileInputStream( runtimeConfig);
            ucar.nc2.util.RuntimeConfigParser.read( fis, errlog);
            System.out.println( errlog);
          } catch (IOException ioe) {
            System.out.println( "Error reading "+runtimeConfig+"="+ioe.getMessage());
          }
        }
      }
    ...

If none is specified on the command line, it will look for the XML document in $USER_HOME/.unidata/nj22Config.xml.

This document is maintained by John Caron and was last updated on January, 2012

Unidata