org.apache.derby.iapi.store.raw
Interface ContainerHandle

All Known Subinterfaces:
RawContainerHandle
All Known Implementing Classes:
BaseContainerHandle

public interface ContainerHandle

A Container contains a contigious address space of pages, the pages start at page number Container.FIRST_PAGE_NUMBER and are numbered sequentially. The page size is set at addContainer() time. RESOLVE: this style of coding is not currently enforced If the caller calls getPage (or one of its variants) more than once on the same page, the caller must call unlatch a corresponding number of times in order to ensure that the page is latched. For example:

    Container c;
        Page p1 = c.getPage(Container.FIRST_PAGE_NUMBER);
        Page p2 = c.getPage(Container.FIRST_PAGE_NUMBER);
        p1.unlatch();  -- Page is still latched.
        p2.unlatch();  -- Page is now unlatched.
        

There is no restriction on the order in which latching and unlatching is done. In the example, p1 could have been unlatched after p2 with no ill effects.

Open container modes ContainerHandle.MODE are used to open or create the container. Unlike TableProperties, MODEs are not permanantely associated with the container, it is effective only for the lifetime of the containerHandle itself.
A container may use any of these mode flags when it is opened.

If neither or both of the {MODE_READONLY, MODE_FORUPDATE} modes are specified then the behaviour of the container is unspecified.
MODE_UNLOGGED must be set for MODE_CREATE_UNLOGGED to be set.

Temporary Containers
If when creating a container the segment used is ContainerHandle.TEMPORARY_SEGMENT then the container is a temporary container. Temporary containers are not logged or locked and do not live across re-boots of the system. In addition any abort or rollback including rollbacks to savepoints truncate the container if it has been opened for update since the last commit or abort. Temporary containers are private to a transaction and must only be used a single thread within the transaction at any time, these restrictions are not currently enforced.
When opening a temporary container for update access these additional mode flags may be used

If a temporary container is opened multiple times in the same transaction with different modes then the most severe mode is used, ie. none < truncate on commit < drop on commit. The MODE_UNLOGGED, MODE_CREAT_UNLOGGED flags are ignored when opening a temporary container, not logged is always assumed.


Field Summary
static int ADD_PAGE_BULK
           
static int ADD_PAGE_DEFAULT
           
static int DEFAULT_ASSIGN_ID
           
static int DEFAULT_PAGESIZE
          Used in add container.
static int DEFAULT_SPARESPACE
           
static long FIRST_PAGE_NUMBER
          The first valid page number
static int GET_PAGE_UNFILLED
           
static long INVALID_PAGE_NUMBER
          A page number that is guaranteed to be invalid.
static int MODE_BASEROW_INSERT_LOCKED
           
static int MODE_CREATE_UNLOGGED
           
static int MODE_DEFAULT
          See comments above for these modes.
static int MODE_DROP_ON_COMMIT
           
static int MODE_FLUSH_ON_COMMIT
           
static int MODE_FORUPDATE
           
static int MODE_LOCK_NOWAIT
           
static int MODE_NO_ACTIONS_ON_COMMIT
           
static int MODE_OPEN_FOR_LOCK_ONLY
           
static int MODE_READONLY
           
static int MODE_SECONDARY_LOCKED
           
static int MODE_TEMP_IS_KEPT
           
static int MODE_TRUNCATE_ON_COMMIT
           
static int MODE_TRUNCATE_ON_ROLLBACK
           
static int MODE_UNLOGGED
           
static int MODE_USE_UPDATE_LOCKS
           
static int TEMPORARY_SEGMENT
           
 
Method Summary
 Page addPage()
          Add an empty page to the container and obtain exclusive access to it.
 Page addPage(int flag)
          Add an empty page to the container and obtain exclusive access to it.
 void backupContainer(java.lang.String backupContainerPath)
          Backup the container to the specified path.
 void close()
          Close me.
 void compactRecord(RecordHandle record)
          This record probably has shrunk considerably.
 void compressContainer()
          Release free space to the OS.
 void flushContainer()
          Flush all dirty pages of the container to disk.
 void getContainerProperties(java.util.Properties prop)
          Request the system properties associated with a container.
 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 the locking policy for this open container.
 Page getNextPage(long prevNum)
          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 getPageForCompress(int flag, long pageno)
           
 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.
 long getReusableRecordIdSequenceNumber()
          Get the reusable recordId sequence number.
 SpaceInfo getSpaceInfo()
          Get information about space used by the container.
 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.
 boolean isReadOnly()
          Is the container opened for read only or update?
 boolean isTemporaryContainer()
          Return true if this containerHandle refers to a temporary container.
 RecordHandle makeRecordHandle(long pageNumber, int recordId)
          Return a record handle that is initialized to the given segment id, container id, page number and record id.
 void preAllocate(int numPage)
          Try to preallocate numPage new pages if possible.
 void removePage(Page page)
          Remove this page from the container and unlatch the page.
 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
 

Field Detail

DEFAULT_PAGESIZE

static final int DEFAULT_PAGESIZE
Used in add container.

See Also:
Constant Field Values

DEFAULT_SPARESPACE

static final int DEFAULT_SPARESPACE
See Also:
Constant Field Values

DEFAULT_ASSIGN_ID

static final int DEFAULT_ASSIGN_ID
See Also:
Constant Field Values

MODE_DEFAULT

static final int MODE_DEFAULT
See comments above for these modes.

See Also:
Constant Field Values

MODE_UNLOGGED

static final int MODE_UNLOGGED
See Also:
Constant Field Values

MODE_CREATE_UNLOGGED

static final int MODE_CREATE_UNLOGGED
See Also:
Constant Field Values

MODE_FORUPDATE

static final int MODE_FORUPDATE
See Also:
Constant Field Values

MODE_READONLY

static final int MODE_READONLY
See Also:
Constant Field Values

MODE_TRUNCATE_ON_COMMIT

static final int MODE_TRUNCATE_ON_COMMIT
See Also:
Constant Field Values

MODE_DROP_ON_COMMIT

static final int MODE_DROP_ON_COMMIT
See Also:
Constant Field Values

MODE_OPEN_FOR_LOCK_ONLY

static final int MODE_OPEN_FOR_LOCK_ONLY
See Also:
Constant Field Values

MODE_LOCK_NOWAIT

static final int MODE_LOCK_NOWAIT
See Also:
Constant Field Values

MODE_TRUNCATE_ON_ROLLBACK

static final int MODE_TRUNCATE_ON_ROLLBACK
See Also:
Constant Field Values

MODE_FLUSH_ON_COMMIT

static final int MODE_FLUSH_ON_COMMIT
See Also:
Constant Field Values

MODE_NO_ACTIONS_ON_COMMIT

static final int MODE_NO_ACTIONS_ON_COMMIT
See Also:
Constant Field Values

MODE_TEMP_IS_KEPT

static final int MODE_TEMP_IS_KEPT
See Also:
Constant Field Values

MODE_USE_UPDATE_LOCKS

static final int MODE_USE_UPDATE_LOCKS
See Also:
Constant Field Values

MODE_SECONDARY_LOCKED

static final int MODE_SECONDARY_LOCKED
See Also:
Constant Field Values

MODE_BASEROW_INSERT_LOCKED

static final int MODE_BASEROW_INSERT_LOCKED
See Also:
Constant Field Values

TEMPORARY_SEGMENT

static final int TEMPORARY_SEGMENT
See Also:
Constant Field Values

FIRST_PAGE_NUMBER

static final long FIRST_PAGE_NUMBER
The first valid page number

See Also:
Constant Field Values

INVALID_PAGE_NUMBER

static final long INVALID_PAGE_NUMBER
A page number that is guaranteed to be invalid.

See Also:
Constant Field Values

ADD_PAGE_DEFAULT

static final int ADD_PAGE_DEFAULT
See Also:
Constant Field Values

ADD_PAGE_BULK

static final int ADD_PAGE_BULK
See Also:
Constant Field Values

GET_PAGE_UNFILLED

static final int GET_PAGE_UNFILLED
See Also:
Constant Field Values
Method Detail

getId

ContainerKey getId()
Return my identifier.


getUniqueId

java.lang.Object getUniqueId()
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.


isReadOnly

boolean isReadOnly()
Is the container opened for read only or update?

Returns:
true if container is opened for read only, else false.

addPage

Page addPage()
             throws StandardException
Add an empty page to the container and obtain exclusive access to it.

Note that the added page may not be the last page in the Container. Once the Page is no longer required the Page's unlatch() method must be called.

Returns:
a reference to the page that was added.
Throws:
StandardException - Standard Derby error policy
StandardException - If a page could not be allocated.
See Also:
Page.unlatch()

compressContainer

void compressContainer()
                       throws StandardException
Release free space to the OS.

As is possible release any free space to the operating system. This will usually mean releasing any free pages located at the end of the file using the java truncate() interface.

Throws:
StandardException - Standard Derby error policy

getReusableRecordIdSequenceNumber

long getReusableRecordIdSequenceNumber()
                                       throws StandardException
Get the reusable recordId sequence number.

Returns:
version sequence number
Throws:
StandardException - Standard Derby error policy

addPage

Page addPage(int flag)
             throws StandardException
Add an empty page to the container and obtain exclusive access to it.

If flag == ADD_PAGE_DEFAULT, this call is identical to addPage().
If flag == ADD_PAGE_BULK, then this call signifies to the container that this addPage is part of a large number of additional pages and it is desirable to do whatever possible to facilitate adding many subsequent pages. The actual container implementation will decide whether or not to heed this hint and what to do about it.

Returns:
a reference to the page that was added.
Throws:
StandardException - Standard Derby error policy
StandardException - If a page could not be allocated.
See Also:
Page.unlatch()

preAllocate

void preAllocate(int numPage)
Try to preallocate numPage new pages if possible.


removePage

void removePage(Page page)
                throws StandardException
Remove this page from the container and unlatch the page. Caller should commit or abort this transaction ASAP because failure to do so will slow down page allocation of this container.
The page to be removed must be latched and gotten (or added) by this ContainerHandle. The page should not be used again after this call as if it has been unlatched. If the call to removePage is successful, this page is invalid should not be gotten again with getPage.
RemovePage will guarantee to unlatch the page even if a StandardException is thrown.

Locking Policy
The page will not be freed until the transaction that removed the page commits. A special RecordHandle.DEALLOC_PROTECTION_HANDLE lock will be gotten for the transaction and which is used to prevent the page from being freed. This lock will be held regardless of the default locking policy of the transaction that called removedPage.

Throws:
StandardException - Standard Derby error policy
See Also:
LockingPolicy, RecordHandle

getPage

Page getPage(long pageNumber)
             throws StandardException
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.

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 Derby error policy

getPageNoWait

Page getPageNoWait(long pageNumber)
                   throws StandardException
Identical to getPage but returns null immediately if the desired page is already latched by another Container.

Returns:
the required Page or null if the page does not exist or the page is already latched.
Throws:
StandardException - Standard Derby error policy

getUserPageNoWait

Page getUserPageNoWait(long pageNumber)
                       throws StandardException
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.

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 Derby error policy

getUserPageWait

Page getUserPageWait(long pageNumber)
                     throws StandardException
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.

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 Derby error policy

getFirstPage

Page getFirstPage()
                  throws StandardException
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.

Returns:
latched page or null if there is no page in the container
Throws:
StandardException - Standard Derby error policy
See Also:
getPage(long)

getNextPage

Page getNextPage(long prevNum)
                 throws StandardException
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

Parameters:
prevNum - 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 Derby error policy
See Also:
getPage(long)

getPageForInsert

Page getPageForInsert(int flag)
                      throws StandardException
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.

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 Derby error policy

getPageForCompress

Page getPageForCompress(int flag,
                        long pageno)
                        throws StandardException
Throws:
StandardException

getContainerProperties

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

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

close

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

See Also:
Page.unlatch()

getEstimatedRowCount

long getEstimatedRowCount(int flag)
                          throws StandardException
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.

Parameters:
flag - different flavors of row count (reserved for future use)
Throws:
StandardException - Standard Derby error policy

setEstimatedRowCount

void setEstimatedRowCount(long count,
                          int flag)
                          throws StandardException
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.

Parameters:
count - the estimated number of rows in the container.
flag - different flavors of row count (reserved for future use)
Throws:
StandardException - Standard Derby error policy

getEstimatedPageCount

long getEstimatedPageCount(int flag)
                           throws StandardException
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.

Parameters:
flag - different flavors of page count (reserved for future use)
Throws:
StandardException - Standard Derby error policy

flushContainer

void flushContainer()
                    throws StandardException
Flush all dirty pages of the container to disk. Used mainly for UNLOGGED or CREATE_UNLOGGED operation.

Throws:
StandardException - Standard Derby error policy

getLockingPolicy

LockingPolicy getLockingPolicy()
Return the locking policy for this open container.


setLockingPolicy

void setLockingPolicy(LockingPolicy newLockingPolicy)
Set the locking policy for this open container


makeRecordHandle

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

Parameters:
pageNumber - the page number of the RecordHandle.
recordId - the record id of the RecordHandle.
Throws:
StandardException - Standard Derby exception policy.
See Also:
RecordHandle

compactRecord

void compactRecord(RecordHandle record)
                   throws StandardException
This record probably has shrunk considerably. Free its reserved space or compact it.

Parameters:
record - The record handle, the record must have been locked execlusively already.
Throws:
StandardException - Standard Derby exception policy.

isTemporaryContainer

boolean isTemporaryContainer()
                             throws StandardException
Return true if this containerHandle refers to a temporary container.

Throws:
StandardException - Standard Derby exception policy.

getSpaceInfo

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

Throws:
StandardException

backupContainer

void backupContainer(java.lang.String backupContainerPath)
                     throws StandardException
Backup the container to the specified path.

Throws:
StandardException - Standard Derby error policy

Built on Thu 2010-12-23 20:49:13+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.