containerhandle.java

derby database source code.good for you.

	public Page getPageNoWait(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.

		<P>
		The Page object is guaranteed to remain in-memory and exclusive to the 
        caller until its unlatch() method is called.

		@return 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)

		@exception StandardException	Standard Cloudscape error policy
	*/
	public 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.

		<P>
		The Page object is guaranteed to remain in-memory and exclusive to the 
        caller until its unlatch() method is called.

		@return 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)

		@exception StandardException	Standard Cloudscape error policy
	*/
	public Page getUserPageWait(long pageNumber) 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.
		<P>
		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.  
		<BR>
		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.

		@return latched page or null if there is no page in the container
		@exception StandardException	Standard Cloudscape error policy

		@see ContainerHandle#getPage
	*/
	public Page getFirstPage() 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.
		<P>
		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.  
		<BR>
		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.
		<BR>
		If no pages are added or removed, then an iteration such as:
		<PRE>
		for (Page p = containerHandle.getFirstPage();
			 p != null;
			 p = containerHandle.getNextPage(p.getPageNumber()))
		<PRE>
		will guarentee to iterate thru and latched all the valid pages 
		in the container

		@param 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.

		@return latched page or null if there is no next page in the container
		@exception StandardException	Standard Cloudscape error policy

		@see ContainerHandle#getPage
	*/
	public Page getNextPage(long prevNum) 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.

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

		@param flag a GET_PAGE_* flag.

		@exception StandardException Standard Cloudscape error policy 
	*/
	public Page getPageForInsert(int flag) 
		 throws StandardException;

	public Page getPageForCompress(
    int     flag,
    long    pageno) 
		 throws StandardException;

	// Try to get a page that is unfilled, 'unfill-ness' is defined by the
	// page.  Since unfill-ness is defined by the page, the only thing RawStore
	// guarentees about the page is that it has space for a a minimum sized
	// record.
	//
	// If this bit is not set, then getPageForInsert will get the page that was
	// last gotten, provided it has space for a minimum sized record.
	//
	// If for whatever reasons RawStore is unable to come up with such a page,
	// null will be returned.
	public static final int GET_PAGE_UNFILLED = 0x1;


    /**
     * Request the system properties associated with a container. 
     * <p>
     * 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
     * <p>
     * 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");
     * }
     *
     * @param prop   Property list to fill in.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    void getContainerProperties(Properties prop)
		throws StandardException;

	/**
		Close me. After using this method the caller must throw away the
		reference to the Container object, e.g.
		<PRE>
			ref.close();
			ref = null;
		</PRE>
		<BR>
		The container will be closed automatically at the commit or abort
		of the transaction if this method is not called explictly.
		<BR>
		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 Page#unlatch
		@see Page#fetch
	*/
	public void close();

	/**
		Cost estimation
	*/

	/**
		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.

		@param flag different flavors of row count (reserved for future use)
		@exception StandardException	Standard Cloudscape error policy
	 */
	public long getEstimatedRowCount(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.
		<BR>
		It is OK for a ReadOnly ContainerHandle to set the estimated row count.

		@param count the estimated number of rows in the container.
		@param flag different flavors of row count (reserved for future use)

		@exception StandardException	Standard Cloudscape error policy
	 */
	public void setEstimatedRowCount(long count, 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.

		@param flag different flavors of page count (reserved for future use)

		@exception StandardException	Standard Cloudscape error policy
	 */
	public long getEstimatedPageCount(int flag) throws StandardException;


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

		@exception StandardException	Standard Cloudscape error policy
	*/
	public void flushContainer() throws StandardException;

	/**
		Return the locking policy for this open container.
	*/
	public LockingPolicy getLockingPolicy();

	/**
		Set the locking policy for this open container
	*/
	public void setLockingPolicy(LockingPolicy newLockingPolicy);

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

		@exception StandardException Standard cloudscape exception policy.

		@param pageNumber   the page number of the RecordHandle.
		@param recordId     the record id of the RecordHandle.

		@see RecordHandle
	*/
	public RecordHandle makeRecordHandle(long pageNumber, int recordId)
		 throws	StandardException;


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

		@param record	The record handle, the record must have been locked execlusively already.
		@exception StandardException Standard cloudscape exception policy.
	*/
	public void compactRecord(RecordHandle record) throws StandardException;

	/**
		Return true if this containerHandle refers to a temporary container.
		@exception StandardException Standard cloudscape exception policy.
	 */
	public boolean isTemporaryContainer() throws StandardException;

    /**
    Get information about space used by the container.
    **/
    public SpaceInfo getSpaceInfo() throws StandardException;

}