org.apache.derby.impl.store.access.btree.index
Class B2I

java.lang.Object
  extended by org.apache.derby.iapi.types.DataType
      extended by org.apache.derby.impl.store.access.conglomerate.GenericConglomerate
          extended by org.apache.derby.impl.store.access.btree.BTree
              extended by org.apache.derby.impl.store.access.btree.index.B2I
All Implemented Interfaces:
java.io.Externalizable, java.io.Serializable, java.lang.Comparable, Formatable, Storable, TypedFormat, Conglomerate, DataValueDescriptor, Orderable
Direct Known Subclasses:
B2I_10_3, B2I_v10_2

public class B2I
extends BTree

Implements an instance of a B-Tree secondary index conglomerate. A B2I object has two roles.

  1. 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.
  2. 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 openScan should be called.

See Also:
Serialized Form

Field Summary
private static int BASE_MEMORY_USAGE
           
(package private)  long baseConglomerateId
          The id of the conglomerate which contains the base table.
(package private) static int FORMAT_NUMBER
           
private static java.lang.String PROPERTY_BASECONGLOMID
           
private static java.lang.String PROPERTY_ROWLOCCOLUMN
           
(package private)  int rowLocationColumn
          The column id (zero-based integer index) of the column which holds the row location to the base conglomerate.
 
Fields inherited from class org.apache.derby.impl.store.access.btree.BTree
ascDescInfo, collation_ids, conglom_format_id, format_ids, id, nKeyFields, PROPERTY_ALLOWDUPLICATES, PROPERTY_MAX_ROWS_PER_PAGE_PARAMETER, PROPERTY_NKEYFIELDS, PROPERTY_NUNIQUECOLUMNS, PROPERTY_PARENTLINKS, PROPERTY_UNIQUE_WITH_DUPLICATE_NULLS, ROOTPAGEID
 
Fields inherited from interface org.apache.derby.iapi.types.DataValueDescriptor
UNKNOWN_LOGICAL_LENGTH
 
Fields inherited from interface org.apache.derby.iapi.types.Orderable
ORDER_OP_EQUALS, ORDER_OP_GREATEROREQUALS, ORDER_OP_GREATERTHAN, ORDER_OP_LESSOREQUALS, ORDER_OP_LESSTHAN
 
Constructor Summary
B2I()
           
 
Method Summary
 void compressConglomerate(TransactionManager xact_manager, Transaction rawtran)
           
 void create(TransactionManager xact_manager, int segmentId, long input_conglomid, DataValueDescriptor[] template, ColumnOrdering[] columnOrder, int[] collationIds, java.util.Properties properties, int temporaryFlag)
          Create an empty secondary index b-tree, using the generic b-tree to do the generic part of the creation process.
 ScanManager defragmentConglomerate(TransactionManager xact_manager, Transaction rawtran, boolean hold, int open_mode, int lock_level, LockingPolicy locking_policy, int isolation_level)
          Open a b-tree compress scan.
 void drop(TransactionManager xact_manager)
          Drop this b-tree secondary index.
 int estimateMemoryUsage()
          Estimate the memory usage in bytes of the data value and the overhead of the class.
 boolean fetchMaxOnBTree(TransactionManager xact_manager, Transaction rawtran, long conglomId, int open_mode, int lock_level, LockingPolicy locking_policy, int isolation_level, FormatableBitSet scanColumnList, DataValueDescriptor[] fetchRow)
          Retrieve the maximum value row in an ordered conglomerate.
protected  BTreeLockingPolicy getBtreeLockingPolicy(Transaction rawtran, int lock_level, int mode, int isolation_level, ConglomerateController base_cc, OpenBTree open_btree)
          Create a new btree locking policy from scratch.
 StaticCompiledOpenConglomInfo getStaticCompiledConglomInfo(TransactionController xact_manager, long conglomId)
          Return static information about the conglomerate to be included in a a compiled plan.
 int getTypeFormatId()
          Return my format identifier.
 long load(TransactionManager xact_manager, boolean createConglom, RowLocationRetRowSource rowSource)
          Bulk Load a B-tree secondary index.
