ucar.nc2

Class NetcdfFiles

java.lang.Object

ucar.nc2.NetcdfFiles

public class NetcdfFiles
extends java.lang.Object

Static helper methods for NetcdfFile objects. These use builders and new versions of Iosp's when available.

Since:

10/3/2019.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	reservedFullName

Constructor Summary

Constructors

Constructor and Description
NetcdfFiles()

Method Summary

Modifier and Type	Method and Description
static NetcdfFile	build(IOServiceProvider spi, RandomAccessFile raf, java.lang.String location, CancelTask cancelTask)
static java.lang.String	canonicalizeUriString(java.lang.String location) Removes the "file:" or "file://" prefix from the location, if necessary.
static boolean	canOpen(java.lang.String location) Find out if the location can be opened, but dont actually open it.
static RandomAccessFile	getRaf(java.lang.String location, int buffer_size) Get the appropriate RandomAccessFile for accessing an object at the provided location
static java.lang.String	makeFullName(Group g) Create a Groups's full name with appropriate backslash escaping.
static java.lang.String	makeFullName(Variable v) Create a Variable's full name with appropriate backslash escaping.
static java.lang.String	makeFullNameSectionSpec(Variable v) Create a Variable's full name with appropriate backslash escaping for use in a section spec.
static java.lang.String	makeValidCDLName(java.lang.String vname) Escape special characters in a netcdf short name when it is intended for use in CDL.
static java.lang.String	makeValidCdmObjectName(java.lang.String shortName) Create a valid CDM object name.
static java.lang.String	makeValidPathName(java.lang.String vname) Escape special characters in a netcdf short name when it is intended for use in a fullname
static java.lang.String	makeValidSectionSpecName(java.lang.String vname) Escape special characters in a netcdf short name when it is intended for use in a sectionSpec
static NetcdfFile	open(RandomAccessFile raf, java.lang.String location, CancelTask cancelTask, java.lang.Object iospMessage) Open a RandomAccessFile as a NetcdfFile, if possible.
static NetcdfFile	open(java.lang.String location) Open an existing netcdf file (read only).
static NetcdfFile	open(java.lang.String location, CancelTask cancelTask) Open an existing file (read only), with option of cancelling.
static NetcdfFile	open(java.lang.String location, int buffer_size, CancelTask cancelTask) Open an existing file (read only), with option of cancelling, setting the RandomAccessFile buffer size for efficiency.
static NetcdfFile	open(java.lang.String location, int buffer_size, CancelTask cancelTask, java.lang.Object iospMessage) 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.
static NetcdfFile	open(java.lang.String location, java.lang.String iospClassName, int bufferSize, CancelTask cancelTask, java.lang.Object iospMessage) Open an existing file (read only), specifying which IOSP is to be used.
static NetcdfFile	openInMemory(java.lang.String filename) Read a local CDM file into memory.
static NetcdfFile	openInMemory(java.lang.String name, byte[] data) Open an in-memory netcdf file.
static NetcdfFile	openInMemory(java.lang.String name, byte[] data, java.lang.String iospClassName) Open an in-memory netcdf file, with a specific iosp.
static NetcdfFile	openInMemory(java.net.URI uri) Read a remote CDM file into memory.
static void	registerIOProvider(java.lang.Class iospClass) Register an IOServiceProvider.
static void	registerIOProvider(java.lang.String className) Register an IOServiceProvider, using its class string name.
static void	registerRandomAccessFileProvider(java.lang.Class rafClass) Register a RandomAccessFile Provider.
static void	registerRandomAccessFileProvider(java.lang.String className) Register a RandomAccessFile Provider, using its class string name.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

reservedFullName

public static final java.lang.String reservedFullName

See Also:

Constant Field Values

Constructor Detail

NetcdfFiles

public NetcdfFiles()

Method Detail

build

public static NetcdfFile build(IOServiceProvider spi,
                               RandomAccessFile raf,
                               java.lang.String location,
                               CancelTask cancelTask)
                        throws java.io.IOException

Throws:

java.io.IOException

canonicalizeUriString

