org.apache.derby.impl.store.access.conglomerate
Class OpenConglomerate

java.lang.Object
  extended by org.apache.derby.impl.store.access.conglomerate.OpenConglomerate
Direct Known Subclasses:
OpenHeap

public abstract class OpenConglomerate
extends java.lang.Object

A Generic class which implements the basic functionality needed to operate on an "open" conglomerate. This class assumes the following general things about the access method.

The access method is page based and contained in a single container maintained by raw store.


Field Summary
private  ContainerHandle container
           
private  boolean forUpdate
           
private  boolean getBaseTableLocks
           
private  Conglomerate init_conglomerate
          The following group of fields are all basic input parameters which are provided by the calling code when doing any sort of operation requiring an open conglomerate (openScan(), open(), openCostController(), ...).
private  DynamicCompiledOpenConglomInfo init_dynamic_info
           
private  boolean init_hold
           
private  int init_lock_level
           
private  LockingPolicy init_locking_policy
           
private  int init_openmode
           
private  Transaction init_rawtran
           
private  TransactionManager init_xact_manager
           
private  OpenConglomerateScratchSpace runtime_mem
          scratch space used for stuff like templates, export rows, ...
private  boolean useUpdateLocks
          convenience boolean's for various mode's
 
Constructor Summary
OpenConglomerate()
           
 
Method Summary
 void checkConsistency()
          Check consistency of a conglomerate.
 void close()
          Close the container.
 void debugConglomerate()
           
 Conglomerate getConglomerate()
           
 ContainerHandle getContainer()
           
abstract  int[] getFormatIds()
           
 boolean getHold()
           
 java.util.Properties getInternalTablePropertySet(java.util.Properties prop)
          Request set of properties associated with a table.
 int getOpenMode()
           
 Transaction getRawTran()
           
 OpenConglomerateScratchSpace getRuntimeMem()
           
 SpaceInfo getSpaceInfo()
          Get information about space used by the conglomerate.
 void getTableProperties(java.util.Properties prop)
          Request the system properties associated with a table.
 TransactionManager getXactMgr()
          Public Accessors of This class:
 ContainerHandle init(ContainerHandle open_container, Conglomerate conglomerate, int[] format_ids, int[] collation_ids, TransactionManager xact_manager, Transaction rawtran, boolean hold, int openmode, int lock_level, LockingPolicy locking_policy, DynamicCompiledOpenConglomInfo dynamic_info)
          Open the container.
 boolean isClosed()
           
 boolean isForUpdate()
           
protected  boolean isKeyed()
           
protected  boolean isTableLocked()
          is the open btree table locked?
 boolean isUseUpdateLocks()
           
 boolean latchPage(RowPosition pos)
           Latch the page containing the current RowPosition.
 boolean latchPageAndRepositionScan(RowPosition pos)
          Latch the page containing the current RowPosition, and reposition scan.
 boolean lockPositionForRead(RowPosition pos, RowPosition aux_pos, boolean moveForwardIfRowDisappears, boolean waitForLock)
           Lock row at given row position for read.
 boolean lockPositionForWrite(RowPosition pos, boolean forInsert, boolean waitForLock)
           Lock the row at the given position for write.
protected abstract  RowLocation newRowLocationTemplate()
          Return an "empty" row location object of the correct type.
 ContainerHandle reopen()
          Open the container.
 void unlockPositionAfterRead(RowPosition pos)
          Unlock the record after a previous request to lock it.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

init_conglomerate

private Conglomerate init_conglomerate
The following group of fields are all basic input parameters which are provided by the calling code when doing any sort of operation requiring an open conglomerate (openScan(), open(), openCostController(), ...). These are just saved values from what was initially input.


init_xact_manager

private TransactionManager init_xact_manager

init_rawtran

private Transaction init_rawtran

init_openmode

private int init_openmode

init_lock_level

private int init_lock_level

init_dynamic_info

private DynamicCompiledOpenConglomInfo init_dynamic_info

init_hold

private boolean init_hold

init_locking_policy

private LockingPolicy init_locking_policy

useUpdateLocks

private boolean useUpdateLocks
convenience boolean's for various mode's


forUpdate

private boolean forUpdate

getBaseTableLocks

private boolean getBaseTableLocks

runtime_mem

private OpenConglomerateScratchSpace runtime_mem
scratch space used for stuff like templates, export rows, ...


container

private ContainerHandle container
Constructor Detail

OpenConglomerate

public OpenConglomerate()
Method Detail

newRowLocationTemplate

protected abstract RowLocation newRowLocationTemplate()
                                               throws StandardException
Return an "empty" row location object of the correct type.

Returns:
The empty Rowlocation.
Throws:
StandardException - Standard exception policy.

getFormatIds

public abstract int[] getFormatIds()

latchPageAndRepositionScan

public boolean latchPageAndRepositionScan(RowPosition pos)
                                   throws StandardException
Latch the page containing the current RowPosition, and reposition scan.

Upon return the scan will hold a latch on the page to continue the scan on. The scan will positioned on the record, just before the next record to return. Note that for both hold cursor and read uncommitted support this routine handles all cases of either the current position "dissappearing" (either the row and/or page). The row and/or page can disappear by deleted space being reclaimed post commit of that delete, and for some reason the code requesting the reposition does not have locks which prevented the space reclamation. Both hold cursor and read uncommitted scans are examples of ways the caller will not prevent space reclamation from claiming the position. This implementation also automatically updates the RowPosition to point at the slot containing the current RowPosition. This slot value is only valid while the latch is held.

Returns:
true if scan had to reposition because a row disappeared.
Throws:
StandardException - Standard exception policy.

latchPage

public boolean latchPage(RowPosition pos)
                  throws StandardException

Latch the page containing the current RowPosition.

This implementation also automatically updates the RowPosition to point at the slot containing the current RowPosition. This slot value is only valid while the latch is held.

If the row pointed to by pos does not exist (including the case where the page itself does not exist), the page will not be latched, and pos.current_page will be set to null.

Parameters:
pos - the position to a row on the page that should be latched
Returns:
true if the page was successfully latched, or false otherwise
Throws:
StandardException - Standard exception policy.

lockPositionForRead

public boolean lockPositionForRead(RowPosition pos,
                                   RowPosition aux_pos,
                                   boolean moveForwardIfRowDisappears,
                                   boolean waitForLock)
                            throws StandardException

Lock row at given row position for read.

This routine requests a row lock NOWAIT on the row located at the given RowPosition. If the lock is granted NOWAIT the routine will return true. If the lock cannot be granted NOWAIT, then the routine will release the latch on "page" and then it will request a WAIT lock on the row.

This implementation: Assumes latch held on current_page. If the current_rh field of RowPosition is non-null it is assumed that we want to lock that record handle and that we don't have a slot number. If the current_rh field of RowPosition is null, it is assumed the we want to lock the indicated current_slot. Upon return current_rh will point to the record handle associated with current_slot.

After waiting and getting the lock on the row, this routine will fix up RowPosition to point at the row locked. This means it will get the page latch again, and it will fix the current_slot to point at the waited for record handle - it may have moved while waiting on the lock.

When this method returns, the page holding the row pointed to by the RowLocation is latched. This is however not the case if moveForwardIfRowDisappears is false and the row has disappeared. Then the latch will be released before the method returns, and pos.current_page will be set to null.

Parameters:
pos - Position to lock.
aux_pos - If you have to give up latch to get lock, then also unlock this position if it is non-null.
moveForwardIfRowDisappears - If true, then this routine must handle the case where the row id we are waiting on disappears when the latch is released. If false, and the row disappears, the latch will be released again and false is returned.
waitForLock - if true wait for lock, if lock can't be granted NOWAIT, else if false, throw a lock timeout exception if the lock can't be granted without waiting.
Returns:
true if lock granted without releasing the latch, else return false.
Throws:
StandardException - Standard exception policy.

lockPositionForWrite

public boolean lockPositionForWrite(RowPosition pos,
                                    boolean forInsert,
                                    boolean waitForLock)
                             throws StandardException

Lock the row at the given position for write.

The page pointed to by the RowPosition is assumed to be latched when this method is called. If the lock cannot be obtained without waiting, the latch will be released and re-obtained when the lock has been acquired.

If the latch was released while waiting for the lock, and the row does not exist after the lock is obtained, the latch will be released again before the method returns, and pos.current_page will be set to null.

Throws:
StandardException

unlockPositionAfterRead

public void unlockPositionAfterRead(RowPosition pos)
                             throws StandardException