private  void localReadExternal(java.io.ObjectInput in)
          Restore the in-memory representation from the stream.
 ConglomerateController lockTable(TransactionManager xact_manager, int open_mode, int lock_level, int isolation_level)
          Lock the base table.
 ConglomerateController open(TransactionManager xact_manager, Transaction rawtran, boolean hold, int open_mode, int lock_level, LockingPolicy locking_policy, StaticCompiledOpenConglomInfo static_info, DynamicCompiledOpenConglomInfo dynamic_info)
          Open a b-tree controller.
 ScanManager openScan(TransactionManager xact_manager, Transaction rawtran, boolean hold, int open_mode, int lock_level, LockingPolicy locking_policy, int isolation_level, FormatableBitSet scanColumnList, DataValueDescriptor[] startKeyValue, int startSearchOperator, Qualifier[][] qualifier, DataValueDescriptor[] stopKeyValue, int stopSearchOperator, StaticCompiledOpenConglomInfo static_info, DynamicCompiledOpenConglomInfo dynamic_info)
          Open a b-tree secondary index scan controller.
 StoreCostController openStoreCost(TransactionManager xact_manager, Transaction rawtran)
          Return an open StoreCostController for the conglomerate.
 void purgeConglomerate(TransactionManager xact_manager, Transaction rawtran)
           
 void readExternal(java.io.ObjectInput in)
          Restore the in-memory representation from the stream.
 void readExternalFromArray(ArrayInputStream in)
          Read the DataValueDescriptor from the stream.
private  void traverseRight()
          Private methods of B2I, arranged alphabetically.
 void writeExternal_v10_2(java.io.ObjectOutput out)
          Store the stored representation of the column value in the stream.
 void writeExternal_v10_3(java.io.ObjectOutput out)
          Store the stored representation of the column value in the stream.
 void writeExternal(java.io.ObjectOutput out)
          Store the stored representation of the column value in the stream.
 
Methods inherited from class org.apache.derby.impl.store.access.btree.BTree
addColumn, create, createTemplate, getContainerid, getDynamicCompiledConglomInfo, getId, isNull, isTemporary, isUnique, isUniqueWithDuplicateNulls, restoreToNull, setUniqueWithDuplicateNulls, toString
 
Methods inherited from class org.apache.derby.impl.store.access.conglomerate.GenericConglomerate
cloneValue, compare, getLength, getNewNull, getObject, getString, getTypeName, setFrom, setValueFromResultSet
 
Methods inherited from class org.apache.derby.iapi.types.DataType
checkHostVariable, cloneHolder, coalesce, compare, compare, compare, compareTo, dataTypeConversion, equals, equals, flip, getBoolean, getByte, getBytes, getDate, getDouble, getFloat, getInt, getLong, getNationalString, getShort, getStream, getTime, getTimestamp, getTraceString, greaterOrEquals, greaterThan, hasStream, in, invalidFormat, isNotNull, isNullOp, lessOrEquals, lessThan, normalize, notEquals, outOfRange, recycle, setBigDecimal, setInto, setInto, setObjectForCast, setToNull, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, throwLangSetMismatch, typePrecedence, typeToBigDecimal
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.apache.derby.iapi.types.DataValueDescriptor
checkHostVariable, cloneHolder, coalesce, compare, compare, compare, equals, getBoolean, getByte, getBytes, getDate, getDouble, getFloat, getInt, getLong, getShort, getStream, getTime, getTimestamp, getTraceString, greaterOrEquals, greaterThan, hasStream, in, isNotNull, isNullOp, lessOrEquals, lessThan, normalize, notEquals, recycle, setBigDecimal, setInto, setInto, setObjectForCast, setToNull, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, typePrecedence, typeToBigDecimal
 

Field Detail

PROPERTY_BASECONGLOMID

private static final java.lang.String PROPERTY_BASECONGLOMID
See Also:
Constant Field Values

PROPERTY_ROWLOCCOLUMN

private static final java.lang.String PROPERTY_ROWLOCCOLUMN
See Also:
Constant Field Values

FORMAT_NUMBER

static final int FORMAT_NUMBER
See Also:
Constant Field Values

baseConglomerateId

long baseConglomerateId
The id of the conglomerate which contains the base table. Row locations inserted into this secondary index are assumed to refer to that conglomerate. Used to obtain table/row locks on the base table rows which the index rows point at.


rowLocationColumn

int rowLocationColumn
The column id (zero-based integer index) of the column which holds the row location to the base conglomerate. The default value of RowLocationColumn is the last key column. Used to obtain table/row locks on the base table rows with the index rows point at. Currently, RowLocationColumn must be the last key column.


BASE_MEMORY_USAGE

private static final int BASE_MEMORY_USAGE
Constructor Detail

B2I

public B2I()
Method Detail

estimateMemoryUsage

public int estimateMemoryUsage()
Description copied from interface: DataValueDescriptor
Estimate the memory usage in bytes of the data value and the overhead of the class.

Returns:
the estimated memory usage

getBtreeLockingPolicy

protected BTreeLockingPolicy getBtreeLockingPolicy(Transaction rawtran,
                                                   int lock_level,
                                                   int mode,
                                                   int isolation_level,
                                                   ConglomerateController base_cc,
                                                   OpenBTree open_btree)
                                            throws StandardException
Create a new btree locking policy from scratch.

Specified by:
getBtreeLockingPolicy in class BTree
Throws:
StandardException - Standard exception policy.

lockTable

public final ConglomerateController lockTable(TransactionManager xact_manager,
                                              int open_mode,
                                              int lock_level,
                                              int isolation_level)
                                       throws StandardException
Lock the base table.

Assumes that segment of the base container is the same as the segment of the btree segment.

RESOLVE - we really want to get the lock without opening the container. raw store will be providing this.

Specified by:
lockTable in class BTree
Parameters:
xact_manager - Transaction to associate the lock with.
Throws:
StandardException - Standard exception policy.

traverseRight

private void traverseRight()
Private methods of B2I, arranged alphabetically.


create

public void create(TransactionManager xact_manager,
                   int segmentId,
                   long input_conglomid,
                   DataValueDescriptor[] template,
                   ColumnOrdering[] columnOrder,
                   int[] collationIds,
                   java.util.Properties properties,
                   int temporaryFlag)
            throws StandardException
Create an empty secondary index b-tree, using the generic b-tree to do the generic part of the creation process. This routine opens the newly created container, adds a single page, and makes this page the root by inserting a LeafControlRow onto this page at slot 0 and marking in that control row that the page is a root page. The following properties are specific to the b-tree secondary index: A secondary index i (a, b) on table t (a, b, c) would have rows which looked like (a, b, row_location). baseConglomerateId is set to the conglomerate id of t. rowLocationColumns is set to 2. allowsDuplicates would be set to false, @see BTree#create. To create a unique secondary index set uniquenessColumns to 2, this means that the btree code will compare the key values but not the row id when determing uniqueness. To create a nonunique secondary index set uniquenessColumns to 3, this would mean that the uniqueness test would include the row location and since all row locations will be unique all rows inserted into the index will be differentiated (at least) by row location.

Throws:
StandardException - Standard exception policy.
See Also:
BTree.create(org.apache.derby.iapi.store.raw.Transaction, int, long, org.apache.derby.iapi.types.DataValueDescriptor[], java.util.Properties, int, int)

fetchMaxOnBTree

public boolean fetchMaxOnBTree(TransactionManager xact_manager,
                               Transaction rawtran,
                               long conglomId,
                               int open_mode,
                               int lock_level,
                               LockingPolicy locking_policy,
                               int isolation_level,
                               FormatableBitSet scanColumnList,
                               DataValueDescriptor[] fetchRow)
                        throws StandardException
