Interface ConglomerateController
-
- All Superinterfaces:
ConglomPropertyQueryable
- All Known Implementing Classes:
B2IController
,BTreeController
,GenericConglomerateController
,HeapController
public interface ConglomerateController extends ConglomPropertyQueryable
A conglomerate is an abstract storage structure (they correspond to access methods). The ConglomerateController interface is the interface that access manager clients can use to manipulate the contents of the underlying conglomerate.Each conglomerate holds a set of rows. Each row has a row location. The conglomerate provides methods for:
- Inserting rows,
- Fetching, deleting, and replacing entire rows by row location, and
- fetching and updating individual columns of a row identified by row location.
Conglomerates do not provide any mechanism for associative access to rows within the conglomerate; this type of access is provided by scans via the ScanController interface.
Although all conglomerates have the same interface, they have different implementations. The implementation of a conglomerate determines some of its user-visible semantics; for example whether the rows are ordered or what the types of the rows' columns must be. The implementation is specified by an implementation id. Currently there are two implementations, "heap", and "btree". The details of their behavior are specified in their implementation documentation. (Currently, only "heap" is implemented).
All conglomerate operations are subject to the transactional isolation of the transaction they were opened from. Transaction rollback will close all conglomerates. Transaction commit will close all non-held conglomerates.
Scans are opened from a TransactionController.
A ConglomerateController can handle partial rows. Partial rows are described in RowUtil.
-
-
Field Summary
Fields Modifier and Type Field Description static int
LOCK_INS
static int
LOCK_INS_PREVKEY
static int
LOCK_READ
static int
LOCK_UPD
static int
LOCK_UPDATE_LOCKS
static int
ROWISDUPLICATE
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
checkConsistency()
Check consistency of a conglomerate.void
close()
Close the conglomerate controller.boolean
closeForEndTransaction(boolean closeHeldScan)
Close conglomerate controller as part of terminating a transaction.void
debugConglomerate()
Dump debugging output to error log.boolean
delete(RowLocation loc)
Delete a row from the conglomerate.boolean
fetch(RowLocation loc, DataValueDescriptor[] destRow, FormatableBitSet validColumns)
Fetch the (partial) row at the given location.boolean
fetch(RowLocation loc, DataValueDescriptor[] destRow, FormatableBitSet validColumns, boolean waitForLock)
Fetch the (partial) row at the given location.SpaceInfo
getSpaceInfo()
Get information about space used by the conglomerate.int
insert(DataValueDescriptor[] row)
Insert a row into the conglomerate.void
insertAndFetchLocation(DataValueDescriptor[] row, RowLocation destRowLocation)
insert row and fetch it's row location in one operation.boolean
isKeyed()
Return whether this is a keyed conglomerate.boolean
lockRow(long page_num, int record_id, int lock_oper, boolean wait, int lock_duration)
Lock the given record id/page num pair.boolean
lockRow(RowLocation loc, int lock_oper, boolean wait, int lock_duration)
Lock the given row location.RowLocation
newRowLocationTemplate()
Return a row location object of the correct type to be used in calls to insertAndFetchLocation.boolean
replace(RowLocation loc, DataValueDescriptor[] row, FormatableBitSet validColumns)
Replace the (partial) row at the given location.void
unlockRowAfterRead(RowLocation loc, boolean forUpdate, boolean row_qualified)
UnLock the given row location.-
Methods inherited from interface org.apache.derby.iapi.store.access.ConglomPropertyQueryable
getInternalTablePropertySet, getTableProperties
-
-
-
-
Field Detail
-
ROWISDUPLICATE
static final int ROWISDUPLICATE
- See Also:
- Constant Field Values
-
LOCK_READ
static final int LOCK_READ
- See Also:
- Constant Field Values
-
LOCK_UPD
static final int LOCK_UPD
- See Also:
- Constant Field Values
-
LOCK_INS
static final int LOCK_INS
- See Also:
- Constant Field Values
-
LOCK_INS_PREVKEY
static final int LOCK_INS_PREVKEY
- See Also:
- Constant Field Values
-
LOCK_UPDATE_LOCKS
static final int LOCK_UPDATE_LOCKS
- See Also:
- Constant Field Values
-
-
Method Detail
-
close
void close() throws StandardException
Close the conglomerate controller.Close the conglomerate controller. Callers must not use the conglomerate controller after calling close. It is strongly recommended that callers clear out the reference after closing, e.g.,
ConglomerateController cc; cc.close; cc = null;
- Throws:
StandardException
- Standard exception policy.
-
closeForEndTransaction
boolean closeForEndTransaction(boolean closeHeldScan) throws StandardException
Close conglomerate controller as part of terminating a transaction.Use this call to close the conglomerate controller resources as part of committing or aborting a transaction. The normal close() routine may do some cleanup that is either unnecessary, or not correct due to the unknown condition of the controller following a transaction ending error. Use this call when closing all controllers as part of an abort of a transaction.
This call is meant to only be used internally by the Storage system, clients of the storage system should use the simple close() interface.
RESOLVE (mikem) - move this call to ConglomerateManager so it is obvious that non-access clients should not call this.
- Parameters:
closeHeldScan
- If true, means to close controller even if it has been opened to be kept opened across commit. This is used to close these controllers on abort.- Returns:
- boolean indicating that the close has resulted in a real close of the controller. A held scan will return false if called by closeForEndTransaction(false), otherwise it will return true. A non-held scan will always return true.
- Throws:
StandardException
- Standard exception policy.
-
checkConsistency
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). Raises a StandardException on first consistency problem.- Throws:
StandardException
- Standard exception policy.
-
delete
boolean delete(RowLocation loc) throws StandardException
Delete a row from the conglomerate.- Returns:
- Returns true if delete was successful, false if the record pointed at no longer represents a valid record.
- Throws:
StandardException
- Standard exception policy.
-
fetch
boolean fetch(RowLocation loc, DataValueDescriptor[] destRow, FormatableBitSet validColumns) throws StandardException
Fetch the (partial) row at the given location.- Parameters:
loc
- The "RowLocation" which describes the exact row to fetch from the table.destRow
- The row to read the data into.validColumns
- A description of which columns to return from row on the page into "destRow." destRow and validColumns work together to describe the row to be returned by the fetch - see RowUtil for description of how these three parameters work together to describe a fetched "row".- Returns:
- Returns true if fetch was successful, false if the record pointed at no longer represents a valid record.
- Throws:
StandardException
- Standard exception policy.- See Also:
RowUtil
-
fetch
boolean fetch(RowLocation loc, DataValueDescriptor[] destRow, FormatableBitSet validColumns, boolean waitForLock) throws StandardException
Fetch the (partial) row at the given location.- Parameters:
loc
- The "RowLocation" which describes the exact row to fetch from the table.destRow
- The row to read the data into.validColumns
- A description of which columns to return from row on the page into "destRow." destRow and validColumns work together to describe the row to be returned by the fetch - see RowUtil for description of how these three parameters work together to describe a fetched "row".waitForLock
- If false, then the call will throw a lock timeout exception immediately, if the lock can not be granted without waiting. If true call will act exactly as fetch() interface with no waitForLock parameter.- Returns:
- Returns true if fetch was successful, false if the record pointed at no longer represents a valid record.
- Throws:
StandardException
- Standard exception policy.- See Also:
RowUtil
-
insert
int insert(DataValueDescriptor[] row) throws StandardException
Insert a row into the conglomerate.- Parameters:
row
- The row to insert into the conglomerate. The stored representations of the row's columns are copied into a new row somewhere in the conglomerate.- Returns:
- Returns 0 if insert succeeded. Returns ConglomerateController.ROWISDUPLICATE if conglomerate supports uniqueness checks and has been created to disallow duplicates, and the row inserted had key columns which were duplicate of a row already in the table. Other insert failures will raise StandardException's.
- Throws:
StandardException
- Standard exception policy.- See Also:
RowUtil
-
insertAndFetchLocation
void insertAndFetchLocation(DataValueDescriptor[] row, RowLocation destRowLocation) throws StandardException
insert row and fetch it's row location in one operation.Insert a row into the conglomerate, and store its location in the provided destination row location. The row location must be of the correct type for this conglomerate (a new row location of the correct type can be obtained from newRowLocationTemplate()).
- Parameters:
row
- The row to insert into the conglomerate. The stored representations of the row's columns are copied into a new row somewhere in the conglomerate.destRowLocation
- The rowlocation to read the inserted row location into.- Throws:
StandardException
- Standard exception policy.- See Also:
RowUtil
-
isKeyed
boolean isKeyed()
Return whether this is a keyed conglomerate.
-
lockRow
boolean lockRow(RowLocation loc, int lock_oper, boolean wait, int lock_duration) throws StandardException
Lock the given row location.Should only be called by access.
This call can be made on a ConglomerateController that was opened for locking only.
RESOLVE (mikem) - move this call to ConglomerateManager so it is obvious that non-access clients should not call this.
- Parameters:
loc
- The "RowLocation" of the exact row to lock.lock_oper
- For what operation are we requesting the lock, this should be one of the following 4 options: LOCK_READ [read lock], (LOCK_INS | LOCK_UPD) [ lock for insert], (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for previous key to insert], (LOCK_UPD) [lock for delete or replace] (LOCK_UPD | LOCK_UPDATE_LOCKS) [lock scan for update, will upgrade lock later if actual update is take place]wait
- Should the lock call wait to be granted?lock_duration
- If set to TransactionManager.LOCK_INSTANT_DURATION, then lock will be released immediately after being granted.- Returns:
- true if lock was granted, only can be false if wait was false.
- Throws:
StandardException
- Standard exception policy.
-
lockRow
boolean lockRow(long page_num, int record_id, int lock_oper, boolean wait, int lock_duration) throws StandardException
Lock the given record id/page num pair.Should only be called by access, to lock "special" locks formed from the Recordhandle.* reserved constants for page specific locks.
This call can be made on a ConglomerateController that was opened for locking only.
RESOLVE (mikem) - move this call to ConglomerateManager so it is obvious that non-access clients should not call this.
- Parameters:
page_num
- page number of record to lock.record_id
- record id of record to lock.lock_oper
- For what operation are we requesting the lock, this should be one of the following 4 options: LOCK_READ [read lock], (LOCK_INS | LOCK_UPD) [ lock for insert], (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for previous key to insert], (LOCK_UPD) [lock for delete or replace] (LOCK_UPD | LOCK_UPDATE_LOCKS) [lock scan for update, will upgrade lock later if actual update is take place]wait
- Should the lock call wait to be granted?lock_duration
- If set to TransactionManager.LOCK_INSTANT_DURATION, then lock will be released immediately after being granted.- Returns:
- true if lock was granted, only can be false if wait was false.
- Throws:
StandardException
- Standard exception policy.
-
unlockRowAfterRead
void unlockRowAfterRead(RowLocation loc, boolean forUpdate, boolean row_qualified) throws StandardException
UnLock the given row location.Should only be called by access.
This call can be made on a ConglomerateController that was opened for locking only.
RESOLVE (mikem) - move this call to ConglomerateManager so it is obvious that non-access clients should not call this.
- Parameters:
loc
- The "RowLocation" which describes the row to unlock.forUpdate
- Row was locked for read or update.row_qualified
- Row was qualified and returned to the user.- Throws:
StandardException
- Standard exception policy.
-
newRowLocationTemplate
RowLocation newRowLocationTemplate() throws StandardException
Return a row location object of the correct type to be used in calls to insertAndFetchLocation.- Throws:
StandardException
- Standard exception policy.
-
replace
boolean replace(RowLocation loc, DataValueDescriptor[] row, FormatableBitSet validColumns) throws StandardException
Replace the (partial) row at the given location.- Returns:
- true if update was successful, returns false if the update fails because the record pointed at no longer represents a valid record.
- Throws:
StandardException
- Standard exception policy.- See Also:
RowUtil
-
getSpaceInfo
SpaceInfo getSpaceInfo() throws StandardException
Get information about space used by the conglomerate.- Throws:
StandardException
-
debugConglomerate
void debugConglomerate() throws StandardException
Dump debugging output to error log.Dump information about the conglomerate to error log. This is only for debugging purposes, does nothing in a delivered system, currently.
- Throws:
StandardException
- Standard exception policy.
-
-