ewe.database
Class EntriesView

java.lang.Object
  ewe.database.EntriesView

public class EntriesView

extends Object

An EntriesView is a view into a FoundEntries object while a FoundEntries object is a view into a database. An EntriesView is effectively a set of indexes that identify a set of entries in the associated FoundEntries. An EntriesView is a better object to use when displaying or manipulating a set of DatabaseEntries because you can re-order an EntriesView any way you wish without affecting the sorted order of its source FoundEntries. Then, re-sorting the EntriesView becomes a simple task because it simply involves sorting the indexes within the view (which can be done very quickly since it does not need to access the database to do this).

Field Summary

boolean

allInclusive

Constructor Summary

EntriesView(FoundEntries fe)
Create a new EntriesView for a FoundEntries, but which initially contains no data.

Method Summary

int	add(DatabaseEntry de) Add a new DatabaseEntry to the view (it is added to the end) and save it in the FoundEntries and database.
int	addData(Object data) Add a new record to the view (it is added to the end) and save it in the FoundEntries and database.
void	addRange(int startIndex, int endIndex) Add a range of indexes to the EntriesView.
void	change() Mark the FoundEntries as having been changed in some way.
protected void	changed(int oldIndex, int newIndex)
void	clear() Clear the EntriesView.
void	closeLookup() This is used with enableLookupMode() - it tells the database that data reading is complete and the underlying file may be closed.
void	delete(int indexInView) Delete the record at the specified index from the database.
protected void	dispatchEvent(int type)
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.
void	exclude(DatabaseEntry entry) Exclude the entry from this view.
void	exclude(EntriesView other) Exclude all the entries in the other view from this view.
void	exclude(int indexInFoundEntries) Exclude the entry from this view.
void	excludeAt(int indexInView) Exclude the entry form this view.
EntriesView	filter(Handle h, Object searchData) Filter all entries in the associated FoundEntries and add them to this EntriesView.
EntriesView	filter(Handle h, Object searchData, boolean hasWildCards) Filter all entries in the associated FoundEntries and add them to this EntriesView.
Handle	filter(Object searchData) Filter all entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the filtering.
Handle	filter(Object searchData, boolean hasWildCards) Filter all entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the filtering.
DatabaseEntry	get(int indexInView) Get the DatabaseEntry at the specified index in the view.
DatabaseEntry	get(int indexInView, DatabaseEntry de) Get the DatabaseEntry at the specified index in the view.
long	getCurrentState() Get the current changed state of the FoundEntries.
Object	getData(int indexInView) Get the DatabaseEntry at the specified index in the view as a data object.
Object	getData(int indexInView, Object dest) Get the DatabaseEntry at the specified index in the view as a data object.
EntriesView	getEmptyView() Use this if you used enableLookupMode() to get a new empty EntriesView for the same FoundEntries as this view.
EventDispatcher	getEventDispatcher() Get the EventDispatcher for this view.
FoundEntries	getFoundEntries() Get the FoundEntries for the view.
void	getFullFiew() Refresh this EntriesView to view the entire source FoundEntries.
int[]	getIndexes() Get the indexes of the entries in the FoundEntries in this view.
IntArray	getIndexes(IntArray destination) Append all the indexes stored in this EntriesView into an IntArray.
int[]	getIndexesInFoundEntries() Get all the indexes as an arry of ints.
DatabaseEntry	getNew() Return a new DatabaseEntry for use with this database.
boolean	hasChangedSince(long previousState) Return if the FoundEntries has changed since the previous state.
int	include(DatabaseEntry entry) Include the specified entry in this view, but only if it is already included in its FoundEntries.
void	include(EntriesView other) Include all the entries in the other view in this view.
int	include(int indexInFoundEntries) Include the specified entry in this view.
void	includeAll(IntArray toAdd) Add all the indexes - sorting this view before the add is done.
int	index(int indexInView) This is the same as indexInFoundEntries().
int	indexInFoundEntries(int indexInView) This is the same as index().
int	indexInView(DatabaseEntry de) Find out the index of the specified entry in this view - if it exists in the view.
int	indexInView(int indexInFoundEntries) Determine the index of the database entry in the View, based on its index in the FoundEntries.
boolean	isSorted(boolean descending) Checks if the indexes in the EntriesView are sorted as per the sort criteria used by the source FoundEntries.
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.
void	removeRange(int startIndex, int endIndex) Add a range of indexes from the EntriesView.
Handle	search(EntrySelector selector) Search for entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the searching.
EntriesView	search(Handle h, EntrySelector selector) Search for entries in the associated FoundEntries and add them to this EntriesView.
EntriesView	search(Handle h, Object searchData) Search for entries in the associated FoundEntries and add them to this EntriesView.
EntriesView	search(Handle h, Object searchData, boolean hasWildCards) Search for entries in the associated FoundEntries and add them to this EntriesView.
EntriesView	search(Handle h, ObjectFinder finder) Search for entries in the associated FoundEntries and add them to this EntriesView.
Handle	search(Object searchData) Search for entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the searching.
Handle	search(Object searchData, boolean hasWildCards) Search for entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the searching.
Handle	search(ObjectFinder finder) Search for entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the searching.
void	set(int indexInView, DatabaseEntry de) Change the database entry at the specified index.
void	setData(int indexInView, Object data) Change the database entry at the specified index.
int	size() Return the number of indexes in the view.
void	sort(boolean descending) Sort the indexes in the EntriesView.
void	store(int indexInView, DatabaseEntry de) Store the DatabaseEntry at the specified index without modifying any of its special synchronization fields.
IntArray	toRanges(IntArray dest) Convert the indexes in this view to a sequence of ranges.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