Retrieve the maximum value row in an ordered conglomerate.

Returns true and fetches the rightmost row of an ordered conglomerate into "fetchRow" if there is at least one row in the conglomerate. If there are no rows in the conglomerate it returns false.

Non-ordered conglomerates will not implement this interface, calls will generate a StandardException.

RESOLVE - this interface is temporary, long term equivalent (and more) functionality will be provided by the openBackwardScan() interface.

Parameters:
xact_manager - The TransactionController under which this operation takes place.
conglomId - The identifier of the conglomerate to open the scan for.
open_mode - Specifiy flags to control opening of table. OPENMODE_FORUPDATE - if set open the table for update otherwise open table shared.
lock_level - One of (MODE_TABLE, MODE_RECORD, or MODE_NONE).
isolation_level - The isolation level to lock the conglomerate at. One of (ISOLATION_READ_COMMITTED or ISOLATION_SERIALIZABLE).
scanColumnList - A description of which columns to return from every fetch in the scan. template, and scanColumnList work together to describe the row to be returned by the scan - see RowUtil for description of how these three parameters work together to describe a "row".
fetchRow - The row to retrieve the maximum value into.
rawtran - The raw store xact to associate all ops with.
locking_policy - The LockingPolicy to use to open the conglomerate.
Returns:
boolean indicating if a row was found and retrieved or not.
Throws:
StandardException - Standard exception policy.

load

public long load(TransactionManager xact_manager,
                 boolean createConglom,
                 RowLocationRetRowSource rowSource)
          throws StandardException
Bulk Load a B-tree secondary index.

Specified by:
load in interface Conglomerate
Specified by:
load in class BTree
Parameters:
xact_manager - The TransactionController under which this operation takes place.
createConglom - If true, the conglomerate is being created in the same operation as the openAndLoadConglomerate. The enables further optimization as recovery does not require page allocation to be logged.
rowSource - Where the rows come from.
Returns:
The number of rows loaded.
Throws:
StandardException - Standard Derby Error policy. raise SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION if a duplicate key is detected in the load.
See Also:
Conglomerate.load(org.apache.derby.iapi.store.access.conglomerate.TransactionManager, boolean, org.apache.derby.iapi.store.access.RowLocationRetRowSource)

open

public ConglomerateController open(TransactionManager xact_manager,
                                   Transaction rawtran,
                                   boolean hold,
                                   int open_mode,
                                   int lock_level,
                                   LockingPolicy locking_policy,
                                   StaticCompiledOpenConglomInfo static_info,
                                   DynamicCompiledOpenConglomInfo dynamic_info)
                            throws StandardException
Open a b-tree controller.

Specified by:
open in interface Conglomerate
Specified by:
open in class BTree
Parameters:
xact_manager - The access xact to associate all ops on cc with.
rawtran - The raw store xact to associate all ops on cc with.
open_mode - A bit mask of TransactionController.MODE_* bits, indicating info about the open.
lock_level - Either TransactionController.MODE_TABLE or TransactionController.MODE_RECORD, as passed into the openConglomerate() call.
locking_policy - The LockingPolicy to use to open the conglomerate.
Returns:
The open ConglomerateController.
Throws:
StandardException - Standard exception policy.
See Also:
Conglomerate.open(org.apache.derby.iapi.store.access.conglomerate.TransactionManager, org.apache.derby.iapi.store.raw.Transaction, boolean, int, int, org.apache.derby.iapi.store.raw.LockingPolicy, org.apache.derby.iapi.store.access.StaticCompiledOpenConglomInfo, org.apache.derby.iapi.store.access.DynamicCompiledOpenConglomInfo)

openScan

