ewe.database
Interface FoundEntries

All Superinterfaces:

DatabaseTypes

All Known Implementing Classes:

FoundEntriesObject

public interface FoundEntries

extends DatabaseTypes

A FoundEntries object holds a sorted view of a set of records in a Database. The actual data is not stored in the FoundEntries, rather references to the records are held instead (usually as 32-bit integers or other such value).

You get a FoundEntries object by calling one of the getFoundEntries() methods on the Database or you can call getEmptyEntries() to get an empty FoundEntries which you can then add records to.

You use FoundEntries to retrieve, add, delete and modify records and the FoundEntries will maintain its sort state during these operations.

You can get an EntriesView object for a FoundEntries using getEmptyEntries() or getFullView() and then use that EntriesView object to search the data using any criteria. You can then create a new FoundEntries from the results of the search using getSubSet() and then create a new FoundEntries object sorted by some other criteria using one of the sort() methods.

Field Summary

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	add(DatabaseEntry toAdd) This saves a new entry to the database AND adds it to this FoundEntries object.
int	addData(Object data) Add a new entry using the data object.
void	change() Mark the FoundEntries as having been changed in some way.
void	delete(int index) This deletes the data AND removes it from this FoundEntries list.
void	erase(int index) This erases the data without marking it as deleted AND removes it from this FoundEntries list.
void	exclude(DatabaseEntry entry) Exclude the entry from this FoundEntries if it is in it.
void	exclude(int index) Exclude the entry from this FoundEntries.
boolean	excludeAll(Handle h, EntriesView viewFromOtherFoundEntries) Exclude all the entries as specified from the view of another FoundEntries from this FoundEntries.
IntArray	filterAll(Handle h, ObjectFinder finder, IntArray dest) Find, using an entry by entry sequential search, all entries in the FoundEntries that match the criteria as specified by the selector.
IntArray	findAll(Handle h, EntrySelector selector, IntArray dest) Find, using a binary chop search, all entries in the FoundEntries that match the criteria as specified by the selector.
int	findFirst(Handle h, Object searchData, boolean hasWildCards) Find the index of the first entry that matches a search criteria.
int	findFirst(Handle h, Object searchData, Comparer comparer) This finds the first index of the entry which (according to the provided Comparer) matches a search criteria.
int	findInsertIndex(DatabaseEntry toAdd) Find the index where the specified entry would be added in the FoundEntries.
int	findLast(Handle h, Object searchData, boolean hasWildCards) Find the index of the last entry that matches a search criteria.
int	findLast(Handle h, Object searchData, Comparer comparer) This finds the last index of the entry which (according to the provided Comparer) matches a search criteria.
Range	findRange(Handle h, EntrySelector selector, Range dest) Find the range of indexes which match the search criteria as specified in the EntrySelector parameter.
DatabaseEntry	get(int index) Get the data at the specified index, creating a new DatabaseEntry to get it from.
DatabaseEntry	get(int index, DatabaseEntry data) Get the data at the specified index.
FoundEntries	getCopy() Get a full copy of this FoundEntries, including the entries themselves.
long	getCurrentState() Get the current changed state of the FoundEntries.
Object	getData(int index) Get the data object from the specified index.
Object	getData(int index, Object destination) Get the data object from the specified index.
Database	getDatabase() Get the database associated with the FoundEntries.
EntriesView	getEmptyView() Get a new EntriesView for this FoundEntries that is initially empty.
EntrySelector	getEntrySelector(Object searchData, boolean hasWildCards) Get an EntrySelector for the data given the search data.
EventDispatcher	getEventDispatcher() Get the EventDispatcher for this FoundEntries.
EntriesView	getFullView(EntriesView destination) Get an EntriesView that contains all the entries in this FoundEntries.
DatabaseEntry	getNew() Create a new DatabaseEntry for this FoundEntries.
Comparer	getSortComparer() Return the current sort Comparer.
int[]	getSortCriteria() Return the current sort criteria if one was used.
int	getSortEntry() Return the ID of the sort used to sort the database by if one was used.
FoundEntries	getSubSet(EntriesView view) Get a SubSet of this FoundEntries using the indexes included in the view.
boolean	hasChangedSince(long previousState) Return if the FoundEntries has changed since the previous state.
int	include(DatabaseEntry entry) Add an entry to the FoundEntries if it was not added before.
boolean	includeAll(Handle h, EntriesView viewFromOtherFoundEntries) Include all the entries as specified from the view of another FoundEntries in this FoundEntries.
int	indexOf(DatabaseEntry entry) Return the index of the entry in the FoundEntries object.
boolean	isAllInclusive() If a FoundEntries is all inclusive then adding entries to the database will automatically add the new entries to the FoundEntries.
boolean	isSorted() Return if the entries are sorted.
boolean	searchIsCompatibleWithSortState(int[] criteria) Check if the proposed search criteria is compatible with the FoundEntries current sort.
int	set(int index, DatabaseEntry changed) This saves changes to the data entry and will rearrange current entries to maintain its sort order.
void	setAddNewEntriesFirst(boolean addFirst) If you add a new entry to a sorted FoundEntries, then that new entry may match exactly other entries already in the FoundEntries.
void	setAllInclusive(boolean allInclusive) If a FoundEntries is all inclusive then adding entries to the database will automatically add the new entries to the FoundEntries.
int	setData(int index, Object data) Set the data at the specified index using the data object.
int	size() Return the number of entries in the FoundEntries.
Handle	sort(Comparer comparer) Sort the found entries in a separate thread.
FoundEntries	sort(Handle h, Comparer comparer) This sorts the FoundEntries in the current thread using the specified Comparer.
FoundEntries	sort(Handle h, int sortID) This sorts the FoundEntries in the current thread using the specified sortID.
FoundEntries	sort(Handle h, int[] criteria) This sorts the FoundEntries in the current thread using the specified sortID.
Handle	sort(int sortID) Sort the found entries in a separate thread.
Handle	sort(int[] criteria) Sort the found entries in a separate thread.
int	store(int index, DatabaseEntry changed) This saves changes to the entry but does not modify its special synchronization fields.

