|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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
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 |
close()
Close me. |
void |
compactRecord(RecordHandle record)
This record probably has shrunk considerably. |
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 |
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. |
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 |
public static final int DEFAULT_PAGESIZE
public static final int DEFAULT_SPARESPACE
public static final int DEFAULT_ASSIGN_ID
public static final int MODE_DEFAULT
public static final int MODE_UNLOGGED
public static final int MODE_CREATE_UNLOGGED
public static final int MODE_FORUPDATE
public static final int MODE_READONLY
public static final int MODE_TRUNCATE_ON_COMMIT
public static final int MODE_DROP_ON_COMMIT
public static final int MODE_OPEN_FOR_LOCK_ONLY
public static final int MODE_LOCK_NOWAIT
public static final int MODE_TRUNCATE_ON_ROLLBACK
public static final int MODE_FLUSH_ON_COMMIT
public static final int MODE_NO_ACTIONS_ON_COMMIT
public static final int MODE_TEMP_IS_KEPT
public static final int MODE_USE_UPDATE_LOCKS
public static final int MODE_SECONDARY_LOCKED
public static final int MODE_BASEROW_INSERT_LOCKED
public static final int TEMPORARY_SEGMENT
public static final long FIRST_PAGE_NUMBER
public static final long INVALID_PAGE_NUMBER
public static final int ADD_PAGE_DEFAULT
public static final int ADD_PAGE_BULK
public static final int GET_PAGE_UNFILLED
Method Detail |
public ContainerKey getId()
public java.lang.Object getUniqueId()
public boolean isReadOnly()
public Page addPage() throws StandardException
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.
StandardException
- Standard Cloudscape error policy
StandardException
- If a page could not be allocated.Page.unlatch()
public Page addPage(int flag) throws StandardException
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.
StandardException
- Standard Cloudscape error policy
StandardException
- If a page could not be allocated.Page.unlatch()
public void preAllocate(int numPage)
public void removePage(Page page) throws StandardException
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.
StandardException
- Standard Cloudscape error policyLockingPolicy
,
RecordHandle
public Page getPage(long pageNumber) throws StandardException
The Page object is guaranteed to remain in-memory and exclusive to the caller until its unlatch() method is called.
StandardException
- Standard Cloudscape error policypublic Page getPageNoWait(long pageNumber) throws StandardException
StandardException
- Standard Cloudscape error policypublic Page getUserPageNoWait(long pageNumber) throws StandardException
The Page object is guaranteed to remain in-memory and exclusive to the caller until its unlatch() method is called.
StandardException
- Standard Cloudscape error policypublic Page getUserPageWait(long pageNumber) throws StandardException
The Page object is guaranteed to remain in-memory and exclusive to the caller until its unlatch() method is called.
StandardException
- Standard Cloudscape error policypublic Page getFirstPage() throws StandardException
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.
StandardException
- Standard Cloudscape error policygetPage(long)
public Page getNextPage(long prevNum) throws StandardException
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
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.
StandardException
- Standard Cloudscape error policygetPage(long)
public Page getPageForInsert(int flag) throws StandardException
flag
- a GET_PAGE_* flag.
StandardException
- Standard Cloudscape error policypublic void getContainerProperties(java.util.Properties prop) throws StandardException
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"); }
prop
- Property list to fill in.
StandardException
- Standard exception policy.public void close()
ref.close(); ref = null;
Page.unlatch()
,
Page.fetch(org.apache.derby.iapi.store.raw.RecordHandle, java.lang.Object[], org.apache.derby.iapi.services.io.FormatableBitSet, boolean)
public long getEstimatedRowCount(int flag) throws StandardException
flag
- different flavors of row count (reserved for future use)
StandardException
- Standard Cloudscape error policypublic void setEstimatedRowCount(long count, int flag) throws StandardException
count
- the estimated number of rows in the container.flag
- different flavors of row count (reserved for future use)
StandardException
- Standard Cloudscape error policypublic long getEstimatedPageCount(int flag) throws StandardException
flag
- different flavors of page count (reserved for future use)
StandardException
- Standard Cloudscape error policypublic void flushContainer() throws StandardException
StandardException
- Standard Cloudscape error policypublic LockingPolicy getLockingPolicy()
public void setLockingPolicy(LockingPolicy newLockingPolicy)
public RecordHandle makeRecordHandle(long pageNumber, int recordId) throws StandardException
pageNumber
- the page number of the RecordHandle.recordId
- the record id of the RecordHandle.
StandardException
- Standard cloudscape exception policy.RecordHandle
public void compactRecord(RecordHandle record) throws StandardException
record
- The record handle, the record must have been locked execlusively already.
StandardException
- Standard cloudscape exception policy.public boolean isTemporaryContainer() throws StandardException
StandardException
- Standard cloudscape exception policy.public SpaceInfo getSpaceInfo() throws StandardException
StandardException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |