org.apache.derby.impl.store.raw.data
Class BaseContainer

java.lang.Object
  extended byorg.apache.derby.impl.store.raw.data.BaseContainer
All Implemented Interfaces:
Lockable
Direct Known Subclasses:
FileContainer

public abstract class BaseContainer
extends java.lang.Object
implements Lockable

BaseContainer is an abstract class that provides the locking bahaviour for an object representing an active container, that is the actual storage container, not the ContainerHandle interface. This class is designed so that it can change the container it represents to avoid creating a new object for every container.

This object implements lockable to provide an object to lock while a page is being allocated.
MT - Mutable - mutable identity :


Field Summary
protected  ContainerKey identity
          Identity of the container.
protected  boolean isCommittedDrop
          Committed Drop state of the container.
protected  boolean isDropped
          Dropped state of the container.
protected  boolean isReusableRecordId
          Is reusable recordId.
 
Constructor Summary
protected BaseContainer()
           
 
Method Summary
 Page addPage(BaseContainerHandle handle, boolean isOverflow)
          Add a page to this container.
protected abstract  boolean canUpdate()
          Can the container be updated.
 void clearIdentity()
           
protected abstract  void clearPreallocThreshold()
          The container will have no pre-allocate threshold, i.e., if the implementation supports it, page preallocation will happen the next time a new page is allocated.
protected abstract  void deallocatePage(BaseContainerHandle userhandle, BasePage page)
          Deallocate a page from the container.
protected abstract  void dropContainer(LogInstant instant, boolean drop)
          Mark the container as drop or not drop depending on the input value.
protected  void fillInIdentity(ContainerKey key)
           
protected abstract  void flushAll()
          Flush all outstanding changes in this container to persistent storage.
protected  Page getAllocPage(BaseContainerHandle handle, long pageNumber, boolean wait)
          Get an allocation page and latch it.
protected abstract  BasePage getAllocPage(long pageNumber)
          Return a BasePage that represents the given alloc page number in this container.
protected abstract  BasePage getAnyPage(BaseContainerHandle handle, long pageNumber)
          Return a BasePage that represents any page - alloc page, valid page, free page, dealloced page etc.
protected  Page getAnyPage(BaseContainerHandle handle, long pageNumber, boolean wait)
          Get any page and latch it .
protected  boolean getCommittedDropState()
           
 long getContainerId()
           
abstract  void getContainerProperties(java.util.Properties prop)
          Request the system properties associated with a container.
 int getContainerStatus()
           
protected abstract  long getContainerVersion()
          Get the logged container version.
protected  boolean getDeallocLock(BaseContainerHandle handle, RecordHandle deallocLock, boolean wait, boolean zeroDuration)
          Get the special dealloc lock on the page - the lock is gotten by the transaction that owns the container handle
protected  boolean getDroppedState()
           
abstract  long getEstimatedPageCount(BaseContainerHandle handle, int flag)
           
abstract  long getEstimatedRowCount(int flag)
           
protected abstract  BasePage getFirstHeadPage(BaseContainerHandle handle, boolean wait)
          Get the first page in the container.
protected  Page getFirstPage(BaseContainerHandle handle)
          Get the first valid page.
protected abstract  BasePage getHeadPage(BaseContainerHandle handle, long pagenumber, boolean wait)
          Get only a valid, non-overflow page.
 java.lang.Object getIdentity()
           
protected abstract  BasePage getNextHeadPage(BaseContainerHandle handle, long pageNumber, boolean wait)
          Get the next page in the container.
protected  Page getNextPage(BaseContainerHandle handle, long pageNumber)
          Get the next valid page and latch it
protected abstract  BasePage getPage(BaseContainerHandle handle, long pageNumber, boolean wait)
          Return a BasePage that represents the given page number in this container.
protected abstract  BasePage getPageForInsert(BaseContainerHandle handle, int flag)
          Get a potentially suitable page for insert and latch it.
 long getSegmentId()
           
protected abstract  SpaceInfo getSpaceInfo(BaseContainerHandle handle)
          Get information about space used by the container.
