ewe.database
Interface Database

All Superinterfaces:
DatabaseTypes, HasProperties
All Known Implementing Classes:
DatabaseObject

public interface Database
extends DatabaseTypes, HasProperties

A Database represents a single relational database table along with associated indexes and other meta data. Note that a full application database will usually consist of a number of individual Database objects, since each one represents a single data table.

The interface specifies the functions a Database provides, not how it is implemented. However the Ewe library provides a Database implementation that can be implemented on any object that provides RandomAccessStream functionality (such as a RandomAccessFile). This allows a Database to be setup in memory as easily as on disk.

Databases can be fully secure using Ewe encryption or any other type of encryption.


Field Summary
static String CreatedSortName
           
static int FIELD_MODIFIER_INTEGER_AUTO_INCREMENT
          Used by modifyField() - this modifies and INTEGER field to be auto-incremental.
static String ModifiedBySortName
           
static String ModifiedSortName
           
static String OidSortName
           
static int SYNC_SLOW
          This is a sync option that suggests that the database use a sync model that uses less memory but may be slower.
static int SYNC_STORE_CREATION_DATE
          This is a sync option that tells the database to store the creation date along with every record.
static int SYNC_STORE_MODIFICATION_DATE
          This is a sync option that tells the database to store the modification date along with every record.
static int SYNC_STORE_MODIFIED_BY
          This is a sync option that tells the database to save the MODIFIED_BY data with each record.
static String 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
 