Unlock the record after a previous request to lock it.

Unlock the record after a previous call to lockRecordForRead(). It is expected that RowPosition contains information used to lock the record, Thus it is important if using a single RowPosition to track a scan to call unlock before you move the position forward to the next record.

Note that this routine assumes that the row was locked forUpdate if the OpenConglomerate is forUpdate, else it assumes the record was locked for read.

Throws:
StandardException - Standard exception policy.

getInternalTablePropertySet

public java.util.Properties getInternalTablePropertySet(java.util.Properties prop)
                                                 throws StandardException
Request set of properties associated with a table.

Returns a property object containing all properties that the store knows about, which are stored persistently by the store. This set of properties may vary from implementation to implementation of the store.

This call is meant to be used only for internal query of the properties by jbms, for instance by language during bulk insert so that it can create a new conglomerate which exactly matches the properties that the original container was created with. This call should not be used by the user interface to present properties to users as it may contain properties that are meant to be internal to jbms. Some properties are meant only to be specified by jbms code and not by users on the command line.

Note that not all properties passed into createConglomerate() are stored persistently, and that set may vary by store implementation.

Parameters:
prop - Property list to add properties to. If null, routine will create a new Properties object, fill it in and return it.
Throws:
StandardException - Standard exception policy.

getTableProperties

public void getTableProperties(java.util.Properties prop)
                        throws StandardException
Request the system properties associated with a table.

Request the value of properties that are associated with a table. The following properties can be requested: derby.storage.pageSize derby.storage.pageReservedSpace derby.storage.minimumRecordSize derby.storage.initialPages

To get the value of a particular property add it to the property list, and on return the value of the property will be set to it's current value. For example: get_prop(ConglomerateController cc) { Properties prop = new Properties(); prop.put("derby.storage.pageSize", ""); cc.getTableProperties(prop); System.out.println( "table's page size = " + prop.getProperty("derby.storage.pageSize"); }

Parameters:
prop - Property list to fill in.
Throws:
StandardException - Standard exception policy.

getXactMgr

public final TransactionManager getXactMgr()
Public Accessors of This class:


getRawTran

public final Transaction getRawTran()

getContainer

public final ContainerHandle getContainer()

getOpenMode

public final int getOpenMode()

getConglomerate

public final Conglomerate getConglomerate()

getHold

public final boolean getHold()

isForUpdate

public final boolean isForUpdate()

isClosed

public final boolean isClosed()

isUseUpdateLocks

public final boolean isUseUpdateLocks()

getRuntimeMem

public final OpenConglomerateScratchSpace getRuntimeMem()

checkConsistency

public void checkConsistency()
                      throws StandardException
Check consistency of a conglomerate.

Checks the consistency of the data within a given conglomerate, does not check consistency external to the conglomerate (ie. does not check that base table row pointed at by a secondary index actually exists).

There is no checking in the default implementation, you must override to get conglomerate specific consistency checking.

Throws:
StandardException - Standard exception policy.

debugConglomerate

public void debugConglomerate()
                       throws StandardException
Throws:
StandardException

getSpaceInfo

public SpaceInfo getSpaceInfo()
                       throws StandardException
Get information about space used by the conglomerate.

Throws:
StandardException

isKeyed

protected boolean isKeyed()

isTableLocked

protected boolean isTableLocked()
is the open btree table locked?


init

public ContainerHandle init(ContainerHandle open_container,
                            Conglomerate conglomerate,
                            int[] format_ids,
                            int[] collation_ids,
                            TransactionManager xact_manager,
                            Transaction rawtran,
                            boolean hold,
                            int openmode,
                            int lock_level,
                            LockingPolicy locking_policy,
                            DynamicCompiledOpenConglomInfo dynamic_info)
                     throws StandardException
Open the container.

Open the container, obtaining necessary locks. Most work is actually done by RawStore.openContainer().

Throws:
StandardException - Standard exception policy.

reopen

public ContainerHandle reopen()
                       throws StandardException
Open the container.

Open the container, obtaining necessary locks. Most work is actually done by RawStore.openContainer(). Will only reopen() if the container is not already open.

Throws:
StandardException - Standard exception policy.

close

public void close()
           throws StandardException
Close the container.

Handles being closed more than once.

Throws:
StandardException - Standard exception policy.

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.