Method Detail

getDatabase

public Database getDatabase()

Get the database associated with the FoundEntries.

size

public int size()

Return the number of entries in the FoundEntries.

getNew

public DatabaseEntry getNew()

Create a new DatabaseEntry for this FoundEntries.

add

public int add(DatabaseEntry toAdd)
        throws IOException

This saves a new entry to the database AND adds it to this FoundEntries object. It returns the index at which the new value was placed such that it maintains the sort order.

Throws:

IOException

delete

public void delete(int index)
            throws IOException

This deletes the data AND removes it from this FoundEntries list.

Throws:

IOException

erase

public void erase(int index)
           throws IOException

This erases the data without marking it as deleted AND removes it from this FoundEntries list.

Throws:

IOException

get

public DatabaseEntry get(int index,
                         DatabaseEntry data)
                  throws IOException

Get the data at the specified index.

Parameters:

index - The index to read from.

data - a destination DatabaseEntry, which can be null.

Returns:

the destination DatabaseEntry or a newly created one.

Throws:

IOException - on error.

get

public DatabaseEntry get(int index)
                  throws IOException

Get the data at the specified index, creating a new DatabaseEntry to get it from.

Parameters:

index - The index to read from.

Returns:

the destination DatabaseEntry or a newly created one.

Throws:

IOException - on error.

indexOf

public int indexOf(DatabaseEntry entry)

Return the index of the entry in the FoundEntries object.

Parameters:

entry - the entry to look for.

Returns:

the index of the entry or -1 if it is not found.

sort

public FoundEntries sort(Handle h,
                         int[] criteria)
                  throws IOException

This sorts the FoundEntries in the current thread using the specified sortID. Other threads will be allowed to run and can monitor the progress and stop the sort by calling stop() on the handle (if it is not null).

Parameters:

h - the Handle for monitoring the sort. This can be null but if it is the possibility exists that the sort may run natively thereby not giving other threads a chance to run.