allInclusive

public boolean allInclusive

Constructor Detail

EntriesView

public EntriesView(FoundEntries fe)

Create a new EntriesView for a FoundEntries, but which initially contains no data.

Method Detail

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.

isSorted

public boolean isSorted(boolean descending)

Checks if the indexes in the EntriesView are sorted as per the sort criteria used by the source FoundEntries. The sorted state of the EntriesView can change as data is added or edited in it.

getFoundEntries

public FoundEntries getFoundEntries()

Get the FoundEntries for the view.

getIndexes

public int[] getIndexes()

Get the indexes of the entries in the FoundEntries in this view.

getIndexes

public IntArray getIndexes(IntArray destination)

Append all the indexes stored in this EntriesView into an IntArray.

Parameters:

destination - The destination IntArray. If it is null a new one is created and returned.

Returns:

the destination IntArray or a new IntArray.

clear

public void clear()

Clear the EntriesView. It will then contain no indexes within it.

sort

public void sort(boolean descending)

Sort the indexes in the EntriesView. This is a fast sort that only sorts indexes without having to refer to the data within the database.

Parameters:

descending - true if you want it sorted in descending order.

addRange

public void addRange(int startIndex,
                     int endIndex)

Add a range of indexes to the EntriesView. This will place the view in an unsorted state.

Parameters:

startIndex - The first index into the FoundEntries.

endIndex - The last index into the FoundEntries, which must be greater than or equal to startIndex.

removeRange

public void removeRange(int startIndex,
                        int endIndex)

Add a range of indexes from the EntriesView. The view is first sorted in normal order before this is done to allow for effecient range removal.

Parameters:

startIndex - The first index into the FoundEntries.

endIndex - The last index into the FoundEntries, which must be greater than or equal to startIndex.

includeAll

public void includeAll(IntArray toAdd)

Add all the indexes - sorting this view before the add is done.

search

public EntriesView search(Handle h,
                          EntrySelector selector)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalStateException

Search for entries in the associated FoundEntries and add them to this EntriesView.

Parameters:

h - An optional handle that can be used to monitor and stop the search.

selector - an object that is used to select which entries will be included in the results.

Returns:

this EntriesView with the results of the search added to the indexes already in this view. If the search was aborted null will be returned.

Throws:

IOException

IllegalArgumentException

IllegalStateException

search

public EntriesView search(Handle h,
                          ObjectFinder finder)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalStateException

Search for entries in the associated FoundEntries and add them to this EntriesView. This method will always cause a filter to be performed instead of a binary search.

Parameters:

h - An optional handle that can be used to monitor and stop the search.

finder - an object that is used to select which entries will be included in the results.

Returns:

this EntriesView with the results of the search added to the indexes already in this view. If the search was aborted null will be returned.

Throws:

IOException

IllegalArgumentException

IllegalStateException

search

public EntriesView search(Handle h,
                          Object searchData,
                          boolean hasWildCards)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalStateException

Search for entries in the associated FoundEntries and add them to this EntriesView.

Parameters:

h - An optional handle that can be used to monitor and stop the search.

searchData - data used for the primary sort fields when searching.

hasWildCards - set this true if the data contain wild card specifications (e.g. '*' characters for Strings).

Returns:

this EntriesView with the results of the search added to the indexes already in this view. If the search was aborted null will be returned.

Throws:

IOException

IllegalArgumentException

IllegalStateException

search

public EntriesView search(Handle h,
                          Object searchData)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalStateException

Search for entries in the associated FoundEntries and add them to this EntriesView.

