svn commit: r189483 - in /incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index: B2I.java B2IController.java B2ICostController.java package.html

[mi...@apache.org]

Author: mikem
Date: Tue Jun  7 17:49:09 2005
New Revision: 189483

URL: http://svn.apache.org/viewcvs?rev=189483&view=rev
Log:
improved javadoc for the java/engine/org/apache/derby/impl/store/access/btree/index
directory.

patch contributed by: dibyendu@mazumdar.demon.co.uk


Added:
    incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/package.html
Modified:
    incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2I.java
    incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2IController.java
    incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2ICostController.java

Modified: incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2I.java
URL: http://svn.apache.org/viewcvs/incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2I.java?rev=189483&r1=189482&r2=189483&view=diff
==============================================================================
--- incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2I.java (original)
+++ incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2I.java Tue Jun  7 17:49:09 2005
@@ -70,13 +70,7 @@
 import org.apache.derby.iapi.services.io.FormatableBitSet;
 import org.apache.derby.iapi.services.cache.ClassSize;
 
-/**
-
-  A B2I object corresponds to an instance of a b-tree secondary index conglomerate.
-
-**/
-
-/**
+/*
  * @format_id ACCESS_B2I_V1_ID
  *
  * @purpose   The tag that describes the on disk representation of the B2I
@@ -96,9 +90,9 @@
  *     array_of_format_ids(byte[][])
  *     baseConglomerateId(long)
  *     rowLocationColumn(int)
- **/
+ */
 
-/**
+/*
  * @format_id ACCESS_B2I_V2_ID
  *
  * @purpose   The tag that describes the on disk representation of the B2I
@@ -126,8 +120,26 @@
  *     array_of_format_ids(byte[][])
  *     baseConglomerateId(long)
  *     rowLocationColumn(int)
- **/
+ */
 
+/**
+ * Implements an instance of a B-Tree secondary index conglomerate.
+ * A B2I object has two roles.
+ * <ol>
+ * <li>
+ * The B2I object is stored on disk, and holds the store specific
+ * information needed to access/describe the conglomerate. This
+ * includes information such as the format ids of the columns, 
+ * the conglomerate id of the base table, the location of 
+ * row location column.
+ * </li>
+ * <li>
+ * Access to all the interfaces start by making a call off the
+ * Conglomerate interface. So for instance to get a scan on the
+ * conglomerate method {@link #openScan openScan} should be called.
+ * </li>
+ * </ol>
+ */
 public class B2I extends BTree
 {
     public    static final String PROPERTY_BASECONGLOMID = "baseConglomerateId";

Modified: incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2IController.java
URL: http://svn.apache.org/viewcvs/incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2IController.java?rev=189483&r1=189482&r2=189483&view=diff
==============================================================================
--- incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2IController.java (original)
+++ incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2IController.java Tue Jun  7 17:49:09 2005
@@ -47,12 +47,12 @@
 import org.apache.derby.iapi.services.io.FormatableBitSet;
 
 /**
-
-  A B2I controller object is the concrete class which corresponds to an open
-  b-tree secondary index.
-
-**/
-
+ * Implements the ConglomerateController interface for the B-Tree index
+ * access method.  The primary use of this interface is to insert rows
+ * into the tree.
+ * <p>
+ * A B2I controller object corresponds to an open B-Tree secondary index.
+ */
 public class B2IController extends BTreeController
 {
 

Modified: incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2ICostController.java
URL: http://svn.apache.org/viewcvs/incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2ICostController.java?rev=189483&r1=189482&r2=189483&view=diff
==============================================================================
--- incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2ICostController.java (original)
+++ incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/B2ICostController.java Tue Jun  7 17:49:09 2005
@@ -37,12 +37,12 @@
 
 
 /**
-
-  A B2I controller object is the concrete class which corresponds to an open
-  b-tree secondary index.
-
-**/
-
+ * Implements the StoreCostController interface for the B-Tree index
+ * implementation.  The primary use of this interface is to provide costs
+ * used by the query optimizer to use when choosing query plans. Provides
+ * costs of things like fetch one row, how many rows in conglomerate, how
+ * many rows between these 2 keys.
+ */
 public class B2ICostController extends BTreeCostController
 {
 

Added: incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/package.html
URL: http://svn.apache.org/viewcvs/incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/package.html?rev=189483&view=auto
==============================================================================
--- incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/package.html (added)
+++ incubator/derby/code/trunk/java/engine/org/apache/derby/impl/store/access/btree/index/package.html Tue Jun  7 17:49:09 2005
@@ -0,0 +1,40 @@
+<html>
+<head>
+<title>BTree Indexes with Locking</title>
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+</head>
+<body>
+<p>
+Implements classes used by the language layer to implement
+SQL secondary indexes. The classes here extend and use the classes in
+{@link org.apache.derby.impl.store.access.btree} to implement 
+a locked btree index.
+<p>
+The key to understanding the class layout is to understand the public
+store interfaces in
+{@link org.apache.derby.iapi.store.access.conglomerate}, which contains
+the shared interfaces that must be implemented by all access methods. 
+Currently Derby implements heap and btree index access methods. Users of 
+access methods use the same interface no matter what the underlying 
+type or particular implementation of the access method. Therefore, Derby 
+can support multiple types of btree index implementations, which if done 
+right should require no changes to actual users of the access methods.
+<p>
+In reality the interfaces would have to change in some ways to 
+support a radically different kind of access method, such as 
+<a href="http://gist.cs.berkeley.edu/gist1.html">GiST</a>. But 
+the implementor should enhance the interfaces in the conglomerate 
+package so that these can then be supported by all existing access 
+methods.
+<h2>Isolation Levels</h2>
+<p>Isolation level implementation in the B-Tree index is done with data
+only locking, i.e., locks on secondary index rows are actually locks on the
+data rows that they point to. The specifics of particular isolation levels
+are hidden in various implementations of the {@link org.apache.derby.impl.store.access.btree.BTreeLockingPolicy BTreeLockingPolicy} class.  
+The classes which do scans, deletes, and inserts do not have isolation 
+specific code, instead they make lock calls using BTreeLockingPolicy 
+interfaces, and then depending on the isolation level one of the implmentations
+does the actual locking.
+</p>
+</body>
+</html>
\ No newline at end of file