Method Summary
 int addField(String fieldName, int fieldType)
          Add a new field.
 int addSort(String sortName, int options, int field)
          Create a new sort criteria that sorts using one field only.
 int addSort(String sortName, int options, int field1, int field2, int field3, int field4)
          Create a new sort criteria allowing you to specify up to four fields.
 int addSort(String sortName, int options, String fieldList)
          Create a new sort criteria allowing you to specify up to four fields.
 void addSpecialField(int fieldCode)
          Use this to add one of the reserved fields (the XXXX_FIELD) values.
 void append(DatabaseEntry de)
          Use this method in "Append" mode to add a data item to the Databse.
 void change()
          Mark the Database as having been changed in some way.
 void close()
          Close the database.
 void closeLookup()
          This is used with enableLookupMode() - it tells the database that data reading is complete and the underlying file may be closed.
 int countDeletedEntries()
          Returns the number of entries marked as deleted.
 Handle countEntries()
          If getEntriesCount() returns -1, indicating that the number of entries is unknown, then this method will count the entries by counting each one if necessary.
 void delete()
          Delete the database.
 boolean deleteMetaData(String name)
           
 boolean deleteStream(String name)
          Delete a Stream from the Database.
 boolean enableLookupMode()
          This method tells the database that it will be used for read-only lookups and that it can close its underlying file if it wishes - and later re-open it when lookups are done without re-reading the database info.
 boolean enableSynchronization(Handle h, int syncOptions)
          This tells the database to include the OID_FIELD, FLAGS_FIELD, CREATED_FIELD and MODIFIED_FIELD information with each record so that it can be synchronized with a other databases.
 void enableSynchronization(int syncOptions)
          This tells the database to include the OID_FIELD, FLAGS_FIELD, CREATED_FIELD and MODIFIED_FIELD information with each record so that it can be synchronized with a other databases.
 int[] ensureFields(Object objectOrClass, String fields, String headers)
          Similar to setFields() except that no error is thrown if any fields of the same name and type already exist.
 int[] ensureSorts(Object objectOrClass, String sorts)
          This works the same as setSorts() except that no error is thrown if any of the sorts already exists and has the same criteria of the already declared sort.
 Iterator entries()
          This returns an Iterator that you can use to go through the entries in the database.
 Iterator entries(Object searchData, Comparer comparer)
          This returns an Iterator that you can use to go through the entries in the database.
 Iterator entries(ObjectFinder entry)
          This returns an Iterator that you can use to go through the entries in the database.
 void eraseDeletedEntries()
          Erase all the entries marked as deleted.
 boolean eraseDeletedEntry(long OID)
          Erase the deleted entry for the specified OID.
 long estimateEntriesCount()
          If getEntriesCount() returns -1, indicating that the number of entries is unknown, then this method will attempt to estimate the entries count via a quick non-blocking method without resorting to counting each entry.
 int findField(String fieldName)
          Find the FieldID of a named field.
 int[] findFields(String fieldNames)
          Get an array of fieldIds for a comma separated list of field names.
 int[] findFields(String[] fieldNames)
          Get an array of fieldIds for an array of field names.
 int findSort(String sortName)
          Get the ID of a named sort criteria.
 long getCurrentState()
          Get the current changed state of the Database.
 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[] getDeletedSince(Time t)
          Get all OIDs of all entries deleted since the Time t.
 FoundEntries getEmptyEntries()
          This returns an empty FoundEntries object for this Database
 FoundEntries getEntries()
          Deprecated. use getFoundEntries(Handle h,int sortID) with a zero sortID instead.
 FoundEntries getEntries(int sortID)
          Deprecated. use getFoundEntries(Handle h,int sortID) instead.
 long getEntriesCount()
          This will return the number of entries in the database if known.
 EventDispatcher getEventDispatcher()
          Get an EventDispatcher which you can use to attach EventListeners to, for listening to the events being generated by the Database.
 String getFieldHeader(int fieldID)
          Get the header for a specified field ID.
 String getFieldName(int fieldID)
          Get the name for a specified field ID.
 int[] getFields()
          Get the IDs of all the fields.
 int getFieldType(int fieldID)
          Get the type of a field.
 Handle getFoundEntries(Comparer comparer)
          Get all the entries in the Database sorted by the specified Comparer in a new thread.
 FoundEntries getFoundEntries(Handle h, Comparer comparer)
          Get all the entries in the Database sorted by the specific comparer.
 FoundEntries getFoundEntries(Handle h, int sortID)
          Get all the entries in the Database sorted by the specified sort ID.
 FoundEntries getFoundEntries(Handle h, int sortID, EntrySelector selector)
          Get a subset of the entries in the Database sorted by the specific sort ID and which the EntrySelector considers to be equal to the searchData.
 FoundEntries getFoundEntries(Handle h, int sortID, Object primarySearchFields)
          Get a subset of the entries in the Database sorted by the specific sort ID and which match the primarySearchFields data.
 FoundEntries getFoundEntries(Handle h, int sortID, ObjectFinder finder)
          Get a subset of the entries in the Database sorted by the specific sort ID and which the ObjectFinder considers to be what is being looked for.
 FoundEntries getFoundEntries(Handle h, String indexName)
          Get all the entries in the database sorted according to the specified index.
 Handle getFoundEntries(int sortID)
          Get all the entries in the Database sorted by the specified sort ID in a new thread.
 Handle getFoundEntries(int sortID, EntrySelector selector)
          Get a subset the entries in the Database sorted by the specified sort ID in a new thread.
 Handle getFoundEntries(int sortID, Object primarySearchFields)
          Get a subset of the entries in the Database sorted by the specific sort ID and which match the primarySearchFields data in a new thread.
 Handle getFoundEntries(int sortID, ObjectFinder finder)
          Get a subset of the entries in the Database sorted by the specific sort ID and which the ObjectFinder considers to be what is being looked for in a new thread.
 Handle getFoundEntries(String indexName)
          Get all the entries in the Database sorted by the specified index in a new thread.
 int getIdentifier()
          Get a unique identifier for this database - used for synchronizing.
 IndexEntry[] getIndexes()
          This returns all the indexes used by the Database.
 Locale getLocale()
          Set the locale being used with the Database.
 Object getMetaData(String name, int length, boolean mustExist)
           
 Time getModifiedTime()
          Get the time of the last modification made to the database.
 DatabaseEntry getNewData()
          Return an empty DatabaseEntry to be used with this database.
 Object getNewDataObject()
          Create and return a new instance of the object class assigned to the database.
 Reflect getObjectClass()
          If setObjectClass() was used on the database to specify a Java class to be used as a data interface, then this will return a Reflect object representing that class.
 int[] getSortFields(int sortID)
          Get the fields by which the Sort will sort.
 String getSortName(int sortID)
          Get the name of a Sort.
 int getSortOptions(int sortID)
          Get the options associated with the sortID.
 int[] getSorts()
          Get the IDs of all the sorts.
 long getStreamLength(String name)
          Returns the length of a meta-data Stream stored in the Database, or -1 if the named Stream does not exist.
 Time getSynchronizedTime(int remoteDatabaseID)
           
 Time getTimeOfDeletion(long OID, Time destination)
          Return the time of deletion of the specified OID.
 boolean hasChangedSince(long previousState)
          Return if the Database has changed since the previous state.
 boolean indexBy(Handle h, Class databaseEntryComparer, String name)
          This tells the Database to keep an index using a particular Comparer class and distinct name.
 boolean indexBy(Handle h, int sortID, String name)
          This tells the Database to keep an index for a particular sort ID and optional distinct name.
 void indexBy(int sortID)
          This is a convenience method for the other indexBy method.
 boolean isIndexedBy(int sortID)
          This returns if the Database has at least one index that uses the specified sort ID.
 boolean isInstanceOfDataObject(Object data)
          Return if the specified object is an instance of the data transfer object assigned in setObjectClass();
 boolean isOpenForReadWrite()
          This should return true if the Database is open in read/write mode, or false if it is open in read-only mode.
 int metaDataLength(String name)
           
 void modifyField(int fieldID, int modifier, Object modifierData)
          Modify a field in some way.
 void openLookup()
          This is used with enableLookupMode() - it tells the database that data is about to be read in and if the underlying file is closed - then it should be re-opened and kept open until closeLookup() is called.
 Stream openStreamForReading(String name)
          Open a Stream into the database to read some sort of meta-data.
 Stream openStreamForReplacing(String name)
          Open a Stream into the database to save some sort of meta-data.
 Stream openStreamForWriting(String name, boolean append)
          Open a Stream into the database to save some sort of meta-data.
 int[] overrideFields(Object objectOrClass, String fields, String headers)
          Similar to setFields() except that no error is thrown if any fields of the same name and type already exist.
 int[] overrideSorts(Object objectOrClass, String sorts)
          This works the same as setSorts() except that no error is thrown if any of the sorts already exists and has the same criteria of the already declared sort, and also any old sorts of the same name will be replaced by the new sort.
 void readMetaData(Object metaLocation, int metaOffset, byte[] data, int offset, int length)
           
 int readMetaDataInt(Object metaLocation, int offset)
           
 boolean reIndex(Handle h)
          In "Append" mode, after all the data has been added, call this method to re-index the database.
 void removeField(int fieldID)
          Remove a field.
 void removeSort(int sortID)
          Remove a Sort.
 void rename(String newName)
          Rename the database.
 void save()
          Save the Database specs to permanent storage.
 void setDataValidator(DataValidator validator)
          Set a DataValidator to validate data before it is saved in the Database.
 void setEncryption(DataProcessor decryptor, DataProcessor encryptor)
          Use this when the Database is initialized to set the decryptor and encryptor for the data.
 boolean setFieldHeader(int fieldID, String newHeader)
          Set the header for a specified field ID.
 int[] setFields(Object objectOrClass)
          Set the fields for the Database, which must match fields in the objectOrClass transfer object.
 int[] setFields(Object objectOrClass, String fields)
          Set the fields for the Database, which must match fields in the objectOrClass transfer object.
 int[] setFields(Object objectOrClass, String fields, String headers)
          Set the fields for the Database, which must match fields in the objectOrClassOrReflect transfer object.
 void setLocale(Locale locale)
          Set the locale to be used with the Database.
 boolean setModifiedTime(Time t)
          Set the time of the last modification made to the database.
 void setObjectClass(Object objectOrClass)
          This is used to set the class of the object used for data transfer to and from the table.
 void setPassword(String password)
          Use this when the Database is initialized to set the encryption key for the database.
 int[] setSorts(Object objectOrClass)
          Set the sorts of the Database as specified by the object provided.
 int[] setSorts(Object objectOrClass, String sorts)
          Set the sorts of the Database as specified by the object provided.
 void setSynchronizedTime(int remoteDatabaseID, Time syncTime)
           
 int[] toCriteria(int sortID)
          Convert the sortID to a Criteria array, used by a number of Database functions.
 boolean useEncryption(DataProcessor decryptor, DataProcessor encryptor)
          Use this when opening the database and accessing the data.
 boolean usePassword(Object key)
          Use this when opening the database and accessing the data.
 void writeMetaData(Object metaLocation, int metaOffset, byte[] data, int offset, int length)
           
 void writeMetaDataInt(Object metaLocation, int offset, int value)
           
 
