org.geotools.data.vpf.file
Class VPFFile

java.lang.Object
  extended byorg.geotools.data.vpf.file.VPFFile
All Implemented Interfaces:
DataTypesDefinition, FeatureType, FileConstants

public class VPFFile
extends java.lang.Object
implements FeatureType, FileConstants, DataTypesDefinition

This class encapsulates VPF files. By implementing the FeatureType interface, it serves as a factory for VPFColumns. Instances of this class should be created by VPFFileFactory.

Author:
Jeff Yutzler

Field Summary
 
Fields inherited from interface org.geotools.data.vpf.ifc.FileConstants
AREA_BOUMDING_RECTANGLE_TABLE, AREA_FEATURE_TABLE, AREA_JOIN_TABLE, AREA_THEMATIC_INDEX, CHARACTER_VALUE_DESCRIPTION_TABLE, COLUMN_MANDATORY, COLUMN_MANDATORY_AT_LEVEL_0, COLUMN_MANDATORY_AT_LEVEL_1, COLUMN_MANDATORY_AT_LEVEL_2, COLUMN_MANDATORY_AT_LEVEL_3, COLUMN_MANDATORY_IF_TILES, COLUMN_OPTIONAL, COLUMN_OPTIONAL_FP, COMPLEX_BOUNDING_RECTANGLE_TABLE, COMPLEX_FEATURE_TABLE, COMPLEX_JOIN_TABLE, COMPLEX_THEMATIC_INDEX, CONNECTED_NODE_PRIMITIVE, CONNECTED_NODE_SPATIAL_INDEX, COVERAGE_ATTRIBUTE_TABLE, DATA_QUALITY_COVERAGE, DATA_QUALITY_TABLE, DATABASE_HEADER_TABLE, DIAGNOSITC_POINT_TABLE, DIR_DQ, DIR_GAZETTE, DIR_LIBREF, DIR_TILEREF, EDGE_BOUNDING_RECTANGLE, EDGE_PRIMITIVE, EDGE_SPATIAL_INDEX, ENTITY_NODE_PRIMITIVE, ENTITY_NODE_SPATIAL_INDEX, EXT_ABR, EXT_AFT, EXT_AJT, EXT_ATI, EXT_CBR, EXT_CFT, EXT_CJT, EXT_CTI, EXT_DOC, EXT_DPT, EXT_FIT, EXT_FTI, EXT_JTI, EXT_LBR, EXT_LFT, EXT_LJT, EXT_LTI, EXT_PBR, EXT_PFT, EXT_PJT, EXT_PTI, EXT_RAT, EXT_RPT, EXT_TFT, EXT_TTI, FACE_BOUNDING_RECTANGLE, FACE_PRIMITIVE, FACE_SPATIAL_INDEX, FEATURE_CLASS_ATTRIBUTE_TABLE, FEATURE_CLASS_SCHEMA_TABLE, FEATURE_INDEX_TABLE, FEATURE_THEMATIC_INDEX, GEOGRAPHIC_REFERENCE_TABLE, INTEGER_VALUE_DESCRIPTION_TABLE, JOIN_THEMATIC_INDEX, KEY_NON_UNIQUE, KEY_PRIMARY, KEY_UNIQUE, LIBRARY_ATTTIBUTE_TABLE, LIBRARY_HEADER_TABLE, LIBRARY_REFERENCE_COVERAGE, LINE_BOUNDING_RECTANGLE_TABLE, LINE_FEATURE_TABLE, LINE_JOIN_TABLE, LINE_THEMATIC_INDEX, NAMES_REFERENCE_COVERAGE, NARRATIVE_TABLE, POINT_BOUNDING_RECTANGLE_TABLE, POINT_FEATURE_TABLE, POINT_JOIN_TABLE, POINT_THEMATIC_INDEX, REGISTRATION_POINT_TABLE, RELATED_ATTRIBUTE_TABLE, RING_TABLE, TABLE_CAT, TABLE_CHAR, TABLE_CND, TABLE_CSI, TABLE_DHT, TABLE_DQT, TABLE_EBR, TABLE_EDG, TABLE_END, TABLE_ESI, TABLE_FAC, TABLE_FBR, TABLE_FCA, TABLE_FCS, TABLE_FSI, TABLE_GRT, TABLE_INT, TABLE_LAT, TABLE_LHT, TABLE_NSI, TABLE_RNG, TABLE_TSI, TABLE_TXT, TEXT_FEATURE_TABLE, TEXT_PRIMITIVE, TEXT_SPATIAL_INDEX, TEXT_THEMATIC_TABLE, TILE_REFERENCE_COVERAGE, VPF_ELEMENT_SEPARATOR, VPF_FIELD_SEPARATOR, VPF_RECORD_SEPARATOR
 
Fields inherited from interface org.geotools.data.vpf.ifc.DataTypesDefinition
BIG_ENDIAN_ORDER, CHAR_NULL_VALUE, DATA_2_COORD_F, DATA_2_COORD_F_LEN, DATA_2_COORD_R, DATA_2_COORD_R_LEN, DATA_3_COORD_F, DATA_3_COORD_F_LEN, DATA_3_COORD_R, DATA_3_COORD_R_LEN, DATA_DATE_TIME, DATA_DATE_TIME_LEN, DATA_LEVEL1_TEXT, DATA_LEVEL2_TEXT, DATA_LEVEL3_TEXT, DATA_LONG_FLOAT, DATA_LONG_FLOAT_LEN, DATA_LONG_INTEGER, DATA_LONG_INTEGER_LEN, DATA_NULL_FIELD, DATA_NULL_FIELD_LEN, DATA_SHORT_FLOAT, DATA_SHORT_FLOAT_LEN, DATA_SHORT_INTEGER, DATA_SHORT_INTEGER_LEN, DATA_TEXT, DATA_TRIPLET_ID, DATA_TRIPLET_ID_LEN, LEAST_SIGNIF_FIRST, LITTLE_ENDIAN_ORDER, MOST_SIGNIF_FIRST, STRING_NULL_VALUE, STRING_NULL_VALUES
 
Constructor Summary
VPFFile(java.lang.String cPathName)
          Constructor.
 
Method Summary
 void close()
          Close the input stream pointed to by the object
 Feature create(java.lang.Object[] attributes)
          Create a new feature from the provided attributes It is unclear why one would want to use this method.
 Feature create(java.lang.Object[] attributes, java.lang.String featureID)
          Scheduled for removal in Geotools 2.2, please use FeatureFactory.
 Feature duplicate(Feature feature)
          Create a duplicate of the provided feature, must delegate to an appropriate FeatureFactory create method.
 int find(AttributeType type)
          Find the position of a given AttributeType.
 int find(java.lang.String attName)
          Find the position of an AttributeType which matches the given String.
 FeatureType[] getAncestors()
          Obtain an array of this FeatureType's direct ancestors.
 int getAttributeCount()
          The number of attribues defined by this schema.
 AttributeType getAttributeType(int position)
          Gets the schema attributeType at the specified index.
 AttributeType getAttributeType(java.lang.String xPath)
          Gets the attributeType at this xPath, if the specified attributeType does not exist then null is returned.
 AttributeType[] getAttributeTypes()
          AttributeTypes for this FeatureType, all attributes defined by this FeatureType and its super types define schema for feature instances.
 char getByteOrder()
          Gets the value of byteOrder variable.
 GeometryAttributeType getDefaultGeometry()
          Gets the default geometry AttributeType.
 java.lang.String getDescription()
          Gets the value of the description of table content.
 java.lang.String getDirectoryName()
          Returns the directory name for this file by chopping off the file name and the separator.
 java.lang.String getFileName()
          Returns the file name (without path) for the file
 java.net.URI getNamespace()
          Gets the global schema namespace.
 java.lang.String getNarrativeTable()
          Gets the value of narrativeTable variable file name.
 java.lang.String getPathName()
          Gets the full path name for this file
protected  int getRecordSize()
          Method getRecordSize is used to return size in bytes of records stored in this table.
 Feature getRowFromId(java.lang.String idName, int id)
          Returns a row with a matching value for the provided column
 java.lang.String getTypeName()
          Gets the type name for this schema.
 boolean hasAttributeType(java.lang.String xPath)
          This is only used twice in the whole geotools code base, and one of those is for a test, so we're removing it from the interface.
 boolean hasNext()
          Determines if the stream contains storage for another object Who knows how well this will work on variable length objects
 boolean isAbstract()
          Is this FeatureType an abstract type?
 boolean isDescendedFrom(FeatureType type)
          A convenience method for calling
FeatureType f1; FeatureType f2; f1.isDescendedFrom(f2.getNamespace(), f2.getName()); Question: this method duplicates the information provided by getAncestors().
 boolean isDescendedFrom(java.net.URI nsURI, java.lang.String typeName)
          Test to determine whether this FeatureType is descended from the given FeatureType.
 java.util.AbstractList readAllRows()
          Generates a list containing all of the features in the file
protected  char readChar()
          Reads a single byte as a character value
protected  double readDouble()
          Retrieves a double from the file
 Feature readFeature()
          Retrieves a feature from the file
protected  java.lang.Object readFixedSizeData(char dataType, int instancesCount)
          Retrieves a fixed amount of data from the file
protected  float readFloat()
          Retrieves a floating point number from the file.
protected  java.lang.Object readGeometry(int instancesCount, int dimensionality, boolean readDoubles)
          Constructs an object which is an instance of Geometry by reading values from the file.
protected  void readHeader()
          Retrieves a number of attributes from the file header
protected  int readInteger()
          Retrieves an integer value from the file
protected  byte[] readNumber(int cnt)
          Reads some byte data from the file
protected  short readShort()
          Retrieves a short value from the file
protected  java.lang.String readString(java.lang.String terminators)
          Reads a string value from the file
protected  TripletId readTripletId()
          Retrieves a triplet object from the file
protected  java.lang.Object readVariableSizeData(char dataType)
          Retrieves variable sized data from the file by first reading an integer which indicates how many instances of the data type to retrieve
 void reset()
          Resets the file stream by setting its pointer to the first position after the header.
protected  void setPosition(long pos)
          Sets the position in the stream
 java.lang.String toString()
           
protected  void unread(long bytes)
          Back up a specified number of bytes in the file stream
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.geotools.feature.FeatureType
equals, hashCode
 

Constructor Detail

VPFFile

public VPFFile(java.lang.String cPathName)
        throws java.io.IOException,
               SchemaException
Constructor.

Parameters:
cPathName - The path to this file
Throws:
java.io.IOException - if the path or the file are invalid
SchemaException - if the contained feature type can not be constructed
Method Detail

create

public Feature create(java.lang.Object[] attributes)
               throws IllegalAttributeException
Create a new feature from the provided attributes It is unclear why one would want to use this method.

Specified by:
create in interface FeatureType
Parameters:
attributes - the attributes to used
Returns:
the created feature
Throws:
IllegalAttributeException - if any of the attributes is invalid

create

public Feature create(java.lang.Object[] attributes,
                      java.lang.String featureID)
               throws IllegalAttributeException
Description copied from interface: FeatureType
Scheduled for removal in Geotools 2.2, please use FeatureFactory.

Creates a new feature, with the proper featureID.

Specified by:
create in interface FeatureType
Parameters:
attributes - the array of attribute values.
featureID - the feature ID.
Returns:
the created feature.
Throws:
IllegalAttributeException - if the FeatureType does not validate the attributes.

duplicate

public Feature duplicate(Feature feature)
                  throws IllegalAttributeException
Description copied from interface: FeatureType
Create a duplicate of the provided feature, must delegate to an appropriate FeatureFactory create method.

The implementation is assumed to make use of AttributeType duplicate as required for a deep copy.