Parameters:

h - An optional handle that can be used to monitor and stop the search.

searchData - data used for the primary sort fields when searching.

Returns:

this EntriesView with the results of the search added to the indexes already in this view. If the search was aborted null will be returned.

Throws:

IOException

IllegalArgumentException

IllegalStateException

search

public Handle search(EntrySelector selector)

Search for entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the searching.

Parameters:

selector - an EntrySelector for selecting the entries.

Returns:

a Handle that can be used to monitor and abort the process. When the Handle reports success then the found entries will have been added to this EntriesView.

search

public Handle search(ObjectFinder finder)

Search for entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the searching.

Parameters:

finder - an ObjectFinder for selecting the entries.

Returns:

a Handle that can be used to monitor and abort the process. When the Handle reports success then the found entries will have been added to this EntriesView.

search

public Handle search(Object searchData,
                     boolean hasWildCards)

Search for entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the searching.

Parameters:

searchData - data used for the primary sort fields when searching.

hasWildCards - set this true if the data contain wild card specifications (e.g. '*' characters for Strings).

Returns:

a Handle that can be used to monitor and abort the process. When the Handle reports success then the found entries will have been added to this EntriesView.

search

public Handle search(Object searchData)

Search for entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the searching.

Parameters:

searchData - data used for the primary sort fields when searching.

Returns:

a Handle that can be used to monitor and abort the process. When the Handle reports success then the found entries will have been added to this EntriesView.

filter

public EntriesView filter(Handle h,
                          Object searchData)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalStateException

Filter all entries in the associated FoundEntries and add them to this EntriesView.

Parameters:

h - An optional handle that can be used to monitor and stop the search.

searchData - data used for the primary sort fields when searching.

Returns:

this EntriesView with the results of the search added to the indexes already in this view. If the search was aborted null will be returned.

Throws:

IOException

IllegalArgumentException

IllegalStateException

filter

public EntriesView filter(Handle h,
                          Object searchData,
                          boolean hasWildCards)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalStateException

Filter all entries in the associated FoundEntries and add them to this EntriesView.

Parameters:

h - An optional handle that can be used to monitor and stop the search.

searchData - data used for the primary sort fields when searching.

hasWildCards - set this true if the data contain wild card specifications (e.g. '*' characters for Strings).

Returns:

this EntriesView with the results of the search added to the indexes already in this view. If the search was aborted null will be returned.

Throws:

IOException

IllegalArgumentException

IllegalStateException

filter

public Handle filter(Object searchData,
                     boolean hasWildCards)
              throws IllegalArgumentException,
                     IllegalStateException

Filter all entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the filtering.

Parameters:

searchData - data used for the primary sort fields when searching.

hasWildCards - set this true if the data contain wild card specifications (e.g. '*' characters for Strings).

Returns:

a Handle that can be used to monitor and abort the process. When the Handle reports success then the found entries will have been added to this EntriesView.

Throws:

IllegalArgumentException

IllegalStateException

filter

public Handle filter(Object searchData)
              throws IllegalArgumentException,
                     IllegalStateException

Filter all entries in the associated FoundEntries and add them to this EntriesView, using a separate thread to do the filtering.

Parameters:

searchData - data used for the primary sort fields when searching.

Returns:

a Handle that can be used to monitor and abort the process. When the Handle reports success then the found entries will have been added to this EntriesView.

Throws:

IllegalArgumentException

IllegalStateException

getFullFiew

public void getFullFiew()

Refresh this EntriesView to view the entire source FoundEntries.

size

public int size()

Return the number of indexes in the view.

get

public DatabaseEntry get(int indexInView,
                         DatabaseEntry de)
                  throws IOException

Get the DatabaseEntry at the specified index in the view.

Parameters:

indexInView - the index of the entry in this view.

de - an optional destination DatabaseEntry.

Returns:

the destination DatabaseEntry or a new entry if de was null.

Throws:

IOException - if there was an error reading the entry.

getData

public Object getData(int indexInView,
                      Object dest)
               throws IOException

Get the DatabaseEntry at the specified index in the view as a data object.

Parameters:

indexInView - the index of the entry in this view.

dest - an optional destination object.

Returns:

the destination Object or a new object if dest was null.

Throws:

IOException - if there was an error reading the entry.

get

public DatabaseEntry get(int indexInView)
                  throws IOException

Get the DatabaseEntry at the specified index in the view.

Parameters:

indexInView - the index of the entry in this view.

Returns:

a new DatabaseEntry.

Throws:

IOException - if there was an error reading the entry.

getData

public Object getData(int indexInView)
               throws IOException

