Module org.arakhne.afc.advanced.dbasefile
Package org.arakhne.afc.io.dbase

Class 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 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 on Locale.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, otherwise false.
        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 - is true to set the given option, or false to unset it.
        See Also:
        OPTION_DECODE_STRING

      • isClosed

        @Pure
public boolean isClosed()
        Replies if the stream was closed.
        Returns:
        true if the input stream is closed, otherwise false.

      • 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 value null.

        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 function readDBFFields() 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 function readDBFFields() 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 function readDBFFields() 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 value null. 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()

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

      • 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, otherwise false