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

java.lang.Object
  extended byjava.util.Observable
      extended byorg.apache.derby.impl.store.raw.data.BaseContainerHandle
All Implemented Interfaces:
ContainerHandle, java.util.Observer, RawContainerHandle

public class BaseContainerHandle
extends java.util.Observable
implements RawContainerHandle, java.util.Observer

A handle to an open container, implememts RawContainerHandle.

This class is an Observer to observe RawTransactions and is also a Observable to handle the list of pages accessed thorough this handle.
This class implements Lockable (defined to be ContainerHandle) and is the object used to logically lock the container.
MT - Mutable - Immutable identity - Thread Aware


Field Summary
protected  PageActions actionsSet
           
protected  boolean active
          Is this ContainerHandle active.
protected  AllocationActions allocActionsSet
           
protected  BaseContainer container
          The actual container we are accessing.
private  boolean forUpdate
          are we going to update?
protected  ContainerKey identity
          Container identifier
MT - Immutable
private  LockingPolicy locking
          the locking policy we opened the container with.
protected  int mode
           
protected  RawTransaction xact
          our transaction.
 
Fields inherited from class java.util.Observable
 
Fields inherited from interface org.apache.derby.iapi.store.raw.data.RawContainerHandle
COMMITTED_DROP, DROPPED, NORMAL
 
Fields inherited from interface org.apache.derby.iapi.store.raw.ContainerHandle
ADD_PAGE_BULK, ADD_PAGE_DEFAULT, DEFAULT_ASSIGN_ID, DEFAULT_PAGESIZE, DEFAULT_SPARESPACE, FIRST_PAGE_NUMBER, GET_PAGE_UNFILLED, INVALID_PAGE_NUMBER, MODE_BASEROW_INSERT_LOCKED, MODE_CREATE_UNLOGGED, MODE_DEFAULT, MODE_DROP_ON_COMMIT, MODE_FLUSH_ON_COMMIT, MODE_FORUPDATE, MODE_LOCK_NOWAIT, MODE_NO_ACTIONS_ON_COMMIT, MODE_OPEN_FOR_LOCK_ONLY, MODE_READONLY, MODE_SECONDARY_LOCKED, MODE_TEMP_IS_KEPT, MODE_TRUNCATE_ON_COMMIT, MODE_TRUNCATE_ON_ROLLBACK, MODE_UNLOGGED, MODE_USE_UPDATE_LOCKS, TEMPORARY_SEGMENT
 
Constructor Summary
BaseContainerHandle(UUID rawStoreId, RawTransaction xact, ContainerKey identity, LockingPolicy locking, int mode)
          Create an object that is only used for locking the container.
BaseContainerHandle(UUID rawStoreId, RawTransaction xact, PageActions actionsSet, AllocationActions allocActionsSet, LockingPolicy locking, BaseContainer container, int mode)
          Create a container handle that is used to actually access the container.
 
Method Summary
 Page addPage()
          Add a page to the container The page returned will be observing me.
 Page addPage(int flag)
          Add a page to the container, if flag == ContainerHandle.ADD_PAGE_BULK, tell the container about it.
protected  void checkOpen()
           
private  void checkUpdateOpen()
           
 void close()
          Close me.
 void compactRecord(RecordHandle record)
          This record probably has shrunk considerably.
 void dropContainer(LogInstant instant, boolean drop)
          If drop is true, drop the container.
 void flushContainer()
          Flush all dirty pages of the container to disk.
 PageActions getActionSet()
           
 AllocationActions getAllocationActionSet()
           
 Page getAllocPage(long pageNumber)
           
 Page getAnyPage(long pageNumber)
          Get this page with no check - any page type or status is fine.
 void getContainerProperties(java.util.Properties prop)
          Request the system properties associated with a container.
 int getContainerStatus()
          Get the container status.
 long getContainerVersion()
          Get the logged container version
 long getEstimatedPageCount(int flag)
          Get the total estimated number of allocated (not freed, not deallocated) user pages in the container, including overflow pages.
 long getEstimatedRowCount(int flag)
          Get the total estimated number of rows in the container, not including overflow rows.
 Page getFirstPage()
          Obtain exclusive access to the current first page of the container.
 ContainerKey getId()
          Return my identifier.
 LockingPolicy getLockingPolicy()
          Return my locking policy, may be different from the Transaction's default locking policy.
 int getMode()
          Get the mode I was opened with.
 Page getNextPage(long pageNumber)
          Obtain exclusive access to the next valid page of the given page number in the container.
 Page getPage(long pageNumber)
          Obtain exclusive access to the page with the given page number.
 Page getPageForInsert(int flag)
          Get a page for insert.
 Page getPageNoWait(long pageNumber)
          Identical to getPage but returns null immediately if the desired page is already latched by another Container.
 SpaceInfo getSpaceInfo()
          Get information about space used by the container.
 RawTransaction getTransaction()
          Return the RawTransaction I was opened in.
 java.lang.Object getUniqueId()
          Return my unique identifier, this identifier will be unique to each instance of an open container handle.
 Page getUserPageNoWait(long pageNumber)
          Obtain exclusive access to the page with the given page number.
 Page getUserPageWait(long pageNumber)
          Obtain exclusive access to the page with the given page number.
protected  void informObservers()
           
 boolean isReadOnly()
          Is the container opened for read only or update?
 boolean isTemporaryContainer()
          Return true if this containerHandle refers to a temporary container.
 ByteArray logCreateContainerInfo()
          Log all information necessary to recreate the container during a load tran.
 RecordHandle makeRecordHandle(long pageNumber, int recordId)
          Return a record handle that is initialized to the given page number and record id.
 void preAllocate(int numPage)
          Preallocate numPage if possible.
 void preDirty(boolean preDirtyOn)
          The container is about to be modified.
 Page reCreatePageForLoadTran(int pageFormat, long pageNumber, long pageOffset)
          Re-create this page for load tran.
 void removeContainer(LogInstant instant)
          remove the container
 void removePage(Page page)
          Remove a page from the container.
 void setEstimatedRowCount(long count, int flag)
          Set the total estimated number of rows in the container.
 void setLockingPolicy(LockingPolicy newLockingPolicy)
          Set the locking policy for this open container
 java.lang.String toString()
           
 void update(java.util.Observable obj, java.lang.Object arg)
          Called when the transaction is about to complete.
 boolean updateOK()
          Was I opened for updates?
 boolean useContainer(boolean droppedOK, boolean waitForLock)
          Attach me to a container.
 
Methods inherited from class java.util.Observable
addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

identity

protected ContainerKey identity
Container identifier
MT - Immutable


active

protected boolean active
Is this ContainerHandle active.
MT - Mutable : scoped


container

protected BaseContainer container
The actual container we are accessing. Only valid when active is true.
MT - Mutable : scoped


locking

private LockingPolicy locking
the locking policy we opened the container with. Only valid when active is true.
MT - Mutable : scoped


xact

protected RawTransaction xact
our transaction. Only valid when active is true.
MT - Mutable : scoped


forUpdate

private boolean forUpdate
are we going to update?
MT - Immutable after container handle becomes active


mode

protected int mode

actionsSet

protected PageActions actionsSet

allocActionsSet

protected AllocationActions allocActionsSet
Constructor Detail

BaseContainerHandle

public BaseContainerHandle(UUID rawStoreId,
                           RawTransaction xact,
                           ContainerKey identity,
                           LockingPolicy locking,
                           int mode)
Create an object that is only used for locking the container.


BaseContainerHandle

public BaseContainerHandle(UUID rawStoreId,
                           RawTransaction xact,
                           PageActions actionsSet,
                           AllocationActions allocActionsSet,
                           LockingPolicy locking,
                           BaseContainer container,
                           int mode)
Create a container handle that is used to actually access the container.

Method Detail

addPage

public Page addPage()
             throws StandardException
Add a page to the container The page returned will be observing me.

Specified by:
addPage in interface ContainerHandle
Returns:
a reference to the page that was added.
Throws:
StandardException - Standard Cloudscape error policy
See Also:
BaseContainer.addPage(org.apache.derby.impl.store.raw.data.BaseContainerHandle, boolean), ContainerHandle.addPage()

addPage

public Page addPage(int flag)
             throws StandardException
Add a page to the container, if flag == ContainerHandle.ADD_PAGE_BULK, tell the container about it. The page returned will be observing me.

Specified by:
addPage in interface ContainerHandle
Returns:
a reference to the page that was added.
Throws:
StandardException - Standard Cloudscape error policy
See Also:
BaseContainer.addPage(org.apache.derby.impl.store.raw.data.BaseContainerHandle, boolean), ContainerHandle.addPage()

preAllocate

public void preAllocate(int numPage)
Preallocate numPage if possible.

Specified by:
preAllocate in interface ContainerHandle

getContainerProperties

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

Specified by:
getContainerProperties in interface ContainerHandle
Parameters:
prop - Property list to fill in.
Throws:
StandardException - Standard exception policy.

removePage

public void removePage(Page page)
                throws StandardException
Remove a page from the container.

Specified by:
removePage in interface ContainerHandle
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.removePage(org.apache.derby.iapi.store.raw.Page)

getPage

public Page getPage(long pageNumber)
             throws StandardException
Description copied from interface: ContainerHandle
Obtain exclusive access to the page with the given page number. Once the Page is no longer required the Page's unlatch() method must be called.

The Page object is guaranteed to remain in-memory and exclusive to the caller until its unlatch() method is called.

Specified by:
getPage in interface ContainerHandle
Returns:
the required Page or null if the page does not exist or is not valid (i.e, it has been deallocated or freed or never initialized) Note that an overflow page will be returned since it is a valid page.
Throws:
StandardException - Standard Cloudscape error policy

getAllocPage

public Page getAllocPage(long pageNumber)
                  throws StandardException
Throws:
StandardException

getUserPageNoWait

public Page getUserPageNoWait(long pageNumber)
                       throws StandardException
Description copied from interface: ContainerHandle
Obtain exclusive access to the page with the given page number. Will only return a valid, non-overflow user page - so can be used by routines in post commit to get pages to attempt deleted row space reclamation. If for some reason a request is made for an overflow page a null will be returned. Once the Page is no longer required the Page's unlatch() method must be called.

The Page object is guaranteed to remain in-memory and exclusive to the caller until its unlatch() method is called.

Specified by:
getUserPageNoWait in interface ContainerHandle
Returns:
the required Page or null if the page does not exist or is not valid (i.e, it has been deallocated, freed, never initialized, or is an allocation page or overflow page)
Throws:
StandardException - Standard Cloudscape error policy

getUserPageWait

public Page getUserPageWait(long pageNumber)
                     throws StandardException
Description copied from interface: ContainerHandle
Obtain exclusive access to the page with the given page number. Will only return a valid, non-overflow user page - so can be used by routines in post commit to get pages to attempt deleted row space reclamation. If for some reason a request is made for an overflow page a null will be returned. Once the Page is no longer required the Page's unlatch() method must be called.

The Page object is guaranteed to remain in-memory and exclusive to the caller until its unlatch() method is called.

Specified by:
getUserPageWait in interface ContainerHandle
Returns:
the required Page or null if the page does not exist or is not valid (i.e, it has been deallocated, freed, never initialized, or is an allocation page or overflow page)
Throws:
StandardException - Standard Cloudscape error policy

getPageNoWait

public Page getPageNoWait(long pageNumber)
                   throws StandardException
