storedcollection.java

嵌入式数据库Berkeley DB-4.5.20源代码

/*-
 * See the file LICENSE for redistribution information.
 *
 * Copyright (c) 2000-2006
 *      Oracle Corporation.  All rights reserved.
 *
 * $Id: StoredCollection.java,v 12.6 2006/09/08 20:32:13 bostic Exp $
 */

package com.sleepycat.collections;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;

import com.sleepycat.db.CursorConfig;
import com.sleepycat.db.DatabaseEntry;
import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.JoinConfig;
import com.sleepycat.db.OperationStatus;

/**
 * A abstract base class for all stored collections.  This class, and its
 * base class {@link StoredContainer}, provide implementations of most methods
 * in the {@link Collection} interface.  Other methods, such as {@link #add}
 * and {@link #remove}, are provided by concrete classes that extend this
 * class.
 *
 * <p>In addition, this class provides the following methods for stored
 * collections only.  Note that the use of these methods is not compatible with
 * the standard Java collections interface.</p>
 * <ul>
 * <li>{@link #getIteratorBlockSize}</li>
 * <li>{@link #setIteratorBlockSize}</li>
 * <li>{@link #storedIterator()}</li>
 * <li>{@link #storedIterator(boolean)}</li>
 * <li>{@link #join}</li>
 * <li>{@link #toList()}</li>
 * </ul>
 *
 * @author Mark Hayes
 */
public abstract class StoredCollection extends StoredContainer
    implements Collection {

    /**
     * The default number of records read at one time by iterators.
     * @see #setIteratorBlockSize
     */
    public static final int DEFAULT_ITERATOR_BLOCK_SIZE = 10;

    private int iteratorBlockSize = DEFAULT_ITERATOR_BLOCK_SIZE;

    StoredCollection(DataView view) {

        super(view);
    }

    /**
     * Returns the number of records read at one time by iterators returned by
     * the {@link #iterator} method.  By default this value is {@link
     * #DEFAULT_ITERATOR_BLOCK_SIZE}.
     */
    public int getIteratorBlockSize() {

        return iteratorBlockSize;
    }

    /**
     * Changes the number of records read at one time by iterators returned by
     * the {@link #iterator} method.  By default this value is {@link
     * #DEFAULT_ITERATOR_BLOCK_SIZE}.
     *
     * @throws IllegalArgumentException if the blockSize is less than two.
     */
    public void setIteratorBlockSize(int blockSize) {

        if (blockSize < 2) {
            throw new IllegalArgumentException
                ("blockSize is less than two: " + blockSize);
        }

        iteratorBlockSize = blockSize;
    }

    final boolean add(Object key, Object value) {

        DataCursor cursor = null;
        boolean doAutoCommit = beginAutoCommit();
        try {
            cursor = new DataCursor(view, true);
            OperationStatus status =
                cursor.putNoDupData(key, value, null, false);
            closeCursor(cursor);
            commitAutoCommit(doAutoCommit);
            return (status == OperationStatus.SUCCESS);
        } catch (Exception e) {
            closeCursor(cursor);
            throw handleException(e, doAutoCommit);
        }
    }

    BlockIterator blockIterator() {
        return new BlockIterator(this, isWriteAllowed(), iteratorBlockSize);
    }

    /**
     * Returns an iterator over the elements in this collection.
     * The iterator will be read-only if the collection is read-only.
     * This method conforms to the {@link Collection#iterator} interface.
     *
     * <p>The iterator returned by this method does not keep a database cursor
     * open and therefore it does not need to be closed.  It reads blocks of
     * records as needed, opening and closing a cursor to read each block of
     * records.  The number of records per block is 10 by default and can be
     * changed with {@link #setIteratorBlockSize}.</p>
     *
     * <p>Because this iterator does not keep a cursor open, if it is used
     * without transactions, the iterator does not have <em>cursor
     * stability</em> characteristics.  In other words, the record at the
     * current iterator position can be changed or deleted by another thread.
     * To prevent this from happening, call this method within a transaction or
     * use the {@link #storedIterator()} method instead.</p>
     *
     * @return a standard {@link Iterator} for this collection.
     *
     * @see #isWriteAllowed
     */
    public Iterator iterator() {
        return blockIterator();
    }

    /**
     * Returns an iterator over the elements in this collection.
     * The iterator will be read-only if the collection is read-only.
     * This method does not exist in the standard {@link Collection} interface.
     *
     * <p><strong>Warning:</strong> The iterator returned must be explicitly
     * closed using {@link StoredIterator#close()} or {@link
     * StoredIterator#close(java.util.Iterator)} to release the underlying
     * database cursor resources.</p>
     *
     * @return a {@link StoredIterator} for this collection.
     *
     * @see #isWriteAllowed
     */
    public StoredIterator storedIterator() {

        return storedIterator(isWriteAllowed());
    }

    /**
     * Returns a read or read-write iterator over the elements in this
     * collection.
     * This method does not exist in the standard {@link Collection} interface.
     *
     * <p><strong>Warning:</strong> The iterator returned must be explicitly
     * closed using {@link StoredIterator#close()} or {@link
     * StoredIterator#close(java.util.Iterator)} to release the underlying
     * database cursor resources.</p>
     *
     * @param writeAllowed is true to open a read-write iterator or false to
     * open a read-only iterator.  If the collection is read-only the iterator
     * will always be read-only.
     *
     * @return a {@link StoredIterator} for this collection.
     *
     * @throws IllegalStateException if writeAllowed is true but the collection
     * is read-only.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     *
     * @see #isWriteAllowed
     */
    public StoredIterator storedIterator(boolean writeAllowed) {

        try {
            return new StoredIterator(this, writeAllowed && isWriteAllowed(),
                                      null);
        } catch (Exception e) {
            throw StoredContainer.convertException(e);
        }
    }

    /**
     * @deprecated Please use {@link #storedIterator()} or {@link
     * #storedIterator(boolean)} instead.  Because the iterator returned must
     * be closed, the method name {@code iterator} is confusing since standard
     * Java iterators do not need to be closed.
     */
    public StoredIterator iterator(boolean writeAllowed) {

        return storedIterator(writeAllowed);
    }

    /**
     * Returns an array of all the elements in this collection.
     * This method conforms to the {@link Collection#toArray()} interface.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public Object[] toArray() {

        ArrayList list = new ArrayList();
        StoredIterator i = storedIterator();
        try {
            while (i.hasNext()) {
                list.add(i.next());
            }
        } finally {
            i.close();
        }
        return list.toArray();
    }

    /**
     * Returns an array of all the elements in this collection whose runtime
     * type is that of the specified array.
     * This method conforms to the {@link Collection#toArray(Object[])}
     * interface.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public Object[] toArray(Object[] a) {

        int j = 0;
        StoredIterator i = storedIterator();
        try {
            while (j < a.length && i.hasNext()) {
                a[j++] = i.next();
            }
            if (j < a.length) {
                a[j] = null;
            } else if (i.hasNext()) {
                ArrayList list = new ArrayList(Arrays.asList(a));
                while (i.hasNext()) {
                    list.add(i.next());
                }
                a = list.toArray(a);
            }
        } finally {
            i.close();
        }
        return a;
    }

    /**
     * Returns true if this collection contains all of the elements in the
     * specified collection.
     * This method conforms to the {@link Collection#containsAll} interface.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public boolean containsAll(Collection coll) {
	Iterator i = storedOrExternalIterator(coll);
        try {
            while (i.hasNext()) {
                if (!contains(i.next())) {
                    return false;
                }
            }
        } finally {
            StoredIterator.close(i);
        }
	return true;
    }

    /**
     * Adds all of the elements in the specified collection to this collection
     * (optional operation).
     * This method calls the {@link #add(Object)} method of the concrete
     * collection class, which may or may not be supported.
     * This method conforms to the {@link Collection#addAll} interface.
     *
     * @throws UnsupportedOperationException if the collection is read-only, or
     * if the collection is indexed, or if the add method is not supported by
     * the concrete collection.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public boolean addAll(Collection coll) {
	Iterator i = null;
        boolean doAutoCommit = beginAutoCommit();