Methods inherited from interface ewe.data.HasProperties
getProperties
 

Field Detail

FIELD_MODIFIER_INTEGER_AUTO_INCREMENT

public static final int FIELD_MODIFIER_INTEGER_AUTO_INCREMENT
Used by modifyField() - this modifies and INTEGER field to be auto-incremental. The modifierData you would use would be an ewe.sys.Long object which contains the initial value

See Also:
Constant Field Values

SYNC_SLOW

public static final int SYNC_SLOW
This is a sync option that suggests that the database use a sync model that uses less memory but may be slower.

See Also:
Constant Field Values

SYNC_STORE_CREATION_DATE

public static final int SYNC_STORE_CREATION_DATE
This is a sync option that tells the database to store the creation date along with every record.

See Also:
Constant Field Values

SYNC_STORE_MODIFICATION_DATE

public static final int SYNC_STORE_MODIFICATION_DATE
This is a sync option that tells the database to store the modification date along with every record. If this is not selected, only the FLAG_SYNCHRONIZED bit is used to determine the sync'ed state of a record.

See Also:
Constant Field Values

SYNC_STORE_MODIFIED_BY

public static final int SYNC_STORE_MODIFIED_BY
This is a sync option that tells the database to save the MODIFIED_BY data with each record. This data is necessary if you are allowing synchronization of one (mobile) database with any number of other desktop databases.

See Also:
Constant Field Values

OidSortName

public static final String OidSortName
See Also:
Constant Field Values

SyncSortName

public static final String SyncSortName
See Also:
Constant Field Values

ModifiedSortName

public static final String ModifiedSortName
See Also:
Constant Field Values

ModifiedBySortName

public static final String ModifiedBySortName
See Also:
Constant Field Values

CreatedSortName

public static final String CreatedSortName
See Also:
Constant Field Values
Method Detail

setEncryption

public void setEncryption(DataProcessor decryptor,
                          DataProcessor encryptor)
                   throws IOException
Use this when the Database is initialized to set the decryptor and encryptor for the data. It must be used before any data is added. Once it has been set it cannot be changed later.

Throws:
IOException

setPassword

public void setPassword(String password)
                 throws IllegalArgumentException,
                        IOException
Use this when the Database is initialized to set the encryption key for the database.

Parameters:
password - a string to be used as the password. Choose a mix of numeric and letters for better security.
Throws:
IllegalArgumentException
IOException

useEncryption

public boolean useEncryption(DataProcessor decryptor,
                             DataProcessor encryptor)
                      throws IOException
Use this when opening the database and accessing the data. The specified decryptor/encryptor must match those used when the setEncryption() method was used to set the encryption for the database. The Database may validate the data at this point and may throw an IOException if it is determined that these are invalid for the database.

Parameters:
decryptor - The decryptor. Necessary for reading and writing if the Database is encrypted.
encryptor - The encryptor. Necessary for writing only if the Database is encrypted.
Throws:
IOException

usePassword

public boolean usePassword(Object key)
                    throws IOException
Use this when opening the database and accessing the data. The specified password must match those used when the setPassword() method was used to set the encryption for the database. The Database may validate the data at this point and may throw an IOException if it is determined that the password is invalid for the database.

Throws:
IOException

getLocale

public Locale getLocale()
Set the locale being used with the Database.


setLocale

public void setLocale(Locale locale)
Set the locale to be used with the Database.


countDeletedEntries

public int countDeletedEntries()
                        throws IOException
Returns the number of entries marked as deleted.

Throws:
IOException - on error.

getDeletedEntries

public long[] getDeletedEntries()
                         throws IOException
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

eraseDeletedEntries

public void eraseDeletedEntries()
                         throws IOException
Erase all the entries marked as deleted. You can also delete them individually using eraseEntry().

Throws:
IOException

getDeletedEntry

public DatabaseEntry getDeletedEntry(long OID,
                                     DatabaseEntry dest)
                              throws IOException
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

getTimeOfDeletion

public Time getTimeOfDeletion(long OID,
                              Time destination)
                       throws IOException
Return the time of deletion of the specified OID.

Parameters:
OID - The OID of the deleted entry.
destination - an optional destination time. If this is null the a new Time will be created.
Returns:
the time of deletion or null if the OID was not found in the deleted list.
Throws:
IOException

eraseDeletedEntry

public boolean eraseDeletedEntry(long OID)
                          throws IOException