Description copied from interface: ContainerHandle
Identical to getPage but returns null immediately if the desired page is already latched by another Container.

Specified by:
getPageNoWait in interface ContainerHandle
Returns:
the required Page or null if the page does not exist or the page is already latched.
Throws:
StandardException - Standard Cloudscape error policy

getFirstPage

public Page getFirstPage()
                  throws StandardException
Description copied from interface: ContainerHandle
Obtain exclusive access to the current first page of the container. Only a valid, non overflow page will be returned. Pages in the container are ordered in an internally defined ordering.

Note that once this method returns this page may no longer be the first page of the container. I.e, other threads may allocate pages prior to this page number while this page is latched. It is up to the caller of this routine to synchronize this call with addPage to assure that this is the first page.
As long as the client provide the necessary lock to ensure that no addPage is called, then this page is guaranteed to be the first page of the container in some internally defined ordering of the pages.

Specified by:
getFirstPage in interface ContainerHandle
Returns:
latched page or null if there is no page in the container
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.getPage(long)

getNextPage

public Page getNextPage(long pageNumber)
                 throws StandardException
Description copied from interface: ContainerHandle
Obtain exclusive access to the next valid page of the given page number in the container. Only a valid, non overflow page will be returned. Pages in the container are ordered in an internally defined ordering.

Note that once this method returns this page may no longer be the next page of the container. I.e, other threads may allocate pages prior to this page number while this page is latched. It is up to the caller of this routine to synchronize this call with addPage to assure that this is the first page.
As long as the client provide the necessary lock to ensure that no addPage is called, then this page is guaranteed to be the next page of the container in some internally defined ordering of the pages.
If no pages are added or removed, then an iteration such as:

                for (Page p = containerHandle.getFirstPage();
                         p != null;
                         p = containerHandle.getNextPage(p.getPageNumber()))
                
                will guarentee to iterate thru and latched all the valid pages 
                in the container

Specified by:
getNextPage in interface ContainerHandle
Parameters:
pageNumber - the pagenumber of the page previous to the page that is to be gotten. The page which correspond to prevNum may or may not be latched by the caller, but it must be gotten via a page which was (or currently still is) latched, and the page number must be gotten while the container must not have been closed or dropped or removed in the interim. In other words, if the user manufactures a page number, or remembers the page number from a previous session or a previous openContainer, then the behavior of this routine is undefined.
Returns:
latched page or null if there is no next page in the container
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.getPage(long)

getPageForInsert

public Page getPageForInsert(int flag)
                      throws StandardException
Description copied from interface: ContainerHandle
Get a page for insert. If RawStore thinks it knows where a potentially suitable page is for insert, it will return it. If RawStore doesn't know where a suitable page for insert is, or if there are no allocated page, then null is returned. If a page is returned, it will be a valid, non-overflow page. A potentially suitable page is one which has enough space for a minium sized record.

Specified by:
getPageForInsert in interface ContainerHandle
Parameters:
flag - a GET_PAGE_* flag.
Returns:
a valid, non-overflow page. Or null if RawStore doesn't know where to find a good valid, non-overflow page.
Throws:
StandardException - Standard Cloudscape error policy

isReadOnly

public final boolean isReadOnly()
Description copied from interface: ContainerHandle
Is the container opened for read only or update?

Specified by:
isReadOnly in interface ContainerHandle
Returns:
true if container is opened for read only, else false.
See Also:
ContainerHandle.isReadOnly()

close

public void close()
Description copied from interface: ContainerHandle
Close me. After using this method the caller must throw away the reference to the Container object, e.g.
                        ref.close();
                        ref = null;
                

The container will be closed automatically at the commit or abort of the transaction if this method is not called explictly.
Any pages that were obtained using me and have not been released using Page's unlatch method are released, and references to them must be thrown away.

Specified by:
close in interface ContainerHandle
See Also:
ContainerHandle.close()

getEstimatedRowCount

public long getEstimatedRowCount(int flag)
                          throws StandardException
Description copied from interface: ContainerHandle
Get the total estimated number of rows in the container, not including overflow rows. This number is a rough estimate and may be grossly off.

Specified by:
getEstimatedRowCount in interface ContainerHandle
Parameters:
flag - different flavors of row count (reserved for future use)
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.getEstimatedRowCount(int)

setEstimatedRowCount

public void setEstimatedRowCount(long count,
                                 int flag)
                          throws StandardException
Description copied from interface: ContainerHandle
Set the total estimated number of rows in the container. Often, after a scan, the client of RawStore has a much better estimate of the number of rows in the container then what RawStore has. Use this better number for future reference.
It is OK for a ReadOnly ContainerHandle to set the estimated row count.

Specified by:
setEstimatedRowCount in interface ContainerHandle
Parameters:
count - the estimated number of rows in the container.
flag - different flavors of row count (reserved for future use)
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.setEstimatedRowCount(long, int)

getEstimatedPageCount

public long getEstimatedPageCount(int flag)
                           throws StandardException
Description copied from interface: ContainerHandle
Get the total estimated number of allocated (not freed, not deallocated) user pages in the container, including overflow pages. this number is a rough estimate and may be grossly off.

Specified by:
getEstimatedPageCount in interface ContainerHandle
Parameters:
flag - different flavors of page count (reserved for future use)
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.getEstimatedPageCount(int)

flushContainer

public void flushContainer()
                    throws StandardException
Description copied from interface: ContainerHandle
Flush all dirty pages of the container to disk. Used mainly for UNLOGGED or CREATE_UNLOGGED operation.

Specified by:
flushContainer in interface ContainerHandle
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.flushContainer()

compactRecord

public void compactRecord(RecordHandle record)
                   throws StandardException
Description copied from interface: ContainerHandle
This record probably has shrunk considerably. Free its reserved space or compact it.

Specified by:
compactRecord in interface ContainerHandle
Parameters:
record - The record handle, the record must have been locked execlusively already.
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.compactRecord(org.apache.derby.iapi.store.raw.RecordHandle)

getContainerStatus

public int getContainerStatus()
                       throws StandardException
Get the container status.

Specified by:
getContainerStatus in interface RawContainerHandle
Throws:
StandardException - Standard Cloudscape error policy
See Also:
RawContainerHandle.getContainerStatus()

removeContainer

public void removeContainer(LogInstant instant)
                     throws StandardException
remove the container

Specified by:
removeContainer in interface RawContainerHandle
Throws:
StandardException - Standard Cloudscape error policy
See Also:
RawContainerHandle.removeContainer(org.apache.derby.iapi.store.raw.log.LogInstant)

getId

public ContainerKey getId()
Description copied from interface: ContainerHandle
Return my identifier.

Specified by:
getId in interface ContainerHandle
See Also:
ContainerHandle.getId()

getUniqueId

public java.lang.Object getUniqueId()
Description copied from interface: ContainerHandle
Return my unique identifier, this identifier will be unique to each instance of an open container handle. This id is used by the locking system to group locks to an open container handle.

Specified by:
getUniqueId in interface ContainerHandle
See Also:
ContainerHandle.getUniqueId()

dropContainer

public void dropContainer(LogInstant instant,
                          boolean drop)
                   throws StandardException
Description copied from interface: RawContainerHandle
If drop is true, drop the container. if drop is false, un-drop the container

Specified by:
dropContainer in interface RawContainerHandle
Throws:
StandardException - Standard cloudscape exception policy
See Also:
RawContainerHandle.dropContainer(org.apache.derby.iapi.store.raw.log.LogInstant, boolean)

getContainerVersion

public long getContainerVersion()
                         throws StandardException
Description copied from interface: RawContainerHandle
Get the logged container version

