Interface ContainerHandle
- All Known Subinterfaces:
RawContainerHandle
- All Known Implementing Classes:
BaseContainerHandle
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.
- MODE_READONLY - Open the container in read only mode.
- MODE_FORUPDATE - Open the container in update mode, if the underlying storage does not allow updates then the container will be opned in read only mode.
- MODE_UNLOGGED - If Unset, any changes to the container are logged. If set, any user changes to the container are unlogged. It is guaranteed at commit time that all changes made during the transaction will have been flushed to disk. Using this mode automatically opens the container in container locking, isolation 3 level. The state of the container following an abort or any type of rollback is unspecified.
- MODE_CREATE_UNLOGGED - If set, not only are user changes to the container are unlogged, page allocations are also unlogged. This MODE is only useful for container is created in the same statement and no change on the container (other than the create) is ever logged. The difference between MODE_UNLOGGED and MODE_CREATE_UNLOGGED is that page allocation is also unlogged and commit of nested transaction will not cause the container to be forced from the cache. Unlike MODE_UNLOGGED, MODE_CREATE_UNLOGGED does not force the cache. It is up to the client of raw store to force the cache at the appropriate time - this allows a statement to create and open the container serveral times for bulk loading without logging or doing any synchronous I/O.
- MODE_LOCK_NOWAIT - if set, then don't wait for the container lock, else wait for the container lock. This flag only dictates whether the lock should be waited for or not. After the container is successfully opened, whether this bit is set or not has no effect on the container handle.
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
- MODE_TRUNCATE_ON_COMMIT - At commit/abort time container is truncated.
- MODE_DROP_ON_COMMIT - At commit/abort time the container is dropped.
- MODE_TEMP_IS_KEPT - At commit/abort time the container is kept around.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
static final int
static final int
static final int
Used in add container.static final int
static final long
The first valid page numberstatic final int
static final long
A page number that is guaranteed to be invalid.static final int
static final int
static final int
See comments above for these modes.static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
-
Method Summary
Modifier and TypeMethodDescriptionaddPage()
Add an empty page to the container and obtain exclusive access to it.addPage
(int flag) Add an empty page to the container and obtain exclusive access to it.void
backupContainer
(String backupContainerPath) Backup the container to the specified path.void
close()
Close me.void
compactRecord
(RecordHandle record) This record probably has shrunk considerably.void
Release free space to the OS.void
Flush all dirty pages of the container to disk.void
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.Obtain exclusive access to the current first page of the container.getId()
Return my identifier.Return the locking policy for this open container.getNextPage
(long prevNum) Obtain exclusive access to the next valid page of the given page number in the container.getPage
(long pageNumber) Obtain exclusive access to the page with the given page number.getPageForCompress
(int flag, long pageno) getPageForInsert
(int flag) Get a page for insert.getPageNoWait
(long pageNumber) Identical to getPage but returns null immediately if the desired page is already latched by another Container.long
Get the reusable recordId sequence number.Get information about space used by the container.Return my unique identifier, this identifier will be unique to each instance of an open container handle.getUserPageNoWait
(long pageNumber) Obtain exclusive access to the page with the given page number.getUserPageWait
(long pageNumber) Obtain exclusive access to the page with the given page number.boolean
Is the container opened for read only or update?boolean
Return true if this containerHandle refers to a temporary container.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 Details
-
DEFAULT_PAGESIZE
static final int DEFAULT_PAGESIZEUsed in add container.- See Also:
-
DEFAULT_SPARESPACE
static final int DEFAULT_SPARESPACE- See Also:
-
DEFAULT_ASSIGN_ID
static final int DEFAULT_ASSIGN_ID- See Also:
-
MODE_DEFAULT
static final int MODE_DEFAULTSee comments above for these modes.- See Also:
-
MODE_UNLOGGED
static final int MODE_UNLOGGED- See Also:
-
MODE_CREATE_UNLOGGED
static final int MODE_CREATE_UNLOGGED- See Also:
-
MODE_FORUPDATE
static final int MODE_FORUPDATE- See Also:
-
MODE_READONLY
static final int MODE_READONLY- See Also:
-
MODE_TRUNCATE_ON_COMMIT
static final int MODE_TRUNCATE_ON_COMMIT- See Also:
-
MODE_DROP_ON_COMMIT
static final int MODE_DROP_ON_COMMIT- See Also:
-
MODE_OPEN_FOR_LOCK_ONLY
static final int MODE_OPEN_FOR_LOCK_ONLY- See Also:
-
MODE_LOCK_NOWAIT
static final int MODE_LOCK_NOWAIT- See Also:
-
MODE_TRUNCATE_ON_ROLLBACK
static final int MODE_TRUNCATE_ON_ROLLBACK- See Also:
-
MODE_FLUSH_ON_COMMIT
static final int MODE_FLUSH_ON_COMMIT- See Also:
-
MODE_NO_ACTIONS_ON_COMMIT
static final int MODE_NO_ACTIONS_ON_COMMIT- See Also:
-
MODE_TEMP_IS_KEPT
static final int MODE_TEMP_IS_KEPT- See Also:
-
MODE_USE_UPDATE_LOCKS
static final int MODE_USE_UPDATE_LOCKS- See Also:
-
MODE_SECONDARY_LOCKED
static final int MODE_SECONDARY_LOCKED- See Also:
-
MODE_BASEROW_INSERT_LOCKED
static final int MODE_BASEROW_INSERT_LOCKED- See Also:
-
MODE_LOCK_ROW_NOWAIT
static final int MODE_LOCK_ROW_NOWAIT- See Also:
-
TEMPORARY_SEGMENT
static final int TEMPORARY_SEGMENT- See Also:
-
FIRST_PAGE_NUMBER
static final long FIRST_PAGE_NUMBERThe first valid page number- See Also:
-
INVALID_PAGE_NUMBER
static final long INVALID_PAGE_NUMBERA page number that is guaranteed to be invalid.- See Also:
-
ADD_PAGE_DEFAULT
static final int ADD_PAGE_DEFAULT- See Also:
-
ADD_PAGE_BULK
static final int ADD_PAGE_BULK- See Also:
-
GET_PAGE_UNFILLED
static final int GET_PAGE_UNFILLED- See Also:
-
-
Method Details
-
getId
ContainerKey getId()Return my identifier. -
getUniqueId
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
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
- If a page could not be allocated.- See Also:
-
compressContainer
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
Get the reusable recordId sequence number.- Returns:
- version sequence number
- Throws:
StandardException
- Standard Derby error policy
-
addPage
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 policyStandardException
- If a page could not be allocated.- See Also:
-
preAllocate
void preAllocate(int numPage) Try to preallocate numPage new pages if possible. -
removePage
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:
-
getPage
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
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
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
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
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:
-
getNextPage
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:
-
getPageForInsert
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
- Throws:
StandardException
-
getContainerProperties
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:
-
getEstimatedRowCount
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
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
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
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
Set the locking policy for this open container -
makeRecordHandle
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:
-
compactRecord
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
Return true if this containerHandle refers to a temporary container.- Throws:
StandardException
- Standard Derby exception policy.
-
getSpaceInfo
Get information about space used by the container.- Throws:
StandardException
-
backupContainer
Backup the container to the specified path.- Throws:
StandardException
- Standard Derby error policy
-