Erase the deleted entry for the specified OID.

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

getDeletedSince

public long[] getDeletedSince(Time t)
                       throws IOException
Get all OIDs of all entries deleted since the Time t. If t is null then all the deleted OIDs are returned. Entries deleted AT the specified time are not returned.

Throws:
IOException

setObjectClass

public void setObjectClass(Object objectOrClass)
                    throws IllegalArgumentException
This is used to set the class of the object used for data transfer to and from the table. If you call setFields(Object objectOrClass,String fields) then you do not need to call this method as it will be done for you.

Parameters:
objectOrClass -
Throws:
IllegalArgumentException

getObjectClass

public Reflect getObjectClass()
If setObjectClass() was used on the database to specify a Java class to be used as a data interface, then this will return a Reflect object representing that class.

Returns:

getNewDataObject

public Object getNewDataObject()
                        throws IllegalStateException
Create and return a new instance of the object class assigned to the database.

Returns:
a new instance of the object class assigned to the database.
Throws:
IllegalStateException - if no object class is specified or the object could not be instantiated.

isInstanceOfDataObject

public boolean isInstanceOfDataObject(Object data)
Return if the specified object is an instance of the data transfer object assigned in setObjectClass();

Parameters:
data - the object to check.
Returns:
true if the specified object is an instance of the data transfer object assigned in setObjectClass();

isOpenForReadWrite

public boolean isOpenForReadWrite()
This should return true if the Database is open in read/write mode, or false if it is open in read-only mode.


setSorts

public int[] setSorts(Object objectOrClass)
               throws IllegalArgumentException
Set the sorts of the Database as specified by the object provided. The object must declare a public variable named "_sorts" of type String.

Parameters:
objectOrClass - the Class of the object or an instance of the object.
Returns:
an array if IDs, one for each sort.
Throws:
IllegalArgumentException - if a sort conflicts with an already saved sort.

setSorts

public int[] setSorts(Object objectOrClass,
                      String sorts)
               throws IllegalArgumentException
Set the sorts of the Database as specified by the object provided.

Parameters:
objectOrClass - the Class of the object or an instance of the object.
sorts - a String specifying the sort criteria to use.
Returns:
an array if IDs, one for each sort.
Throws:
IllegalArgumentException - if a sort conflicts with an already saved sort.

ensureSorts

public int[] ensureSorts(Object objectOrClass,
                         String sorts)
                  throws IllegalArgumentException
This works the same as setSorts() except that no error is thrown if any of the sorts already exists and has the same criteria of the already declared sort. This means that this method can be called repeatedly with the same data without causing an error.

Parameters:
objectOrClass - the Class of the object or an instance of the object.
sorts - a String specifying the sort criteria to use.
Returns:
an array if IDs, one for each sort.
Throws:
IllegalArgumentException

overrideSorts

public int[] overrideSorts(Object objectOrClass,
                           String sorts)
                    throws IllegalArgumentException
This works the same as setSorts() except that no error is thrown if any of the sorts already exists and has the same criteria of the already declared sort, and also any old sorts of the same name will be replaced by the new sort.

Parameters:
objectOrClass - the Class of the object or an instance of the object.
sorts - a String specifying the sort criteria to use.
Returns:
an array if IDs, one for each sort.
Throws:
IllegalArgumentException

ensureFields

public int[] ensureFields(Object objectOrClass,
                          String fields,
                          String headers)
                   throws IllegalArgumentException
Similar to setFields() except that no error is thrown if any fields of the same name and type already exist. This means that this method can be called repeatedly with the same data without causing an error.

Parameters:
objectOrClass - The object or class of the object to be used for data transfer.
fields - A comma separated list of fields.
headers - An optional comma separated list of headers.
Throws:
IllegalArgumentException

overrideFields

public int[] overrideFields(Object objectOrClass,
                            String fields,
                            String headers)
                     throws IllegalArgumentException
Similar to setFields() except that no error is thrown if any fields of the same name and type already exist. This means that this method can be called repeatedly with the same data without causing an error. This will also override any previous fields with the same name and different type.

Parameters:
objectOrClass - The object or class of the object to be used for data transfer.
fields - A comma separated list of fields.
headers - An optional comma separated list of headers.
Throws:
IllegalArgumentException

setFields

public int[] setFields(Object objectOrClass)
                throws IllegalArgumentException
Set the fields for the Database, which must match fields in the objectOrClass transfer object.

Parameters:
objectOrClass - The object or class of the object to be used for data transfer.
Returns:
an array of integers representing the field IDs.
Throws:
IllegalArgumentException

setFields

public int[] setFields(Object objectOrClass,
                       String fields)
                throws IllegalArgumentException
Set the fields for the Database, which must match fields in the objectOrClass transfer object.

Parameters:
objectOrClass - The object or class of the object to be used for data transfer.
fields - A comma separated list of fields.
Returns:
an array of integers representing the field IDs.
Throws:
IllegalArgumentException

setFields

public int[] setFields(Object objectOrClass,
                       String fields,
                       String headers)
                throws IllegalArgumentException
Set the fields for the Database, which must match fields in the objectOrClassOrReflect transfer object.

Parameters:
objectOrClass - The object or class of the object to be used for data transfer.
fields - A comma separated list of fields.
headers - An optional comma separated list of headers.
Returns:
an array of integers representing the field IDs.
Throws:
IllegalArgumentException

findField

public int findField(String fieldName)
Find the FieldID of a named field. This is NOT case sensistive.

Parameters:
fieldName - The name of the field.
Returns:
The field id, or 0 if not found.

findFields

public int[] findFields(String[] fieldNames)
Get an array of fieldIds for an array of field names.


findFields

public int[] findFields(String fieldNames)
Get an array of fieldIds for a comma separated list of field names.


getFieldName