public static java.lang.String canonicalizeUriString(java.lang.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.

canOpen

public static boolean canOpen(java.lang.String location)
                       throws java.io.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:

java.io.IOException - on read error

getRaf

public static RandomAccessFile getRaf(java.lang.String location,
                                      int buffer_size)
                               throws java.io.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:

java.io.IOException

makeFullName

public static java.lang.String makeFullName(Group g)

Create a Groups's full name with appropriate backslash escaping.

makeFullName

public static java.lang.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 java.lang.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

makeValidCDLName

public static java.lang.String makeValidCDLName(java.lang.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

makeValidCdmObjectName

public static java.lang.String makeValidCdmObjectName(java.lang.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

makeValidPathName

public static java.lang.String makeValidPathName(java.lang.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 java.lang.String makeValidSectionSpecName(java.lang.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

open

public static NetcdfFile open(RandomAccessFile raf,
                              java.lang.String location,
                              CancelTask cancelTask,
                              java.lang.Object iospMessage)
                       throws java.io.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:

java.io.IOException - if cannot open as a CDM NetCDF.

open

public static NetcdfFile open(java.lang.String location)
                       throws java.io.IOException

Open an existing netcdf file (read only).

Parameters:

location - location of file.

Returns:

the NetcdfFile.

Throws:

java.io.IOException - if error

open

public static NetcdfFile open(java.lang.String location,
                              CancelTask cancelTask)
                       throws java.io.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:

java.io.IOException - if error

open

public static NetcdfFile open(java.lang.String location,
                              int buffer_size,
                              CancelTask cancelTask)
                       throws java.io.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:

java.io.IOException - if error

open

public static NetcdfFile open(java.lang.String location,
                              int buffer_size,
                              CancelTask cancelTask,
                              java.lang.Object iospMessage)
                       throws java.io.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:

java.io.IOException - if error

open

public static NetcdfFile open(java.lang.String location,
                              java.lang.String iospClassName,
                              int bufferSize,
                              CancelTask cancelTask,
                              java.lang.Object iospMessage)
                       throws java.lang.ClassNotFoundException,
                              java.lang.IllegalAccessException,
                              java.lang.InstantiationException,
                              java.io.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:

java.io.IOException - if read error

java.lang.ClassNotFoundException - cannot find iospClassName in the class path

java.lang.InstantiationException - if class cannot be instantiated

java.lang.IllegalAccessException - if class is not accessible

openInMemory

public static NetcdfFile openInMemory(java.lang.String filename)
                               throws java.io.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:

java.io.IOException - if error reading file

openInMemory

public static NetcdfFile openInMemory(java.lang.String name,
                                      byte[] data)
                               throws java.io.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:

java.io.IOException - if error

openInMemory

public static NetcdfFile openInMemory(java.lang.String name,
                                      byte[] data,
                                      java.lang.String iospClassName)
                               throws java.io.IOException,
                                      java.lang.ClassNotFoundException,
                                      java.lang.IllegalAccessException,
                                      java.lang.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:

java.io.IOException - if read error

java.lang.ClassNotFoundException - cannat find iospClassName in the class path

java.lang.InstantiationException - if class cannot be instantiated

java.lang.IllegalAccessException - if class is not accessible

openInMemory

public static NetcdfFile openInMemory(java.net.URI uri)
                               throws java.io.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:

java.io.IOException - if error reading file

registerIOProvider

public static void registerIOProvider(java.lang.Class iospClass)
                               throws java.lang.IllegalAccessException,
                                      java.lang.InstantiationException

Register an IOServiceProvider. A new instance will be created when one of its files is opened.

Parameters:

iospClass - Class that implements IOServiceProvider.

Throws:

java.lang.IllegalAccessException - if class is not accessible.

java.lang.InstantiationException - if class doesnt have a no-arg constructor.

java.lang.ClassCastException - if class doesnt implement IOServiceProvider interface.

registerIOProvider

public static void registerIOProvider(java.lang.String className)
                               throws java.lang.IllegalAccessException,
                                      java.lang.InstantiationException,
                                      java.lang.ClassNotFoundException

Register an IOServiceProvider, using its class string name.

Parameters:

className - Class that implements IOServiceProvider.

Throws:

java.lang.IllegalAccessException - if class is not accessible.

java.lang.InstantiationException - if class doesnt have a no-arg constructor.

java.lang.ClassNotFoundException - if class not found.

registerRandomAccessFileProvider

public static void registerRandomAccessFileProvider(java.lang.Class rafClass)
                                             throws java.lang.IllegalAccessException,
                                                    java.lang.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:

java.lang.IllegalAccessException - if class is not accessible.

java.lang.InstantiationException - if class doesnt have a no-arg constructor.

java.lang.ClassCastException - if class doesnt implement IOServiceProvider interface.

registerRandomAccessFileProvider

public static void registerRandomAccessFileProvider(java.lang.String className)
                                             throws java.lang.IllegalAccessException,
                                                    java.lang.InstantiationException,
                                                    java.lang.ClassNotFoundException

Register a RandomAccessFile Provider, using its class string name.

Parameters:

className - Class that implements RandomAccessFileProvider.

Throws:

java.lang.IllegalAccessException - if class is not accessible.

java.lang.InstantiationException - if class doesnt have a no-arg constructor.

java.lang.ClassNotFoundException - if class not found.