public Interface ContainerHandle

Used in add container.

The first valid page number

A page number that is guaranteed to be invalid.

See comments above for these modes.

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:Page

a reference to the page that was added.

Exceptions

StandardException:

If a page could not be allocated.

See Also

Page#unlatch

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:Page

a reference to the page that was added.

Exceptions

StandardException:

• Standard Derby error policy
• If a page could not be allocated.

See Also

Page#unlatch

Backup the container to the specified path.

Exceptions

StandardException:

Standard Derby error policy

Close me. After using this method the caller must throw away the reference to the Container object, e.g.

	ref.close();
	ref = null;

See Also

Page#unlatch

This record probably has shrunk considerably. Free its reserved space or compact it.

Parameters

record:RecordHandle

The record handle, the record must have been locked execlusively already.

Exceptions

StandardException:

Standard Derby exception policy.

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.

Exceptions

StandardException:

Standard Derby error policy

Flush all dirty pages of the container to disk. Used mainly for UNLOGGED or CREATE_UNLOGGED operation.

Exceptions

StandardException:

Standard Derby error policy

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:Properties

Property list to fill in.

Exceptions

StandardException:

Standard exception policy.

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:int

different flavors of page count (reserved for future use)

Exceptions

StandardException:

Standard Derby error policy

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:int

different flavors of row count (reserved for future use)

Exceptions

StandardException:

Standard Derby error policy

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:Page

latched page or null if there is no page in the container

Exceptions

StandardException:

Standard Derby error policy

See Also

ContainerHandle#getPage

Return my identifier.

Return the locking policy for this open container.

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()))

Parameters

prevNum:long

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:Page

latched page or null if there is no next page in the container

Exceptions

StandardException:

Standard Derby error policy

See Also

ContainerHandle#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:Page

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.

Exceptions

StandardException:

Standard Derby error policy

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:int

a GET_PAGE_* flag.

Returns:Page

a valid, non-overflow page. Or null if RawStore doesn't know where to find a good valid, non-overflow page.

Exceptions

StandardException:

Standard Derby error policy

Identical to getPage but returns null immediately if the desired page is already latched by another Container.

Returns:Page

the required Page or null if the page does not exist or the page is already latched.

Exceptions

StandardException:

Standard Derby error policy

Get the reusable recordId sequence number.

Returns:long

version sequence number

Exceptions

StandardException:

Standard Derby error policy

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. This id is used by the locking system to group locks to an open container handle.

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:Page

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)

Exceptions

StandardException:

Standard Derby error policy

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:Page

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)

Exceptions

StandardException:

Standard Derby error policy

Is the container opened for read only or update?

Returns:boolean

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

Return true if this containerHandle refers to a temporary container.

Exceptions

StandardException:

Standard Derby exception policy.

Return a record handle that is initialized to the given segment id, container id, page number and record id.

Parameters

pageNumber:long

the page number of the RecordHandle.

recordId:int

the record id of the RecordHandle.

Exceptions

StandardException:

Standard Derby exception policy.

See Also

RecordHandle

Try to preallocate numPage new pages if possible.

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.

Exceptions

StandardException:

Standard Derby error policy

See Also

LockingPolicy, RecordHandle

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:long

the estimated number of rows in the container.

flag:int

different flavors of row count (reserved for future use)

Exceptions

StandardException:

Standard Derby error policy

Set the locking policy for this open container