public String getFieldName(int fieldID)
Get the name for a specified field ID.


getFieldHeader

public String getFieldHeader(int fieldID)
Get the header for a specified field ID.


setFieldHeader

public boolean setFieldHeader(int fieldID,
                              String newHeader)
Set the header for a specified field ID.

Returns:
true if successful.

getSortName

public String getSortName(int sortID)
Get the name of a Sort.


getSortFields

public int[] getSortFields(int sortID)
Get the fields by which the Sort will sort.

Returns:
an array of 1 or more fields to sort by.

getSortOptions

public int getSortOptions(int sortID)
Get the options associated with the sortID.


toCriteria

public int[] toCriteria(int sortID)
                 throws IllegalArgumentException
Convert the sortID to a Criteria array, used by a number of Database functions.

Throws:
IllegalArgumentException

getFieldType

public int getFieldType(int fieldID)
Get the type of a field.


getFields

public int[] getFields()
Get the IDs of all the fields.


getSorts

public int[] getSorts()
Get the IDs of all the sorts.


addField

public int addField(String fieldName,
                    int fieldType)
             throws IllegalArgumentException
Add a new field. This will return the ID of the new field or throw an exception on failure. This will method will fail if:
1. An invalid fieldType is specified.
2. An already used fieldName is specified.
3. There are already the maximum of 240 fields.

Parameters:
fieldName - The name of the new field.
fieldType - The type of the new field.
Returns:
the ID of the newly added field.
Throws:
IllegalArgumentException

modifyField

public void modifyField(int fieldID,
                        int modifier,
                        Object modifierData)
                 throws IllegalArgumentException,
                        IOException
Modify a field in some way.

Parameters:
fieldID - The id of the field to modify.
modifier - one of the FIELD_MODIFIER_XXX values appropriate for the field type.
modifierData - Some data dependant on the field modifier used.
Throws:
IllegalArgumentException - if the modifier is not appropriate for the field or if the data is not the correct type for the modifier.
IOException

findSort

public int findSort(String sortName)
Get the ID of a named sort criteria.

Parameters:
sortName - The name of the sort criteria.
Returns:
The ID of the sort criteria or 0 if it is not found.

addSort

public int addSort(String sortName,
                   int options,
                   int field)
            throws IllegalArgumentException
Create a new sort criteria that sorts using one field only. Returns the ID of the new sort.

Throws:
IllegalArgumentException

addSort

public int addSort(String sortName,
                   int options,
                   int field1,
                   int field2,
                   int field3,
                   int field4)
            throws IllegalArgumentException
Create a new sort criteria allowing you to specify up to four fields. Set any unused sort fields to zero. Returns the ID of the new sort.

Throws:
IllegalArgumentException

addSort

public int addSort(String sortName,
                   int options,
                   String fieldList)
            throws IllegalArgumentException
Create a new sort criteria allowing you to specify up to four fields.

Parameters:
sortName - The name of the sort.
options - Sorting options.
fieldList - A comma separated field list.
Returns:
The ID of the new sort.
Throws:
IllegalArgumentException - if any of the fields could not be found, or if too many fields are specified.

removeField

public void removeField(int fieldID)
Remove a field. Note that if this Database is a live one (i.e. it exists within an open database), then calling this method may take time as all of the records in the table will have this field removed from them. This does not happen with addField().

Parameters:
fieldID - the ID of the field to remove.

removeSort

public void removeSort(int sortID)
Remove a Sort.

Parameters:
sortID - the ID of the sort to remove.

getNewData

public DatabaseEntry getNewData()
Return an empty DatabaseEntry to be used with this database. This method may be used in "Append" mode to get a DatabaseEntry which you can use to append entries to the database.


append

public void append(DatabaseEntry de)
            throws IOException
Use this method in "Append" mode to add a data item to the Databse. In "Append" mode you add data directly to the database and then do "reIndex()" at the end.

Throws:
IOException

reIndex

public boolean reIndex(Handle h)
                throws IOException
In "Append" mode, after all the data has been added, call this method to re-index the database.

If you close the database without doing reIndex, it will be reIndexed automatically the next time it is opened.

Parameters:
h - a Handle that can be used to monitor or abort the operation.
Returns:
true if the re-indexing ended successfully, false if it was aborted because the stop() method was called on the Handle h.
Throws:
IOException - if there was an error writing to the database.

getEmptyEntries

public FoundEntries getEmptyEntries()
This returns an empty FoundEntries object for this Database


getEntries

public FoundEntries getEntries()
                        throws IOException,
                               DataTooBigException
Deprecated. use getFoundEntries(Handle h,int sortID) with a zero sortID instead.

Get an unsorted FoundEntries representing all the entries in the database.

Throws:
DataTooBigException - if the number of entries cannot fit in a FoundEntries object. In this case the method should be called again with a finder that is more restrictive of the included entries.
IOException

getEntries

public FoundEntries getEntries(int sortID)
                        throws IOException,
                               DataTooBigException
Deprecated. use getFoundEntries(Handle h,int sortID) instead.

Get all the entries in the Database sorted by the specified sort ID.

Parameters:
sortID - The sortID to use. If this is 0 the entries are not sorted.
Returns:
A new FoundEntries object.
Throws:
IOException
DataTooBigException - if the number of entries cannot fit in a FoundEntries object. In this case the method should be called again with a finder that is more restrictive of the included entries.

getFoundEntries

public FoundEntries getFoundEntries(Handle h,
                                    int sortID)
                             throws IOException,
                                    DataTooBigException
Get all the entries in the Database sorted by the specified sort ID. This is done in the same thread as the calling thread, but uses a handle to report its progress to other threads. This allows you to put this call in its own thread while allowing other threads to run.

Parameters:
h - a handle that other threads can use to monitor the operation progress.
sortID - The sortID to use. If this is 0 the entries are not sorted.
Returns:
A new FoundEntries object.
Throws:
IOException
DataTooBigException - if the number of entries cannot fit in a FoundEntries object. In this case the method should be called again with a finder that is more restrictive of the included entries.

getFoundEntries

public FoundEntries getFoundEntries(Handle h,
                                    int sortID,
                                    EntrySelector selector)
                             throws IOException,
                                    DataTooBigException
Get a subset of the entries in the Database sorted by the specific sort ID and which the EntrySelector considers to be equal to the searchData.

Parameters:
h - an optional Handle used to monitor and possibly abort the process.
sortID - The sortID to use. If this is 0 the entries are not sorted.
selector - An object used to select the data according to certain criteria.
Returns:
A new FoundEntries object containing references to only those entries that are considered equal to the searchData by the comparer. If the handle is stopped then null will be returned.
Throws:
IOException
DataTooBigException - if the number of entries cannot fit in a FoundEntries object. In this case the method should be called again with a finder that is more restrictive of the included entries.

getFoundEntries

public FoundEntries getFoundEntries(Handle h,
                                    int sortID,
                                    ObjectFinder finder)
                             throws IOException,
                                    DataTooBigException
Get a subset of the entries in the Database sorted by the specific sort ID and which the ObjectFinder considers to be what is being looked for.

Parameters:
h - an optional Handle used to monitor and possibly abort the process.
sortID - The sortID to use. If this is 0 the entries are not sorted.
finder - This object will have its lookingFor(Object obj) method called for each entry in the database. If the finder returns true, then that entry will be placed in the FoundEntries returned.
Returns:
A new FoundEntries object containing references to only those entries that are considered to be what the finder is looking for. If the handle is stopped then null will be returned.
Throws:
IOException
DataTooBigException - if the number of entries cannot fit in a FoundEntries object. In this case the method should be called again with a finder that is more restrictive of the included entries.

getFoundEntries

public FoundEntries getFoundEntries(Handle h,
                                    int sortID,
                                    Object primarySearchFields)
                             throws IOException,
                                    DataTooBigException
Get a subset of the entries in the Database sorted by the specific sort ID and which match the primarySearchFields data.

Parameters:
h - an optional Handle used to monitor and possibly abort the process.
sortID - The sortID to use. If this is 0 the entries are not sorted.
primarySearchFields - data that will be used to select entries in the Database.
Returns:
A new FoundEntries object containing references to only those entries that are considered to match the search data. If the handle is stopped then null will be returned.
Throws:
IOException
DataTooBigException - if the number of entries cannot fit in a FoundEntries object. In this case the method should be called again with a finder that is more restrictive of the included entries.

getFoundEntries

public FoundEntries getFoundEntries(Handle h,
                                    Comparer comparer)
                             throws IOException,
                                    DataTooBigException
Get all the entries in the Database sorted by the specific comparer.

Parameters:
h - an optional Handle used to monitor and possibly abort the process.
comparer - This is used to sort the entries.
Returns:
A new FoundEntries object containing the entries sorted according to the comparer. If the handle is stopped then null will be returned.
Throws:
IOException
DataTooBigException - if the number of entries cannot fit in a FoundEntries object. In this case the method should be called again with a finder that is more restrictive of the included entries.

getFoundEntries

public FoundEntries getFoundEntries(Handle h,
                                    String indexName)
                             throws IllegalArgumentException,
                                    IOException,
                                    DataTooBigException
Get all the entries in the database sorted according to the specified index.

Parameters:
h - an optional Handle used to monitor and possibly abort the process.
indexName - a valid index name.
Returns:
A new FoundEntries object containing the entries sorted according to the index. If the handle is stopped then null will be returned.
Throws:
IllegalArgumentException
IOException
DataTooBigException - if the number of entries cannot fit in a FoundEntries object. In this case the method should be called again with a finder that is more restrictive of the included entries.

getFoundEntries

public Handle getFoundEntries(int sortID)
Get all the entries in the Database sorted by the specified sort ID in a new thread.

Parameters:
sortID - The sortID to use. If this is 0 the entries are not sorted.
Returns:
a Handle that can be used to monitor and abort the process. When the Handle reports Success, the returnValue of the Handle will hold a new FoundEntries object containing the found and sorted entries.

getFoundEntries

public Handle getFoundEntries(int sortID,
                              EntrySelector selector)
Get a subset the entries in the Database sorted by the specified sort ID in a new thread.

Parameters:
sortID - The sortID to use. If this is 0 the entries are not sorted.
selector - An object used to select the data according to certain criteria.
Returns:
a Handle that can be used to monitor and abort the process. When the Handle reports Success, the returnValue of the Handle will hold a new FoundEntries object containing the found and sorted entries.

getFoundEntries

public Handle getFoundEntries(int sortID,
                              ObjectFinder finder)
Get a subset of the entries in the Database sorted by the specific sort ID and which the ObjectFinder considers to be what is being looked for in a new thread.

Parameters:
sortID - The sortID to use. If this is 0 the entries are not sorted.
finder - This object will have its lookingFor(Object obj) method called for each entry in the database. If the finder returns true, then that entry will be placed in the FoundEntries returned.
Returns:
a Handle that can be used to monitor and abort the process. When the Handle reports Success, the returnValue of the Handle will hold a new FoundEntries object containing the found and sorted entries.

getFoundEntries

public Handle getFoundEntries(int sortID,
                              Object primarySearchFields)
Get a subset of the entries in the Database sorted by the specific sort ID and which match the primarySearchFields data in a new thread.

