com.healthmarketscience.jackcess.impl

Class IndexPageCache

java.lang.Object

com.healthmarketscience.jackcess.impl.IndexPageCache

public class IndexPageCache
extends java.lang.Object

Manager of the index pages for a IndexData.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	IndexPageCache.CacheDataPage IndexPageCache implementation of an Index IndexData.DataPage.
private static class	IndexPageCache.DataPageExtra Keeps track of the extra info for an index page.
private class	IndexPageCache.DataPageMain Keeps track of the main info for an index page.
private static class	IndexPageCache.EntryListView A view of an index page's entries which combines the normal entries and tail entry into one collection.
private static class	IndexPageCache.UpdateType

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.Map<java.lang.Integer,IndexPageCache.DataPageMain>	_dataPages the currently loaded pages for this index, pageNumber -> page
private IndexData	_indexData the index whose pages this cache is managing
private java.util.List<IndexPageCache.CacheDataPage>	_modifiedPages the currently modified index pages
private IndexPageCache.DataPageMain	_rootPage the root page for the index
private static int	MAX_CACHE_SIZE max number of pages to cache (unless a write operation is in progress)

Constructor Summary

Constructors

Constructor and Description
IndexPageCache(IndexData indexData)

Method Summary

Modifier and Type	Method and Description
private void	addEntry(IndexPageCache.CacheDataPage cacheDataPage, int entryIdx, IndexData.Entry newEntry) Adds the entry to the given page at the given index.
private void	addParentEntry(IndexPageCache.CacheDataPage parentDataPage, IndexPageCache.CacheDataPage childDataPage) Adds an entry for the given child page to the given parent page.
private void	addToPeersBefore(IndexPageCache.CacheDataPage newDataPage, IndexPageCache.CacheDataPage origDataPage) Inserts the new page as a peer between the given original page and any previous peer page.
private IndexPageCache.CacheDataPage	allocateNewCacheDataPage(java.lang.Integer parentPageNumber, boolean isLeaf) Allocates a new index page with the given parent page and type.
private java.util.List<java.lang.Object>	collectPages(java.util.List<java.lang.Object> pages, IndexPageCache.DataPageMain dpMain) Collects all the cache pages in the cache.
private void	deleteDataPage(IndexPageCache.CacheDataPage cacheDataPage) Deletes the given index page from the file (clears the page).
private void	demoteTail(IndexPageCache.CacheDataPage cacheDataPage) Makes the tail entry of the given page a normal entry on that page, done when there is only one entry left on a page, and it is the tail.
IndexPageCache.CacheDataPage	findCacheDataPage(IndexData.Entry e) Finds the index page on which the given entry does or should reside.
private static byte[]	findCommonPrefix(IndexData.Entry e1, IndexData.Entry e2) Finds the valid entry prefix given the first/last entries on an index page.
IndexPageCache.CacheDataPage	getCacheDataPage(java.lang.Integer pageNumber) Returns a CacheDataPage for the given page number, may be null if the given page number is invalid.
private IndexPageCache.DataPageMain	getDataPage(java.lang.Integer pageNumber) Returns a DataPageMain for the given page number, may be null if the given page number is invalid.
IndexData	getIndexData()
PageChannel	getPageChannel()
private void	handleEmptyPages() Handles any modified pages which are empty as the first pass during a write() call.
private IndexPageCache.CacheDataPage	nestRootDataPage(IndexPageCache.CacheDataPage rootDataPage) Copies the current root page info into a new page and nests this page under the root page.
private void	preparePagesForWriting() Prepares any non-empty modified pages for writing as the second pass during a write() call.
private void	promoteTail(IndexPageCache.CacheDataPage cacheDataPage) Makes the last normal entry of the given page the tail entry on that page, done when there are multiple entries on a page and no tail entry.
private void	purgeOldPages() Trims the size of the _dataPages cache appropriately (assuming caller has already verified that the cache needs trimming).
private IndexPageCache.CacheDataPage	readDataPage(java.lang.Integer pageNumber) Reads the given index page from the file.
private void	removeDataPage(IndexPageCache.CacheDataPage parentDataPage, IndexPageCache.CacheDataPage cacheDataPage, IndexData.Entry oldLastEntry) Removes an index page which has become empty.
private IndexData.Entry	removeEntry(IndexPageCache.CacheDataPage cacheDataPage, int entryIdx) Removes the entry with the given index from the given page.
private void	removeFromPeers(IndexPageCache.CacheDataPage cacheDataPage) Removes a now empty index page from its next and previous peers.
private void	reparentChildren(IndexPageCache.CacheDataPage cacheDataPage) Sets the parent info for the children of the given page to the given page.
private void	replaceParentEntry(IndexPageCache.CacheDataPage parentDataPage, IndexPageCache.CacheDataPage childDataPage, IndexData.Entry oldEntry) Replaces the entry for the given child page in the given parent page.
private void	separateFromNextPeer(IndexPageCache.CacheDataPage cacheDataPage) Separates the given index page from any next peer page.
private void	setModified(IndexPageCache.CacheDataPage cacheDataPage) Marks the given index page as modified and saves it for writing, if necessary (if the page is already marked, does nothing).
void	setRootPageNumber(int pageNumber) Sets the root page for this index, must be called before normal usage.
private void	splitDataPage(IndexPageCache.CacheDataPage origDataPage) Splits an index page which has too many entries on it.
java.lang.String	toString()
private IndexData.Entry	updateEntry(IndexPageCache.CacheDataPage cacheDataPage, int entryIdx, IndexData.Entry newEntry, IndexPageCache.UpdateType upType) Updates the entries on the given page according to the given updateType.
private void	updateParentEntry(IndexPageCache.CacheDataPage parentDataPage, IndexPageCache.CacheDataPage childDataPage, IndexData.Entry oldEntry, IndexData.Entry newEntry, IndexPageCache.UpdateType upType) Updates the entry for the given child page in the given parent page according to the given updateType.
private void	updateParentTail(IndexPageCache.CacheDataPage parentDataPage, IndexPageCache.CacheDataPage childDataPage, IndexPageCache.UpdateType upType) Updates the child tail info in the given parent page according to the given updateType.
(package private) void	validate() Used by unit tests to validate the internal status of the index.
private void	validateChildren(IndexPageCache.DataPageMain dpMain, IndexPageCache.DataPageExtra dpExtra) Validates the children for an index page
private void	validateEntries(IndexPageCache.DataPageExtra dpExtra) Validates the entries for an index page
private void	validateEntryForPage(IndexPageCache.DataPageMain dpMain, IndexData.Entry entry) Verifies that the given entry type (node/leaf) is valid for the given page (node/leaf).
private void	validatePeers(IndexPageCache.DataPageMain dpMain) Validates the peer pages for an index page.
private void	validatePeerStatus(IndexPageCache.DataPageMain dpMain, IndexPageCache.DataPageMain peerMain) Validates the given peer page against the given index page
private java.lang.String	withErrorContext(java.lang.String msg)
void	write() Writes any outstanding changes for this index to the file.
private void	writeDataPage(IndexPageCache.CacheDataPage cacheDataPage) Writes the given index page to the file.
private void	writeDataPages() Writes any non-empty modified pages as the last pass during a write() call.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MAX_CACHE_SIZE

private static final int MAX_CACHE_SIZE

max number of pages to cache (unless a write operation is in progress)

See Also:

Constant Field Values

_indexData

private final IndexData _indexData

the index whose pages this cache is managing

_rootPage

private IndexPageCache.DataPageMain _rootPage

the root page for the index

_dataPages

private final java.util.Map<java.lang.Integer,IndexPageCache.DataPageMain> _dataPages

the currently loaded pages for this index, pageNumber -> page

_modifiedPages

private final java.util.List<IndexPageCache.CacheDataPage> _modifiedPages

the currently modified index pages

Constructor Detail

IndexPageCache

public IndexPageCache(IndexData indexData)

Method Detail

getIndexData

public IndexData getIndexData()

getPageChannel

public PageChannel getPageChannel()

setRootPageNumber

public void setRootPageNumber(int pageNumber)
                       throws java.io.IOException

Sets the root page for this index, must be called before normal usage.

Parameters:

pageNumber - the root page number

Throws:

java.io.IOException

write

public void write()
           throws java.io.IOException

Writes any outstanding changes for this index to the file.

Throws:

java.io.IOException

handleEmptyPages

private void handleEmptyPages()
                       throws java.io.IOException

Handles any modified pages which are empty as the first pass during a write() call. All empty pages are removed from the _modifiedPages collection by this method.

Throws:

java.io.IOException

preparePagesForWriting

private void preparePagesForWriting()
                             throws java.io.IOException

Prepares any non-empty modified pages for writing as the second pass during a write() call. Updates entry prefixes, promotes/demotes tail pages, and splits pages as needed.

Throws:

java.io.IOException

writeDataPages

private void writeDataPages()
                     throws java.io.IOException

Writes any non-empty modified pages as the last pass during a write() call. Clears the _modifiedPages collection when finised.

Throws:

java.io.IOException

getCacheDataPage

public IndexPageCache.CacheDataPage getCacheDataPage(java.lang.Integer pageNumber)
                                              throws java.io.IOException

Returns a CacheDataPage for the given page number, may be null if the given page number is invalid. Loads the given page if necessary.

Throws:

java.io.IOException

getDataPage

private IndexPageCache.DataPageMain getDataPage(java.lang.Integer pageNumber)
                                         throws java.io.IOException

Returns a DataPageMain for the given page number, may be null if the given page number is invalid. Loads the given page if necessary.

Throws:

java.io.IOException

writeDataPage

private void writeDataPage(IndexPageCache.CacheDataPage cacheDataPage)
                    throws java.io.IOException

Writes the given index page to the file.

Throws:

java.io.IOException

deleteDataPage

private void deleteDataPage(IndexPageCache.CacheDataPage cacheDataPage)
                     throws java.io.IOException

Deletes the given index page from the file (clears the page).

Throws:

java.io.IOException

readDataPage

private IndexPageCache.CacheDataPage readDataPage(java.lang.Integer pageNumber)
                                           throws java.io.IOException

Reads the given index page from the file.

Throws:

java.io.IOException

removeEntry

private IndexData.Entry removeEntry(IndexPageCache.CacheDataPage cacheDataPage,
                                    int entryIdx)
                             throws java.io.IOException

Removes the entry with the given index from the given page.

Parameters:

cacheDataPage - the page from which to remove the entry

entryIdx - the index of the entry to remove

Throws:

java.io.IOException

addEntry

private void addEntry(IndexPageCache.CacheDataPage cacheDataPage,
                      int entryIdx,
                      IndexData.Entry newEntry)
               throws java.io.IOException

Adds the entry to the given page at the given index.

Parameters:

cacheDataPage - the page to which to add the entry

entryIdx - the index at which to add the entry

newEntry - the entry to add

Throws:

java.io.IOException

updateEntry

private IndexData.Entry updateEntry(IndexPageCache.CacheDataPage cacheDataPage,
                                    int entryIdx,
                                    IndexData.Entry newEntry,
                                    IndexPageCache.UpdateType upType)
                             throws java.io.IOException

Updates the entries on the given page according to the given updateType.

Parameters:

cacheDataPage - the page to update

entryIdx - the index at which to add/remove/replace the entry

newEntry - the entry to add/replace

upType - the type of update to make

Throws:

java.io.IOException

removeDataPage

private void removeDataPage(IndexPageCache.CacheDataPage parentDataPage,
                            IndexPageCache.CacheDataPage cacheDataPage,
                            IndexData.Entry oldLastEntry)
                     throws java.io.IOException

Removes an index page which has become empty. If this page is the root page, just clears it.

Parameters:

parentDataPage - the parent of the removed page

cacheDataPage - the page to remove

oldLastEntry - the last entry for this page (before it was removed)

Throws:

java.io.IOException

removeFromPeers

private void removeFromPeers(IndexPageCache.CacheDataPage cacheDataPage)
                      throws java.io.IOException

Removes a now empty index page from its next and previous peers.

Parameters:

cacheDataPage - the page to remove

Throws:

java.io.IOException

addParentEntry

private void addParentEntry(IndexPageCache.CacheDataPage parentDataPage,
                            IndexPageCache.CacheDataPage childDataPage)
                     throws java.io.IOException

Adds an entry for the given child page to the given parent page.

Parameters:

parentDataPage - the parent page to which to add the entry

childDataPage - the child from which to get the entry to add

Throws:

java.io.IOException

replaceParentEntry

private void replaceParentEntry(IndexPageCache.CacheDataPage parentDataPage,
                                IndexPageCache.CacheDataPage childDataPage,
                                IndexData.Entry oldEntry)
                         throws java.io.IOException

Replaces the entry for the given child page in the given parent page.

Parameters:

parentDataPage - the parent page in which to replace the entry

childDataPage - the child for which the entry is being replaced

oldEntry - the old child entry for the child page

Throws:

java.io.IOException

updateParentEntry

private void updateParentEntry(IndexPageCache.CacheDataPage parentDataPage,
                               IndexPageCache.CacheDataPage childDataPage,
                               IndexData.Entry oldEntry,
                               IndexData.Entry newEntry,
                               IndexPageCache.UpdateType upType)
                        throws java.io.IOException

Updates the entry for the given child page in the given parent page according to the given updateType.

Parameters:

parentDataPage - the parent page in which to update the entry

childDataPage - the child for which the entry is being updated

oldEntry - the old child entry to remove/replace

newEntry - the new child entry to replace/add

upType - the type of update to make

Throws:

java.io.IOException

updateParentTail

private void updateParentTail(IndexPageCache.CacheDataPage parentDataPage,
                              IndexPageCache.CacheDataPage childDataPage,
                              IndexPageCache.UpdateType upType)
                       throws java.io.IOException

Updates the child tail info in the given parent page according to the given updateType.

Parameters:

parentDataPage - the parent page in which to update the child tail

childDataPage - the child to add/replace

upType - the type of update to make

Throws:

java.io.IOException

validateEntryForPage

private void validateEntryForPage(IndexPageCache.DataPageMain dpMain,
                                  IndexData.Entry entry)

Verifies that the given entry type (node/leaf) is valid for the given page (node/leaf).

Parameters:

dpMain - the page to which the entry will be added

entry - the entry being added

Throws:

java.lang.IllegalStateException - if the entry type does not match the page type

splitDataPage

private void splitDataPage(IndexPageCache.CacheDataPage origDataPage)
                    throws java.io.IOException

Splits an index page which has too many entries on it.

Parameters:

origDataPage - the page to split

Throws:

java.io.IOException

nestRootDataPage

private IndexPageCache.CacheDataPage nestRootDataPage(IndexPageCache.CacheDataPage rootDataPage)
                                               throws java.io.IOException

Copies the current root page info into a new page and nests this page under the root page. This must be done when the root page needs to be split.

Parameters:

rootDataPage - the root data page

Returns:

the newly created page nested under the root page

Throws:

java.io.IOException

allocateNewCacheDataPage

private IndexPageCache.CacheDataPage allocateNewCacheDataPage(java.lang.Integer parentPageNumber,
                                                              boolean isLeaf)
                                                       throws java.io.IOException

Allocates a new index page with the given parent page and type.

Parameters:

parentPageNumber - the parent page for the new page

isLeaf - whether or not the new page is a leaf page

Returns:

the newly created page

Throws:

java.io.IOException

addToPeersBefore

