Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.impl.store.access.conglomerate.OpenConglomerate

Modifier and Type	Field and Description
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

Access	Constructor and Description
public	OpenConglomerate()

Method Summary

Modifier and Type	Method and Description
public void	checkConsistency() Check consistency of a conglomerate.
public void	close() Close the container.
public void	debugConglomerate()
public final Conglomerate	getConglomerate()
public final ContainerHandle	getContainer()
public abstract int[]	getFormatIds()
public final boolean	getHold()
public Properties	getInternalTablePropertySet(Properties Property list to add properties to. If null, routine will create a new Properties object, fill it in and return it. prop) Request set of properties associated with a table.
public final int	getOpenMode()
public final Transaction	getRawTran()
public final OpenConglomerateScratchSpace	getRuntimeMem()
public SpaceInfo	getSpaceInfo() Get information about space used by the conglomerate.
public void	getTableProperties(Properties Property list to fill in. prop) Request the system properties associated with a table.
public final TransactionManager	getXactMgr() Public Accessors of This class:
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) Open the container.
public final boolean	isClosed()
public final boolean	isForUpdate()
protected boolean	isKeyed()
protected boolean	isTableLocked() is the open btree table locked?
public final boolean	isUseUpdateLocks()
public boolean	Returns: `true` if the page was successfully latched, or `false` otherwise latchPage(RowPosition the position to a row on the page that should be latched pos) Latch the page containing the current RowPosition.
public boolean	Returns: true if scan had to reposition because a row disappeared. latchPageAndRepositionScan(RowPosition pos) Latch the page containing the current RowPosition, and reposition scan.
public boolean	Returns: true if lock granted without releasing the latch, else return false. lockPositionForRead(RowPosition Position to lock. pos, RowPosition If you have to give up latch to get lock, then also unlock this position if it is non-null. aux_pos, boolean 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. moveForwardIfRowDisappears, boolean 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. waitForLock) Lock row at given row position for read.
public boolean	lockPositionForWrite(RowPosition pos, boolean waitForLock) Lock the row at the given position for write.
protected abstract RowLocation	Returns: The empty Rowlocation. newRowLocationTemplate() Return an "empty" row location object of the correct type.
public ContainerHandle	reopen() Open the container.
public void	unlockPositionAfterRead(RowPosition pos) Unlock the record after a previous request to lock it.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

container	back to summary
private ContainerHandle container

forUpdate	back to summary
private boolean forUpdate

getBaseTableLocks	back to summary
private boolean getBaseTableLocks

init_conglomerate	back to summary
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_dynamic_info	back to summary
private DynamicCompiledOpenConglomInfo init_dynamic_info

init_hold	back to summary
private boolean init_hold

init_lock_level	back to summary
private int init_lock_level

init_locking_policy	back to summary
private LockingPolicy init_locking_policy

init_openmode	back to summary
private int init_openmode

init_rawtran	back to summary
private Transaction init_rawtran

init_xact_manager	back to summary
private TransactionManager init_xact_manager

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

useUpdateLocks	back to summary
private boolean useUpdateLocks convenience boolean's for various mode's

OpenConglomerate	back to summary
public OpenConglomerate()

Method Detail

checkConsistency	back to summary
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. Exceptions StandardException: Standard exception policy.

checkConsistency

back to summary

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.

Exceptions

StandardException:: Standard exception policy.

close	back to summary
public void close() throws StandardException Close the container. Handles being closed more than once. Exceptions StandardException: Standard exception policy.

back to summary

public void close() throws StandardException

Close the container.

Handles being closed more than once.

Exceptions

StandardException:: Standard exception policy.

debugConglomerate	back to summary
public void debugConglomerate() throws StandardException

getConglomerate	back to summary
public final Conglomerate getConglomerate()

getContainer	back to summary
public final ContainerHandle getContainer()

getFormatIds	back to summary
public abstract int[] getFormatIds()

