ewe.database
Class RecordFile

java.lang.Object
  ewe.database.DatabaseObject
      ewe.database.RecordDatabaseObject
          ewe.database.RecordFile

All Implemented Interfaces:

Database, DatabaseTypes, HasProperties

public class RecordFile

extends RecordDatabaseObject

A RecordFile is an implementation of a Database that uses a DatabaseStream to store a set of Records as linked lists within the file.

Nested Class Summary

Nested classes inherited from class ewe.database.DatabaseObject

DatabaseObject.MetaData

Field Summary

Lock	lock Use this to synchronize operations on the RecordFile.
int	minimumLines

Fields inherited from class ewe.database.DatabaseObject

buffer, byteArray, dataValidator, decryptor, encryptor, encryptorNotSet, entries, file, foundEntries, INDEX_FLAG_DO_REINDEX, indexFlag, intArray, myLocale, now, openIndexes, openMode, openModifiers, SETFIELDS_MODE_ENSURE, SETFIELDS_MODE_OVERRIDE, SETFIELDS_MODE_SET, stream

Fields inherited from interface ewe.database.Database

CreatedSortName, FIELD_MODIFIER_INTEGER_AUTO_INCREMENT, ModifiedBySortName, ModifiedSortName, OidSortName, SYNC_SLOW, SYNC_STORE_CREATION_DATE, SYNC_STORE_MODIFICATION_DATE, SYNC_STORE_MODIFIED_BY, SyncSortName

Fields inherited from interface ewe.database.DatabaseTypes

BOOLEAN, BYTE_ARRAY, CREATED_FIELD, DATE, DATE_TIME, DECIMAL, DOUBLE, FIRST_SPECIAL_FIELD, FLAG_SYNCHRONIZED, FLAGS_FIELD, INTEGER, JAVA_OBJECT, LONG, MAX_ID, MODIFIED_BY_FIELD, MODIFIED_FIELD, NAME_FIELD, OBJECT_BYTES_FIELD, OBJECT_TEXT_FIELD, OID_FIELD, reservedFieldHeaders, reservedFieldIDs, reservedFieldNames, reservedFieldTypes, SORT_DATE_ONLY, SORT_IGNORE_CASE, SORT_TIME_ONLY, SORT_UNKNOWN_IS_GREATER_THAN_KNOWN, SORT_UNKNOWN_IS_LESS_THAN_KNOWN, STRING, TIME, TIMESTAMP

Constructor Summary

RecordFile(DatabaseStream stream, String mode)
Open a Record file using an already open DatabaseStream.

RecordFile(File file, String mode)
Open a Record file using a specified File.

RecordFile(File file, String mode, boolean ignoreInconsistentState)

RecordFile(RandomAccessStream stream, String mode)
Open a Record file using an already open RandomAccessStream.

RecordFile(RandomAccessStream stream, String mode, boolean ignoreInconsistentState)

Method Summary

