nl.knaw.dans.common.dbflib
Class Table

java.lang.Object
  nl.knaw.dans.common.dbflib.Table

public class Table
extends Object

Represents a single table in a xBase database. A table is represented by a single .DBF file. Some tables have an associated .DBT file to store memo field data.

Author:

Jan van Mansum, Vesa Åkerman

Constructor Summary

Table(File tableFile)
Creates a new Table object.

Table(File tableFile, String charsetName)
Creates a new Table object.

Table(File tableFile, Version version, List<Field> fields)
As Table(File, Version, List, String) but uses the platform's default character set.

Table(File tableFile, Version version, List<Field> fields, String charsetName)
Creates a new Table object.

Method Summary

void	addRecord(Object... fieldValues) Constructs and adds a record.
void	addRecord(Record record) Adds a record to this table.
void	close() Closes this table for reading and writing.
void	delete() Closes and deletes the underlying table file and associated files.
void	deleteRecordAt(int index) Flags the record at index as "deleted".
String	getCharsetName() Returns the name of the character set used to read and write from/to this table file.
List<Field>	getFields() Returns a List of Field objects, which provide a description of each field (column) in the table.
Date	getLastModifiedDate() Returns the date on which this table was last modified.
String	getName() Returns the name of the table, including the extension.
Record	getRecordAt(int index) Returns the record at index.
int	getRecordCount() Returns the record count.
Version	getVersion() Returns the version of DBF use to write to the table file.
void	open() Opens the table for reading and writing.
void	open(IfNonExistent ifNonExistent) Opens the table for reading and writing.
void	pack() Physically remove the records currently flagged as "deleted".
Iterator<Record>	recordIterator() Returns a Record iterator.
Iterator<Record>	recordIterator(boolean includeDeleted) Returns a Record iterator.
void	updateRecordAt(int index, Record record)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Table

public Table(File tableFile)
      throws IllegalArgumentException

Creates a new Table object. A File object representing the .DBF file must be provided. To read from or write to the table it must first be opened.

Parameters:

tableFile - a File object representing the .DBF file that stores this table's data.

Throws:

IllegalArgumentException - if tableFile is null

See Also:

open(IfNonExistent)

Table

public Table(File tableFile,
             String charsetName)
      throws IllegalArgumentException

Creates a new Table object. A File object representing the .DBF file must be provided. To read from or write to the table it must first be opened.

Parameters:

tableFile - a File object representing the .DBF file that stores this table's data.

charsetName - the charset to use for reading and writing this file

Throws:

IllegalArgumentException - if tableFile is null

See Also:

open(IfNonExistent)

Table

public Table(File tableFile,
             Version version,
             List<Field> fields,
             String charsetName)
      throws InvalidFieldTypeException,
             InvalidFieldLengthException

Creates a new Table object. In order to read from or write to the table it must first be opened.

Note: if the .DBF file already exists aFields will be overwritten by the values in the existing file when opened. To replace an existing table, first delete it and then create and open a new Table object.

Parameters:

tableFile - the .DBF file that contains the table data

version - the dBase version to support

fields - the fields to create if this is a new table

charsetName - the charset to use for reading and writing this file

Throws:

IllegalArgumentException - if aTableField is null

InvalidFieldLengthException

InvalidFieldTypeException

See Also:

open(IfNonExistent)

Table

public Table(File tableFile,
             Version version,
             List<Field> fields)
      throws InvalidFieldTypeException,
             InvalidFieldLengthException

As Table(File, Version, List, String) but uses the platform's default character set.

Throws:

InvalidFieldTypeException

InvalidFieldLengthException

Method Detail

open

public void open()
          throws IOException,
                 CorruptedTableException

Opens the table for reading and writing. Equivalent to Table.open(IfNonExistent.ERROR)

Throws:

IOException - if the table file does not exist or could not be opened

CorruptedTableException - if the header of the table file was corrupt

open

public void open(IfNonExistent ifNonExistent)
          throws IOException,
                 CorruptedTableException

Opens the table for reading and writing.

Parameters:

ifNonExistent - what to do if the table file does not exist yet

Throws:

IOException - if the table does not exist or could be opened

CorruptedTableException - if the header of the table file was corrupt

close

public void close()
           throws IOException

Closes this table for reading and writing.

Throws:

IOException - if the table file or an associated file cannot be closed

delete

public void delete()
            throws IOException

Closes and deletes the underlying table file and associated files.

Throws:

IOException - if the table file or an associated file cannot be closed or deleted

getLastModifiedDate

public Date getLastModifiedDate()

Returns the date on which this table was last modified. Note that the hours, minutes, seconds and milliseconds fields are always set to zero. Also, the date time is not normalized to UTC.

Returns:

the last modified date of the table

getName

public String getName()

Returns the name of the table, including the extension.

Returns:

the name of the table

getFields

public List<Field> getFields()

Returns a List of Field objects, which provide a description of each field (column) in the table. The order of the Field objects is guaranteed to be the same as the order of the fields in each record returned. A new copy of the field list is returned on each call.

Returns:

the list of field objects.

recordIterator

public Iterator<Record> recordIterator()

Returns a Record iterator. Note that, to use the iterator the table must be opened. This iterator skips the records flagged as "deleted".

Returns:

a Record iterator

See Also:

Record, recordIterator(boolean)

recordIterator

public Iterator<Record> recordIterator(boolean includeDeleted)

Returns a Record iterator. Note that, to use the iterator the table must be opened. If includeDeleted is true, records flagged as "deleted" are included in the iteration.

Parameters:

includeDeleted - if true deleted records are returned, otherwise not

Returns:

a Record iterator

addRecord

public void addRecord(Object... fieldValues)
               throws IOException,
                      DbfLibException

Constructs and adds a record. The fields values for the record must be provided as parameters in the same order that the fields are provided in the field list.

Throws:

IOException - if the record could not be written to the database file

CorruptedTableException - if the table was corrupt

ValueTooLargeException - if a field value exceeds the length of its corresponding field

RecordTooLargeException - if more field values are provided than there are field in this table

DbfLibException

addRecord

public void addRecord(Record record)
               throws IOException,
                      DbfLibException

Adds a record to this table.

Parameters:

record - the record to add.

Throws:

IOException - if the record could not be written to the database file

CorruptedTableException - if the table was corrupt

ValueTooLargeException - if a field value exceeds the length of its corresponding field

DbfLibException

See Also:

Record

updateRecordAt

public void updateRecordAt(int index,
                           Record record)
                    throws IOException,
                           DbfLibException

Throws:

IOException

DbfLibException

deleteRecordAt

public void deleteRecordAt(int index)
                    throws IOException

Flags the record at index as "deleted". To physically remove "deleted" records, a call to pack() is necessary.

Parameters:

index - the index of the record to delete

Throws:

IOException

getRecordAt

public Record getRecordAt(int index)
                   throws IOException,
                          CorruptedTableException

Returns the record at index. If the index points to a record beyond the last a NoSuchElementException is thrown. Attention: records marked as deleted are returned.

Parameters:

index - the zero-based index of the record

Returns:

a Record object

Throws:

IOException

CorruptedTableException

pack

public void pack()
          throws IOException,
                 DbfLibException

Physically remove the records currently flagged as "deleted".

Throws:

IOException

DbfLibException

getCharsetName

public String getCharsetName()

Returns the name of the character set used to read and write from/to this table file.

Returns:

a charset name

getVersion

public Version getVersion()

Returns the version of DBF use to write to the table file. For existing files, some detection is attempted by the library, but it should not be relied on to heavily.

Returns:

the version of DBF

getRecordCount

public int getRecordCount()

Returns the record count. This number includes the records flagged as deleted. These records were visible in the original dBase program user interface, although with a visual indication that they were deleted. To phyically removed them you need to call pack()

Returns:

the record count

See Also:

pack(), Record.isMarkedDeleted()