getHold	back to summary
public final boolean getHold()

getInternalTablePropertySet	back to summary
public Properties getInternalTablePropertySet(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:Properties Property list to add properties to. If null, routine will create a new Properties object, fill it in and return it. Exceptions StandardException: Standard exception policy.

getInternalTablePropertySet

back to summary

public Properties getInternalTablePropertySet(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:Properties: Property list to add properties to. If null, routine will create a new Properties object, fill it in and return it.

Exceptions

StandardException:: Standard exception policy.

getOpenMode	back to summary
public final int getOpenMode()

getRawTran	back to summary
public final Transaction getRawTran()

getRuntimeMem	back to summary
public final OpenConglomerateScratchSpace getRuntimeMem()

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

getTableProperties	back to summary
public void getTableProperties(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:Properties Property list to fill in. Exceptions StandardException: Standard exception policy.

getTableProperties

back to summary

public void getTableProperties(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:Properties: Property list to fill in.

Exceptions

StandardException:: Standard exception policy.

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

init	back to summary
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(). Exceptions StandardException: Standard exception policy.

init

back to summary

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().

Exceptions

StandardException:: Standard exception policy.

isClosed	back to summary
public final boolean isClosed()

isForUpdate	back to summary
public final boolean isForUpdate()

isKeyed	back to summary
protected boolean isKeyed()

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

isUseUpdateLocks	back to summary
public final boolean isUseUpdateLocks()

latchPage back to summary

latchPage	back to summary
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:RowPosition the position to a row on the page that should be latched Returns:boolean `true` if the page was successfully latched, or `false` otherwise Exceptions StandardException: Standard exception policy.

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:RowPosition: the position to a row on the page that should be latched

Returns:boolean

true if the page was successfully latched, or false otherwise

Exceptions

StandardException:: Standard exception policy.

latchPageAndRepositionScan	back to summary
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:boolean true if scan had to reposition because a row disappeared. Exceptions StandardException: Standard exception policy.

latchPageAndRepositionScan

back to summary

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:boolean

true if scan had to reposition because a row disappeared.

Exceptions

StandardException:: Standard exception policy.

lockPositionForRead back to summary

lockPositionForRead	back to summary
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:RowPosition Position to lock. aux_pos:RowPosition If you have to give up latch to get lock, then also unlock this position if it is non-null. moveForwardIfRowDisappears:boolean 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:boolean 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:boolean true if lock granted without releasing the latch, else return false. Exceptions StandardException: Standard exception policy.

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:RowPosition: Position to lock.
aux_pos:RowPosition: If you have to give up latch to get lock, then also unlock this position if it is non-null.
moveForwardIfRowDisappears:boolean: 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:boolean: 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:boolean

true if lock granted without releasing the latch, else return false.

Exceptions

StandardException:: Standard exception policy.

lockPositionForWrite back to summary

lockPositionForWrite	back to summary
public boolean lockPositionForWrite(RowPosition pos, 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`.

public boolean lockPositionForWrite(RowPosition pos, 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.

newRowLocationTemplate	back to summary
protected abstract RowLocation newRowLocationTemplate() throws StandardException Return an "empty" row location object of the correct type. Returns:RowLocation The empty Rowlocation. Exceptions StandardException: Standard exception policy.

newRowLocationTemplate

back to summary

protected abstract RowLocation newRowLocationTemplate() throws StandardException

Return an "empty" row location object of the correct type.

Returns:RowLocation

The empty Rowlocation.

Exceptions

StandardException:: Standard exception policy.

reopen	back to summary
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. Exceptions StandardException: Standard exception policy.

reopen

back to summary

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.

Exceptions

StandardException:: Standard exception policy.

unlockPositionAfterRead	back to summary
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. Exceptions StandardException: Standard exception policy.

unlockPositionAfterRead

back to summary

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.

Exceptions

StandardException:: Standard exception policy.

public abstract Class OpenConglomerate

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail