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 
    Type of data allowed in header records.
  • Field Summary

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

    Fields inherited from class org.apache.sis.internal.referencing.provider.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
    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>
    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 org.apache.sis.internal.referencing.provider.DatumShiftGridLoader

    canNotLoad, ensureBufferContains, log, skip, startLoading

    Methods inherited from class java.lang.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:
    • 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:
    • 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.
    • 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.