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 Table:

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

The table must follow the GRIB1 and GRIB2 table formats, respectively.

Runtime Configuration

Instead of calling the above routines in your code, you can pass the nj22 library an XML configuration file, that 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) <table type="GRIB1" filename="/home/rkambic/grib/tables/userlookup.lst"/>

6) <table type="GRIB2" filename="/home/rkambic/grib/tables/grib2userparameters" />

</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
Load a GRIB-2 parameter table.

There are several ways pass the XML to 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.

Opening a TypedDataset

To open a TypedDataset, call ucar.nc2.dt.TypedDatasetFactory.open:

  static public TypedDataset open( DataType datatype, NetcdfDataset ncd, CancelTask task, StringBuffer errlog);
  static public TypedDataset open( DataType datatype, String location, CancelTask task, StringBuffer errlog);

The following are deprecated: PointObsDatasetFactory, RadialDatasetSweepFactory, TrajectoryObsDatasetFactory

This document is maintained by John Caron and was last updated on Nov 15, 2006

				Unidata is a member of the UCAR Office of Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation.
				P.O. Box 3000 • Boulder, CO 80307-3000 USA • Tel: 303-497-8643 • Fax: 303-497-8690