private void addToPeersBefore(IndexPageCache.CacheDataPage newDataPage,
                              IndexPageCache.CacheDataPage origDataPage)
                       throws java.io.IOException

Inserts the new page as a peer between the given original page and any previous peer page.

Parameters:

newDataPage - the new index page

origDataPage - the current index page

Throws:

java.io.IOException

separateFromNextPeer

private void separateFromNextPeer(IndexPageCache.CacheDataPage cacheDataPage)
                           throws java.io.IOException

Separates the given index page from any next peer page.

Parameters:

cacheDataPage - the index page to be separated

Throws:

java.io.IOException

reparentChildren

private void reparentChildren(IndexPageCache.CacheDataPage cacheDataPage)
                       throws java.io.IOException

Sets the parent info for the children of the given page to the given page.

Parameters:

cacheDataPage - the page whose children need to be updated

Throws:

java.io.IOException

demoteTail

private void demoteTail(IndexPageCache.CacheDataPage cacheDataPage)
                 throws java.io.IOException

Makes the tail entry of the given page a normal entry on that page, done when there is only one entry left on a page, and it is the tail.

Parameters:

cacheDataPage - the page whose tail must be updated

Throws:

java.io.IOException

promoteTail

private void promoteTail(IndexPageCache.CacheDataPage cacheDataPage)
                  throws java.io.IOException

Makes the last normal entry of the given page the tail entry on that page, done when there are multiple entries on a page and no tail entry.

Parameters:

cacheDataPage - the page whose tail must be updated

Throws:

java.io.IOException

findCacheDataPage

public IndexPageCache.CacheDataPage findCacheDataPage(IndexData.Entry e)
                                               throws java.io.IOException

Finds the index page on which the given entry does or should reside.

Parameters:

e - the entry to find

Throws:

java.io.IOException

setModified

private void setModified(IndexPageCache.CacheDataPage cacheDataPage)

Marks the given index page as modified and saves it for writing, if necessary (if the page is already marked, does nothing).

Parameters:

cacheDataPage - the modified index page

findCommonPrefix

private static byte[] findCommonPrefix(IndexData.Entry e1,
                                       IndexData.Entry e2)

Finds the valid entry prefix given the first/last entries on an index page.

Parameters:

e1 - the first entry on the page

e2 - the last entry on the page

Returns:

a valid entry prefix for the page

validate

void validate()
       throws java.io.IOException

Used by unit tests to validate the internal status of the index.

Throws:

java.io.IOException

validateEntries

private void validateEntries(IndexPageCache.DataPageExtra dpExtra)
                      throws java.io.IOException

Validates the entries for an index page

Parameters:

dpExtra - the entries to validate

Throws:

java.io.IOException

validateChildren

private void validateChildren(IndexPageCache.DataPageMain dpMain,
                              IndexPageCache.DataPageExtra dpExtra)
                       throws java.io.IOException

Validates the children for an index page

Parameters:

dpMain - the index page

dpExtra - the child entries to validate

Throws:

java.io.IOException

validatePeers

private void validatePeers(IndexPageCache.DataPageMain dpMain)
                    throws java.io.IOException

Validates the peer pages for an index page.

Parameters:

dpMain - the index page

Throws:

java.io.IOException

validatePeerStatus

private void validatePeerStatus(IndexPageCache.DataPageMain dpMain,
                                IndexPageCache.DataPageMain peerMain)
                         throws java.io.IOException

Validates the given peer page against the given index page

Parameters:

dpMain - the index page

peerMain - the peer index page

Throws:

java.io.IOException

collectPages

private java.util.List<java.lang.Object> collectPages(java.util.List<java.lang.Object> pages,
                                                      IndexPageCache.DataPageMain dpMain)

Collects all the cache pages in the cache.

Parameters:

pages - the List to update

dpMain - the index page to collect

purgeOldPages

private void purgeOldPages()

Trims the size of the _dataPages cache appropriately (assuming caller has already verified that the cache needs trimming).

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

withErrorContext

private java.lang.String withErrorContext(java.lang.String msg)