protected  boolean isReusableRecordId()
           
protected  BasePage latchPage(BaseContainerHandle handle, BasePage foundPage, boolean wait)
           
protected  void letGo(BaseContainerHandle handle)
          Discontinue use of this container.
 boolean lockAttributes(int flag, java.util.Hashtable attributes)
          If this lockable object wants to participate in a diagnostic virtual lock table, then put any relavent attributes of this lock into the attributes list (the attribute must be an immutable object).
 boolean lockerAlwaysCompatible()
          Returns true if any lock request on a Lockable L in a compatibility space CS1 is compatible with any other lock held on L in CS1.
 void lockEvent(Latch lockInfo)
          Note the fact the object is locked.
protected abstract  ByteArray logCreateContainerInfo()
          Log all information on the container creation necessary to recreate teh container during a load tran.
protected abstract  BasePage newPage(BaseContainerHandle userhandle, RawTransaction t, BaseContainerHandle allocHandle, boolean isOverflow)
          Create a new page in the container.
protected abstract  void preDirty(boolean preDirtyOn)
          The container is about to be modified.
protected abstract  void prepareForBulkLoad(BaseContainerHandle handle, int numPage)
          The container will be grown vastly, prepare for it.
protected abstract  BasePage reCreatePageForLoadTran(BaseContainerHandle handle, int pageFormat, long pageNumber, long pageOffset)
          ReCreate a page for load tran.
protected abstract  void removeContainer(LogInstant instant, boolean leaveStub)
          Remove the container and reclaim its space.
protected  void removePage(BaseContainerHandle handle, BasePage page)
          Remove a page from this container.
 boolean requestCompatible(java.lang.Object requestedQualifier, java.lang.Object grantedQualifier)
          Return true if the requested qualifier is compatible with the already granted qualifier.
protected  void setCommittedDropState(boolean isCommittedDrop)
           
protected  void setDroppedState(boolean isDropped)
          Set the container's dropped state
abstract  void setEstimatedRowCount(long count, int flag)
           
protected  void setReusableRecordIdState(boolean isReusableRecordId)
           
protected  void truncate(BaseContainerHandle handle)
           
 void unlockEvent(Latch lockInfo)
          Note that the object has been unlocked Must only be called by the lock manager.
protected  boolean use(BaseContainerHandle handle, boolean forUpdate, boolean droppedOK)
          Lock the container and mark the container as in-use by this container handle.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

identity

protected ContainerKey identity
Identity of the container.
MT - Mutable


isDropped

protected boolean isDropped
Dropped state of the container.
MT - mutable : single thread required. Either the container must be exclusive locked by this thread, or the container must have no identity (ie. it is being created or opened).


isCommittedDrop

protected boolean isCommittedDrop
Committed Drop state of the container. If a post comit action determined that the drop container operation is committed, the whole container may be removed and space reclaimed.
MT - mutable : single thread required. Either the container must be exclusive locked by this thread, or the container must have no identity (ie. it is being created or opened).


isReusableRecordId

protected boolean isReusableRecordId
Is reusable recordId. By default, record Ids are not reusable when a page is reused. However, under special circumstances, clients to raw store may decide that record Ids may be reused after the page is reused. When this flag is set, pages that are reused will have its next recordId set to RecordHandle.FIRST_RECORD_ID

Constructor Detail

BaseContainer

protected BaseContainer()
Method Detail

fillInIdentity

protected void fillInIdentity(ContainerKey key)

clearIdentity

public void clearIdentity()

getIdentity

public java.lang.Object getIdentity()

lockEvent

public void lockEvent(Latch lockInfo)
Description copied from interface: Lockable
Note the fact the object is locked. Performs required actions to ensure that unlockEvent() work correctly. This method does not actually perform any locking of the object, the locking mechanism is provided by the lock manager.

If the class supports multiple lockers of the object then this method will be called once per locker, each with their own qualifier.

Must only be called by the lock manager. Synchronization will be handled by the lock manager.

Specified by:
lockEvent in interface Lockable

requestCompatible