Specified by:
getContainerVersion in interface RawContainerHandle
Throws:
StandardException - Standard cloudscape exception policy
See Also:
RawContainerHandle.getContainerVersion()

getAnyPage

public Page getAnyPage(long pageNumber)
                throws StandardException
Get this page with no check - any page type or status is fine. Caller must be prepared to handle freed, deallocated,or alloc page Called by recovery ONLY.

Specified by:
getAnyPage in interface RawContainerHandle
Throws:
StandardException - Cloudscape Standard error policy

reCreatePageForLoadTran

public Page reCreatePageForLoadTran(int pageFormat,
                                    long pageNumber,
                                    long pageOffset)
                             throws StandardException
Re-create this page for load tran. Called by recovery redo ONLY

Specified by:
reCreatePageForLoadTran in interface RawContainerHandle
Throws:
StandardException - Cloudscape Standard error policy

logCreateContainerInfo

public ByteArray logCreateContainerInfo()
                                 throws StandardException
Log all information necessary to recreate the container during a load tran.

Specified by:
logCreateContainerInfo in interface RawContainerHandle
Throws:
StandardException - Standard Cloudscape error policy

makeRecordHandle

public RecordHandle makeRecordHandle(long pageNumber,
                                     int recordId)
                              throws StandardException
Return a record handle that is initialized to the given page number and record id.

Specified by:
makeRecordHandle in interface ContainerHandle
Parameters:
pageNumber - the page number of the RecordHandle.
recordId - the record id of the RecordHandle.
Throws:
StandardException - Standard cloudscape exception policy.
See Also:
RecordHandle

update

public void update(java.util.Observable obj,
                   java.lang.Object arg)
Called when the transaction is about to complete.

Specified by:
update in interface java.util.Observer
See Also:
Observer.update(java.util.Observable, java.lang.Object)

getActionSet

public PageActions getActionSet()

getAllocationActionSet

public AllocationActions getAllocationActionSet()

useContainer

public boolean useContainer(boolean droppedOK,
                            boolean waitForLock)
                     throws StandardException
Attach me to a container. If this method returns false then I cannot be used anymore, and any reference to me must be discarded.

Parameters:
droppedOK - if true, use this container even if it is dropped, otherwise, return false if container is dropped.
waitForLock - if true, wait on lock, otherwise, get lock no wait.
Throws:
StandardException - Standard Cloudscape error policy

getTransaction

public final RawTransaction getTransaction()
Return the RawTransaction I was opened in.


getLockingPolicy

public final LockingPolicy getLockingPolicy()
Return my locking policy, may be different from the Transaction's default locking policy.

Specified by:
getLockingPolicy in interface ContainerHandle

setLockingPolicy

public final void setLockingPolicy(LockingPolicy newLockingPolicy)
Description copied from interface: ContainerHandle
Set the locking policy for this open container

Specified by:
setLockingPolicy in interface ContainerHandle

updateOK

public final boolean updateOK()
Was I opened for updates?
MT - thread safe


getMode

public int getMode()
Get the mode I was opened with.


preDirty

public void preDirty(boolean preDirtyOn)
              throws StandardException
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.

Specified by:
preDirty in interface RawContainerHandle
Throws:
StandardException - Standard Cloudscape error policy

isTemporaryContainer

public boolean isTemporaryContainer()
                             throws StandardException
Description copied from interface: ContainerHandle
Return true if this containerHandle refers to a temporary container.

Specified by:
isTemporaryContainer in interface ContainerHandle
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.isTemporaryContainer()

checkOpen

protected void checkOpen()
                  throws StandardException
Throws:
StandardException

checkUpdateOpen

private void checkUpdateOpen()
                      throws StandardException
Throws:
StandardException

informObservers

protected void informObservers()

getSpaceInfo

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

Specified by:
getSpaceInfo in interface ContainerHandle
Throws:
StandardException

toString

public java.lang.String toString()


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