org.geotools.data.vpf.file
Class VPFFile

java.lang.Object
  org.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).

• length 0 - a root FeatureType
• length 1 - singe inhieratance
• length 1+ - multiple inheiratance, order is not significant

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.

Notes:
• for FeatureType with no super type this count value is the the same as getAttributeTypes().length.

  Specified by:

  getAttributeCount in interface FeatureType

  Returns:

  number of distinct attributeTypes available, taking ancestors and taking overrides into account.

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).

The index value should not be used with either:
• FeatureType.getAttributeTypes()[index] - as it defines only attributes contributed by this FeatureType
• Feature.getAttribute( index ) - as attributes order may or may not be in sequence

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:

• L - least-significant-first
• M - most-significant-first

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