Author: elecharny
Date: Sat Mar 30 18:03:38 2013
New Revision: 1462827
URL: http://svn.apache.org/r1462827
Log:
Cleaned up the Javadoc
Modified:
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Leaf.java
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Node.java
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Page.java
Modified:
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Leaf.java
URL:
http://svn.apache.org/viewvc/labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Leaf.java?rev=1462827&r1=1462826&r2=1462827&view=diff
==============================================================================
---
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Leaf.java
(original)
+++
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Leaf.java
Sat Mar 30 18:03:38 2013
@@ -43,7 +43,9 @@ public class Leaf<K, V> extends Abstract
/**
- * Empty constructor
+ * Constructor used to create a new Leaf when we read it from a file.
+ *
+ * @param btree The BTree this page belongs to.
*/
/* No qualifier */Leaf( BTree<K, V> btree )
{
@@ -53,6 +55,10 @@ public class Leaf<K, V> extends Abstract
/**
* Internal constructor used to create Page instance used when a page is
being copied or overflow
+ *
+ * @param btree The BTree this page belongs to.
+ * @param revision The page revision
+ * @param nbElems The number of elements this page will contain
*/
@SuppressWarnings("unchecked")
// Cannot create an array of generic objects
@@ -60,9 +66,10 @@ public class Leaf<K, V> extends Abstract
{
super( btree, revision, nbElems );
- if( btree.isAllowDuplicates() )
+ if ( btree.isAllowDuplicates() )
{
- this.values = ( DuplicateKeyMemoryHolder<K, V>[] )
Array.newInstance( DuplicateKeyMemoryHolder.class, nbElems );
+ this.values = ( DuplicateKeyMemoryHolder<K, V>[] )
Array.newInstance( DuplicateKeyMemoryHolder.class,
+ nbElems );
}
else
{
@@ -73,7 +80,6 @@ public class Leaf<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
*/
public InsertResult<K, V> insert( long revision, K key, V value ) throws
IOException
{
@@ -116,12 +122,10 @@ public class Leaf<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
@SuppressWarnings("unchecked")
public DeleteResult<K, V> delete( long revision, K key, Page<K, V> parent,
int parentPos )
- throws EndOfFileExceededException, IOException
+ throws IOException
{
// Check that the leaf is not empty
if ( nbElems == 0 )
@@ -204,15 +208,14 @@ public class Leaf<K, V> extends Abstract
/**
- * Merge the sibling with the current leaf, after having removed the
element in the page.
+ * Merges the sibling with the current leaf, after having removed the
element in the page.
*
* @param revision The new revision
* @param sibling The sibling we will merge with
* @param isLeft Tells if the sibling is on the left or on the right
* @param pos The position of the removed element
* @return The new created leaf containing the sibling and the old page.
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
private DeleteResult<K, V> mergeWithSibling( long revision, Leaf<K, V>
sibling, boolean isLeft, int pos )
throws EndOfFileExceededException, IOException
@@ -262,7 +265,7 @@ public class Leaf<K, V> extends Abstract
/**
- * Borrow an element from the left sibling, creating a new sibling with one
+ * Borrows an element from the left sibling, creating a new sibling with
one
* less element and creating a new page where the element to remove has
been
* deleted and the borrowed element added on the left.
*
@@ -270,11 +273,10 @@ public class Leaf<K, V> extends Abstract
* @param sibling The left sibling
* @param pos The position of the element to remove
* @return The resulting pages
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
private DeleteResult<K, V> borrowFromLeft( long revision, Leaf<K, V>
sibling, int pos )
- throws EndOfFileExceededException, IOException
+ throws IOException
{
// The sibling is on the left, borrow the rightmost element
K siblingKey = sibling.keys[sibling.getNbElems() - 1];
@@ -309,7 +311,7 @@ public class Leaf<K, V> extends Abstract
/**
- * Borrow an element from the right sibling, creating a new sibling with
one
+ * Borrows an element from the right sibling, creating a new sibling with
one
* less element and creating a new page where the element to remove has
been
* deleted and the borrowed element added on the right.
*
@@ -317,11 +319,10 @@ public class Leaf<K, V> extends Abstract
* @param sibling The right sibling
* @param pos The position of the element to remove
* @return The resulting pages
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
private DeleteResult<K, V> borrowFromRight( long revision, Leaf<K, V>
sibling, int pos )
- throws EndOfFileExceededException, IOException
+ throws IOException
{
// The sibling is on the left, borrow the rightmost element
K siblingKey = sibling.keys[0];
@@ -360,15 +361,14 @@ public class Leaf<K, V> extends Abstract
/**
- * Remove the element at a given position.
+ * Removes the element at a given position.
*
* @param revision The revision of the modified page
* @param pos The position into the page of the element to remove
* @return The modified page with the <K,V> element added
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
- private DeleteResult<K, V> removeElement( long revision, int pos ) throws
EndOfFileExceededException, IOException
+ private DeleteResult<K, V> removeElement( long revision, int pos ) throws
IOException
{
// First copy the current page, but remove one element in the copied
page
Leaf<K, V> newLeaf = new Leaf<K, V>( btree, revision, nbElems - 1 );
@@ -416,10 +416,8 @@ public class Leaf<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
- public V get( K key ) throws KeyNotFoundException,
EndOfFileExceededException, IOException
+ public V get( K key ) throws KeyNotFoundException, IOException
{
int pos = findPos( key );
@@ -451,7 +449,8 @@ public class Leaf<K, V> extends Abstract
/**
- * Set the value at a give position
+ * Sets the value at a give position.
+ *
* @param pos The position in the values array
* @param value the value to inject
*/
@@ -477,7 +476,7 @@ public class Leaf<K, V> extends Abstract
ParentPos<K, V> parentPos = new ParentPos<K, V>( this, index );
setDupsContainer( parentPos );
stack.push( parentPos );
-
+
cursor = new Cursor<K, V>( btree, transaction, stack );
}
else
@@ -523,9 +522,9 @@ public class Leaf<K, V> extends Abstract
{
// Start at the beginning of the page
ParentPos<K, V> parentPos = new ParentPos<K, V>( this, pos );
-
+
setDupsContainer( parentPos );
-
+
stack.push( parentPos );
cursor = new Cursor<K, V>( btree, transaction, stack );
@@ -562,11 +561,10 @@ public class Leaf<K, V> extends Abstract
* @param value the new value
* @param pos The position of the key in the page
* @return The copied page
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
private InsertResult<K, V> replaceElement( long revision, K key, V value,
int pos )
- throws EndOfFileExceededException, IOException
+ throws IOException
{
Leaf<K, V> newLeaf = this;
@@ -577,12 +575,12 @@ public class Leaf<K, V> extends Abstract
}
V oldValue = null;
-
- if( btree.isAllowDuplicates() )
+
+ if ( btree.isAllowDuplicates() )
{
- BTree<V, V> dupValues = ( BTree<V, V> )
newLeaf.values[pos].getValue( btree );
- // 'oldValue' will always be null here
- oldValue = dupValues.insert( value, null, 0 );
+ BTree<V, V> dupValues = ( BTree<V, V> )
newLeaf.values[pos].getValue( btree );
+ // 'oldValue' will always be null here
+ oldValue = dupValues.insert( value, null, 0 );
}
else
{
@@ -590,16 +588,16 @@ public class Leaf<K, V> extends Abstract
oldValue = newLeaf.values[pos].getValue( btree );
newLeaf.values[pos] = btree.createHolder( value );
}
-
+
// Create the result
InsertResult<K, V> result = new ModifyResult<K, V>( newLeaf, oldValue
);
-
+
return result;
}
/**
- * Add a new <K, V> into a copy of the current page at a given position.
We return the
+ * Adds a new <K, V> into a copy of the current page at a given position.
We return the
* modified page. The new page will have one more element than the current
page.
*
* @param revision The revision of the modified page
@@ -614,10 +612,10 @@ public class Leaf<K, V> extends Abstract
Leaf<K, V> newLeaf = new Leaf<K, V>( btree, revision, nbElems + 1 );
// Atm, store the value in memory
-
+
ElementHolder valueHolder = null;
-
- if( btree.isAllowDuplicates() )
+
+ if ( btree.isAllowDuplicates() )
{
valueHolder = new DuplicateKeyMemoryHolder<K, V>( btree, value );
}
@@ -625,7 +623,7 @@ public class Leaf<K, V> extends Abstract
{
valueHolder = new MemoryHolder<K, V>( btree, value );
}
-
+
//ValueHolder<K, V> valueHolder = btree.createHolder( value );
// Deal with the special case of an empty page
@@ -758,46 +756,42 @@ public class Leaf<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
- public Tuple<K, V> findLeftMost() throws EndOfFileExceededException,
IOException
+ public Tuple<K, V> findLeftMost() throws IOException
{
V val = null;
-
- if( btree.isAllowDuplicates() )
+
+ if ( btree.isAllowDuplicates() )
{
- BTree<V,V> dupTree = ( BTree<V,V> ) values[0].getValue( btree );
+ BTree<V, V> dupTree = ( BTree<V, V> ) values[0].getValue( btree );
val = dupTree.rootPage.getLeftMostKey();
}
else
{
val = values[0].getValue( btree );
}
-
+
return new Tuple<K, V>( keys[0], val );
}
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
public Tuple<K, V> findRightMost() throws EndOfFileExceededException,
IOException
{
V val = null;
-
- if( btree.isAllowDuplicates() )
+
+ if ( btree.isAllowDuplicates() )
{
- BTree<V,V> dupTree = ( BTree<V,V> ) values[nbElems - 1].getValue(
btree );
+ BTree<V, V> dupTree = ( BTree<V, V> ) values[nbElems -
1].getValue( btree );
val = dupTree.rootPage.getRightMostKey();
}
else
{
val = values[nbElems - 1].getValue( btree );
}
-
+
return new Tuple<K, V>( keys[nbElems - 1], val );
}
@@ -838,23 +832,29 @@ public class Leaf<K, V> extends Abstract
return sb.toString();
}
-
- private void setDupsContainer( ParentPos<K,V> parentPos )
+
+ /**
+ * Creates a sub-tree if the BTree accept multiple values for a key.
+ *
+ * @param parentPos The position we will add the sub-tree at
+ */
+ private void setDupsContainer( ParentPos<K, V> parentPos )
{
- if( btree.isAllowDuplicates() )
+ if ( btree.isAllowDuplicates() )
{
try
{
BTree<V, V> dupsContainer = ( BTree<V, V> )
values[parentPos.pos].getValue( btree );
parentPos.dupsContainer = dupsContainer;
}
- catch( IOException e )
+ catch ( IOException e )
{
throw new RuntimeException( e );
}
}
}
+
/**
* {@inheritDoc}
*/
Modified:
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Node.java
URL:
http://svn.apache.org/viewvc/labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Node.java?rev=1462827&r1=1462826&r2=1462827&view=diff
==============================================================================
---
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Node.java
(original)
+++
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Node.java
Sat Mar 30 18:03:38 2013
@@ -44,7 +44,7 @@ public class Node<K, V> extends Abstract
/**
- * Create a new Node which will contain only one key, with references to
+ * Creates a new Node which will contain only one key, with references to
* a left and right page. This is a specific constructor used by the btree
* when the root was full when we added a new value.
*
@@ -63,7 +63,7 @@ public class Node<K, V> extends Abstract
/**
- * Create a new Node which will contain only one key, with references to
+ * Creates a new Node which will contain only one key, with references to
* a left and right page. This is a specific constructor used by the btree
* when the root was full when we added a new value.
*
@@ -104,7 +104,7 @@ public class Node<K, V> extends Abstract
/**
- * Create a new Node which will contain only one key, with references to
+ * Creates a new Node which will contain only one key, with references to
* a left and right page. This is a specific constructor used by the btree
* when the root was full when we added a new value.
*
@@ -194,9 +194,15 @@ public class Node<K, V> extends Abstract
/**
- * Modify the current node after a remove has been done in one of its
children.
+ * Modifies the current node after a remove has been done in one of its
children.
* The node won't be merged with another node.
- * @throws IOException
+ *
+ * @param removeResult The result of a remove operation
+ * @param index the position of the key, not transformed
+ * @param pos The position of the key, as a positive value
+ * @param found If the key has been found in the page
+ * @return The new result
+ * @throws IOException If we have an error while trying to access the page
*/
private RemoveResult<K, V> handleRemoveResult( RemoveResult<K, V>
removeResult, int index, int pos, boolean found )
throws IOException
@@ -230,14 +236,14 @@ public class Node<K, V> extends Abstract
/**
- * Handle the removal of an element from the root page, when two of its
children
+ * Handles the removal of an element from the root page, when two of its
children
* have been merged.
*
* @param mergedResult The merge result
* @param pos The position in the current root
* @param found Tells if the removed key is present in the root page
* @return The resulting root page
- * @throws IOException
+ * @throws IOException If we have an error while trying to access the page
*/
private RemoveResult<K, V> handleRootRemove( MergedWithSiblingResult<K, V>
mergedResult, int pos, boolean found )
throws IOException
@@ -262,7 +268,7 @@ public class Node<K, V> extends Abstract
/**
- * Borrow an element from the right sibling, creating a new sibling with
one
+ * Borrows an element from the right sibling, creating a new sibling with
one
* less element and creating a new page where the element to remove has
been
* deleted and the borrowed element added on the right.
*
@@ -270,7 +276,7 @@ public class Node<K, V> extends Abstract
* @param sibling The right sibling
* @param pos The position of the element to remove
* @return The resulting pages
- * @throws IOException
+ * @throws IOException If we have an error while trying to access the page
*/
private DeleteResult<K, V> borrowFromRight( long revision,
MergedWithSiblingResult<K, V> mergedResult,
Node<K, V> sibling, int pos ) throws IOException
@@ -344,7 +350,7 @@ public class Node<K, V> extends Abstract
/**
- * Borrow an element from the left sibling, creating a new sibling with one
+ * Borrows an element from the left sibling, creating a new sibling with
one
* less element and creating a new page where the element to remove has
been
* deleted and the borrowed element added on the left.
*
@@ -352,7 +358,7 @@ public class Node<K, V> extends Abstract
* @param sibling The left sibling
* @param pos The position of the element to remove
* @return The resulting pages
- * @throws IOException
+ * @throws IOException If we have an error while trying to access the page
*/
private DeleteResult<K, V> borrowFromLeft( long revision,
MergedWithSiblingResult<K, V> mergedResult,
Node<K, V> sibling, int pos ) throws IOException
@@ -428,13 +434,15 @@ public class Node<K, V> extends Abstract
* We have to merge the node with its sibling, both have N/2 elements
before the element
* removal.
*
- * @param revision
- * @param mergedResult
- * @param pos
- * @return
- * @throws IOException
+ * @param revision The revision
+ * @param mergedResult The result of the merge
+ * @param sibling The Page we will merge the current page with
+ * @param isLeft Tells if the sibling is on the left
+ * @param pos The position of the key that has been removed
+ * @return The page resulting of the merge
+ * @throws IOException If we have an error while trying to access the page
*/
- public DeleteResult<K, V> mergeWithSibling( long revision,
MergedWithSiblingResult<K, V> mergedResult,
+ private DeleteResult<K, V> mergeWithSibling( long revision,
MergedWithSiblingResult<K, V> mergedResult,
Node<K, V> sibling, boolean isLeft, int pos ) throws IOException
{
// Create the new node. It will contain N - 1 elements (the maximum
number)
@@ -551,7 +559,6 @@ public class Node<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
*/
public DeleteResult<K, V> delete( long revision, K key, Page<K, V> parent,
int parentPos ) throws IOException
{
@@ -677,7 +684,7 @@ public class Node<K, V> extends Abstract
* @param borrowedResult The result of the deletion from the children
* @param pos The position the key was found in the current node
* @return The result
- * @throws IOException
+ * @throws IOException If we have an error while trying to access the page
*/
private RemoveResult<K, V> handleBorrowedResult(
BorrowedFromSiblingResult<K, V> borrowedResult, int pos )
throws IOException
@@ -744,10 +751,11 @@ public class Node<K, V> extends Abstract
/**
* Remove the key at a given position.
*
+ * @param mergedResult The page we will remove a key from
* @param revision The revision of the modified page
* @param pos The position into the page of the element to remove
* @return The modified page with the <K,V> element added
- * @throws IOException
+ * @throws IOException If we have an error while trying to access the page
*/
private RemoveResult<K, V> removeKey( MergedWithSiblingResult<K, V>
mergedResult, long revision, int pos )
throws IOException
@@ -822,9 +830,6 @@ public class Node<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
- * @throws KeyNotFoundException
- * @throws EndOfFileExceededException
*/
public V get( K key ) throws IOException, KeyNotFoundException
{
@@ -845,6 +850,7 @@ public class Node<K, V> extends Abstract
/**
* Set the value at a give position
+ *
* @param pos The position in the values array
* @param value the value to inject
*/
@@ -856,10 +862,8 @@ public class Node<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
- public Page<K, V> getReference( int pos ) throws
EndOfFileExceededException, IOException
+ public Page<K, V> getReference( int pos ) throws IOException
{
if ( pos < nbElems + 1 )
{
@@ -874,11 +878,9 @@ public class Node<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
public Cursor<K, V> browse( K key, Transaction<K, V> transaction,
LinkedList<ParentPos<K, V>> stack )
- throws EndOfFileExceededException, IOException
+ throws IOException
{
int pos = findPos( key );
@@ -896,11 +898,9 @@ public class Node<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
public Cursor<K, V> browse( Transaction<K, V> transaction,
LinkedList<ParentPos<K, V>> stack )
- throws EndOfFileExceededException, IOException
+ throws IOException
{
stack.push( new ParentPos<K, V>( this, 0 ) );
@@ -917,7 +917,7 @@ public class Node<K, V> extends Abstract
* @param result The modified page
* @param pos The position of the found key
* @return A modified page
- * @throws IOException
+ * @throws IOException If we have an error while trying to access the page
*/
private InsertResult<K, V> replaceChild( long revision, ModifyResult<K, V>
result, int pos ) throws IOException
{
@@ -938,6 +938,13 @@ public class Node<K, V> extends Abstract
}
+ /**
+ * Creates a new holder contaning a reference to a Page
+ *
+ * @param page The page we will refer to
+ * @return A holder contaning a reference to the child page
+ * @throws IOException If we have an error while trying to access the page
+ */
private ElementHolder<Page<K, V>, K, V> createHolder( Page<K, V> page )
throws IOException
{
if ( btree.isManaged() )
@@ -960,7 +967,7 @@ public class Node<K, V> extends Abstract
/**
- * Add a new key into a copy of the current page at a given position. We
return the
+ * Adds a new key into a copy of the current page at a given position. We
return the
* modified page. The new page will have one more key than the current
page.
*
* @param revision The revision of the modified page
@@ -969,7 +976,7 @@ public class Node<K, V> extends Abstract
* @param rightPage The right child
* @param pos The position into the page
* @return The modified page with the <K,V> element added
- * @throws IOException
+ * @throws IOException If we have an error while trying to access the page
*/
private InsertResult<K, V> insertChild( long revision, K key, Page<K, V>
leftPage, Page<K, V> rightPage, int pos )
throws IOException
@@ -1007,7 +1014,7 @@ public class Node<K, V> extends Abstract
/**
- * Split a full page into two new pages, a left, a right and a pivot
element. The new pages will
+ * Splits a full page into two new pages, a left, a right and a pivot
element. The new pages will
* each contains half of the original elements. <br/>
* The pivot will be computed, depending on the place
* we will inject the newly added element. <br/>
@@ -1016,12 +1023,12 @@ public class Node<K, V> extends Abstract
* on the left, or the first element in the right page if it's added on
the right.
*
* @param revision The new revision for all the created pages
- * @param key The key to add
+ * @param pivot The key that will be move up after the split
* @param leftPage The left child
* @param rightPage The right child
* @param pos The position of the insertion of the new element
* @return An OverflowPage containing the pivot, and the new left and
right pages
- * @throws IOException
+ * @throws IOException If we have an error while trying to access the page
*/
private InsertResult<K, V> addAndSplit( long revision, K pivot, Page<K, V>
leftPage, Page<K, V> rightPage, int pos )
throws IOException
@@ -1106,7 +1113,7 @@ public class Node<K, V> extends Abstract
/**
- * Copy the current page and all its keys, with a new revision.
+ * Copies the current page and all its keys, with a new revision.
*
* @param revision The new revision
* @return The copied page
@@ -1127,8 +1134,6 @@ public class Node<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
public K getLeftMostKey() throws EndOfFileExceededException, IOException
{
@@ -1144,11 +1149,9 @@ public class Node<K, V> extends Abstract
return children[nbElems - 1].getValue( btree ).getRightMostKey();
}
-
+
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
public Tuple<K, V> findLeftMost() throws EndOfFileExceededException,
IOException
{
@@ -1158,8 +1161,6 @@ public class Node<K, V> extends Abstract
/**
* {@inheritDoc}
- * @throws IOException
- * @throws EndOfFileExceededException
*/
public Tuple<K, V> findRightMost() throws EndOfFileExceededException,
IOException
{
@@ -1168,8 +1169,6 @@ public class Node<K, V> extends Abstract
/**
- * @throws IOException
- * @throws EndOfFileExceededException
* @see Object#toString()
*/
public String toString()
Modified:
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Page.java
URL:
http://svn.apache.org/viewvc/labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Page.java?rev=1462827&r1=1462826&r2=1462827&view=diff
==============================================================================
---
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Page.java
(original)
+++
labs/mavibot/branches/mavibot-multivalue-support/mavibot/src/main/java/org/apache/mavibot/btree/Page.java
Sat Mar 30 18:03:38 2013
@@ -28,7 +28,8 @@ import org.apache.mavibot.btree.exceptio
/**
- * A MVCC Page interface.
+ * A MVCC Page interface. A Page can be either a Leaf (containing keys and
values) or a Node
+ * (containing keys and references to child pages).
*
* @param <K> The type for the Key
* @param <V> The type for the stored value
@@ -44,7 +45,7 @@ public interface Page<K, V>
/**
- * Insert the given key and value into this page. We first find the place
were to
+ * Inserts the given key and value into this page. We first find the place
were to
* inject the <K,V> into the tree, by recursively browsing the pages :<br/>
* <ul>
* <li>If the index is below zero, the key is present in the Page : we
modify the
@@ -59,20 +60,22 @@ public interface Page<K, V>
* @param key Inserted key
* @param value Inserted value
* @return Either a modified Page or an Overflow element if the Page was
full
+ * @throws IOException If we have an error while trying to access the page
*/
InsertResult<K, V> insert( long revision, K key, V value ) throws
IOException;
/**
- * delete an entry with the given key from this page. We first find the
place were to
+ * Deletes an entry with the given key from this page. We first find the
place were to
* remove the <K,V> into the tree, by recursively browsing the pages :<br/>
* <p>
*
* @param revision The new revision for the modified pages
* @param key The key to delete
* @param parent The parent page
- * @param parentPos he position of the current page in it's parent
- * @return
+ * @param parentPos The position of the current page in it's parent
+ * @return Either a modified Page if the key has been removed from the
page, or a NotPresentResult.
+ * @throws IOException If we have an error while trying to access the page
*/
DeleteResult<K, V> delete( long revision, K key, Page<K, V> parent, int
parentPos ) throws IOException;
@@ -88,39 +91,40 @@ public interface Page<K, V>
/**
- * Get the value associated with the given key, if any. If we don't have
+ * Gets the value associated with the given key, if any. If we don't have
* one, this method will throw a KeyNotFoundException.<br/>
* Note that we may get back null if a null value has been associated
* with the key.
*
* @param key The key we are looking for
+ * @return The associated value, which can be null
* @throws KeyNotFoundException If no entry with the given key can be found
- * @return The associated value, or null if there is none
+ * @throws IOException If we have an error while trying to access the page
*/
V get( K key ) throws KeyNotFoundException, IOException;
/**
- * browse the tree, looking for the given key, and create a Cursor on top
- * of the found result.
+ * Browses the tree, looking for the given key, and creates a Cursor on top
+ * of the found results.
*
* @param key The key we are looking for.
* @param transaction The started transaction for this operation
* @param stack The stack of parents we go through to get to this page
* @return A Cursor to browse the next elements
+ * @throws IOException If we have an error while trying to access the page
*/
Cursor<K, V> browse( K key, Transaction<K, V> transaction,
LinkedList<ParentPos<K, V>> stack )
- throws EndOfFileExceededException, IOException;
+ throws IOException;
/**
- * browse the whole tree, and create a Cursor on top of it.
+ * Browses the whole tree, and creates a Cursor on top of it.
*
* @param transaction The started transaction for this operation
* @param stack The stack of parents we go through to get to this page
* @return A Cursor to browse the next elements
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
Cursor<K, V> browse( Transaction<K, V> transaction,
LinkedList<ParentPos<K, V>> stack )
throws EndOfFileExceededException, IOException;
@@ -133,7 +137,8 @@ public interface Page<K, V>
/**
- * Return the key at a given position
+ * Returns the key at a given position
+ *
* @param pos The position of the key we want to retrieve
* @return The key found at the given position
*/
@@ -141,51 +146,48 @@ public interface Page<K, V>
/**
- * Find the leftmost key in this page. If the page is a node, it will go
+ * Finds the leftmost key in this page. If the page is a node, it will go
* down in the leftmost children to recursively find the leftmost key.
*
* @return The leftmost key in the tree
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
- K getLeftMostKey() throws EndOfFileExceededException, IOException;
+ K getLeftMostKey() throws IOException;
/**
- * Find the rightmost key in this page. If the page is a node, it will go
+ * Finds the rightmost key in this page. If the page is a node, it will go
* down in the rightmost children to recursively find the rightmost key.
*
* @return The rightmost key in the tree
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
- K getRightMostKey() throws EndOfFileExceededException, IOException;
+ K getRightMostKey() throws IOException;
+
-
/**
- * Find the leftmost element in this page. If the page is a node, it will
go
+ * Finds the leftmost element in this page. If the page is a node, it will
go
* down in the leftmost children to recursively find the leftmost element.
*
* @return The leftmost element in the tree
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
- Tuple<K, V> findLeftMost() throws EndOfFileExceededException, IOException;
+ Tuple<K, V> findLeftMost() throws IOException;
/**
- * Find the rightmost element in this page. If the page is a node, it will
go
+ * Finds the rightmost element in this page. If the page is a node, it
will go
* down in the rightmost children to recursively find the rightmost
element.
*
* @return The rightmost element in the tree
- * @throws IOException
- * @throws EndOfFileExceededException
+ * @throws IOException If we have an error while trying to access the page
*/
- Tuple<K, V> findRightMost() throws EndOfFileExceededException, IOException;
+ Tuple<K, V> findRightMost() throws IOException;
/**
- * Pretty-print the tree with tabs
+ * Pretty-prints the tree with tabs
+ *
* @param tabs The tabs to add in front of each node
* @return A pretty-print dump of the tree
*/
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
