Java Doc for ContainerHandle.java in  » Database-DBMS » db-derby-10.2 » org » apache » derby » iapi » store » raw » Java Source Code / Java DocumentationJava Source Code and Java Documentation

 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.

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.

As is possible release any free space to the operating system.

Note that once this method returns this page may no longer be the first page of the container.

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. a reference to the page that was added.
See Also:   Page.unlatch
exception:
  StandardException - Standard Cloudscape error policy
exception:
  StandardException - If a page could not be allocated.

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. a reference to the page that was added.
See Also:   Page.unlatch
exception:
  StandardException - Standard Cloudscape error policy
exception:
  StandardException - If a page could not be allocated.

 ref.close();
 ref = null;
 

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.
exception:
  StandardException - Standard Cloudscape error policy

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.
exception:
  StandardException - Standard exception policy.

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. latched page or null if there is no page in the container
exception:
  StandardException - Standard Cloudscape error policy
See Also:   ContainerHandle.getPage

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 pagethat is to be gotten.  The page which correspond to prevNummay 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 pagenumber 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. latched page or null if there is no next page in the container
exception:
  StandardException - 	Standard Cloudscape error policy
See Also:   ContainerHandle.getPage

The Page object is guaranteed to remain in-memory and exclusive to the caller until its unlatch() method is called. 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.
exception:
  StandardException - Standard Cloudscape error policy

The Page object is guaranteed to remain in-memory and exclusive to the caller until its unlatch() method is called. 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 isan allocation page or overflow page)
exception:
  StandardException - Standard Cloudscape error policy

The Page object is guaranteed to remain in-memory and exclusive to the caller until its unlatch() method is called. 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 isan allocation page or overflow page)
exception:
  StandardException - Standard Cloudscape error policy

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.
See Also:   LockingPolicy
See Also:   RecordHandle
exception:
  StandardException - Standard Cloudscape error policy