criteria - the sort criteria.

Returns:

a new FoundEntries or null if the sort was aborted.

Throws:

IOException - if there was an error reading data for sorting.

sort

public Handle sort(int[] criteria)
            throws IOException

Sort the found entries in a separate thread. If there is an error or the sorting is aborted the FoundEntries will be in its original state.

Parameters:

criteria - The criteria for sorting.

Returns:

a Handle that you can use to monitor the sorting. When the Handle reports success the returnValue of the handle will hold a new FoundEntries object which contains the entries re-sorted by the specified criteria.

Throws:

IOException

sort

public FoundEntries sort(Handle h,
                         int sortID)
                  throws IllegalArgumentException,
                         IOException

This sorts the FoundEntries in the current thread using the specified sortID. Other threads will be allowed to run and can monitor the progress and stop the sort by calling stop() on the handle (if it is not null).

Parameters:

h - the Handle for monitoring the sort. This can be null but if it is the possibility exists that the sort may run natively thereby not giving other threads a chance to run.

sortID - The sortID in the database to sort by.

Returns:

a new FoundEntries or null if the sort was aborted.

Throws:

IllegalArgumentException - if the sortID is not valid.

IOException - if there was an error reading data for sorting.

sort

public Handle sort(int sortID)
            throws IllegalArgumentException

Sort the found entries in a separate thread.

Parameters:

sortID - The sortID in the database to sort by.

Returns:

a Handle that you can use to monitor the sorting. When the Handle reports success the returnValue of the handle will hold a new FoundEntries object which contains the entries re-sorted by the specified id.

Throws:

IllegalArgumentException

sort

public FoundEntries sort(Handle h,
                         Comparer comparer)
                  throws IOException

This sorts the FoundEntries in the current thread using the specified Comparer. Other threads will be allowed to run and can monitor the progress and stop the sort by calling stop() on the handle (if it is not null).

Parameters:

h - the Handle for monitoring the sort. This can be null but if it is the possibility exists that the sort may run natively thereby not giving other threads a chance to run.

comparer - a Comparer used to compare each entry.

Returns:

a new FoundEntries or null if the sort was aborted.

Throws:

IOException - if there was an error reading data for sorting.

sort

public Handle sort(Comparer comparer)
            throws IOException

Sort the found entries in a separate thread.

Parameters:

comparer - a Comparer used to compare each entry.

Returns:

a Handle that you can use to monitor the sorting. When the Handle reports success the returnValue of the handle will hold a new FoundEntries object which contains the entries re-sorted by the specified comparer.

Throws:

IOException

getCopy

public FoundEntries getCopy()

Get a full copy of this FoundEntries, including the entries themselves.

isSorted

public boolean isSorted()

Return if the entries are sorted.

getSortEntry

public int getSortEntry()

Return the ID of the sort used to sort the database by if one was used. If a non-standard Comparer was used, or if the entries are not sorted, this will return 0.

getSortCriteria

public int[] getSortCriteria()

Return the current sort criteria if one was used. If a non-standard Comparer was used, or if the entries are not sorted, this will return null.

getSortComparer

public Comparer getSortComparer()

Return the current sort Comparer. This will always return a valid object as long as the FoundEntries was sorted via some method.

getCurrentState

public long getCurrentState()

Get the current changed state of the FoundEntries. You can check if the FoundEntries have been changed later by calling hasChangedSince(). The changed state does not have to do with the data stored in the database but rather whether the internal index table has changed. If this FoundEntries is stored in a file then if it has changed since the last state then it would need to be saved again.

Returns:

a reference to its current state.

hasChangedSince

public boolean hasChangedSince(long previousState)

Return if the FoundEntries has changed since the previous state.

change

public void change()

Mark the FoundEntries as having been changed in some way.

getData

public Object getData(int index,
                      Object destination)
               throws IllegalStateException,
                      IllegalArgumentException,
                      IOException

Get the data object from the specified index.

Parameters:

index - the index in the FoundEntries object.

destination - a destination object. If this is null a new one will be created if possible.