public boolean requestCompatible(java.lang.Object requestedQualifier,
                                 java.lang.Object grantedQualifier)
Description copied from interface: Lockable
Return true if the requested qualifier is compatible with the already granted qualifier.

Specified by:
requestCompatible in interface Lockable

lockerAlwaysCompatible

public boolean lockerAlwaysCompatible()
Description copied from interface: Lockable
Returns true if any lock request on a Lockable L in a compatibility space CS1 is compatible with any other lock held on L in CS1.

Specified by:
lockerAlwaysCompatible in interface Lockable

unlockEvent

public void unlockEvent(Latch lockInfo)
Description copied from interface: Lockable
Note that the object has been unlocked

Must only be called by the lock manager. Synchronization will be handled by the lock manager.

Specified by:
unlockEvent in interface Lockable

addPage

public Page addPage(BaseContainerHandle handle,
                    boolean isOverflow)
             throws StandardException
Add a page to this container.
MT - thread aware - The add page operation involves 2 transactions, one is the user transaction (the transaction which owns the passed in handle), the other one is a NestedTopTransaction created by this BaseContainer. The nestedTopTransaction is used by the underlying container to change high contention structures, such as link list anchor or bit map pages. The nestedTopTransaction commits or aborts before this routine returns. The user transaction is used to latch the newly created page.

Throws:
StandardException - Standard Cloudscape error policy

getContainerProperties

public abstract void getContainerProperties(java.util.Properties prop)
                                     throws StandardException
Request the system properties associated with a container.

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

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(BaseContainer base) { Properties prop = new Properties(); prop.put("derby.storage.pageSize", ""); base.getContainerProperties(prop); System.out.println( "container's page size = " + prop.getProperty("derby.storage.pageSize"); }

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

removePage

protected void removePage(BaseContainerHandle handle,
                          BasePage page)
                   throws StandardException
Remove a page from this container. The page will be unlatched by this routine before it returns. Unlike addPage, this method done as part of the user transaction. The removed page is not usable by anyone until the user transaction comits. If the user transaction rolls back, the removed page is un-removed.
MT - thread aware -

Parameters:
handle - the container handle that has opened the container and latched the page
page - the latched page that is to be deallocated
Throws:
StandardException - Standard Cloudscape error policy

getDeallocLock

protected boolean getDeallocLock(BaseContainerHandle handle,
                                 RecordHandle deallocLock,
                                 boolean wait,
                                 boolean zeroDuration)
                          throws StandardException
Get the special dealloc lock on the page - the lock is gotten by the transaction that owns the container handle

Throws:
StandardException - Standard Cloudscape error policy

getAllocPage

protected Page getAllocPage(BaseContainerHandle handle,
                            long pageNumber,
                            boolean wait)
                     throws StandardException
Get an allocation page and latch it.

Throws:
StandardException - Standard Cloudscape error policy

getAnyPage

protected Page getAnyPage(BaseContainerHandle handle,
                          long pageNumber,
                          boolean wait)
                   throws StandardException
Get any page and latch it .

Throws:
StandardException - Standard Cloudscape error policy

getFirstPage

protected Page getFirstPage(BaseContainerHandle handle)
                     throws StandardException
Get the first valid page. Result is latched.

Throws:
StandardException - Standard Cloudscape error policy

getNextPage

protected Page getNextPage(BaseContainerHandle handle,
                           long pageNumber)
                    throws StandardException
Get the next valid page and latch it

Throws:
StandardException - Standard Cloudscape error policy

latchPage

protected BasePage latchPage(BaseContainerHandle handle,
                             BasePage foundPage,
                             boolean wait)
                      throws StandardException
Throws:
StandardException

use

protected boolean use(BaseContainerHandle handle,
                      boolean forUpdate,
                      boolean droppedOK)
               throws StandardException
Lock the container and mark the container as in-use by this container handle.

Parameters:
droppedOK - if true, use this container even if it is dropped.,
Returns:
true if the container can be used, false if it has been dropped since the lock was requested and droppedOK is not true.
Throws:
StandardException - I cannot be opened for update.

letGo

protected void letGo(BaseContainerHandle handle)
Discontinue use of this container. Note that the unlockContainer call made from this method may not release any locks. The container lock may be held until the end of the transaction.


getDroppedState

protected boolean getDroppedState()

getCommittedDropState

protected boolean getCommittedDropState()

isReusableRecordId

protected boolean isReusableRecordId()

getContainerStatus

public int getContainerStatus()

getContainerId

public long getContainerId()

getSegmentId

public long getSegmentId()

getSpaceInfo

protected abstract SpaceInfo getSpaceInfo(BaseContainerHandle handle)
                                   throws StandardException
Get information about space used by the container.

Throws:
StandardException

canUpdate

protected abstract boolean canUpdate()
Can the container be updated.

Returns:
true if the container can be updated, false otherwise.

preDirty

protected abstract void preDirty(boolean preDirtyOn)
The container is about to be modified. Loggable actions use this to make sure the container gets cleaned if a checkpoint is taken after any log record is sent to the log stream but before the container is actually dirtied.


getPage

protected abstract BasePage getPage(BaseContainerHandle handle,
                                    long pageNumber,
                                    boolean wait)
                             throws StandardException
Return a BasePage that represents the given page number in this container. The resulting page is latched.

Throws:
StandardException - Standard Cloudscape error policy

getAllocPage

protected abstract BasePage getAllocPage(long pageNumber)
                                  throws StandardException
Return a BasePage that represents the given alloc page number in this container.

Throws:
StandardException - Standard Cloudscape error policy

getAnyPage

protected abstract BasePage getAnyPage(BaseContainerHandle handle,
                                       long pageNumber)
                                throws StandardException
Return a BasePage that represents any page - alloc page, valid page, free page, dealloced page etc. The only requirement is that the page is initialized...

Throws:
StandardException - Cloudscape Standard error policy

reCreatePageForLoadTran

protected abstract BasePage reCreatePageForLoadTran(BaseContainerHandle handle,
                                                    int pageFormat,
                                                    long pageNumber,
                                                    long pageOffset)
                                             throws StandardException
ReCreate a page for load tran. The argument passed in need to be sufficient for the page cache to materialize a brand new page and write it to disk. The reason why this method is necessary is because we first create the page, write it to disk, and then log the init page log record to make sure there are enough space on disk. During load tran, the page creation part is missing.

Load tran will do no preallocation.

Only called during recovery redo.

Throws:
StandardException - Cloudscape Standard error policy

logCreateContainerInfo

protected abstract ByteArray logCreateContainerInfo()
                                             throws StandardException
Log all information on the container creation necessary to recreate teh container during a load tran.

Throws:
StandardException - Cloudscape Standard error policy

getHeadPage

protected abstract BasePage getHeadPage(BaseContainerHandle handle,
                                        long pagenumber,
                                        boolean wait)
                                 throws StandardException
Get only a valid, non-overflow page. If page number is either invalid or overflow, returns null

Throws:
StandardException - Cloudscape Standard error policy

getFirstHeadPage

protected abstract BasePage getFirstHeadPage(BaseContainerHandle handle,
                                             boolean wait)
                                      throws StandardException
Get the first page in the container.

Throws:
StandardException - Standard Cloudscape error policy

getNextHeadPage

protected abstract BasePage getNextHeadPage(BaseContainerHandle handle,
                                            long pageNumber,
                                            boolean wait)
                                     throws StandardException
Get the next page in the container.

Throws:
StandardException - Standard Cloudscape error policy

getPageForInsert

protected abstract BasePage getPageForInsert(BaseContainerHandle handle,
                                             int flag)
                                      throws StandardException
Get a potentially suitable page for insert and latch it.

Throws:
StandardException - Standard Cloudscape error policy

newPage

protected abstract BasePage newPage(BaseContainerHandle userhandle,
                                    RawTransaction t,
                                    BaseContainerHandle allocHandle,
                                    boolean isOverflow)
                             throws StandardException
Create a new page in the container.

Throws:
StandardException - Standard Cloudscape error policy

deallocatePage

protected abstract void deallocatePage(BaseContainerHandle userhandle,
                                       BasePage page)
                                throws StandardException
Deallocate a page from the container.

Throws:
StandardException - Standard Cloudscape error policy

truncate

protected void truncate(BaseContainerHandle handle)
                 throws StandardException
Throws:
StandardException

dropContainer

protected abstract void dropContainer(LogInstant instant,
                                      boolean drop)
Mark the container as drop or not drop depending on the input value.


removeContainer

protected abstract void removeContainer(LogInstant instant,
                                        boolean leaveStub)
                                 throws StandardException
Remove the container and reclaim its space. Once executed, this operation cannot be undone - as opposed to dropContainer which only marks the container as dropped and can be rolled back.
This operation should only be called by post commit clean up

Parameters:
leaveStub - if true, leave a stub. If false, remove everything
Throws:
StandardException - Standard Cloudscape error policy
See Also:
RawContainerHandle.removeContainer(org.apache.derby.iapi.store.raw.log.LogInstant)

getContainerVersion

protected abstract long getContainerVersion()
                                     throws StandardException
Get the logged container version.

Throws:
StandardException - Standard Cloudscape error policy

flushAll

protected abstract void flushAll()
                          throws StandardException
Flush all outstanding changes in this container to persistent storage.

Throws:
StandardException - Standard Cloudscape error policy

prepareForBulkLoad

protected abstract void prepareForBulkLoad(BaseContainerHandle handle,
                                           int numPage)
The container will be grown vastly, prepare for it.


clearPreallocThreshold

protected abstract void clearPreallocThreshold()
The container will have no pre-allocate threshold, i.e., if the implementation supports it, page preallocation will happen the next time a new page is allocated.


getEstimatedRowCount

public abstract long getEstimatedRowCount(int flag)
                                   throws StandardException
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.getEstimatedRowCount(int)

setEstimatedRowCount

public abstract void setEstimatedRowCount(long count,
                                          int flag)
                                   throws StandardException
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.setEstimatedRowCount(long, int)

getEstimatedPageCount

public abstract long getEstimatedPageCount(BaseContainerHandle handle,
                                           int flag)
                                    throws StandardException
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.getEstimatedPageCount(int)

setDroppedState

protected void setDroppedState(boolean isDropped)
Set the container's dropped state


setCommittedDropState

protected void setCommittedDropState(boolean isCommittedDrop)

setReusableRecordIdState

protected void setReusableRecordIdState(boolean isReusableRecordId)

lockAttributes

public boolean lockAttributes(int flag,
                              java.util.Hashtable attributes)
Description copied from interface: Lockable
If this lockable object wants to participate in a diagnostic virtual lock table, then put any relavent attributes of this lock into the attributes list (the attribute must be an immutable object). The list of attributes of interest to the virtual lock table can be found in VirtualLockTable. The toString method will be called by the VirtualTable on the attribute value for display.

Specified by:
lockAttributes in interface Lockable
Parameters:
flag - use the bits in this int to decide if the user is interested in this kind of lockable object. The bits are defined in VirtualLockTable. For instance, the user may only ask for TABLE_AND_ROWLOCK and if this is not a table or row lock, then don't paritipate.
attributes - if this decides to participate, put all relavent attributes into the Hashtable. The complete list of interesting attributes is listed in VirtualLockTable. The following attributes must be present for all participating lockables: VirtualLockTable.LOCKNAME, VirtualLockTable.LOCKTYPE, either VirtualLockTable.CONTAINERID or VirtualLockTable.CONGLOMID,

MT - this routine must be MP safe, caller will not be single threading the lock manager.

Returns:
true if this object has diagnostic information to add to the virtual lock table. If this object either does not want to participate in the diagnostic virtual lock table or none of the attributes requested are attributes of this lock, returns false.
See Also:
VirtualLockTable


Apache Derby V10.0 Engine Documentation - Copyright © 1997,2004 The Apache Software Foundation or its licensors, as applicable.