Parameters:
sortID - The sortID to use. If this is 0 the entries are not sorted.
primarySearchFields - data that will be used to select entries in the Database.
Returns:
a Handle that can be used to monitor and abort the process. When the Handle reports Success, the returnValue of the Handle will hold a new FoundEntries object containing the found and sorted entries.

getFoundEntries

public Handle getFoundEntries(Comparer comparer)
Get all the entries in the Database sorted by the specified Comparer in a new thread.

Parameters:
comparer - This is used to sort the entries.
Returns:
a Handle that can be used to monitor and abort the process. When the Handle reports Success, the returnValue of the Handle will hold a new FoundEntries object containing the found and sorted entries.

getFoundEntries

public Handle getFoundEntries(String indexName)
Get all the entries in the Database sorted by the specified index in a new thread.

Parameters:
indexName - a valid index name.
Returns:
a Handle that can be used to monitor and abort the process. When the Handle reports Success, the returnValue of the Handle will hold a new FoundEntries object containing the sorted entries.

save

public void save()
          throws IOException
Save the Database specs to permanent storage. Call this after changing fields and sorts.

Throws:
IOException - if an error occurs.

close

public void close()
           throws IOException
Close the database.

Throws:
IOException - on error.

delete

public void delete()
            throws IOException
Delete the database.

Throws:
IOException - if the database could not be deleted.

rename

public void rename(String newName)
            throws IOException
Rename the database.

Parameters:
newName - the new name for the database.
Throws:
IOException - if the database could not be renamed.

getModifiedTime

public Time getModifiedTime()
                     throws IOException
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
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.

addSpecialField

public void addSpecialField(int fieldCode)
                     throws IllegalArgumentException
Use this to add one of the reserved fields (the XXXX_FIELD) values.

Throws:
IllegalArgumentException

enableSynchronization

public void enableSynchronization(int syncOptions)
                           throws IOException
This tells the database to include the OID_FIELD, FLAGS_FIELD, CREATED_FIELD and MODIFIED_FIELD information with each record so that it can be synchronized with a other databases. This is only guaranteed to work when you first initialize a Database. Some implementations may allow you to do this even if records already exists, but if it does not then an IOException will be thrown. This will save the database.

Throws:
IOException

enableSynchronization

public boolean enableSynchronization(Handle h,
                                     int syncOptions)
                              throws IOException
This tells the database to include the OID_FIELD, FLAGS_FIELD, CREATED_FIELD and MODIFIED_FIELD information with each record so that it can be synchronized with a other databases. This is only guaranteed to work when you first initialize a Database. Some implementations may allow you to do this even if records already exists, but if it does not then an IOException will be thrown. This will save the database.

Throws:
IOException

getIdentifier

public int getIdentifier()
                  throws IOException
Get a unique identifier for this database - used for synchronizing.

Throws:
IOException

setSynchronizedTime

public void setSynchronizedTime(int remoteDatabaseID,
                                Time syncTime)
                         throws IOException
Throws:
IOException

getSynchronizedTime

public Time getSynchronizedTime(int remoteDatabaseID)
                         throws IOException
Throws:
IOException

getEntriesCount

public long getEntriesCount()
                     throws IOException
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.

Returns:
the number of entries in the database if known, or -1 if unknown.
Throws:
IOException - on error.

estimateEntriesCount

public long estimateEntriesCount()
                          throws IOException
If getEntriesCount() returns -1, indicating that the number of entries is unknown, then this method will attempt to estimate the entries count via a quick non-blocking method without resorting to counting each entry. This method may also return -1, indicating that the database cannot even estimate the number of entries and a countEntries() will need to be done if you want any indication of the size of the database.

Returns:
the estimate of the number of entries in the database, or the exact number if it is known, or -1 if it cannot even estimate the number of entries.
Throws:
IOException - on error.

countEntries

public Handle countEntries()
If getEntriesCount() returns -1, indicating that the number of entries is unknown, then this method will count the entries by counting each one if necessary. Since this may take some time it is done in a separate thread and a Handle is returned that can monitor and stop the count if necessary. On completion the handle's returnValue will be an ewe.sys.Long() object holding the count of the entries.

Returns:
a Handle which you can monitor and stop the count. On successful completion the returnValue will hold the number of entries.

entries

public Iterator entries()
                 throws IOException
This returns an Iterator that you can use to go through the entries in the database.

The getNext() method of the returned iterator may throw a DatabaseIOException if there is an IO error when retrieving the next entry.

Throws:
IOException

entries

public Iterator entries(ObjectFinder entry)
                 throws IOException
This returns an Iterator that you can use to go through the entries in the database. Only the entries that the ObjectFinder returns true for lookingFor() will be provided by the getNext() method of the iterator.

The getNext() method of the returned iterator may throw a DatabaseIOException if there is an IO error when retrieving the next entry.

Throws:
IOException

entries

public Iterator entries(Object searchData,
                        Comparer comparer)
                 throws IOException
This returns an Iterator that you can use to go through the entries in the database. Only the entries that the Comparer returns 0 for when comparing the entry with the searchData will be provided by the getNext() method of the iterator.

The getNext() method of the returned iterator may throw a DatabaseIOException if there is an IO error when retrieving the next entry.

Throws:
IOException

indexBy

public boolean indexBy(Handle h,
                       int sortID,
                       String name)
                throws IOException,
                       IllegalArgumentException
This tells the Database to keep an index for a particular sort ID and optional distinct name. If an index of the same name and sortID is already being kept then this will simply return true immediately. Otherwise the index will be created.

Creating a new index will usually involve sorting all the entries of the database so this may take some time to complete and you can monitor and abort the operation using the Handle parameter.

Parameters:
h - An optional handle that you can use to monitor and control any index creation operation.
sortID - A valid sort ID for the database.
name - A distinct name for the index. If it is null then the same name as the sort ID will be used.
Returns:
true if the operation completed successfully, false if it was aborted.
Throws:
IOException - If an IO error occured using the database.
IllegalArgumentException - if the sort ID is invalid.