//@deprecated This method will be removed in 2.2, please use FeatureFactory obtained from FactoryFinder

Specified by:
duplicate in interface FeatureType
Parameters:
feature -
Returns:
a deep copy of feature
Throws:
IllegalAttributeException

find

public int find(AttributeType type)
Description copied from interface: FeatureType
Find the position of a given AttributeType.

Match is based on attribute type name, the resulting index may be used with getAttributeType( index ).

Specified by:
find in interface FeatureType
Parameters:
type - The type to search for.
Returns:
-1 if not found, a zero-based index if found.

getAncestors

public FeatureType[] getAncestors()
Description copied from interface: FeatureType
Obtain an array of this FeatureType's direct ancestors. Implementors should return a non-null array (may be of length 0).

GetAncestors() indicates *just* the direct parents of this FeatureType. It capures the inheirtance relationship from the OGC overview document.

Example Code:


 public FeatureType getAncestors()}
     return new FeatureType[]{ getSuper(), };
 }
 

Specified by:
getAncestors in interface FeatureType
Returns:
An array of ancestors.

getAttributeCount

public int getAttributeCount()
Description copied from interface: FeatureType
The number of attribues defined by this schema.

This method to allows access to the complete schema as defined by this FeatureType and its ancestors.


getAttributeType

public AttributeType getAttributeType(int position)
Description copied from interface: FeatureType
Gets the schema attributeType at the specified index.

The index is specified with respect to the entire Schema (as defined by this FeatureType and it's ancestors).

Specified by:
getAttributeType in interface FeatureType
Returns:
The attribute type at the specified position.

getAttributeType

public AttributeType getAttributeType(java.lang.String xPath)
Description copied from interface: FeatureType
Gets the attributeType at this xPath, if the specified attributeType does not exist then null is returned.

Question: it is unclear how this interacts with the complete schema defined by this FeatureType and its ancestors (in which a given xpath may refer to several AttributeTypes as restrictions are applied.

Perhaps this method should be restricted to a FlatFeatureType? Or should have the option of returning an array of matching AttributeType in order of inheiritence?

Specified by:
getAttributeType in interface FeatureType
Parameters:
xPath - XPath pointer to attribute type.
Returns:
AttributeType, or null if unavaialble

getAttributeTypes

public AttributeType[] getAttributeTypes()
Description copied from interface: FeatureType
AttributeTypes for this FeatureType, all attributes defined by this FeatureType and its super types define schema for feature instances.

The provided array of AttributeTypes should be considered as adding to (or overriding) the the AttribtueTypes defined by this FeatureTypes ancestors.

Note Well: Client code should not consider the index provided by the find( attName ) method as a valid index into the returned array.

Specified by:
getAttributeTypes in interface FeatureType
Returns:
Array of AttributeType describing this schema, array may be length 0, but should not be null

getByteOrder

public char getByteOrder()
Gets the value of byteOrder variable. Byte order in which table is written:

Returns:
the value of byteOrder

getDefaultGeometry

public GeometryAttributeType getDefaultGeometry()
Description copied from interface: FeatureType
Gets the default geometry AttributeType.

If the FeatureType has more one geometry it is up to the implementor to determine which geometry is the default. If working with multiple geometries it is best to get the attributeTypes and iterate through them, checking for instances of GeometryAttribtueType.

This should just be used a convenience method when it is known that the features do not have multiple geometries.

Specified by:
getDefaultGeometry in interface FeatureType
Returns:
The attribute type of the default geometry, which will contain the position.

getDescription

public java.lang.String getDescription()
Gets the value of the description of table content. This is nice to have, but I don't know how to make use of it.

Returns:
the value of description

getDirectoryName

public java.lang.String getDirectoryName()
Returns the directory name for this file by chopping off the file name and the separator.

Returns:
the directory name for this file

getFileName

public java.lang.String getFileName()
Returns the file name (without path) for the file

Returns:
the file name for this file

getNamespace

public java.net.URI getNamespace()
Description copied from interface: FeatureType
Gets the global schema namespace.

This is often used to record the schema prefix (not the URI) required when writing out this Feature using GML. The supporting application will need to be able to start the GMLWriter off with the correct URI information so everything makes sense.

The Registry interface provided by the data module provides an example of how to store associate FeatureType and namespace information. Please note that you may not have duplicate typeNames in the same Namespace.

Specified by:
getNamespace in interface FeatureType
Returns:
Namespace of schema

getNarrativeTable

public java.lang.String getNarrativeTable()
Gets the value of narrativeTable variable file name.

Returns:
the value of narrativeTable

getPathName

public java.lang.String getPathName()
Gets the full path name for this file

Returns:
the path name for this file

getRecordSize

protected int getRecordSize()
Method getRecordSize is used to return size in bytes of records stored in this table. If table keeps variable length records -1 should be returned.

Returns:
an int value

getRowFromId

public Feature getRowFromId(java.lang.String idName,
                            int id)
                     throws IllegalAttributeException
Returns a row with a matching value for the provided column

Parameters:
idName - The name of the column to look for, such as "id"
id - An identifier for the requested row
Returns:
The first row which matches the ID
Throws:
IllegalAttributeException - The feature can not be created due to illegal attributes in the source file

getTypeName

public java.lang.String getTypeName()
Description copied from interface: FeatureType
Gets the type name for this schema.

In GML this must be the element name of the Feature.

Specified by:
getTypeName in interface FeatureType
Returns:
The name of this feature type.

hasAttributeType

public boolean hasAttributeType(java.lang.String xPath)
Description copied from interface: FeatureType
This is only used twice in the whole geotools code base, and one of those is for a test, so we're removing it from the interface. If getAttributeType does not have the AttributeType it will just return null. Gets the number of occurrences of this attribute.

Question: the comment says we are removing this, but it is not depricated? And how the heck can the number of occurances out of a boolean.

Specified by:
hasAttributeType in interface FeatureType
Parameters:
xPath - XPath pointer to attribute type.
Returns:
Number of occurrences.

hasNext

public boolean hasNext()
Determines if the stream contains storage for another object Who knows how well this will work on variable length objects

Returns:

isAbstract

public boolean isAbstract()
Description copied from interface: FeatureType
Is this FeatureType an abstract type?

When true is returned instances of this Feature cannot be created, instead a child FeatureType must use this FeatureType as its ancestor.

Specified by:
isAbstract in interface FeatureType
Returns:
true if abstract, false otherwise.

isDescendedFrom

public boolean isDescendedFrom(FeatureType type)
Description copied from interface: FeatureType
A convenience method for calling
 FeatureType f1;
 FeatureType f2;
 f1.isDescendedFrom(f2.getNamespace(), f2.getName());
 

Question: this method duplicates the information provided by getAncestors().

Specified by:
isDescendedFrom in interface FeatureType
Parameters:
type - The type to compare to.
Returns:
true if descendant, false otherwise.

isDescendedFrom

public boolean isDescendedFrom(java.net.URI nsURI,
                               java.lang.String typeName)
Description copied from interface: FeatureType
Test to determine whether this FeatureType is descended from the given FeatureType. Think of this relationship likes the "extends" relationship in java.

Specified by:
isDescendedFrom in interface FeatureType
Parameters:
nsURI - The namespace URI to use.
typeName - The typeName.
Returns:
true if descendant, false otherwise.

readAllRows

public java.util.AbstractList readAllRows()
                                   throws java.io.IOException
Generates a list containing all of the features in the file

Returns:
a List value containing Feature objects
Throws:
java.io.IOException - if an error occurs

readChar

protected char readChar()
                 throws java.io.IOException
Reads a single byte as a character value

Returns:
a char value
Throws:
java.io.IOException - if an error occurs

readGeometry

protected java.lang.Object readGeometry(int instancesCount,
                                        int dimensionality,
                                        boolean readDoubles)
                                 throws java.io.IOException
Constructs an object which is an instance of Geometry by reading values from the file.

Parameters:
instancesCount - number of coordinates to read
dimensionality - either 2 or 3
readDoubles - true: read a double value; false: read a float value
Returns:
the constructed object
Throws:
java.io.IOException - on any file IO errors

readDouble

protected double readDouble()
                     throws java.io.IOException
Retrieves a double from the file

Returns:
a double value
Throws:
java.io.IOException - if an error occurs

readFeature

public Feature readFeature()
                    throws java.io.IOException,
                           IllegalAttributeException
Retrieves a feature from the file

Returns:
the retieved feature
Throws:
java.io.IOException - on any file IO errors
IllegalAttributeException - if any of the attributes retrieved are illegal

readFixedSizeData

protected java.lang.Object readFixedSizeData(char dataType,
                                             int instancesCount)
                                      throws java.io.IOException
Retrieves a fixed amount of data from the file

Parameters:
dataType - a char value indicating the data type
instancesCount - an int value indicating the number of instances to retrieve.
Returns:
an Object value
Throws:
java.io.IOException - if an error occurs

readFloat

protected float readFloat()
                   throws java.io.IOException
Retrieves a floating point number from the file.

Returns:
a float value
Throws:
java.io.IOException - if an error occurs

readHeader

protected void readHeader()
                   throws VPFHeaderFormatException,
                          java.io.IOException
Retrieves a number of attributes from the file header

Throws:
VPFHeaderFormatException - if an error occurs
java.io.IOException - if an error occurs

readInteger

protected int readInteger()
                   throws java.io.IOException
Retrieves an integer value from the file

Returns:
an int value
Throws:
java.io.IOException - if an error occurs

readNumber

protected byte[] readNumber(int cnt)
                     throws java.io.IOException
Reads some byte data from the file

Parameters:
cnt - an int value indicating the number of bytes to retrieve
Returns:
a byte[] value
Throws:
java.io.IOException - if an error occurs

readShort

protected short readShort()
                   throws java.io.IOException
Retrieves a short value from the file

Returns:
a short value
Throws:
java.io.IOException - if an error occurs

readString

protected java.lang.String readString(java.lang.String terminators)
                               throws java.io.IOException
Reads a string value from the file

Parameters:
terminators - a String value indicating the terminators to look for
Returns:
a String value
Throws:
java.io.IOException - if an error occurs

readTripletId

protected TripletId readTripletId()
                           throws java.io.IOException
Retrieves a triplet object from the file

Returns:
a TripletId value
Throws:
java.io.IOException - on any IO errors

readVariableSizeData

protected java.lang.Object readVariableSizeData(char dataType)
                                         throws java.io.IOException
Retrieves variable sized data from the file by first reading an integer which indicates how many instances of the data type to retrieve

Parameters:
dataType - a char value indicating the data type
Returns:
an Object value
Throws:
java.io.IOException - if an error occurs

reset

public void reset()
Resets the file stream by setting its pointer to the first position after the header.


close

public void close()
           throws java.io.IOException
Close the input stream pointed to by the object

Throws:
java.io.IOException - in some unlikely situation

setPosition

protected void setPosition(long pos)
                    throws java.io.IOException
Sets the position in the stream

Parameters:
pos - A 1-indexed position
Throws:
java.io.IOException - on any IO failures

toString

public java.lang.String toString()

unread

protected void unread(long bytes)
               throws java.io.IOException
Back up a specified number of bytes in the file stream

Parameters:
bytes - a long value
Throws:
java.io.IOException - if an error occurs

find

public int find(java.lang.String attName)
Description copied from interface: FeatureType
Find the position of an AttributeType which matches the given String.

This index may be used with getAttributeType( index ), the search space is the entire schema defined by this FeatureType and its ancestors.

Specified by:
find in interface FeatureType
Parameters:
attName - the name to look for
Returns:
-1 if not found, zero-based index otherwise


Copyright © GeoTools. All Rights Reserved.