Returns:

the destination or new object.

Throws:

IllegalArgumentException - if the destination object is not the right type.

IllegalStateException - if a new object was requested but could not be created.

IOException - if there is an error reading the data.

getData

public Object getData(int index)
               throws IllegalStateException,
                      IOException

Get the data object from the specified index.

Parameters:

index - the index in the FoundEntries object.

Returns:

the data in a new Object.

Throws:

IllegalStateException - if a new object could not be created.

IOException - if there is an error reading the data.

setData

public int setData(int index,
                   Object data)
            throws IllegalArgumentException,
                   IOException

Set the data at the specified index using the data object. This will maintain the sort order.

Parameters:

index - the index in the FoundEntries object.

data - the data object.

Returns:

the new index of the data.

Throws:

IllegalArgumentException - if the destination object is not the right type.

IOException - if there is an error writing the data.

set

public int set(int index,
               DatabaseEntry changed)
        throws IOException

This saves changes to the data entry and will rearrange current entries to maintain its sort order.

Parameters:

index - The index of the entry.

changed - the changed entry.

Returns:

the index where the entry is now.

Throws:

IOException - on error.

store

public int store(int index,
                 DatabaseEntry changed)
          throws IOException

This saves changes to the entry but does not modify its special synchronization fields. It will rearrange current entries to maintain its sort order.

Parameters:

index - The index of the entry.

changed - the changed entry.

Returns:

the index where the entry is now.

Throws:

IOException - on error.

addData

public int addData(Object data)
            throws IllegalArgumentException,
                   IOException

Add a new entry using the data object. This maintains the sort order.

Parameters:

data - the data object.

Returns:

the index of the new entry.

Throws:

IllegalArgumentException - if the destination object is not the right type.

IOException - if there is an error writing the data.

include

public int include(DatabaseEntry entry)
            throws IllegalArgumentException,
                   IOException

Add an entry to the FoundEntries if it was not added before. This does not change the data in the database.

Parameters:

entry - the entry to include.

Returns:

the index of the entry as it is now in the database.

Throws:

IllegalArgumentException - if the entry is not a valid saved entry.

IOException - on error.

exclude

public void exclude(DatabaseEntry entry)
             throws IllegalArgumentException,
                    IOException,
                    IllegalStateException

Exclude the entry from this FoundEntries if it is in it.

Parameters:

entry - the entry to exclude.

Throws:

IllegalArgumentException - if the entry is not a valid saved entry.

IOException - on error.

IllegalStateException - if the FoundEntries is all-inclusive or is a DatabaseIndex.

exclude

public void exclude(int index)
             throws IOException,
                    IllegalStateException

Exclude the entry from this FoundEntries.

Parameters:

index - the index of the entry.

Throws:

IOException - on error.

IllegalStateException - if the FoundEntries is all-inclusive or is a DatabaseIndex.

setAllInclusive

public void setAllInclusive(boolean allInclusive)
                     throws IllegalArgumentException

If a FoundEntries is all inclusive then adding entries to the database will automatically add the new entries to the FoundEntries. FoundEntries associated with a DatabaseIndex are all inclusive.

Parameters:

allInclusive - true to set the FoundEntries to all inclusive, false to set to be not all inclusive.

Throws:

IllegalArgumentException - if you try to set a FoundEntries associated with a DatabaseIndex to non all inclusive.

isAllInclusive

public boolean isAllInclusive()

If a FoundEntries is all inclusive then adding entries to the database will automatically add the new entries to the FoundEntries. FoundEntries associated with a DatabaseIndex are all inclusive.

Returns:

true if the FoundEntries is considered all inclusive.

setAddNewEntriesFirst

public void setAddNewEntriesFirst(boolean addFirst)

If you add a new entry to a sorted FoundEntries, then that new entry may match exactly other entries already in the FoundEntries. The FoundEntries then must decide whether to add the new one before the other matching entries or after the other matching entries. This method tells the FoundEntries whether to add the new one before or after(the default).

Parameters:

addFirst - if this is true then the new entry is added before the matching entries.

searchIsCompatibleWithSortState

public boolean searchIsCompatibleWithSortState(int[] criteria)

Check if the proposed search criteria is compatible with the FoundEntries current sort. If this returns false then a call to search() will have to filter all the data (i.e. step through each one in turn). If it returns true then a search() will perform a quick binary search on the data.

Parameters:

criteria - the proposed sort criteria.

Returns:

true if it is compatible with the current sort, false if not.

getEntrySelector

public EntrySelector getEntrySelector(Object searchData,
                                      boolean hasWildCards)
                               throws IllegalStateException

Get an EntrySelector for the data given the search data.

Parameters:

searchData - the data to search for.

hasWildCards - this should be true if the data contains wild cards.

Returns:

a new EntrySelector for the data given the search data.

Throws:

IllegalStateException

getEmptyView

public EntriesView getEmptyView()

Get a new EntriesView for this FoundEntries that is initially empty.

getFullView

public EntriesView getFullView(EntriesView destination)

Get an EntriesView that contains all the entries in this FoundEntries.

Parameters:

destination - an optional EntriesView object to hold the data.

Returns:

the destination or new EntriesView.

getSubSet

public FoundEntries getSubSet(EntriesView view)

Get a SubSet of this FoundEntries using the indexes included in the view. If this FoundEntries is sorted the specified view will first be sorted before the new FoundEntries is created.

includeAll

public boolean includeAll(Handle h,
                          EntriesView viewFromOtherFoundEntries)
                   throws IOException

Include all the entries as specified from the view of another FoundEntries in this FoundEntries.

Parameters:

h - an optional handle used to monitor and possibly abort the process.

viewFromOtherFoundEntries - a view into another FoundEntries object.

Returns:

true if the operation completed successfully, false if it did not.

Throws:

IOException

excludeAll

public boolean excludeAll(Handle h,
                          EntriesView viewFromOtherFoundEntries)
                   throws IOException

Exclude all the entries as specified from the view of another FoundEntries from this FoundEntries.

Parameters:

h - an optional handle used to monitor and possibly abort the process.

viewFromOtherFoundEntries - a view into another FoundEntries object.

Returns:

true if the operation completed successfully, false if it did not.

Throws:

IOException

findFirst

public int findFirst(Handle h,
                     Object searchData,
                     Comparer comparer)
              throws IOException,
                     IllegalStateException,
                     HandleStoppedException

This finds the first index of the entry which (according to the provided Comparer) matches a search criteria. A binary chop search is done so it is assumed that all indexes between the one found by findFirst and by findLast inclusive (for the same finder) will also match. It returns -1 if no match could be found.

During the search the comparer will have its compare() method called with the searchData parameter object as the first parameter and a DatabaseEntry object as the second parameter. The comparer should return

 <0 if the DatabaseEntry is considered greater than the search data.
 0 if the DatabaseEntry is considered to match the search data.
 >0 if the DatabaseEntry is considered less than the search data.
 
 The Comparer should NOT take into account if the SORT_DESCENDING option
 is set - that will be taken care of by the search routine.





Parameters:
h - an optional handle used to monitor and possibly abort the process.
searchData - search data possibly used by the comparer - this can be null.
comparer - a comparer to compare the search data with the data in records of the FoundEntries.
Returns:
the index of the first matching entry or -1 if no match was found.
Throws:
IOException
IllegalStateException - if this FoundEntries is not sorted.
HandleStoppedException - if the operation was aborted.

findLast

public int findLast(Handle h,
                    Object searchData,
                    Comparer comparer)
             throws IOException,
                    IllegalStateException,
                    HandleStoppedException

This finds the last index of the entry which (according to the provided Comparer) matches a search criteria. A binary chop search is done so it is assumed that all indexes between the one found by findFirst and by findLast inclusive (for the same finder) will also match. It returns -1 if no match could be found.