int	addRecord(byte[] data, int offset, int length)
int	addRecord(byte[] data, int offset, int length, boolean useFreeSpace) Add the data as a new record.
void	close() Close the database.
int	countDeletedEntries() Returns the number of deleted records.
void	delete() Delete the database.
boolean	deleteMetaData(String name)
void	deleteRecord(int location) Delete the record at the specified location.
protected boolean	doEnableLookupMode() This should check if the underlying stream supports temporary closing/re-opening.
protected void	doErase(int location, boolean isDeleted)
protected ByteArray	doLoad(int location, ByteArray dest)
protected void	doMarkAsDeleted(int location, long OID, long deleteTime)
protected void	doOpenCloseLookup(boolean isOpen) This should temporarily close or re-open the underlying data.
protected int	doSave(int location, byte[] data, int offset, int length)
void	eraseDeletedEntries() Free all the deleted records.
boolean	eraseDeletedEntry(long oid) Free a particular deleted entry.
protected boolean	getAllRecords(Handle h, int[] dest, int offset, int need) Copy all the records into the array.
long[]	getDeletedEntries() Get an array of object IDs representing all the deleted entries.
DatabaseEntry	getDeletedEntry(long oid, DatabaseEntry dest) Get the DatabaseEntry of the deleted OID.
long	getEntriesCount() This will return the number of entries in the database if known.
int	getFirstEntry() Retrieve the location of the first record.
byte[]	getMetaData() Read in the meta-data.
Object	getMetaData(String name, int length, boolean mustExist)
Time	getModifiedTime() Get the time of the last modification made to the database.
protected DatabaseObject.MetaData	getNewMetaData(String name) These deal with fields and sorts and specs.
int	getNextEntry(int previous) Retrieve the location of the normal record following the previous record.
void	initialize() Initialize the RecordFile - you do not need to call this for new RecordFiles, it is done if a new RecordFile is created automatically.
int	lengthOfRecord(int record) Return the number of bytes needed to fetch a record.
protected ewe.database.DatabaseIndex	makeNewIndex(String name)
void	markAsDeleted(int location, long OID, long deleteTime) Delete the record, leaving behind a special deleted record marker.
int	metaDataLength(String name)
int	modifyRecord(int location, byte[] data, boolean useFreeSpace) Modify the record data, returning a new location if the record had to be moved.
int	modifyRecord(int location, byte[] data, int offset, int length)
int	modifyRecord(int location, byte[] data, int offset, int length, boolean useFreeSpace) Modify the record data, returning a new location if the record had to be moved.
void	readMetaData(Object metaLocation, int metaOffset, byte[] data, int offset, int length)
int	readMetaDataInt(Object metaLocation, int offset)
byte[]	readRecord(int record) Read in and return the record data.
int	readRecord(int record, byte[] dest, int offset) Read in the record data.
ByteArray	readRecord(int record, ByteArray dest) Read the record data and append it to a ByteArray.
void	removeFieldIDs(int fieldID)
void	rename(String newName) Rename the database.
void	setDatabaseStream(DatabaseStream stream, String mode, boolean ignoreInconsistentState)
boolean	setModifiedTime(Time t) Set the time of the last modification made to the database.
void	writeMetaData(Object metaLocation, int metaOffset, byte[] data, int offset, int length)
void	writeMetaDataInt(Object metaLocation, int offset, int value)

Methods inherited from class ewe.database.RecordDatabaseObject

doErase, doLoad, doMarkAsDeleted, doStore, entries, getAllEntries, getAllFoundEntries, makeNewData, makeNewFoundEntries

Methods inherited from class ewe.database.DatabaseObject

addField, addSort, addSort, addSort, addSpecialField, append, change, closeLookup, countEntries, createIndex, createIndex, deleteStream, dispatchEvent, doAppend, doEstimateEntriesCount, doOpenIndex, doOpenIndex, doReIndex, enableLookupMode, enableSynchronization, enableSynchronization, ensureFields, ensureSorts, entries, entries, estimateEntriesCount, findField, findField, findFields, findFields, findIndex, findIndex, findOpenIndex, findSort, findSort, getCurrentState, getData, getDeletedSince, getEmptyEntries, getEntries, getEntries, getEventDispatcher, getField, getFieldHeader, getFieldName, getFields, getFieldType, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntries, getFoundEntriesForIndex, getIdentifier, getIndexes, getIndexSort, getLocale, getMetaData, getMyDatabaseEntries, getMyFoundEntries, getNewData, getNewDataObject, getNewOID, getObjectClass, getProperties, getSortFields, getSortName, getSortOptions, getSorts, getStreamLength, getSynchronizedTime, getTimeOfDeletion, hasChangedSince, hasDatabaseEntries, hasField, hasFoundEntries, indexBy, indexBy, indexBy, isIndexedBy, isInstanceOfDataObject, isOpenForReadWrite, load, markForReIndex, modifyField, openIndex, openLookup, openStreamForReading, openStreamForReplacing, openStreamForWriting, overrideFields, overrideSorts, overwriteMetaData, recordIndexChange, registerIndex, registerNewFoundEntries, reIndex, removeField, removeSort, save, saveIndex, setData, setDataValidator, setEncryption, setFieldHeader, setFields, setFields, setFields, setFields, setLocale, setMetaData, setObjectClass, setPassword, setSorts, setSorts, setSorts, setSynchronizedTime, toCriteria, updateTypes, useEncryption, usePassword

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

lock

public Lock lock

Use this to synchronize operations on the RecordFile.

minimumLines

public final int minimumLines

See Also:

Constant Field Values

Constructor Detail

RecordFile

public RecordFile(DatabaseStream stream,
                  String mode)
           throws IOException,
                  InconsistentDatabaseStateException

Open a Record file using an already open DatabaseStream.

Parameters:

stream - The alredy opened DatabaseStream

mode - the mode to use the RecordFile. This can be "r" or "rw" or "a" (for append only). Note that you may have to open the DatabaseStream in "rw" mode even if you are only going to access the records in read-only ("r") mode. This is because the safeWrite feature of the DatabaseStream may require you always open in "rw" mode to ensure that incomplete operations are completed.

Throws:

IOException

InconsistentDatabaseStateException

RecordFile

public RecordFile(RandomAccessStream stream,
                  String mode)
           throws IOException,
                  InconsistentDatabaseStateException

Open a Record file using an already open RandomAccessStream.

Parameters:

stream - The alredy opened RandomAccessStream. This will be wrapped in a RandomAccessDatabaseStream for use by the RecordFile.

mode - the mode to use the RecordFile. This can be "r" or "rw" or "a" (for append only). Note that you may have to open the RandomAccessStream in "rw" mode even if you are only going to access the records in read-only ("r") mode. This is because the safeWrite feature of the RandomAccessDatabaseStream may require you always open in "rw" mode to ensure that incomplete operations are completed.

Throws:

IOException

InconsistentDatabaseStateException

RecordFile

public RecordFile(File file,
                  String mode)
           throws IOException,
                  InconsistentDatabaseStateException

Open a Record file using a specified File.

Parameters:

mode - the mode to use the RecordFile. This can be "r" or "rw" or "a" (for append only).

Throws:

IOException

InconsistentDatabaseStateException

RecordFile

public RecordFile(RandomAccessStream stream,
                  String mode,
                  boolean ignoreInconsistentState)
           throws IOException,
                  InconsistentDatabaseStateException

RecordFile

public RecordFile(File file,
                  String mode,
                  boolean ignoreInconsistentState)
           throws IOException,
                  InconsistentDatabaseStateException

Method Detail

setDatabaseStream

public void setDatabaseStream(DatabaseStream stream,
                              String mode,
                              boolean ignoreInconsistentState)
                       throws IOException

Throws:

IOException

doEnableLookupMode

protected boolean doEnableLookupMode()
                              throws IOException

Description copied from class: DatabaseObject

This should check if the underlying stream supports temporary closing/re-opening. If it does it should close it temporarily and return true. Otherwise it should return false. If this method returns true it will not be called again - even if enableLookupMode() is called again. This method is not called if the Database is opened in R/W mode.

Overrides:

doEnableLookupMode in class DatabaseObject

Returns:

true if lookup mode was successfully done.

Throws:

IOException - if an error occured which renders the Database unusable.

doOpenCloseLookup

protected void doOpenCloseLookup(boolean isOpen)
                          throws IOException

Description copied from class: DatabaseObject

This should temporarily close or re-open the underlying data. This will only be called if doEnableLookupMode() returned true.

Overrides:

doOpenCloseLookup in class DatabaseObject

Parameters:

isOpen - true to reopen the underlying data, false to close it.

Throws:

IOException - if an error occured which renders the Database unusable.

initialize

public void initialize()
                throws IOException

Initialize the RecordFile - you do not need to call this for new RecordFiles, it is done if a new RecordFile is created automatically. This will erase any data in the File, setup the internal directory and truncate the file to the minimum length if possible.

Throws:

IOException

getNewMetaData

protected DatabaseObject.MetaData getNewMetaData(String name)

Description copied from class: DatabaseObject

These deal with fields and sorts and specs.

Specified by:

getNewMetaData in class DatabaseObject

makeNewIndex

protected ewe.database.DatabaseIndex makeNewIndex(String name)

Specified by:

makeNewIndex in class DatabaseObject

deleteRecord

public void deleteRecord(int location)
                  throws IOException

Delete the record at the specified location. This can only be applied to a Data Record.

Parameters:

location - The record location.

Throws:

IOException

markAsDeleted

public void markAsDeleted(int location,
                          long OID,
                          long deleteTime)
                   throws IOException

Delete the record, leaving behind a special deleted record marker.

Parameters:

location - The record to delete.

OID - a unique ID to associate with the record.

deleteTime - a time stamp (from Time.getTime()) to associate with the deletion.

Throws:

IOException - on error.

DatabaseOperationException - if the location is not a valid database record.

countDeletedEntries

public int countDeletedEntries()
                        throws IOException

Returns the number of deleted records.

Throws:

IOException - on error.

eraseDeletedEntries

public void eraseDeletedEntries()
                         throws IOException

Free all the deleted records.

Throws:

IOException

eraseDeletedEntry

public boolean eraseDeletedEntry(long oid)
                          throws IOException

Free a particular deleted entry.

Parameters:

oid - the OID of the deleted entry.

Returns:

true if it was deleted, false if that OID was not found i the deleted list.

Throws:

IOException

modifyRecord

public int modifyRecord(int location,
                        byte[] data,
                        int offset,
                        int length,
                        boolean useFreeSpace)
                 throws IOException

Modify the record data, returning a new location if the record had to be moved. This should only be applied to normal records.

Parameters:

location - the location of the record.

data - The data bytes.

offset - The index of the first data byte.

length - The number of data bytes.

useFreeSpace - if this is false then it will be appended to the file without any attempt to use space occupied by previously deleted records. This is the fastest modify that you can do.

Returns:

the location of the saved record.

Throws:

IOException

addRecord

public int addRecord(byte[] data,
                     int offset,
                     int length,
                     boolean useFreeSpace)
              throws IOException

Add the data as a new record. This is ONLY to be used with normal

Parameters:

data - The data bytes.

offset - The index of the first data byte.

length - The number of data bytes.

useFreeSpace - if this is false the record will be appended to the file without any attempt to use space occupied by previously deleted records. This is the fastest add that you can do.

Returns:

the location of the saved record.

Throws:

IOException

modifyRecord

public int modifyRecord(int location,
                        byte[] data,
                        int offset,
                        int length)
                 throws IOException

Throws:

IOException

addRecord

public int addRecord(byte[] data,
                     int offset,
                     int length)
              throws IOException

Throws:

IOException

modifyRecord

public int modifyRecord(int location,
                        byte[] data,
                        boolean useFreeSpace)
                 throws IOException

Modify the record data, returning a new location if the record had to be moved.

Parameters:

location - the location of the record.

data - The data bytes.

useFreeSpace - if this is false and the record must be placed in a new location because its data now exceeds its space allocation, then it will be appended to the file without any attempt to use space occupied by previously deleted records. This is the fastest add that you can do.

Returns:

the location of the saved record.

Throws:

IOException

lengthOfRecord

public int lengthOfRecord(int record)
                   throws IOException

Return the number of bytes needed to fetch a record.

Parameters:

record - the record location.

Returns:

the number of bytes needed to fetch a record.

Throws:

IOException

readRecord

public int readRecord(int record,
                      byte[] dest,
                      int offset)
               throws IOException

Read in the record data.

Parameters:

record - the record location.

dest - the destination for the data bytes.

offset - the location to read to.

Returns:

the number of bytes read.

Throws:

IOException

readRecord

public byte[] readRecord(int record)
                  throws IOException

Read in and return the record data. This is a very inefficient way of doing this since it creates a new byte array each time.

Parameters:

record - the record location.

Returns:

the record data as an array of bytes.

Throws:

IOException

readRecord

public ByteArray readRecord(int record,
                            ByteArray dest)
                     throws IOException

Read the record data and append it to a ByteArray.

Parameters:

record - the record to read.

dest - a destination ByteArray. This can be null in which case a new one will be created.

Returns:

the dest ByteArray or a new one.

Throws:

IOException

getMetaData

public byte[] getMetaData()
                   throws IOException

Read in the meta-data.

Returns:

the meta-data or null if none is set.

Throws:

IOException

getFirstEntry

public int getFirstEntry()
                  throws IOException

Retrieve the location of the first record. There is no getLastRecord() since record ordering is meaningless in this file.

Returns:

the location of the first record or 0 if there is no first record.

Throws:

IOException

getNextEntry

public int getNextEntry(int previous)
                 throws IOException

Retrieve the location of the normal record following the previous record.

Specified by:

getNextEntry in class RecordDatabaseObject

Parameters:

previous - The previous record. A value of zero will return the first record.

Returns:

the location of the record following the previous record.

Throws:

IOException

getAllRecords

protected boolean getAllRecords(Handle h,
                                int[] dest,
                                int offset,
                                int need)
                         throws IOException

Copy all the records into the array. Use countEntries() to find out how many records there are.

