- java.lang.Object
-
- org.arakhne.afc.io.dbase.DBaseFileReader
-
- All Implemented Interfaces:
AutoCloseable
,Iterable<AttributeProvider>
public class DBaseFileReader extends Object implements Iterable<AttributeProvider>, AutoCloseable
This class permits to read a dBASE file which is typically generated by a GIS.This class supports dBASE version 5. Version 7 specification is available at http://www.dbase.com/KnowledgeBase/int/db7_file_fmt.htm.
ESRi Limitations
Additionally, this writer includes the ESRi restrictions on dBASE files. Shapefile feature attributes are stored in an associated .dbf file, and so attributes suffer a number of limitations.
Attribute names can only be up to 10 characters long. Longer names will be silently truncated. This may result in non-unique column names, which will definitely cause problems later. Starting with version 1.7, the OGR Shapefile driver tries to generate unique field names. Successive duplicate field names, including those created by truncation to 10 characters, will be truncated to 8 characters and appended with a serial number from 1 to 99.
Only Integer, Real, String and Date (not DateTime, just year/month/day) field types are supported. The various list, and binary field types cannot be created.
The field width and precision are directly used to establish storage size in the .dbf file. This means that strings longer than the field width, or numbers that don't fit into the indicated field format will suffer truncation.
Integer fields without an explicit width are treated as width 11.
Real (floating point) fields without an explicit width are treated as width 24 with 15 decimal places of precision.
String fields without an assigned width are treated as 80 characters.
Also, .dbf files are required to have at least one field. If none are created by the application an "FID" field will be automatically created and populated with the record number.
The OGR shapefile driver supports rewriting existing shapes in a shapefile as well as deleting shapes. Deleted shapes are marked for deletion in the .dbf file, and then ignored by OGR. To actually remove them permanently (resulting in renumbering of FIDs) invoke the SQL 'REPACK <tablename>' via the datasource ExecuteSQL() method.
- Since:
- 14.0
- Version:
- 17.0 2020-01-04 14:41:52
- Author:
- Stéphane GALLAND, Olivier LAMOTTE
- Maven Group Id:
- org.arakhne.afc.advanced
- Maven Artifact Id:
- dbasefile
-
-
Field Summary
Fields Modifier and Type Field Description static int
OPTION_DECODE_STRING
This option forces the reader to decode the string read from dBASE files.
-
Constructor Summary
Constructors Constructor Description DBaseFileReader(File file)
Constructor.DBaseFileReader(InputStream inputStream)
Constructor.DBaseFileReader(URL url)
Constructor.DBaseFileReader(ReadableByteChannel channel)
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addOption(int option)
Add the specified option.void
close()
int
getDBFFieldCount()
Replies the count of columns.int
getDBFFieldIndex(String name)
Replies the column index of the specified column name.String
getDBFFieldName(int index)
Replies the name of the i-th field.List<DBaseFileField>
getDBFFields()
Read the field definitions.DBaseFieldType
getDBFFieldType(int index)
Replies the type of the i-th field.int
getDBFHeaderSize()
Replies the size of the header in bytes.DBaseCodePage
getDBFLanguage()
Replies the language used in the dBASE file.Date
getDBFLastUpdateDate()
Replies the date of the last update of the DBF file.int
getDBFRecordCount()
Replies the count of records.int
getDBFRecordSize()
Replies the size of a record in bytes.int
getDBFVersion()
Replies the version of the DBF file.boolean
hasOption(int option)
Replies if the specified option was set.boolean
isClosed()
Replies if the stream was closed.boolean
isColumnSelectable(DBaseFileField column)
Replies if the specified column could be replied or ignored.Iterator<AttributeProvider>
iterator()
static void
main(String[] args)
Main program to display the content of the dBASE file.List<DBaseFileField>
readDBFFields()
Read the field definitions.void
readDBFHeader()
Read the header of the DBF file.AttributeProvider
readNextAttributeProvider()
Read the next record.DBaseFileRecord
readNextDBFRecord()
Read the next record.List<DBaseFileRecord>
readRestOfDBFRecords()
Read all the records.void
removeOption(int option)
Remove the specified option.void
seek(int recordIndex)
Move the reading head at the specified record index.void
selectAllColumns()
Clear the list of column that must be replied.void
selectColumn(DBaseFileField column)
Indicates to this reader that the specified column could be replied.void
setOption(int option, boolean option_is_set)
Set or unset the specified option.void
skip(int skipAmount)
Move the reading head by the specified record count amount.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
-
-
-
Field Detail
-
OPTION_DECODE_STRING
public static final int OPTION_DECODE_STRING
This option forces the reader to decode the string read from dBASE files. The decoding is based onLocale.decodeString(byte[])
and could be time-consuming.If this option was not set, this dBASE reader will not decode the strings. It means that the strings could contains not printable characters according to the default character set (UTF or ISO).
This option was set by default.
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
DBaseFileReader
public DBaseFileReader(InputStream inputStream)
Constructor.- Parameters:
inputStream
- is the stream to read.
-
DBaseFileReader
public DBaseFileReader(File file) throws IOException
Constructor.- Parameters:
file
- is the file to read.- Throws:
IOException
- in case of error.
-
DBaseFileReader
public DBaseFileReader(URL url) throws IOException
Constructor.- Parameters:
url
- is the URL to read.- Throws:
IOException
- in case of error.
-
DBaseFileReader
public DBaseFileReader(ReadableByteChannel channel)
Constructor.- Parameters:
channel
- is the channel to read.
-
-
Method Detail
-
main
public static void main(String[] args) throws IOException
Main program to display the content of the dBASE file. This program works in a similar way than the dbview unix command.- Parameters:
args
- command line arguments.- Throws:
IOException
- in case of error.
-
hasOption
@Pure public boolean hasOption(int option)
Replies if the specified option was set.- Parameters:
option
- is the option to test- Returns:
true
if the given option was previously set, otherwisefalse
.- See Also:
OPTION_DECODE_STRING
-
addOption
public void addOption(int option)
Add the specified option.- Parameters:
option
- is the option to set.- See Also:
OPTION_DECODE_STRING
-
removeOption
public void removeOption(int option)
Remove the specified option.- Parameters:
option
- is the option to remove- See Also:
OPTION_DECODE_STRING
-
setOption
public void setOption(int option, boolean option_is_set)
Set or unset the specified option.- Parameters:
option
- is the option to set or unset.option_is_set
- istrue
to set the given option, orfalse
to unset it.- See Also:
OPTION_DECODE_STRING
-
close
public void close() throws IOException
- Specified by:
close
in interfaceAutoCloseable
- Throws:
IOException
-
isClosed
@Pure public boolean isClosed()
Replies if the stream was closed.- Returns:
true
if the input stream is closed, otherwisefalse
.
-
getDBFRecordCount
@Pure public int getDBFRecordCount() throws MustCallReadHeaderFunctionException
Replies the count of records.- Returns:
- the count of records.
- Throws:
MustCallReadHeaderFunctionException
- if the header must be read before.
-
getDBFRecordSize
@Pure public int getDBFRecordSize() throws MustCallReadHeaderFunctionException
Replies the size of a record in bytes.- Returns:
- the size of a record in bytes.
- Throws:
MustCallReadHeaderFunctionException
- if the header must be read before.
-
getDBFHeaderSize
@Pure public int getDBFHeaderSize() throws MustCallReadHeaderFunctionException
Replies the size of the header in bytes.- Returns:
- the size of the header in bytes.
- Throws:
MustCallReadHeaderFunctionException
- if the header must be read before.- Since:
- 4.0
-
getDBFFieldCount
@Pure public int getDBFFieldCount() throws MustCallReadHeaderFunctionException
Replies the count of columns.- Returns:
- the count of columns.
- Throws:
MustCallReadHeaderFunctionException
- if the header must be read before.
-
getDBFLastUpdateDate
@Pure public Date getDBFLastUpdateDate()
Replies the date of the last update of the DBF file.- Returns:
- the date or
null
of the date is unknown. - Since:
- 4.0
-
getDBFLanguage
@Pure public DBaseCodePage getDBFLanguage()
Replies the language used in the dBASE file.- Returns:
- the language used in the dBASE file, or
null
if unknown. - Since:
- 4.0
-
getDBFVersion
@Pure public int getDBFVersion()
Replies the version of the DBF file.- Returns:
- the version of the DBF file.
- Since:
- 4.0
-
readDBFHeader
public void readDBFHeader() throws IOException
Read the header of the DBF file.- Throws:
IOException
- in case of error.
-
getDBFFields
@Pure public List<DBaseFileField> getDBFFields()
Read the field definitions. Multiple calls to this method will return always the same data structure. The column list is red only at the first call to this function. So you could use this method to obtain the list of the dBASE file's columns.Instead of
readDBFFields()
, this method does not throws any exception. It prefers to return the valuenull
.- Returns:
- all the columns or
null
- See Also:
readDBFFields()
-
getDBFFieldName
@Pure public String getDBFFieldName(int index)
Replies the name of the i-th field.- Parameters:
index
- the index.- Returns:
- the name or
null
if the functionreadDBFFields()
was never called.
-
getDBFFieldIndex
@Pure public int getDBFFieldIndex(String name)
Replies the column index of the specified column name.- Parameters:
name
- the field name.- Returns:
- the index or
-1
if the columns was not found or the functionreadDBFFields()
was never called
-
getDBFFieldType
@Pure public DBaseFieldType getDBFFieldType(int index)
Replies the type of the i-th field.- Parameters:
index
- the index.- Returns:
- the type or
null
if the functionreadDBFFields()
was never called.
-
readDBFFields
public List<DBaseFileField> readDBFFields() throws IOException, EOFException
Read the field definitions. Multiple calls to this method will return always the same data structure. The column list is red only at the first call to this function. So you could use this method to obtain the list of the dBASE file's columns.Instead of
getDBFFields()
, this method does not returns the valuenull
. It prefers to throw an exception.- Returns:
- all the columns
- Throws:
IOException
- if the stream cannot be read.EOFException
- if unexpected end-of-file.- See Also:
getDBFFields()
-
readNextDBFRecord
public DBaseFileRecord readNextDBFRecord() throws IOException
Read the next record.- Returns:
- the next record from the input stream or
null
if none. - Throws:
IOException
- in case of error.- See Also:
readNextAttributeProvider()
-
skip
public void skip(int skipAmount) throws IOException
Move the reading head by the specified record count amount.If the count of records to skip puts the reading head after the last record, the exception
EOFException
is thrown.- Parameters:
skipAmount
- is the count of records to skip.- Throws:
IOException
- in case of error.
-
seek
public void seek(int recordIndex) throws IOException
Move the reading head at the specified record index.If the index is negative, the next record to read is assumed to be the first record. If the index is greater or equals to the count of records, the exception
EOFException
will be thrown.- Parameters:
recordIndex
- is the index of record to reply at the next read.- Throws:
IOException
- in case of error.
-
readNextAttributeProvider
public AttributeProvider readNextAttributeProvider() throws IOException
Read the next record.This function calls
readNextDBFRecord()
and replies an attribute provider that corresponds to the corresponds DBase record.- Returns:
- the next record from the input stream or
null
if none. - Throws:
IOException
- in case of error.- See Also:
readNextDBFRecord()
-
readRestOfDBFRecords
public List<DBaseFileRecord> readRestOfDBFRecords() throws IOException
Read all the records.This method close the input stream !!!
The returned value could take a lot of memory. In this case, the virtual machine could freeze when you try to access to the collection content.
- Returns:
- all the records
- Throws:
IOException
- in case of error.
-
selectColumn
public void selectColumn(DBaseFileField column)
Indicates to this reader that the specified column could be replied.- Parameters:
column
- is the column allowed to be replied
-
selectAllColumns
public void selectAllColumns()
Clear the list of column that must be replied.
-
isColumnSelectable
@Pure public boolean isColumnSelectable(DBaseFileField column)
Replies if the specified column could be replied or ignored.- Parameters:
column
- the column.- Returns:
true
if the given column is selectable, otherwisefalse
-
iterator
@Pure public Iterator<AttributeProvider> iterator()
- Specified by:
iterator
in interfaceIterable<AttributeProvider>
-
-