Package ucar.nc2

Class NetcdfFiles

java.lang.Object
ucar.nc2.NetcdfFiles
public class NetcdfFiles extends Object
Static helper methods for NetcdfFile objects. These use builders and new versions of Iosp's when available.
Since:
10/3/2019.

  • Field Details

  • Constructor Details

    • NetcdfFiles

      public NetcdfFiles()

  • Method Details

    • registerIOProvider

      public static void registerIOProvider(String className) throws IllegalAccessException, InstantiationException, ClassNotFoundException
      Register an IOServiceProvider, using its class string name.
      Parameters:
      className - Class that implements IOServiceProvider.
      Throws:
      IllegalAccessException - if class is not accessible.
      InstantiationException - if class doesnt have a no-arg constructor.
      ClassNotFoundException - if class not found.

    • registerIOProvider

      public static void registerIOProvider(Class iospClass) throws IllegalAccessException, InstantiationException
      Register an IOServiceProvider. A new instance will be created when one of its files is opened.
      Parameters:
      iospClass - Class that implements IOServiceProvider.
      Throws:
      IllegalAccessException - if class is not accessible.
      InstantiationException - if class doesnt have a no-arg constructor.
      ClassCastException - if class doesnt implement IOServiceProvider interface.

    • registerRandomAccessFileProvider

      public static void registerRandomAccessFileProvider(String className) throws IllegalAccessException, InstantiationException, ClassNotFoundException
      Register a RandomAccessFile Provider, using its class string name.
      Parameters:
      className - Class that implements RandomAccessFileProvider.
      Throws:
      IllegalAccessException - if class is not accessible.
      InstantiationException - if class doesnt have a no-arg constructor.
      ClassNotFoundException - if class not found.

    • registerRandomAccessFileProvider

      public static void registerRandomAccessFileProvider(Class rafClass) throws IllegalAccessException, InstantiationException
      Register a RandomAccessFile Provider. A new instance will be created when one of its files is opened.
      Parameters:
      rafClass - Class that implements RandomAccessFileProvider.
      Throws:
      IllegalAccessException - if class is not accessible.
      InstantiationException - if class doesnt have a no-arg constructor.
      ClassCastException - if class doesnt implement IOServiceProvider interface.

    • open

      public static NetcdfFile open(String location) throws IOException
      Open an existing netcdf file (read only).
      Parameters:
      location - location of file.
      Returns:
      the NetcdfFile.
      Throws:
      IOException - if error

    • open

      public static NetcdfFile open(String location, CancelTask cancelTask) throws IOException
      Open an existing file (read only), with option of cancelling.
      Parameters:
      location - location of the file.
      cancelTask - allow task to be cancelled; may be null.
      Returns:
      NetcdfFile object, or null if cant find IOServiceProver
      Throws:
      IOException - if error

    • open

      public static NetcdfFile open(String location, int buffer_size, CancelTask cancelTask) throws IOException
      Open an existing file (read only), with option of cancelling, setting the RandomAccessFile buffer size for efficiency.
      Parameters:
      location - location of file.
      buffer_size - RandomAccessFile buffer size, if <= 0, use default size
      cancelTask - allow task to be cancelled; may be null.
      Returns:
      NetcdfFile object, or null if cant find IOServiceProver
      Throws:
      IOException - if error

    • open

      public static NetcdfFile open(String location, int buffer_size, CancelTask cancelTask, Object iospMessage) throws IOException
      Open an existing file (read only), with option of cancelling, setting the RandomAccessFile buffer size for efficiency, with an optional special object for the iosp.
      Parameters:
      location - location of file. This may be a
      1. local netcdf-3 filename (with a file: prefix or no prefix)
      2. remote netcdf-3 filename (with an http: prefix)
      3. local netcdf-4 filename (with a file: prefix or no prefix)
      4. local hdf-5 filename (with a file: prefix or no prefix)
      5. local iosp filename (with a file: prefix or no prefix)
      If file ends with ".Z", ".zip", ".gzip", ".gz", or ".bz2", it will uncompress/unzip and write to new file without the suffix, then use the uncompressed file. It will look for the uncompressed file before it does any of that. Generally it prefers to place the uncompressed file in the same directory as the original file. If it does not have write permission on that directory, it will use the directory defined by ucar.nc2.util.DiskCache class.
      buffer_size - RandomAccessFile buffer size, if <= 0, use default size
      cancelTask - allow task to be cancelled; may be null.
      iospMessage - special iosp tweaking (sent before open is called), may be null
      Returns:
      NetcdfFile object, or null if can't find IOServiceProver
      Throws:
      IOException - if error

    • open

      public static NetcdfFile open(String location, String iospClassName, int bufferSize, CancelTask cancelTask, Object iospMessage) throws ClassNotFoundException, IllegalAccessException, InstantiationException, IOException
      Open an existing file (read only), specifying which IOSP is to be used.
      Parameters:
      location - location of file
      iospClassName - fully qualified class name of the IOSP class to handle this file
      bufferSize - RandomAccessFile buffer size, if <= 0, use default size
      cancelTask - allow task to be cancelled; may be null.
      iospMessage - special iosp tweaking (sent before open is called), may be null
      Returns:
      NetcdfFile object, or null if cant find IOServiceProver
      Throws:
      IOException - if read error
      ClassNotFoundException - cannot find iospClassName in the class path
      InstantiationException - if class cannot be instantiated
      IllegalAccessException - if class is not accessible

    • canOpen

      public static boolean canOpen(String location) throws IOException
      Find out if the location can be opened, but dont actually open it. In order for a location to be openable by netCDF-java, we must have 1) a proper RandomAccessFile implementation, and 2) a proper IOServiceProvider implementation.
      Parameters:
      location - location of file
      Returns:
      true if can be opened
      Throws:
      IOException - on read error

    • canonicalizeUriString

      public static String canonicalizeUriString(String location)
      Removes the "file:" or "file://" prefix from the location, if necessary. Also replaces back slashes with forward slashes.
      Parameters:
      location - a URI string.
      Returns:
      a canonical URI string.

    • getRaf

      public static RandomAccessFile getRaf(String location, int buffer_size) throws IOException
      Get the appropriate RandomAccessFile for accessing an object at the provided location
      Parameters:
      location - a URI string.
      buffer_size - size of the RandomAccessFileBuffer
      Returns:
      RandomAccessFile for the object at location
      Throws:
      IOException

    • openInMemory

      public static NetcdfFile openInMemory(String filename) throws IOException
      Read a local CDM file into memory. All reads are then done from memory.
      Parameters:
      filename - location of CDM file, must be a local file.
      Returns:
      a NetcdfFile, which is completely in memory
      Throws:
      IOException - if error reading file

    • openInMemory

      public static NetcdfFile openInMemory(URI uri) throws IOException
      Read a remote CDM file into memory. All reads are then done from memory.
      Parameters:
      uri - location of CDM file, must be accessible through url.toURL().openStream().
      Returns:
      a NetcdfFile, which is completely in memory
      Throws:
      IOException - if error reading file

    • openInMemory

      public static NetcdfFile openInMemory(String name, byte[] data) throws IOException
      Open an in-memory netcdf file.
      Parameters:
      name - name of the dataset. Typically use the filename or URI.
      data - in-memory netcdf file
      Returns:
      memory-resident NetcdfFile
      Throws:
      IOException - if error

    • openInMemory

      public static NetcdfFile openInMemory(String name, byte[] data, String iospClassName) throws IOException, ClassNotFoundException, IllegalAccessException, InstantiationException
      Open an in-memory netcdf file, with a specific iosp.
      Parameters:
      name - name of the dataset. Typically use the filename or URI.
      data - in-memory netcdf file
      iospClassName - fully qualified class name of the IOSP class to handle this file
      Returns:
      NetcdfFile object, or null if cant find IOServiceProver
      Throws:
      IOException - if read error
      ClassNotFoundException - cannat find iospClassName in the class path
      InstantiationException - if class cannot be instantiated
      IllegalAccessException - if class is not accessible

    • open

      public static NetcdfFile open(RandomAccessFile raf, String location, CancelTask cancelTask, Object iospMessage) throws IOException
      Open a RandomAccessFile as a NetcdfFile, if possible.
      Parameters:
      raf - The open raf, is not cloised by this method.
      location - human readable locatoin of this dataset.
      cancelTask - used to monitor user cancellation; may be null.
      iospMessage - send this message to iosp; may be null.
      Returns:
      NetcdfFile or throw an Exception.
      Throws:
      IOException - if cannot open as a CDM NetCDF.

    • build

      public static NetcdfFile build(IOServiceProvider spi, RandomAccessFile raf, String location, CancelTask cancelTask) throws IOException
      Throws:
      IOException

    • makeValidCdmObjectName

      public static String makeValidCdmObjectName(String shortName)
      Create a valid CDM object name. Control chars (< 0x20) are not allowed. Trailing and leading blanks are not allowed and are stripped off. A space is converted into an underscore "_". A forward slash "/" is converted into an underscore "_".
      Parameters:
      shortName - from this name
      Returns:
      valid CDM object name

    • makeValidCDLName

      public static String makeValidCDLName(String vname)
      Escape special characters in a netcdf short name when it is intended for use in CDL.
      Parameters:
      vname - the name
      Returns:
      escaped version of it

    • makeValidPathName

      public static String makeValidPathName(String vname)
      Escape special characters in a netcdf short name when it is intended for use in a fullname
      Parameters:
      vname - the name
      Returns:
      escaped version of it

    • makeValidSectionSpecName

      public static String makeValidSectionSpecName(String vname)
      Escape special characters in a netcdf short name when it is intended for use in a sectionSpec
      Parameters:
      vname - the name
      Returns:
      escaped version of it

    • makeFullName

      public static String makeFullName(Group g)
      Create a Groups's full name with appropriate backslash escaping.

    • makeFullName

      public static String makeFullName(Variable v)
      Create a Variable's full name with appropriate backslash escaping. Warning: do not use for a section spec.
      Parameters:
      v - the Variable
      Returns:
      full name

    • makeFullNameSectionSpec

      public static String makeFullNameSectionSpec(Variable v)
      Create a Variable's full name with appropriate backslash escaping for use in a section spec.
      Parameters:
      v - the cdm node
      Returns:
      full name