public ScanManager openScan(TransactionManager xact_manager,
                            Transaction rawtran,
                            boolean hold,
                            int open_mode,
                            int lock_level,
                            LockingPolicy locking_policy,
                            int isolation_level,
                            FormatableBitSet scanColumnList,
                            DataValueDescriptor[] startKeyValue,
                            int startSearchOperator,
                            Qualifier[][] qualifier,
                            DataValueDescriptor[] stopKeyValue,
                            int stopSearchOperator,
                            StaticCompiledOpenConglomInfo static_info,
                            DynamicCompiledOpenConglomInfo dynamic_info)
                     throws StandardException
Open a b-tree secondary index scan controller.

Throws:
StandardException - Standard exception policy.
See Also:
Conglomerate.openScan(org.apache.derby.iapi.store.access.conglomerate.TransactionManager, org.apache.derby.iapi.store.raw.Transaction, boolean, int, int, org.apache.derby.iapi.store.raw.LockingPolicy, int, org.apache.derby.iapi.services.io.FormatableBitSet, org.apache.derby.iapi.types.DataValueDescriptor[], int, org.apache.derby.iapi.store.access.Qualifier[][], org.apache.derby.iapi.types.DataValueDescriptor[], int, org.apache.derby.iapi.store.access.StaticCompiledOpenConglomInfo, org.apache.derby.iapi.store.access.DynamicCompiledOpenConglomInfo), Conglomerate.openScan(org.apache.derby.iapi.store.access.conglomerate.TransactionManager, org.apache.derby.iapi.store.raw.Transaction, boolean, int, int, org.apache.derby.iapi.store.raw.LockingPolicy, int, org.apache.derby.iapi.services.io.FormatableBitSet, org.apache.derby.iapi.types.DataValueDescriptor[], int, org.apache.derby.iapi.store.access.Qualifier[][], org.apache.derby.iapi.types.DataValueDescriptor[], int, org.apache.derby.iapi.store.access.StaticCompiledOpenConglomInfo, org.apache.derby.iapi.store.access.DynamicCompiledOpenConglomInfo)

defragmentConglomerate

public ScanManager defragmentConglomerate(TransactionManager xact_manager,
                                          Transaction rawtran,
                                          boolean hold,
                                          int open_mode,
                                          int lock_level,
                                          LockingPolicy locking_policy,
                                          int isolation_level)
                                   throws StandardException
Open a b-tree compress scan.

B2I does not support a compress scan.

hold - see openScan()
open_mode - see openScan()
lock_level - see openScan()
isolation_level - see openScan()
Returns:
The GroupFetchScanController to be used to fetch the rows.
Throws:
StandardException - Standard exception policy.
See Also:
Conglomerate.defragmentConglomerate(org.apache.derby.iapi.store.access.conglomerate.TransactionManager, org.apache.derby.iapi.store.raw.Transaction, boolean, int, int, org.apache.derby.iapi.store.raw.LockingPolicy, int)

purgeConglomerate

public void purgeConglomerate(TransactionManager xact_manager,
                              Transaction rawtran)
                       throws StandardException
Throws:
StandardException

compressConglomerate

public void compressConglomerate(TransactionManager xact_manager,
                                 Transaction rawtran)
                          throws StandardException
Throws:
StandardException

openStoreCost

public StoreCostController openStoreCost(TransactionManager xact_manager,
                                         Transaction rawtran)
                                  throws StandardException
Return an open StoreCostController for the conglomerate.

Return an open StoreCostController which can be used to ask about the estimated row counts and costs of ScanController and ConglomerateController operations, on the given conglomerate.

Parameters:
xact_manager - The TransactionController under which this operation takes place.
rawtran - raw transaction context in which scan is managed.
Returns:
The open StoreCostController.
Throws:
StandardException - Standard exception policy.
See Also:
StoreCostController

drop

public void drop(TransactionManager xact_manager)
          throws StandardException
Drop this b-tree secondary index.

Specified by:
drop in interface Conglomerate
Specified by:
drop in class BTree
Throws:
StandardException - Standard exception policy.
See Also:
Conglomerate.drop(org.apache.derby.iapi.store.access.conglomerate.TransactionManager), BTree.drop(org.apache.derby.iapi.store.access.conglomerate.TransactionManager)

getStaticCompiledConglomInfo

public StaticCompiledOpenConglomInfo getStaticCompiledConglomInfo(TransactionController xact_manager,
                                                                  long conglomId)
                                                           throws StandardException
Return static information about the conglomerate to be included in a a compiled plan.

The static info would be valid until any ddl was executed on the conglomid, and would be up to the caller to throw away when that happened. This ties in with what language already does for other invalidation of static info. The type of info in this would be containerid and array of format id's from which templates can be created. The info in this object is read only and can be shared among as many threads as necessary.

Parameters:
conglomId - The identifier of the conglomerate to open.
xact_manager - The TransactionController under which this operation takes place.
Returns:
The static compiled information.
Throws:
StandardException - Standard exception policy.

getTypeFormatId

public int getTypeFormatId()
Return my format identifier.

Returns:
The identifier. (A UUID stuffed in an array of 16 bytes).
See Also:
TypedFormat.getTypeFormatId()

writeExternal_v10_2

public void writeExternal_v10_2(java.io.ObjectOutput out)
                         throws java.io.IOException
Store the stored representation of the column value in the stream.

For more detailed description of the ACCESS_B2I_V3_ID format see documentation at top of file.

Throws:
java.io.IOException
See Also:
Externalizable.writeExternal(java.io.ObjectOutput)

writeExternal_v10_3

public void writeExternal_v10_3(java.io.ObjectOutput out)
                         throws java.io.IOException
Store the stored representation of the column value in the stream.

For more detailed description of the ACCESS_B2I_V3_ID and ACCESS_B2I_V4_ID formats see documentation at top of file.

Throws:
java.io.IOException
See Also:
Externalizable.writeExternal(java.io.ObjectOutput)

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
Store the stored representation of the column value in the stream.

For more detailed description of the ACCESS_B2I_V3_ID and ACCESS_B2I_V5_ID formats see documentation at top of file.

Specified by:
writeExternal in interface java.io.Externalizable
Overrides:
writeExternal in class BTree
Throws:
java.io.IOException - thrown by writeObject()
See Also:
Externalizable.writeExternal(java.io.ObjectOutput)

localReadExternal

private final void localReadExternal(java.io.ObjectInput in)
                              throws java.io.IOException,
                                     java.lang.ClassNotFoundException
Restore the in-memory representation from the stream.

Throws:
java.lang.ClassNotFoundException - Thrown if the stored representation is serialized and a class named in the stream could not be found.
java.io.IOException
See Also:
Externalizable.readExternal(java.io.ObjectInput)

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
Description copied from class: BTree
Restore the in-memory representation from the stream.

Specified by:
readExternal in interface java.io.Externalizable
Overrides:
readExternal in class BTree
Throws:
java.io.IOException - thrown by readObject()
java.lang.ClassNotFoundException - Thrown if the stored representation is serialized and a class named in the stream could not be found.
See Also:
Externalizable.readExternal(java.io.ObjectInput)

readExternalFromArray

public void readExternalFromArray(ArrayInputStream in)
                           throws java.io.IOException,
                                  java.lang.ClassNotFoundException
Description copied from interface: DataValueDescriptor
Read the DataValueDescriptor from the stream.

Initialize the data value by reading it's values from the ArrayInputStream. This interface is provided as a way to achieve possible performance enhancement when reading an array can be optimized over reading from a generic stream from readExternal().

Specified by:
readExternalFromArray in interface DataValueDescriptor
Overrides:
readExternalFromArray in class BTree
Parameters:
in - The array stream positioned at the beginning of the byte stream to read from.
Throws:
java.io.IOException - Usual error is if you try to read past limit on the stream.
java.lang.ClassNotFoundException - If a necessary class can not be found while reading the object from the stream.

Built on Thu 2010-12-23 20:49:13+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.