added IIndex (index lifecycle) documentation and improved clarity of lifecycle related exception messages
git-svn-id: https://hyracks.googlecode.com/svn/branches/hyracks_lsm_tree@1743 123451ca-8445-de46-9d55-352943316053
diff --git a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/dataflow/IIndex.java b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/dataflow/IIndex.java
index 7cb9cb3..c17b03c 100644
--- a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/dataflow/IIndex.java
+++ b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/dataflow/IIndex.java
@@ -18,6 +18,7 @@
import edu.uci.ics.hyracks.api.exceptions.HyracksDataException;
import edu.uci.ics.hyracks.storage.am.common.api.IIndexAccessor;
import edu.uci.ics.hyracks.storage.am.common.api.IIndexBulkLoader;
+import edu.uci.ics.hyracks.storage.am.common.api.IIndexLifecycleManager;
import edu.uci.ics.hyracks.storage.am.common.api.IModificationOperationCallback;
import edu.uci.ics.hyracks.storage.am.common.api.ISearchOperationCallback;
import edu.uci.ics.hyracks.storage.am.common.api.IndexException;
@@ -25,58 +26,101 @@
import edu.uci.ics.hyracks.storage.common.buffercache.IBufferCache;
/**
- * Interface describing the operations common to all index structures. Indexes
+ * This interface describes the operations common to all indexes. Indexes
* implementing this interface can easily reuse existing index operators for
- * dataflow. Users must perform operations on an IIndex via an IIndexAccessor.
+ * dataflow. Users must perform operations on an via an {@link IIndexAccessor}.
+ *
+ * During dataflow, the lifecycle of IIndexes are handled through an
+ * {@link IIndexLifecycleManager}.
*/
public interface IIndex {
+
/**
- * Initializes the persistent state of an index, e.g., the root page, and
- * metadata pages.
+ * Initializes the persistent state of an index.
*
- * @throws HyracksDataException
- * If the BufferCache throws while un/pinning or un/latching.
+ * An index cannot be created if it is in the activated state.
+ * Calling create on an index that is deactivated has the effect of clearing the index.
+ *
+ * @throws HyracksDataException
+ * if there is an error in the BufferCache while (un)pinning pages, (un)latching pages,
+ * creating files, or deleting files
+ *
+ * if the index is in the activated state
*/
public void create() throws HyracksDataException;
+ /**
+ * Initializes the index's operational state. An index in the activated state may perform
+ * operations via an {@link IIndexAccessor}.
+ *
+ * @throws HyracksDataException
+ * if there is a problem in the BufferCache while (un)pinning pages, (un)latching pages,
+ * creating files, or deleting files
+ */
public void activate() throws HyracksDataException;
- public void deactivate() throws HyracksDataException;
-
- public void destroy() throws HyracksDataException;
-
+ /**
+ * Resets the operational state of the index. Calling clear has the same logical effect
+ * as calling deactivate(), destroy(), create(), then activate(), but not necessarily the
+ * same physical effect.
+ *
+ * @throws HyracksDataException
+ * if there is a problem in the BufferCache while (un)pinning pages, (un)latching pages,
+ * creating files, or deleting files
+ *
+ * if the index is not in the activated state
+ */
public void clear() throws HyracksDataException;
/**
- * Creates an index accessor for performing operations on this index.
- * (insert/delete/update/search/diskorderscan). An IIndexAccessor is not
- * thread safe, but different IIndexAccessors can concurrently operate
- * on the same IIndex
+ * Deinitializes the index's operational state. An index in the deactivated state may not
+ * perform operations.
*
- * @returns IIndexAccessor An accessor for this tree.
- * @param modificationCallback
- * TODO
- * @param searchCallback
- * TODO
+ * @throws HyracksDataException
+ * if there is a problem in the BufferCache while (un)pinning pages, (un)latching pages,
+ * creating files, or deleting files
+ */
+ public void deactivate() throws HyracksDataException;
+
+ /**
+ * Removes the persistent state of an index.
+ *
+ * An index cannot be destroyed if it is in the activated state.
+ *
+ * @throws HyracksDataException
+ * if there is an error in the BufferCache while (un)pinning pages, (un)latching pages,
+ * creating files, or deleting files
+ *
+ * if the index is already activated
+ */
+ public void destroy() throws HyracksDataException;
+
+ /**
+ * Creates an {@link IIndexAccessor} for performing operations on this index.
+ * An IIndexAccessor is not thread safe, but different IIndexAccessors can concurrently operate
+ * on the same {@link IIndex}.
+ *
+ * @returns IIndexAccessor an accessor for this {@link IIndex}
+ * @param modificationCallback the callback to be used for modification operations
+ * @param searchCallback the callback to be used for search operations
*/
public IIndexAccessor createAccessor(IModificationOperationCallback modificationCallback,
ISearchOperationCallback searchCallback);
/**
- * @param fillFactor
- * TODO
+ * @param fillFactor the fill factor for the bulk-loaded index or index component
* @throws IndexException
- * TODO
+ * if the index is required to be non-empty but is not
*/
public IIndexBulkLoader createBulkLoader(float fillFactor) throws IndexException;
/**
- * @return BufferCache underlying this index.
+ * @return the {@link IBufferCache} underlying this index.
*/
public IBufferCache getBufferCache();
/**
- * @return An enum of the concrete type of this index.
+ * @return the {@link IndexType} of this index.
*/
public IndexType getIndexType();
}
diff --git a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/impls/AbstractTreeIndex.java b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/impls/AbstractTreeIndex.java
index 21d2529..86b99e5 100644
--- a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/impls/AbstractTreeIndex.java
+++ b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/impls/AbstractTreeIndex.java
@@ -54,7 +54,7 @@
protected FileReference file;
protected int fileId = -1;
- private boolean isOpen = false;
+ private boolean isActivated = false;
public AbstractTreeIndex(IBufferCache bufferCache, IFileMapProvider fileMapProvider,
IFreePageManager freePageManager, ITreeIndexFrameFactory interiorFrameFactory,
@@ -71,8 +71,8 @@
}
public synchronized void create() throws HyracksDataException {
- if (isOpen) {
- throw new HyracksDataException("Failed to create since index is already open.");
+ if (isActivated) {
+ throw new HyracksDataException("Failed to create the index since it is activated.");
}
boolean fileIsMapped = false;
@@ -117,7 +117,7 @@
}
public synchronized void activate() throws HyracksDataException {
- if (isOpen) {
+ if (isActivated) {
return;
}
@@ -144,23 +144,23 @@
// TODO: Should probably have some way to check that the tree is physically consistent
// or that the file we just opened actually is a tree
- isOpen = true;
+ isActivated = true;
}
public synchronized void deactivate() throws HyracksDataException {
- if (!isOpen) {
+ if (!isActivated) {
return;
}
bufferCache.closeFile(fileId);
freePageManager.close();
- isOpen = false;
+ isActivated = false;
}
public synchronized void destroy() throws HyracksDataException {
- if (isOpen) {
- throw new HyracksDataException("Failed to destroy since index is already open.");
+ if (isActivated) {
+ throw new HyracksDataException("Failed to destroy the index since it is activated.");
}
file.getFile().delete();
@@ -173,8 +173,8 @@
}
public synchronized void clear() throws HyracksDataException {
- if (!isOpen) {
- throw new HyracksDataException("Failed to clear since index is not open.");
+ if (!isActivated) {
+ throw new HyracksDataException("Failed to clear the index since it is not activated.");
}
initEmptyTree();
diff --git a/hyracks-storage-am-lsm-btree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/btree/impls/LSMBTree.java b/hyracks-storage-am-lsm-btree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/btree/impls/LSMBTree.java
index 9df8f17..7f6e511 100644
--- a/hyracks-storage-am-lsm-btree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/btree/impls/LSMBTree.java
+++ b/hyracks-storage-am-lsm-btree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/btree/impls/LSMBTree.java
@@ -100,7 +100,7 @@
private final ITreeIndexFrameFactory deleteLeafFrameFactory;
private final IBinaryComparatorFactory[] cmpFactories;
- private boolean isOpen = false;
+ private boolean isActivated = false;
public LSMBTree(IBufferCache memBufferCache, InMemoryFreePageManager memFreePageManager,
ITreeIndexFrameFactory interiorFrameFactory, ITreeIndexFrameFactory insertLeafFrameFactory,
@@ -128,25 +128,17 @@
@Override
public synchronized void create() throws HyracksDataException {
- if (isOpen) {
- throw new HyracksDataException("Failed to create since index is already open.");
+ if (isActivated) {
+ throw new HyracksDataException("Failed to create the index since it is activated.");
}
fileManager.deleteDirs();
fileManager.createDirs();
}
- /**
- * Opens LSMBTree, cleaning up invalid files from base dir, and registering
- * all valid files as on-disk BTrees.
- *
- * @param fileReference
- * Dummy file id used for in-memory BTree.
- * @throws HyracksDataException
- */
@Override
public synchronized void activate() throws HyracksDataException {
- if (isOpen) {
+ if (isActivated) {
return;
}
@@ -160,12 +152,12 @@
BTree btree = createDiskBTree(diskBTreeFactory, fileRef, false);
diskBTrees.add(btree);
}
- isOpen = true;
+ isActivated = true;
}
@Override
public synchronized void deactivate() throws HyracksDataException {
- if (!isOpen) {
+ if (!isActivated) {
return;
}
@@ -186,13 +178,13 @@
memBTree.deactivate();
memBTree.destroy();
((InMemoryBufferCache) memBTree.getBufferCache()).close();
- isOpen = false;
+ isActivated = false;
}
@Override
public void destroy() throws HyracksDataException {
- if (isOpen) {
- throw new HyracksDataException("Failed to destroy since index is already open.");
+ if (isActivated) {
+ throw new HyracksDataException("Failed to destroy the index since it is activated.");
}
for (Object o : diskBTrees) {
@@ -205,8 +197,8 @@
@Override
public void clear() throws HyracksDataException {
- if (!isOpen) {
- throw new HyracksDataException("Failed to clear since index is not open.");
+ if (!isActivated) {
+ throw new HyracksDataException("Failed to clear the index since it is not activated.");
}
memBTree.clear();
diff --git a/hyracks-storage-am-lsm-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/rtree/impls/AbstractLSMRTree.java b/hyracks-storage-am-lsm-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/rtree/impls/AbstractLSMRTree.java
index 5008b04..ff4d87e 100644
--- a/hyracks-storage-am-lsm-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/rtree/impls/AbstractLSMRTree.java
+++ b/hyracks-storage-am-lsm-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/rtree/impls/AbstractLSMRTree.java
@@ -115,7 +115,7 @@
protected final ITreeIndexFrameFactory rtreeLeafFrameFactory;
protected final ITreeIndexFrameFactory btreeLeafFrameFactory;
- private boolean isOpen = false;
+ private boolean isActivated = false;
public AbstractLSMRTree(IBufferCache memBufferCache, InMemoryFreePageManager memFreePageManager,
ITreeIndexFrameFactory rtreeInteriorFrameFactory, ITreeIndexFrameFactory rtreeLeafFrameFactory,
@@ -152,8 +152,8 @@
@Override
public synchronized void create() throws HyracksDataException {
- if (isOpen) {
- throw new HyracksDataException("Failed to create since index is already open.");
+ if (isActivated) {
+ throw new HyracksDataException("Failed to create the index since it is activated.");
}
fileManager.deleteDirs();
@@ -162,7 +162,7 @@
@Override
public synchronized void activate() throws HyracksDataException {
- if (isOpen) {
+ if (isActivated) {
return;
}
@@ -171,17 +171,17 @@
memComponent.getBTree().create();
memComponent.getRTree().activate();
memComponent.getBTree().activate();
- isOpen = true;
+ isActivated = true;
}
@Override
public synchronized void deactivate() throws HyracksDataException {
- if (!isOpen) {
+ if (!isActivated) {
return;
}
- isOpen = false;
-
+ isActivated = false;
+
BlockingIOOperationCallback cb = new BlockingIOOperationCallback();
ILSMIndexAccessor accessor = (ILSMIndexAccessor) createAccessor(NoOpOperationCallback.INSTANCE,
NoOpOperationCallback.INSTANCE);
@@ -201,8 +201,8 @@
@Override
public synchronized void destroy() throws HyracksDataException {
- if (isOpen) {
- throw new HyracksDataException("Failed to destroy since index is already open.");
+ if (isActivated) {
+ throw new HyracksDataException("Failed to destroy the index since it is activated.");
}
memComponent.getRTree().deactivate();
@@ -212,8 +212,8 @@
@Override
public synchronized void clear() throws HyracksDataException {
- if (!isOpen) {
- throw new HyracksDataException("Failed to clear since index is not open.");
+ if (!isActivated) {
+ throw new HyracksDataException("Failed to clear the index since it is not activated.");
}
memComponent.getRTree().clear();
diff --git a/hyracks-storage-am-lsm-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/rtree/impls/LSMRTreeWithAntiMatterTuples.java b/hyracks-storage-am-lsm-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/rtree/impls/LSMRTreeWithAntiMatterTuples.java
index 36c5255..6a9531c 100644
--- a/hyracks-storage-am-lsm-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/rtree/impls/LSMRTreeWithAntiMatterTuples.java
+++ b/hyracks-storage-am-lsm-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/lsm/rtree/impls/LSMRTreeWithAntiMatterTuples.java
@@ -88,14 +88,6 @@
}
- /**
- * Opens LSMRTree, cleaning up invalid files from base dir, and registering
- * all valid files as on-disk RTrees and BTrees.
- *
- * @param fileReference
- * Dummy file id.
- * @throws HyracksDataException
- */
@Override
public synchronized void activate() throws HyracksDataException {
super.activate();