Get the DatabaseEntry at the specified index in the view as a data object.

Parameters:

indexInView - the index of the entry in this view.

Returns:

a new data Object.

Throws:

IOException - if there was an error reading the entry.

set

public void set(int indexInView,
                DatabaseEntry de)
         throws IOException

Change the database entry at the specified index.

Parameters:

indexInView - the index of the entry in this view.

de - a database entry object containing the new data.

Throws:

IOException - if there was an error writing the entry.

setData

public void setData(int indexInView,
                    Object data)
             throws IOException

Change the database entry at the specified index.

Parameters:

indexInView - the index of the entry in this view.

data - an object containing the new data.

Throws:

IOException - if there was an error writing the entry.

getNew

public DatabaseEntry getNew()

Return a new DatabaseEntry for use with this database.

store

public void store(int indexInView,
                  DatabaseEntry de)
           throws IOException

Store the DatabaseEntry at the specified index without modifying any of its special synchronization fields.

Parameters:

indexInView - the index of the entry in this view.

de - a database entry object containing the new data.

Throws:

IOException - if there was an error writing the entry.

add

public int add(DatabaseEntry de)
        throws IOException

Add a new DatabaseEntry to the view (it is added to the end) and save it in the FoundEntries and database.

Parameters:

de - a DatabaseEntry object holding the data to be saved.

Returns:

the index where the new entry was added to the view.

Throws:

IOException

addData

public int addData(Object data)
            throws IOException

Add a new record to the view (it is added to the end) and save it in the FoundEntries and database.

Parameters:

data - a data object holding the data to be saved.

Returns:

the index where the new entry was added to the view.

Throws:

IOException

delete

public void delete(int indexInView)
            throws IOException

Delete the record at the specified index from the database. It will also remove the entry from this EntriesView.

Parameters:

indexInView - the index of the entry in the view.

Throws:

IOException

toRanges

public IntArray toRanges(IntArray dest)

Convert the indexes in this view to a sequence of ranges.

changed

protected void changed(int oldIndex,
                       int newIndex)

indexInView

public int indexInView(DatabaseEntry de)

Find out the index of the specified entry in this view - if it exists in the view.

Parameters:

de - the entry to look for.

Returns:

the index of the entry in this view or -1 if it is not in this view.

indexInView

public int indexInView(int indexInFoundEntries)

Determine the index of the database entry in the View, based on its index in the FoundEntries.

Parameters:

indexInFoundEntries - The index of the record in the FoundEntries.

Returns:

the index of the entry in this View or -1 if it is not included in the view.

indexInFoundEntries

public int indexInFoundEntries(int indexInView)

This is the same as index(). It returns the index of an item in the FoundEntries, given the index of the item in this view.

index

public int index(int indexInView)

This is the same as indexInFoundEntries(). It returns the index of an item in the FoundEntries, given the index of the item in this view.

include

public int include(DatabaseEntry entry)

Include the specified entry in this view, but only if it is already included in its FoundEntries.

Parameters:

entry - the entry to include.

Returns:

the index of the included entry in the View or -1 if it was not included because it is not in the FoundEntries.

include

public int include(int indexInFoundEntries)

Include the specified entry in this view.

Parameters:

indexInFoundEntries - the index of the entry in the FoundEntries.

Returns:

the index of the included entry in the View or -1 if it was not included because it is not in the FoundEntries.

include

public void include(EntriesView other)
             throws IllegalArgumentException

Include all the entries in the other view in this view.

Parameters:

other - The other EntriesView

Throws:

IllegalArgumentException - if the other EntriesView is not of the same FoundEntries.

exclude

public void exclude(EntriesView other)
             throws IllegalArgumentException

Exclude all the entries in the other view from this view.

Parameters:

other - The other EntriesView.

Throws:

IllegalArgumentException - if the other EntriesView is not of the same FoundEntries.

exclude

public void exclude(DatabaseEntry entry)

Exclude the entry from this view.

exclude

public void exclude(int indexInFoundEntries)

Exclude the entry from this view.

excludeAt

public void excludeAt(int indexInView)

Exclude the entry form this view.

Parameters:

indexInView - the index of the entry in this view.

getIndexesInFoundEntries

public int[] getIndexesInFoundEntries()

Get all the indexes as an arry of ints. This does not sort the view.

getEventDispatcher

public EventDispatcher getEventDispatcher()

Get the EventDispatcher for this view.

dispatchEvent

protected void dispatchEvent(int type)

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.

getEmptyView

public EntriesView getEmptyView()

Use this if you used enableLookupMode() to get a new empty EntriesView for the same FoundEntries as this view.