basecontainer.java

derby database source code.good for you.

/*

   Derby - Class org.apache.derby.impl.store.raw.data.BaseContainer

   Copyright 1997, 2004 The Apache Software Foundation or its licensors, as applicable.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

 */

package org.apache.derby.impl.store.raw.data;

import org.apache.derby.iapi.reference.SQLState;
import org.apache.derby.iapi.services.locks.Lockable;
import org.apache.derby.iapi.services.locks.Latch;
import org.apache.derby.iapi.services.locks.C_LockFactory;
import org.apache.derby.iapi.services.sanity.SanityManager;

import org.apache.derby.iapi.error.StandardException;

import org.apache.derby.iapi.store.access.TransactionController;
import org.apache.derby.iapi.store.access.SpaceInfo;

import org.apache.derby.iapi.store.raw.ContainerHandle;
import org.apache.derby.iapi.store.raw.LockingPolicy;
import org.apache.derby.iapi.store.raw.Page;
import org.apache.derby.iapi.store.raw.PageKey;
import org.apache.derby.iapi.store.raw.PageTimeStamp;
import org.apache.derby.iapi.store.raw.RecordHandle;
import org.apache.derby.iapi.store.raw.Transaction;
import org.apache.derby.iapi.store.raw.ContainerKey;
import org.apache.derby.iapi.store.raw.data.RawContainerHandle;
import org.apache.derby.iapi.store.raw.log.LogInstant;
import org.apache.derby.iapi.store.raw.xact.RawTransaction;

import org.apache.derby.iapi.util.ByteArray;

import java.util.Properties;
import java.util.Hashtable;

/**
	BaseContainer is an abstract class that provides the locking bahaviour
	for an object representing an active container, that is the actual
	storage container, not the ContainerHandle interface. This class is designed
	so that it can change the container it represents to avoid creating
	a new object for every container.
	<P>
	This object implements lockable to provide an object to lock while a page is being
	allocated.
	<BR> MT - Mutable - mutable identity : 
*/
abstract class BaseContainer implements Lockable {

	/**
		Identity of the container.

		<BR> MT - Mutable
	*/
	protected ContainerKey identity;

	
	/**
		Dropped state of the container.

		<BR> MT - mutable : single thread required. Either the container must be exclusive
		locked by this thread, or the container must have no identity (ie. it is being created
		or opened).
	*/
	protected boolean	isDropped;


	/**
		Committed Drop state of the container.  If a post comit action
		determined that the drop container operation is committed, the whole
		container may be removed and space reclaimed.

		<BR> MT - mutable : single thread required. Either the container must be exclusive
		locked by this thread, or the container must have no identity (ie. it is being created
		or opened).
	*/
	protected boolean isCommittedDrop;


	/**
		Is reusable recordId.  By default, record Ids are not reusable when a
		page is reused.  However, under special circumstances, clients to raw
		store may decide that record Ids may be reused after the page is
		reused.   When this flag is set, pages that are reused will have its
		next recordId set to RecordHandle.FIRST_RECORD_ID
	*/
	protected boolean isReusableRecordId = false;

	BaseContainer() {
	}

	/*
	** portions of Cacheable interface, interface is actually implemented by
	** sub-class. This section also contains methods related to this interface.
	*/

	protected void fillInIdentity(ContainerKey key) {

		if (SanityManager.DEBUG) {
			SanityManager.ASSERT(identity == null || (identity == key));
		}

		identity = key;
	}

	public void clearIdentity() {
		if (SanityManager.DEBUG) {
			SanityManager.ASSERT(identity != null);
		}

		identity = null;
	}

	public Object getIdentity() {
		return identity;
	}

	/*
	** Methods from Lockable, just require a single exclusive locker
	*/

	public void lockEvent(Latch lockInfo) {
		if (SanityManager.DEBUG) {
			SanityManager.ASSERT(identity != null);
		}
	}

	public boolean requestCompatible(Object requestedQualifier, Object grantedQualifier) {
		if (SanityManager.DEBUG) {
			SanityManager.ASSERT(identity != null);
		}
		return false;
	}

	public boolean lockerAlwaysCompatible() {
		if (SanityManager.DEBUG) {
			SanityManager.ASSERT(identity != null);
		}
		return false;
	}

	public void unlockEvent(Latch lockInfo) {
		if (SanityManager.DEBUG) {
			SanityManager.ASSERT(identity != null);
		}
	}

	/*
	** Implementation specific methods
	*/


	/**
		Release free space to the OS.
		<P>
        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
	*/
	public void compressContainer(BaseContainerHandle handle)
        throws StandardException
    {
		RawTransaction ntt = handle.getTransaction().startNestedTopTransaction();

		int mode = handle.getMode(); 

		if (SanityManager.DEBUG)
		{
			SanityManager.ASSERT((mode & ContainerHandle.MODE_FORUPDATE) ==
								 ContainerHandle.MODE_FORUPDATE, 
								 "addPage handle not for update");
		}

		// if we are not in the same transaction as the one which created the
		// container and the container may have logged some operation already, 
		// then we need to log allocation regardless of whether user changes
		// are logged.  Otherwise, the database will be corrupted if it
		// crashed. 
		if ((mode & ContainerHandle.MODE_CREATE_UNLOGGED) == 0 &&
			(mode & ContainerHandle.MODE_UNLOGGED) ==
						ContainerHandle.MODE_UNLOGGED) 
			mode &= ~ContainerHandle.MODE_UNLOGGED;

		// make a handle which is tied to the ntt, not to the user transaction 
        // this handle is tied to.  The container is already locked by the 
        // user transaction, open it nolock
		BaseContainerHandle allocHandle = (BaseContainerHandle)
            ntt.openContainer(identity, (LockingPolicy)null, mode);

		if (allocHandle == null)
        {
			throw StandardException.newException(
                    SQLState.DATA_ALLOC_NTT_CANT_OPEN, 
                    new Long(getSegmentId()), 
                    new Long(getContainerId()));
        }

		// Latch this container, the commit will release the latch
		ntt.getLockFactory().lockObject(
                ntt, ntt, this, null, C_LockFactory.WAIT_FOREVER);

		try
		{
            compressContainer(ntt, allocHandle);
		}
		finally
		{
            ntt.commit();

			ntt.close();
		}
    }

	/**
		Add a page to this container.

		<BR> MT - thread aware - 

		The add page operation involves 2 transactions, one is the user
		transaction (the transaction which owns the passed in handle), the
		other one is a NestedTopTransaction created by this BaseContainer.

		The nestedTopTransaction is used by the underlying container to change
		high contention structures, such as link list anchor or bit map pages.
		The nestedTopTransaction commits or aborts before this routine returns.

		The user transaction is used to latch the newly created page.

		@exception StandardException Standard Cloudscape error policy
	*/
	public Page addPage(BaseContainerHandle handle, boolean isOverflow) throws StandardException {
		
		RawTransaction ntt = handle.getTransaction().startNestedTopTransaction();

		int mode = handle.getMode(); 

		if (SanityManager.DEBUG)
		{
			SanityManager.ASSERT((mode & ContainerHandle.MODE_FORUPDATE) ==
								 ContainerHandle.MODE_FORUPDATE, 
								 "addPage handle not for update");
		}

		// if we are not in the same transaction as the one which created the
		// container and the container may have logged some operation already, 
		// then we need to log allocation regardless of whether user changes
		// are logged.  Otherwise, the database will be corrupted if it
		// crashed. 
		if ((mode & ContainerHandle.MODE_CREATE_UNLOGGED) == 0 &&
			(mode & ContainerHandle.MODE_UNLOGGED) ==
						ContainerHandle.MODE_UNLOGGED) 
			mode &= ~ContainerHandle.MODE_UNLOGGED;

		// make a handle which is tied to the ntt, not to the user transaction this
		// handle is tied to.  The container is already locked by the user transaction,
		// open it nolock
		BaseContainerHandle allocHandle = (BaseContainerHandle)ntt.openContainer
			(identity, (LockingPolicy)null, mode);

		if (allocHandle == null)
        {
			throw StandardException.newException(
                    SQLState.DATA_ALLOC_NTT_CANT_OPEN, 
                    new Long(getSegmentId()), 
                    new Long(getContainerId()));
        }

		// Latch this container, the commit will release the latch
		ntt.getLockFactory().lockObject(
                ntt, ntt, this, null, C_LockFactory.WAIT_FOREVER);

		BasePage newPage = null;
		try
		{
			newPage = newPage(handle, ntt, allocHandle, isOverflow);
		}
		finally
		{
			if (newPage != null)
            {
                // it is ok to commit without syncing, as it is ok if this
                // transaction never makes it to the db, if no subsequent
                // log record makes it to the log.  If any subsequent log
                // record is sync'd then this transaction will be sync'd
                // as well.
				ntt.commitNoSync(Transaction.RELEASE_LOCKS);
            }
			else
            {      
				ntt.abort();
            }
			ntt.close();
		}

		if (SanityManager.DEBUG) {
			SanityManager.ASSERT(newPage.isLatched());
		}

		if (!this.identity.equals(newPage.getPageId().getContainerId())) {

			if (SanityManager.DEBUG) {
				SanityManager.THROWASSERT("BaseContainer.addPage(), just got a new page from a different container"
					+ "\n this.identity = " + this.identity
					+ "\n newPage.getPageId().getContainerId() = " + newPage.getPageId().getContainerId()
					+ "\n handle is: " + handle
					+ "\n allocHandle is: " + allocHandle
					+ "\n this container is: " + this);
			}

			throw StandardException.newException(
                    SQLState.DATA_DIFFERENT_CONTAINER,
                    this.identity, newPage.getPageId().getContainerId());
		}

		return newPage;
	}

    /**
     * Request the system properties associated with a container.
     * <p>
     * Request the value of properties that are associated with a container.  
     * 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(BaseContainer base)
     * {
     *     Properties prop = new Properties();
     *     prop.put("derby.storage.pageSize", "");
     *     base.getContainerProperties(prop);
     *
     *     System.out.println(
     *         "container's page size = " + 
     *         prop.getProperty("derby.storage.pageSize");
     * }
     *
     * @param prop   Property list to fill in.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    public abstract void getContainerProperties(Properties prop)
		throws StandardException;

	/**
		Remove a page from this container.  The page will be unlatched by this
		routine before it returns.

		Unlike addPage, this method done as part of the user transaction.  
		The removed page is not usable by anyone until the user transaction 
        comits.
		If the user transaction rolls back, the removed page is un-removed.

		<BR> MT - thread aware -

		@param handle the container handle that has opened the container and latched the page
		@param page the latched page that is to be deallocated

		@exception StandardException Standard Cloudscape error policy
	*/
	protected void removePage(BaseContainerHandle handle, BasePage page) 
		 throws StandardException
	{
		try
		{
			if (SanityManager.DEBUG)
			{
				SanityManager.ASSERT(page.isLatched(), "page is not latched");
			}

			// get dealloc lock nowait on the page to be deallocated
			// this lock is held until this transaction commits.
			// then gc can free this page
			RecordHandle deallocLock = 
				page.makeRecordHandle(RecordHandle.DEALLOCATE_PROTECTION_HANDLE);

			// don't get deallocLock wait because caller have a page latched
			if (!getDeallocLock(handle, deallocLock, 
								false /* no wait */,
								false /* not zeroDuration */))
            {
				throw StandardException.newException(
                        SQLState.DATA_CANNOT_GET_DEALLOC_LOCK, 
                        page.getIdentity());
            }

			deallocatePage(handle, page);
		}
		finally
		{
			if (page != null)
				page.unlatch();
		}

	}

	/**
		Get the special dealloc lock on the page - the lock is gotten by the
		transaction that owns the container handle

		@exception StandardException Standard Cloudscape error policy
	*/
	protected boolean getDeallocLock(BaseContainerHandle handle, 
									 RecordHandle deallocLock, 
									 boolean wait,
									 boolean zeroDuration)
		 throws StandardException
	{
		// get deallocate lock on page so that the GC won't attempt to 
		// free and re-allocate it until the transaction commits