added documentation for operation callbacks and removed extraneous callback call
git-svn-id: https://hyracks.googlecode.com/svn/branches/hyracks_lsm_tree@1748 123451ca-8445-de46-9d55-352943316053
diff --git a/hyracks-storage-am-btree/src/main/java/edu/uci/ics/hyracks/storage/am/btree/impls/BTree.java b/hyracks-storage-am-btree/src/main/java/edu/uci/ics/hyracks/storage/am/btree/impls/BTree.java
index 6a12e55..e90eaf5 100644
--- a/hyracks-storage-am-btree/src/main/java/edu/uci/ics/hyracks/storage/am/btree/impls/BTree.java
+++ b/hyracks-storage-am-btree/src/main/java/edu/uci/ics/hyracks/storage/am/btree/impls/BTree.java
@@ -214,12 +214,12 @@
}
private void insert(ITupleReference tuple, BTreeOpContext ctx) throws HyracksDataException, TreeIndexException {
- ctx.modificationCallback.commence(tuple);
+ ctx.modificationCallback.before(tuple);
insertUpdateOrDelete(tuple, ctx);
}
private void upsert(ITupleReference tuple, BTreeOpContext ctx) throws HyracksDataException, TreeIndexException {
- ctx.modificationCallback.commence(tuple);
+ ctx.modificationCallback.before(tuple);
insertUpdateOrDelete(tuple, ctx);
}
@@ -230,12 +230,12 @@
if (fieldCount == ctx.cmp.getKeyFieldCount()) {
throw new BTreeNotUpdateableException("Cannot perform updates when the entire tuple forms the key.");
}
- ctx.modificationCallback.commence(tuple);
+ ctx.modificationCallback.before(tuple);
insertUpdateOrDelete(tuple, ctx);
}
private void delete(ITupleReference tuple, BTreeOpContext ctx) throws HyracksDataException, TreeIndexException {
- ctx.modificationCallback.commence(tuple);
+ ctx.modificationCallback.before(tuple);
insertUpdateOrDelete(tuple, ctx);
}
diff --git a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/api/IModificationOperationCallback.java b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/api/IModificationOperationCallback.java
index 0e2ff20..5028aee 100644
--- a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/api/IModificationOperationCallback.java
+++ b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/api/IModificationOperationCallback.java
@@ -2,10 +2,34 @@
import edu.uci.ics.hyracks.dataflow.common.data.accessors.ITupleReference;
+/**
+ * This operation callback allows for arbitrary actions to be taken while traversing
+ * an index structure. The {@link IModificationOperationCallback} will be called on
+ * all modifying operations (e.g. insert, update, delete...) for all indexes.
+ *
+ * @author zheilbron
+ */
public interface IModificationOperationCallback {
+
+ /**
+ * This method is called on a tuple that is about to traverse an index's structure
+ * (i.e. before any pages are pinned or latched).
+ *
+ * The format of the tuple is the format that would be stored in the index itself.
+ *
+ * @param tuple the tuple that is about to be operated on
+ */
public void before(ITupleReference tuple);
- public void commence(ITupleReference tuple);
-
+ /**
+ * This method is called on a tuple when a tuple with a matching key is found for the
+ * current operation. It is possible that tuple is null, in which case no tuple with a
+ * matching key was found.
+ *
+ * When found is called, the leaf page where the tuple resides will be pinned and latched,
+ * so blocking operations should be avoided.
+ *
+ * @param tuple a tuple with a matching key, otherwise null if none exists
+ */
public void found(ITupleReference tuple);
}
diff --git a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/api/ISearchOperationCallback.java b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/api/ISearchOperationCallback.java
index 5bfa219..aad109f 100644
--- a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/api/ISearchOperationCallback.java
+++ b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/api/ISearchOperationCallback.java
@@ -2,8 +2,34 @@
import edu.uci.ics.hyracks.dataflow.common.data.accessors.ITupleReference;
+/**
+ * This operation callback allows for arbitrary actions to be taken while traversing
+ * an index structure. The {@link ISearchOperationCallback} will be called on
+ * all search operations for ordered indexes only.
+ *
+ * @author zheilbron
+ */
public interface ISearchOperationCallback {
+
+ /**
+ * During an index search operation, this method will be called on tuples as they are
+ * passed by with a search cursor. This call will be invoked while a leaf page is latched
+ * and pinned. If the call returns false, then the page will be unlatched and unpinned and
+ * {@link #reconcile(ITupleReference)} will be called with the tuple that was not proceeded
+ * on.
+ *
+ * @param tuple the tuple that is being passed over by the search cursor
+ * @return true to proceed otherwise false to unlatch and unpin, leading to reconciliation
+ */
public boolean proceed(ITupleReference tuple);
+ /**
+ * This method is only called on a tuple that was not 'proceeded' on
+ * (see {@link #proceed(ITupleReference)}). This method allows an opportunity to reconcile
+ * by performing any necessary actions before resuming the search (e.g. a try-lock may have
+ * failed in the proceed call, and now in reconcile we should take a full (blocking) lock).
+ *
+ * @param tuple the tuple that failed to proceed
+ */
public void reconcile(ITupleReference tuple);
}
diff --git a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/dataflow/TreeIndexInsertUpdateDeleteOperatorNodePushable.java b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/dataflow/TreeIndexInsertUpdateDeleteOperatorNodePushable.java
index e68c335..98fcf4a 100644
--- a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/dataflow/TreeIndexInsertUpdateDeleteOperatorNodePushable.java
+++ b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/dataflow/TreeIndexInsertUpdateDeleteOperatorNodePushable.java
@@ -97,7 +97,6 @@
}
tuple.reset(accessor, i);
- modCallback.before(tuple);
switch (op) {
case INSERT: {
indexAccessor.insert(tuple);
diff --git a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/impls/NoOpOperationCallback.java b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/impls/NoOpOperationCallback.java
index d7f7518..ee36f9f 100644
--- a/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/impls/NoOpOperationCallback.java
+++ b/hyracks-storage-am-common/src/main/java/edu/uci/ics/hyracks/storage/am/common/impls/NoOpOperationCallback.java
@@ -41,11 +41,6 @@
}
@Override
- public void commence(ITupleReference tuple) {
- // Do nothing.
- }
-
- @Override
public void found(ITupleReference tuple) {
// Do nothing.
}
diff --git a/hyracks-storage-am-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/rtree/impls/RTree.java b/hyracks-storage-am-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/rtree/impls/RTree.java
index eba7c12..322b8b0 100644
--- a/hyracks-storage-am-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/rtree/impls/RTree.java
+++ b/hyracks-storage-am-rtree/src/main/java/edu/uci/ics/hyracks/storage/am/rtree/impls/RTree.java
@@ -153,7 +153,7 @@
ctx.splitKey.reset();
ctx.splitKey.getLeftTuple().setFieldCount(cmpFactories.length);
ctx.splitKey.getRightTuple().setFieldCount(cmpFactories.length);
- ctx.modificationCallback.commence(tuple);
+ ctx.modificationCallback.before(tuple);
int maxFieldPos = cmpFactories.length / 2;
for (int i = 0; i < maxFieldPos; i++) {
diff --git a/hyracks-test-support/src/main/java/edu/uci/ics/hyracks/storage/am/common/TestOperationCallback.java b/hyracks-test-support/src/main/java/edu/uci/ics/hyracks/storage/am/common/TestOperationCallback.java
index 1858e6a..8189818 100644
--- a/hyracks-test-support/src/main/java/edu/uci/ics/hyracks/storage/am/common/TestOperationCallback.java
+++ b/hyracks-test-support/src/main/java/edu/uci/ics/hyracks/storage/am/common/TestOperationCallback.java
@@ -38,11 +38,6 @@
}
@Override
- public void commence(ITupleReference tuple) {
- // Do nothing.
- }
-
- @Override
public void found(ITupleReference tuple) {
// Do nothing.
}