|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.coyotegulch.jisp.BTreeIndex
public class BTreeIndex
Associates a key value with a long
reference. In general, the
reference is a file pointer that locates a serializable object associated with
the key value; however, the index itself does not apply semantics to the reference.
The user of index interprets the reference according to its design; an
IndexedObjectDatabase
, for example, uses the reference to record the
file position of a Serializable
object with a specific key.
Use the IndexedObjectDatabase.attachIndex
method to attach a
BTreeIndex
to a database. A database updates all attached indexes
when it writes or removes objects from its file. This is the most common use
of BTreeIndex
es.
It's important to realize that each key is associated with a long
reference which is interpretted by the user. For example, the
IndexedObjectDatabase
class stores a file pointer in reference, thus
associating a key value with a serialized object stored in the database. You can
also use the reference as an index into an array, or in any other way appropriate
to your application. It is even possible associate the same reference value with
different keys.
ObjectIndex
,
IndexedObjectDatabase
Field Summary | |
---|---|
protected com.coyotegulch.jisp.PageFileHeader |
m_header
Header data for a file containing B-Tree pages. |
protected java.util.HashMap |
m_pageCache
A cache of pages that have already been loaded into memory. |
Constructor Summary | |
---|---|
BTreeIndex(java.lang.String name)
Opens an existing file, name , as a BTreeIndex . |
|
BTreeIndex(java.lang.String name,
int order,
KeyObject nullKey,
boolean hasDupes)
Creates the specified file as a BTreeIndex , using the given order and
null key value. |
Method Summary | |
---|---|
void |
close()
Closes an open BTreeIndex and empties the page cache to release memory. |
static int |
computeOrder(int numRecords,
int maxHeight)
Calculates a suggested value for a B-tree order, based on a given number of records and a maximum "height" for the B-tree structure. |
int |
count()
Returns the number of keys stored in this index. |
void |
dumpTree(java.io.PrintStream output)
Dumps the entire B-Tree to System.out for analysis. |
void |
emptyPageCache()
Empty the page cache. |
long |
findKey(KeyObject key)
Find the position of the object associated with a given key. |
long |
findKey(KeyObject key,
boolean allowNext)
Find the position of an object associated with a given key, or its successor. |
int |
getPageCacheSize()
Get the size of the page cache, in number of B-tree pages stored in memory. |
void |
insertKey(KeyObject key,
long reference)
Insert a key into the index, associating a "reference" value with the given key. |
void |
removeKey(KeyObject key)
Removes the given key from the index. |
void |
replaceKey(KeyObject key,
long reference)
Replaces the reference for the given key. |
void |
storeKey(KeyObject key,
long reference)
Replaces or inserts the reference for the given key. |
long |
ticker()
Returns the number of keys added to this index since its creation. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected com.coyotegulch.jisp.PageFileHeader m_header
protected java.util.HashMap m_pageCache
Constructor Detail |
---|
public BTreeIndex(java.lang.String name) throws java.io.IOException, java.lang.ClassNotFoundException
name
, as a BTreeIndex
.
name
- name of the external index file to be opened.
java.io.IOException
- when an I/O exception is thrown by an underlying java.io.* class
java.lang.ClassNotFoundException
- for a casting error, usually when a persistent object or index does
match the expected typepublic BTreeIndex(java.lang.String name, int order, KeyObject nullKey, boolean hasDupes) throws java.io.IOException, java.lang.ClassNotFoundException
BTreeIndex
, using the given order and
null
key value. The null key is a "blank" key used in padding empty
entries in B-tree pages. Obtain a null key for any key type by either invoking the
default constructor or calling the KeyObject.makeNullKey
method.
name
- name of the external index file to be opened.order
- order (page size) the the B-Tree. This should be an odd number
greater than or equal to five (5). BTreeIndex
will
increment any even numbered order to the next consecutive odd number
(if you specfy an order of 32, the index will actually have an order
of 33). Also, an order less than 5 will be set to 5 automatically.nullKey
- identifies a blank table entry and provides type-checking on new
keys added to the index. All keys added to the index must have the
same type as nullkey
.hasDupes
- Determines whether or not this index allows duplicate keys.
java.io.IOException
- when an I/O exception is thrown by an underlying java.io.* class
java.lang.ClassNotFoundException
- for a casting error, usually when a persistent object or index does
match the expected typeKeyObject
Method Detail |
---|
public static int computeOrder(int numRecords, int maxHeight)
numRecords
- number of records expected in a B-tree indexmaxHeight
- maximum allowable height for the B-tree (i.e., maximum number of pages to be read
when searching for a key)
BTreeIndex
public void close() throws java.io.IOException
BTreeIndex
and empties the page cache to release memory.
java.io.IOException
public int count()
public long ticker()
count, it is never
decremented. In an index with a one-to-one correspondence between records and keys,
this value provides a unique "record ID".
- Returns:
- the number of keys added to this index since its creation
public void insertKey(KeyObject key, long reference) throws java.io.IOException, java.lang.ClassNotFoundException
insertKey
in interface ObjectIndex
key
- identifies the record to be readreference
- reference associated with key
java.io.IOException
- when an I/O exception is thrown by an underlying java.io.* class
java.lang.ClassNotFoundException
- for a casting error, usually when a persistent object or index does
match the expected type
DuplicateKey
- when inserting a duplicate key into an index that does not
support duplicatesDuplicateKey
,
KeyObject
public void replaceKey(KeyObject key, long reference) throws java.io.IOException, java.lang.ClassNotFoundException
replaceKey
in interface ObjectIndex
key
- identifies the record being replacedreference
- new reference to be associated with key
java.io.IOException
- when an I/O exception is thrown by an underlying java.io.* class
java.lang.ClassNotFoundException
- for a casting error, usually when a persistent object or index does
match the expected type
KeyNotFound
- when the specified key can not be found in the indexDuplicateKey
,
KeyObject
public void storeKey(KeyObject key, long reference) throws java.io.IOException, java.lang.ClassNotFoundException
storeKey
in interface ObjectIndex
key
- identifies the record to be storedposition
- reference associated with key
java.io.IOException
- when an I/O exception is thrown by an underlying java.io.* class
java.lang.ClassNotFoundException
- for a casting error, usually when a persistent object or index does
match the expected typeKeyObject
public long findKey(KeyObject key) throws java.io.IOException, java.lang.ClassNotFoundException
findKey
in interface ObjectIndex
key
- a key to be sought in the index
key
.
java.io.IOException
- when an I/O exception is thrown by an underlying java.io.* class
java.lang.ClassNotFoundException
- for a casting error, usually when a persistent object or index does
match the expected type
KeyNotFound
- when the specified key can not be found in the indexKeyNotFound
,
KeyObject
public long findKey(KeyObject key, boolean allowNext) throws java.io.IOException, java.lang.ClassNotFoundException
key
- a key to be sought in the indexallowNext
- when true
, findKey
will return
the reference associated with the key greater than or
equal to key
key
.
java.io.IOException
- when an I/O exception is thrown by an underlying java.io.* class
java.lang.ClassNotFoundException
- for a casting error, usually when a persistent object or index does
match the expected type
KeyNotFound
- when the specified key can not be found in the indexKeyNotFound
,
KeyObject
public void removeKey(KeyObject key) throws java.io.IOException, java.lang.ClassNotFoundException
key
,
the first key found will be deleted.
removeKey
in interface ObjectIndex
key
- A key identifying the record to be read.
java.io.IOException
- when an I/O exception is thrown by an underlying java.io.* class
java.lang.ClassNotFoundException
- for a casting error, usually when a persistent object or index does
match the expected type
KeyNotFound
- when the specified key can not be found in the indexKeyNotFound
,
KeyObject
public void emptyPageCache()
public int getPageCacheSize()
public void dumpTree(java.io.PrintStream output) throws java.io.IOException, DuplicateKey, java.lang.ClassNotFoundException
System.out
for analysis. For diagnostic purposes only.
java.io.IOException
- when an I/O exception is thrown by an underlying java.io.* class
java.lang.ClassNotFoundException
- for a casting error, usually when a persistent object or index does
match the expected type
DuplicateKey
- when inserting a duplicate key into an index that does not
support duplicates
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |