Class NTv2.Loader

java.lang.Object

org.apache.sis.internal.referencing.provider.DatumShiftGridLoader

org.apache.sis.internal.referencing.provider.NTv2.Loader

Enclosing class:

NTv2

private static final class NTv2.Loader
extends DatumShiftGridLoader

Loaders of NTv2 data. Instances of this class exist only at loading time. More information on that file format can be found with ESRI NTv2 routines.

A NTv2 file contains an arbitrary number of sub-files, where each sub-file is a grid. There is at least one grid (the parent), and potentially many sub-grids of higher density. At the beginning is an overview header block of information that is common to all sub-files. Then there is other headers specific to each sub-files.

While this loader is primarily targeted at loading NTv2 files, it can also opportunistically read NTv1 files. The two file formats differ by some header records having different names (but same meanings), the possibility to have sub-grids and the presence of accuracy information.

Since:

0.7

Version:

1.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static enum	NTv2.Loader.DataType	Type of data allowed in header records.

Field Summary

Fields

Modifier and Type	Field	Description
private String	created	Dates at which the grid has been created or updated, or null if unknown.
private boolean	hasUnrecognized	true if the header map contains at least one key associated to a null value.
private final Map<String,Object>	header	The headers content, as the union of the overview header and the header in process of being read.
private final boolean	isV2	true if we are reading a NTv2 file, or false if we are reading a NTv1 file.
private static final int	KEY_LENGTH	Maximum number of characters for a key in a header record.
private final int	numGrids	Number of grids expected in the file.
private final String[]	overviewKeys	Keys of header for entries that were declared in the overview header.
private static final int	RECORD_LENGTH	Size of a record.
private static final Map<String, NTv2.Loader.DataType>	TYPES	Some known keywords that may appear in NTv2 header records, associated the the expected type of values.
private String	updated	Dates at which the grid has been created or updated, or null if unknown.

Fields inherited from class DatumShiftGridLoader

buffer, DEGREES_TO_SECONDS, file, SECOND_PRECISION

Constructor Summary

Constructors

Constructor	Description
Loader(ReadableByteChannel channel, Path file, int version)	Creates a new reader for the given channel.

Method Summary

Modifier and Type	Method	Description
private Object	get(String key, boolean mandatory)	Gets the value for the given key.
private Object	get(String key, String alt, String kv1)	Returns the value for the given key, or thrown an exception if the value is not found.
private static boolean	isLittleEndian(int n)	Returns true if the given value seems to be stored in little endian order.
(package private) final DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle>	readAllGrids()	Reads all grids and returns the root grid.
private void	readGrid(Map<String, DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle>> addTo, Map<String, List<DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle>>> children)	Reads the next grid, starting at the current position.
private void	readHeader(int numRecords, String numkey)	Reads all records found in the header, starting from the current buffer position.
private String	readString(int length)	Reads a string at the current buffer position, assuming ASCII encoding.
(package private) void	report(Class<? extends AbstractProvider> caller)	If we had any warnings during the loading process, report them now.

Methods inherited from class DatumShiftGridLoader

canNotLoad, ensureBufferContains, log, skip, startLoading

Methods inherited from class Object

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

Field Details

RECORD_LENGTH

private static final int RECORD_LENGTH

Size of a record. This value applies to both the header records and the data records. In the case of header records, this is the size of the key plus the size of the value.

See Also:

• Constant Field Values

KEY_LENGTH

private static final int KEY_LENGTH

Maximum number of characters for a key in a header record. Expected keys are listed in the TYPES map.

See Also:

• Constant Field Values

TYPES

private static final Map<String, NTv2.Loader.DataType> TYPES

Some known keywords that may appear in NTv2 header records, associated the the expected type of values. The type is not encoded in a NTv2 file; it has to be hard-coded in this table. The first 11 entries in this map (ignoring entries marked by "NTv1") are typically found in overview header, and the remaining entries in the sub-grid headers.

header

private final Map<String,Object> header

The headers content, as the union of the overview header and the header in process of being read. Keys are strings like "VERSION", "SYSTEM_F", "LONG_INC", etc.. Values are String, Integer or Double. If some keys are unrecognized, they will be put in this map with the null value and the hasUnrecognized flag will be set to true.

overviewKeys

private final String[] overviewKeys

Keys of header for entries that were declared in the overview header. This is used after readGrid(Map, Map) execution for discarding all entries specific to sub-grids, for avoiding to mix entries from two sub-grids.

isV2

private final boolean isV2

true if we are reading a NTv2 file, or false if we are reading a NTv1 file.

hasUnrecognized

private boolean hasUnrecognized

true if the header map contains at least one key associated to a null value.

numGrids

private final int numGrids

Number of grids expected in the file.

created

private String created

Dates at which the grid has been created or updated, or null if unknown. Used for information purpose only.

updated

private String updated

Dates at which the grid has been created or updated, or null if unknown. Used for information purpose only.

Constructor Details

Loader

Loader(ReadableByteChannel channel,
 Path file,
 int version)
throws IOException,
org.opengis.util.FactoryException

Creates a new reader for the given channel. This constructor parses the header immediately, but does not read any grid. A hint about expected NTv2 version is given, but this constructor may override that hint with information found in the file.

Parameters:

channel - where to read data from.

file - path to the longitude and latitude difference file. Used for parameter declaration and error reporting.

version - the expected version (1 or 2).

Throws:

org.opengis.util.FactoryException - if a data record cannot be parsed.

IOException

Method Details

isLittleEndian

private static boolean isLittleEndian(int n)

Returns true if the given value seems to be stored in little endian order. The strategy is to read an integer that we expect to be small (the HEADER or NUM_OREC value which should be 12 or 11) and to check which order gives the smallest value.

readString

private String readString(int length)

Reads a string at the current buffer position, assuming ASCII encoding. After this method call, the buffer position will be the first byte after the string. The buffer content is unmodified.

Parameters:

length - number of bytes to read.

readHeader

private void readHeader(int numRecords,
 String numkey)
                 throws IOException,
org.opengis.util.FactoryException

Reads all records found in the header, starting from the current buffer position. The header may be the overview header (in which case we expect a number of records given by HEADER or NUM_OREC value) or a sub-grid header (in which case we expect NUM_SREC records).

The numRecords given in argument is a default value. It will be updated as soon as the numKey record is found.

Parameters:

numRecords - default number of expected records (usually 11).

numkey - key of the record giving the number of records: "NUM_OREC" or "NUM_SREC".

Throws:

IOException

org.opengis.util.FactoryException

readAllGrids

final DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle> readAllGrids()
                                                                                           throws IOException,
org.opengis.util.FactoryException,
org.opengis.referencing.operation.NoninvertibleTransformException

Reads all grids and returns the root grid. After reading all grids, this method rearrange them in a child-parent relationship. The result is a tree with a single root containing sub-grids (if any) as children.

Throws:

IOException

org.opengis.util.FactoryException

org.opengis.referencing.operation.NoninvertibleTransformException

readGrid

private void readGrid(Map<String, DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle>> addTo,
 Map<String, List<DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle>>> children)
               throws IOException,
org.opengis.util.FactoryException,
org.opengis.referencing.operation.NoninvertibleTransformException

Reads the next grid, starting at the current position. A NTv2 file can have many grids. This can be used for grids having different resolutions depending on the geographic area. The first grid can cover a large area with a coarse resolution, and next grids cover smaller areas overlapping the first grid but with finer resolution.

NTv2 grids contain also information about shifts accuracy. This is not yet handled by SIS, except for determining an approximate grid cell resolution.

Parameters:

addTo - the map where to add the grid with the grid name as the key.

children - the map where to add children with the parent name as the key.

Throws:

IOException

org.opengis.util.FactoryException

org.opengis.referencing.operation.NoninvertibleTransformException

get

private Object get(String key,
 boolean mandatory)
            throws org.opengis.util.FactoryException

Gets the value for the given key. If the value is absent, then this method throws an exception if mandatory is true or returns null otherwise.

Parameters:

key - key of the value to search.

mandatory - whether to throw an exception if the value is not found.

Returns:

value associated to the given key, or null if none and not mandatory.

Throws:

org.opengis.util.FactoryException

get

private Object get(String key,
 String alt,
 String kv1)
            throws org.opengis.util.FactoryException

Returns the value for the given key, or thrown an exception if the value is not found. Before to fail if the key is not found, this method searches for a value associated to an alternative name. That alternative should be the name used in legacy NTv1.

Parameters:

key - key of the value to search.

alt - alternative key name, or name used in NTv1, or null if none.

kv1 - name used in NTv1, or null if none.

Returns:

value associated to the given key (never null).

Throws:

org.opengis.util.FactoryException

report

void report(Class<? extends AbstractProvider> caller)

If we had any warnings during the loading process, report them now.

Parameters:

caller - the provider which created this loader.