indexBy

public boolean indexBy(Handle h,
                       Class databaseEntryComparer,
                       String name)
                throws IOException,
                       IllegalArgumentException
This tells the Database to keep an index using a particular Comparer class and distinct name. If an index of the same name is already being kept then this will simply return true immediately. Otherwise the index will be created.

Creating a new index will usually involve sorting all the entries of the database so this may take some time to complete and you can monitor and abort the operation using the Handle parameter.

Parameters:
h - An optional handle that you can use to monitor and control any index creation operation.
databaseEntryComparer - A valid object that implements DatabaseEntryComparer
name - A distinct name for the index, which must not be null.
Returns:
true if the operation completed successfully, false if it was aborted.
Throws:
IOException - If an IO error occured using the database.
IllegalArgumentException - if the comparer or name is invalid.

indexBy

public void indexBy(int sortID)
             throws IOException,
                    IllegalArgumentException
This is a convenience method for the other indexBy method. It will simply call indexBy(Handle h, int sortID, String name) using a null "h" and "name" parameters.

Parameters:
sortID - A valid sort ID for the database.
Returns:
true if the operation completed successfully, false if it was aborted.
Throws:
IOException - If an IO error occured using the database.
IllegalArgumentException - if the sort ID is invalid.

isIndexedBy

public boolean isIndexedBy(int sortID)
This returns if the Database has at least one index that uses the specified sort ID.


getIndexes

public IndexEntry[] getIndexes()
This returns all the indexes used by the Database. You can use getIndexSort(String indexName) to find out which sort ID is being used by each of the indexes returned.

Returns:
An array of index names.

getCurrentState

public long getCurrentState()
Get the current changed state of the Database. You can check if the Database have been changed later by calling hasChangedSince().

Returns:
a reference to its current state.

hasChangedSince

public boolean hasChangedSince(long previousState)
Return if the Database has changed since the previous state.


change

public void change()
Mark the Database as having been changed in some way.


getEventDispatcher

public EventDispatcher getEventDispatcher()
Get an EventDispatcher which you can use to attach EventListeners to, for listening to the events being generated by the Database.


openStreamForWriting

public Stream openStreamForWriting(String name,
                                   boolean append)
                            throws IOException
Open a Stream into the database to save some sort of meta-data. Calling this method does not guarantee a consistent state if an error occurs. That is to say, if an error occurs before close() is called on the Stream, then it is possible that incomplete data will be saved.

Parameters:
name - The name of the meta-data Stream.
append - Set this true if you want to add to the data already stored in the stream.
Returns:
A Stream that you can write meta-data to.
Throws:
IOException - if an error occurs.

openStreamForReplacing

public Stream openStreamForReplacing(String name)
                              throws IOException
Open a Stream into the database to save some sort of meta-data. Calling this method will guarantee a consistent state if an error occurs. That is to say, if an error occurs before close() is called on the Stream, then the new data is lost and the original data (if present) will still be accessible for reading the next time the Database is opened. If the close() method completes successfully, then the new data will then be available for reading.

Parameters:
name - The name of the meta-data Stream.
Returns:
A Stream that you can write meta-data to.
Throws:
IOException - if an error occurs.

openStreamForReading

public Stream openStreamForReading(String name)
                            throws IOException
Open a Stream into the database to read some sort of meta-data.

Parameters:
name - The name of the meta-data Stream.
Returns:
A Stream that you can write meta-data to.
Throws:
IOException - if an error occurs or if the Stream does not exist.

deleteStream

public boolean deleteStream(String name)
                     throws IOException
Delete a Stream from the Database.

Parameters:
name - The name of the meta-data Stream.
Returns:
true if the stream was found and deleted, false if it was not found.
Throws:
IOException - if an error occurs.
IOException - if an error occurs.

getStreamLength

public long getStreamLength(String name)
                     throws IOException
Returns the length of a meta-data Stream stored in the Database, or -1 if the named Stream does not exist. You can use this method to test for the existance of a Stream.

Parameters:
name - the name of the Stream.
Returns:
the length of a meta-data Stream stored in the Database, or -1 if the named Stream
Throws:
IOException - if an error occurs.

setDataValidator

public void setDataValidator(DataValidator validator)
Set a DataValidator to validate data before it is saved in the Database. Call save() on the Database to save the validator.

Parameters:
validator - A validator or null to clear the validator.
Throws:
IOException - if there was an error saving the validator.

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

getMetaData

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

deleteMetaData

public boolean deleteMetaData(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

metaDataLength

public int metaDataLength(String name)
                   throws IOException
Throws:
IOException

enableLookupMode

public boolean enableLookupMode()
                         throws IOException
This method tells the database that it will be used for read-only lookups and that it can close its underlying file if it wishes - and later re-open it when lookups are done without re-reading the database info.

Not all Databases may support this and if it does not, it will return false - although normal database operations will not be affected. In other words - if this method returns false, the application can continue as if it returned true - but its operations will not be optimized in this way.

Returns:
true if this optimization is enabled, false if not.
Throws:
IOException - if an IO error occurs.

openLookup

public void openLookup()
                throws IOException
This is used with enableLookupMode() - it tells the database that data is about to be read in and if the underlying file is closed - then it should be re-opened and kept open until closeLookup() is called. Each call to openLookup() should have a corresponding call to closeLookup().

Throws:
IOException - if an IO error occurs.

closeLookup

public void closeLookup()
                 throws IOException
This is used with enableLookupMode() - it tells the database that data reading is complete and the underlying file may be closed. Each call to openLookup() should have a corresponding call to closeLookup().

Throws:
IOException - if an IO error occurs.