Specified by:

getAllRecords in class RecordDatabaseObject

Parameters:

dest - the destination for the records.

offset - the location in the destination to write to.

Throws:

IOException

close

public void close()
           throws IOException

Description copied from interface: Database

Close the database.

Throws:

IOException - on error.

delete

public void delete()
            throws IOException

Description copied from interface: Database

Delete the database.

Throws:

IOException - if the database could not be deleted.

rename

public void rename(String newName)
            throws IOException

Description copied from interface: Database

Rename the database.

Parameters:

newName - the new name for the database.

Throws:

IOException - if the database could not be renamed.

getEntriesCount

public long getEntriesCount()
                     throws IOException

Description copied from interface: Database

This will return the number of entries in the database if known. If it is unknown it will return -1 and you can call either estimateEntriesCount() or countEntries() to to get an entry count.

Specified by:

getEntriesCount in interface Database

Specified by:

getEntriesCount in class DatabaseObject

Throws:

IOException

removeFieldIDs

public void removeFieldIDs(int fieldID)
                    throws IOException

Specified by:

removeFieldIDs in class RecordDatabaseObject

Throws:

IOException

doErase

protected void doErase(int location,
                       boolean isDeleted)
                throws IOException

Specified by:

doErase in class RecordDatabaseObject

Throws:

IOException

doMarkAsDeleted

protected void doMarkAsDeleted(int location,
                               long OID,
                               long deleteTime)
                        throws IOException

Specified by:

doMarkAsDeleted in class RecordDatabaseObject

Throws:

IOException

doLoad

protected ByteArray doLoad(int location,
                           ByteArray dest)
                    throws IOException

Specified by:

doLoad in class RecordDatabaseObject

Throws:

IOException

doSave

protected int doSave(int location,
                     byte[] data,
                     int offset,
                     int length)
              throws IOException

Specified by:

doSave in class RecordDatabaseObject

Throws:

IOException

getDeletedEntries

public long[] getDeletedEntries()
                         throws IOException

Description copied from interface: Database

Get an array of object IDs representing all the deleted entries. You can then call getDeletedEntry(OID) to get the DatabaseEntry OR you can call getTimeOfDeletion(OID,Time) to find out when it was deleted.

Returns:

an array of OIDs representing all the deleted entries.

Throws:

IOException

getModifiedTime

public Time getModifiedTime()
                     throws IOException

Description copied from interface: Database

Get the time of the last modification made to the database.

Returns:

the time of the last modification made to the database or null if it could not be determined.

Throws:

IOException - on error.

setModifiedTime

public boolean setModifiedTime(Time t)
                        throws IOException

Description copied from interface: Database

Set the time of the last modification made to the database.

Parameters:

t - the modified time.

Returns:

true if the operation was successful, false if the modification time cannot be set.

Throws:

IOException - on error.

getMetaData

public Object getMetaData(String name,
                          int length,
                          boolean mustExist)
                   throws IOException,
                          IllegalArgumentException

Throws:

IOException

IllegalArgumentException

readMetaData

public void readMetaData(Object metaLocation,
                         int metaOffset,
                         byte[] data,
                         int offset,
                         int length)
                  throws IOException

Throws:

IOException

writeMetaData

public void writeMetaData(Object metaLocation,
                          int metaOffset,
                          byte[] data,
                          int offset,
                          int length)
                   throws IOException

Throws:

IOException

deleteMetaData

public boolean deleteMetaData(String name)
                       throws IOException

Throws:

IOException

metaDataLength

public int metaDataLength(String name)
                   throws IOException

Throws:

IOException

readMetaDataInt

public int readMetaDataInt(Object metaLocation,
                           int offset)
                    throws IOException

Throws:

IOException

writeMetaDataInt

public void writeMetaDataInt(Object metaLocation,
                             int offset,
                             int value)
                      throws IOException

Throws:

IOException

getDeletedEntry

public DatabaseEntry getDeletedEntry(long oid,
                                     DatabaseEntry dest)
                              throws IOException

Description copied from interface: Database

Get the DatabaseEntry of the deleted OID. This will not hold the original information in the entry. It will just hold the OID and the MODIFIED_FIELD - which will be the date of deletion.

Parameters:

oid - The OID to look for.

Returns:

The DatabaseEntry or null if not found.

Throws:

IOException