sleepycat/collections/StoredCollection.java

/*-
 * See the file LICENSE for redistribution information.
 *
 * Copyright (c) 2000,2008 Oracle.  All rights reserved.
 *
 * $Id: StoredCollection.java,v 12.10 2008/02/07 17:12:26 mark 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.compat.DbCompat;
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>If {@code Iterator.set} or {@code Iterator.remove} will be called
     * and the underlying Database is transactional, then a transaction must be
     * active when calling this method and must remain active while using the
     * iterator.</p>
     *
     * <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>If {@code Iterator.set} or {@code Iterator.remove} will be called
     * and the underlying Database is transactional, then a transaction must be
     * active when calling this method and must remain active while using the
     * iterator.</p>
     *
     * <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();
        try {
            i = storedOrExternalIterator(coll);
            boolean changed = false;
            while (i.hasNext()) {
                if (add(i.next())) {
                    changed = true;
                }
            }
            StoredIterator.close(i);
            commitAutoCommit(doAutoCommit);
            return changed;
        } catch (Exception e) {
            StoredIterator.close(i);
            throw handleException(e, doAutoCommit);
        }
    }

    /**
     * Removes all this collection's elements that are also contained in the
     * specified collection (optional operation).
     * This method conforms to the {@link Collection#removeAll} interface.
     *
     * @throws UnsupportedOperationException if the collection is read-only.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public boolean removeAll(Collection coll) {

        return removeAll(coll, true);
    }

    /**
     * Retains only the elements in this collection that are contained in the
     * specified collection (optional operation).
     * This method conforms to the {@link Collection#removeAll} interface.
     *
     * @throws UnsupportedOperationException if the collection is read-only.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public boolean retainAll(Collection coll) {

        return removeAll(coll, false);
    }

    private boolean removeAll(Collection coll, boolean ifExistsInColl) {
	StoredIterator i = null;
        boolean doAutoCommit = beginAutoCommit();
        try {
            boolean changed = false;
            i = storedIterator();
            while (i.hasNext()) {
                if (ifExistsInColl == coll.contains(i.next())) {
                    i.remove();
                    changed = true;
                }
            }
            i.close();
            commitAutoCommit(doAutoCommit);
            return changed;
        } catch (Exception e) {
            if (i != null) {
                i.close();
            }
            throw handleException(e, doAutoCommit);
        }
    }

    /**
     * Compares the specified object with this collection for equality.
     * A value comparison is performed by this method and the stored values
     * are compared rather than calling the equals() method of each element.
     * This method conforms to the {@link Collection#equals} interface.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public boolean equals(Object other) {

        if (other instanceof Collection) {
            Collection otherColl = StoredCollection.copyCollection(other);
            StoredIterator i = storedIterator();
            try {
                while (i.hasNext()) {
                    if (!otherColl.remove(i.next())) {
                        return false;
                    }
                }
                return otherColl.isEmpty();
            } finally {
                i.close();
            }
        } else {
            return false;
        }
    }

    /*
     * Add this in to keep FindBugs from whining at us about implementing
     * equals(), but not hashCode().
     */
    public int hashCode() {
	return super.hashCode();
    }

    /**
     * Returns a copy of this collection as an ArrayList.  This is the same as
     * {@link #toArray()} but returns a collection instead of an array.
     *
     * @return an {@link ArrayList} containing a copy of all elements in this
     * collection.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public List toList() {

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

    /**
     * Converts the collection to a string representation for debugging.
     * WARNING: The returned string may be very large.
     *
     * @return the string representation.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public String toString() {
	StringBuffer buf = new StringBuffer();
	buf.append("[");
	StoredIterator i = storedIterator();
        try {
            while (i.hasNext()) {
                if (buf.length() > 1) buf.append(',');
                buf.append(i.next().toString());
            }
            buf.append(']');
            return buf.toString();
        } finally {
            i.close();
        }
    }

    // Inherit javadoc
    public int size() {

        boolean countDups = iterateDuplicates();
        if (DbCompat.DATABASE_COUNT && countDups && !view.range.hasBound()) {
            try {
                return (int) DbCompat.getDatabaseCount(view.db);
            } catch (Exception e) {
                throw StoredContainer.convertException(e);
            }
        } else {
            int count = 0;
            CursorConfig cursorConfig = view.currentTxn.isLockingMode() ?
                CursorConfig.READ_UNCOMMITTED : null;
            DataCursor cursor = null;
            try {
                cursor = new DataCursor(view, false, cursorConfig);
                OperationStatus status = cursor.getFirst(false);
                while (status == OperationStatus.SUCCESS) {
                    if (countDups) {
                        count += cursor.count();
                    } else {
                        count += 1;
                    }
                    status = cursor.getNextNoDup(false);
                }
            } catch (Exception e) {
                throw StoredContainer.convertException(e);
            } finally {
                closeCursor(cursor);
            }
            return count;
        }
    }

    /**
     * Returns an iterator representing an equality join of the indices and
     * index key values specified.
     * 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>
     *
     * <p>The returned iterator supports only the two methods: hasNext() and
     * next().  All other methods will throw UnsupportedOperationException.</p>
     *
     * @param indices is an array of indices with elements corresponding to
     * those in the indexKeys array.
     *
     * @param indexKeys is an array of index key values identifying the
     * elements to be selected.
     *
     * @param joinConfig is the join configuration, or null to use the
     * default configuration.
     *
     * @return an iterator over the elements in this collection that match
     * all specified index key values.
     *
     * @throws IllegalArgumentException if this collection is indexed or if a
     * given index does not have the same store as this collection.
     *
     * @throws RuntimeExceptionWrapper if a {@link DatabaseException} is
     * thrown.
     */
    public StoredIterator join(StoredContainer[] indices, Object[] indexKeys,
                               JoinConfig joinConfig) {

        try {
            DataView[] indexViews = new DataView[indices.length];
            for (int i = 0; i < indices.length; i += 1) {
                indexViews[i] = indices[i].view;
            }
            DataCursor cursor = view.join(indexViews, indexKeys, joinConfig);
            return new StoredIterator(this, false, cursor);
        } catch (Exception e) {
            throw StoredContainer.convertException(e);
        }
    }

    final Object getFirstOrLast(boolean doGetFirst) {

        DataCursor cursor = null;
        try {
            cursor = new DataCursor(view, false);
            OperationStatus status;
            if (doGetFirst) {
                status = cursor.getFirst(false);
            } else {
                status = cursor.getLast(false);
            }
            return (status == OperationStatus.SUCCESS) ?
                    makeIteratorData(null, cursor) : null;
        } catch (Exception e) {
            throw StoredContainer.convertException(e);
        } finally {
            closeCursor(cursor);
        }
    }

    Object makeIteratorData(BaseIterator iterator, DataCursor cursor) {

        return makeIteratorData(iterator,
                                cursor.getKeyThang(),
                                cursor.getPrimaryKeyThang(),
                                cursor.getValueThang());
    }

    abstract Object makeIteratorData(BaseIterator iterator,
                                     DatabaseEntry keyEntry,
                                     DatabaseEntry priKeyEntry,
                                     DatabaseEntry valueEntry);

    abstract boolean hasValues();

    boolean iterateDuplicates() {

        return true;
    }

    void checkIterAddAllowed()
        throws UnsupportedOperationException {

        if (!areDuplicatesAllowed()) {
            throw new UnsupportedOperationException("duplicates required");
        }
    }

    int getIndexOffset() {

        return 0;
    }

    private static Collection copyCollection(Object other) {

        if (other instanceof StoredCollection) {
            return ((StoredCollection) other).toList();
        } else {
            return new ArrayList((Collection) other);
        }
    }
}