During the search the comparer will have its compare() method called with the searchData parameter object as the first parameter and a DatabaseEntry object as the second parameter. The comparer should return

 <0 if the DatabaseEntry is considered greater than the search data.
 0 if the DatabaseEntry is considered to match the search data.
 >0 if the DatabaseEntry is considered less than the search data.
 
 The Comparer should NOT take into account if the SORT_DESCENDING option
 is set - that will be taken care of by the search routine.





Parameters:
h - an optional handle used to monitor and possibly abort the process.
searchData - search data possibly used by the comparer.
comparer - a comparer to compare the search data with the data in records of the FoundEntries.
Returns:
the index of the first matching entry or -1 if no match was found.
Throws:
IOException
IllegalStateException - if this FoundEntries is not sorted.
HandleStoppedException - if the operation was aborted.

findFirst

public int findFirst(Handle h,
                     Object searchData,
                     boolean hasWildCards)
              throws IOException,
                     IllegalStateException,
                     HandleStoppedException

Find the index of the first entry that matches a search criteria.

Parameters:

h - an optional handle used to monitor and possibly abort the process.

searchData - search data possibly used by the comparer.

hasWildCards - set this true if the search data has wildcard data (e.g. '*' characters).

Returns:

the index of the first matching entry or -1 if no match was found.

Throws:

IOException

IllegalStateException - if this FoundEntries is not sorted.

HandleStoppedException - if the operation was aborted.

findLast

public int findLast(Handle h,
                    Object searchData,
                    boolean hasWildCards)
             throws IOException,
                    IllegalStateException,
                    HandleStoppedException

Find the index of the last entry that matches a search criteria.

Parameters:

h - an optional handle used to monitor and possibly abort the process.

searchData - search data possibly used by the comparer.

hasWildCards - set this true if the search data has wildcard data (e.g. '*' characters).

Returns:

the index of the first matching entry or -1 if no match was found.

Throws:

IOException

IllegalStateException - if this FoundEntries is not sorted.

HandleStoppedException - if the operation was aborted.

findInsertIndex

public int findInsertIndex(DatabaseEntry toAdd)
                    throws IOException

Find the index where the specified entry would be added in the FoundEntries.

Throws:

IOException

findRange

public Range findRange(Handle h,
                       EntrySelector selector,
                       Range dest)
                throws IOException,
                       IllegalArgumentException

Find the range of indexes which match the search criteria as specified in the EntrySelector parameter.

Parameters:

h - An optional handle that can be used to monitor the progress of the operation.

selector - An EntrySelector used to determine which entries to include in the range.

dest - An optional destination Range object.

Returns:

The destination or new Range object. If it returns null then the search was aborted because the stop() method was called on the Handle. If it returns a Range where the "first" field is less than zero then this indicates that no entries match. Otherwise it will return a valid Range where the matching entries are specified by the "first" and "last" fields of the returned Range (first and last are both inclusive).

Throws:

IOException - On error reading the database.

IllegalArgumentException - If the EntrySelector specifies a search that is not compatible with the sort criteria used by the FoundEntries.

findAll

public IntArray findAll(Handle h,
                        EntrySelector selector,
                        IntArray dest)
                 throws IOException

Find, using a binary chop search, all entries in the FoundEntries that match the criteria as specified by the selector.

Parameters:

h - an optional handle used to monitor and possibly abort the search.

selector - an EntrySelector created using getEntrySelector().

dest - an optional destination IntArray.

Returns:

the destination IntArray or a new IntArray if dest was null. If the operation was aborted, null will be returned.

Throws:

IOException

filterAll

public IntArray filterAll(Handle h,
                          ObjectFinder finder,
                          IntArray dest)
                   throws IOException

Find, using an entry by entry sequential search, all entries in the FoundEntries that match the criteria as specified by the selector.

Parameters:

h - an optional handle used to monitor and possibly abort the search.

finder - an ObjectFinder used to select the entries.

dest - an optional destination IntArray.

Returns:

the destination IntArray or a new IntArray if dest was null. If the operation was aborted, null will be returned.

Throws:

IOException

getEventDispatcher

public EventDispatcher getEventDispatcher()

Get the EventDispatcher for this FoundEntries.