storage.java

这个是perst-269.zip下面的SOURCECODE,和大家分享了。

package org.garret.perst;

import java.util.Iterator;
import org.garret.perst.impl.ThreadTransactionContext;

/**
 * Object storage
 */
public interface Storage { 
    /**
     * Constant specifying that page pool should be dynamically extended 
     * to conatins all database file pages
     */
    public static final int INFINITE_PAGE_POOL = 0;
    /**
     * Constant specifying default pool size
     */
    public static final int DEFAULT_PAGE_POOL_SIZE = 4*1024*1024;

    /**
     * Open the storage
     * @param filePath path to the database file
     * @param pagePoolSize size of page pool (in bytes). Page pool should contain
     * at least ten 4kb pages, so minimal page pool size should be at least 40Kb.
     * But larger page pool usually leads to better performance (unless it could not fit
     * in memory and cause swapping). Value 0 of this paremeter corresponds to infinite
     * page pool (all pages are cashed in memory). It is especially useful for in-memory
     * database, when storage is created with NullFile.
     * 
     */
    public void open(String filePath, int pagePoolSize);

    /**
     * Open the storage
     * @param file user specific implementation of IFile interface
     * @param pagePoolSize size of page pool (in bytes). Page pool should contain
     * at least ten 4kb pages, so minimal page pool size should be at least 40Kb.
     * But larger page pool ussually leads to better performance (unless it could not fit
     * in memory and cause swapping).
     */
    public void open(IFile file, int pagePoolSize);

    /**
     * Open the storage with default page pool size
     * @param file user specific implementation of IFile interface
     */ 
    public void open(IFile file);

    /**
     * Open the storage with default page pool size
     * @param filePath path to the database file
     */ 
    public void open(String filePath);

    /**
     * Open the encrypted storage
     * @param filePath path to the database file
     * @param pagePoolSize size of page pool (in bytes). Page pool should contain
     * at least ten 4kb pages, so minimal page pool size should be at least 40Kb.
     * But larger page pool ussually leads to better performance (unless it could not fit
     * in memory and cause swapping).
     * @param cipherKey cipher key
     */
    public void open(String filePath, int pagePoolSize, String cipherKey);

    /**
     * Check if database is opened
     * @return <code>true</code> if database was opened by <code>open</code> method, 
     * <code>false</code> otherwise
     */
    public boolean isOpened();
    
    /**
     * Get storage root. Storage can have exactly one root object. 
     * If you need to have several root object and access them by name (as is is possible 
     * in many other OODBMSes), you should create index and use it as root object.
     * @return root object or <code>null</code> if root is not specified (storage is not yet initialized)
     */
    public IPersistent getRoot();
    
    /**
     * Set new storage root object.
     * Previous reference to the root object is rewritten but old root is not automatically deallocated.
     * @param root object to become new storage root. If it is not persistent yet, it is made
     * persistent and stored in the storage
     */
    public void setRoot(IPersistent root);

    

    /**
     * Commit changes done by the last transaction. Transaction is started implcitlely with forst update
     * opertation.
     */
    public void commit();

    /**
     * Rollback changes made by the last transaction
     */
    public void rollback();


    /**
     * Backup current state of database
     * @param out output stream to which backup is done
     */
    public void backup(java.io.OutputStream out) throws java.io.IOException;

    /**
     * Exclusive per-thread transaction: each thread access database in exclusive mode
     */
    public static final int EXCLUSIVE_TRANSACTION   = 0;
    /**
     * Alias for EXCLUSIVE_TRANSACTION. In case of multiclient access, 
     * and transaction modifying database should be exclusive.
     */
    public static final int READ_WRITE_TRANSACTION = EXCLUSIVE_TRANSACTION;
    /**
     * Cooperative mode; all threads share the same transaction. Commit will commit changes made
     * by all threads. To make this schema work correctly, it is necessary to ensure (using locking)
     * that no thread is performing update of the database while another one tries to perform commit.
     * Also please notice that rollback will undo the work of all threads. 
     */
    public static final int COOPERATIVE_TRANSACTION = 1;
    /**
     * Alias for COOPERATIVE_TRANSACTION. In case of multiclient access, 
     * only read-only transactions can be executed in parallel.
     */
    public static final int READ_ONLY_TRANSACTION = COOPERATIVE_TRANSACTION;
    /**
     * Serializable per-thread transaction. Unlike exclusive mode, threads can concurrently access database, 
     * but effect will be the same as them work exclusively.
     * To provide such behavior, programmer should lock all access objects (or use hierarchical locking).
     * When object is updated, exclusive lock should be set, otherwise shared lock is enough.
     * Lock should be preserved until the end of transaction.
     */
    public static final int SERIALIZABLE_TRANSACTION = 2;

    /**
     * Read only transaction which can be started at replicastion slave node.
     * It runs concurrently with receiving updates from master node.
     */
    public static final int REPLICATION_SLAVE_TRANSACTION = 3;

    /** 
     * Begin per-thread transaction. Three types of per-thread transactions are supported: 
     * exclusive, cooperative and serializable. In case of exclusive transaction, only one 
     * thread can update the database. In cooperative mode, multiple transaction can work 
     * concurrently and commit() method will be invoked only when transactions of all threads
     * are terminated. Serializable transactions can also work concurrently. But unlike
     * cooperative transaction, the threads are isolated from each other. Each thread
     * has its own associated set of modified objects and committing the transaction will cause
     * saving only of these objects to the database. To synchronize access to the objects
     * in case of serializable transaction programmer should use lock methods
     * of IResource interface. Shared lock should be set before read access to any object, 
     * and exclusive lock - before write access. Locks will be automatically released when
     * transaction is committed (so programmer should not explicitly invoke unlock method)
     * In this case it is guaranteed that transactions are serializable.<br>
     * It is not possible to use <code>IPersistent.store()</code> method in
     * serializable transactions. That is why it is also not possible to use Index and FieldIndex
     * containers (since them are based on B-Tree and B-Tree directly access database pages
     * and use <code>store()</code> method to assign OID to inserted object. 
     * You should use <code>SortedCollection</code> based on T-Tree instead or alternative
     * B-Tree implemenataion (set "perst.alternative.btree" property).
     * @param mode <code>EXCLUSIVE_TRANSACTION</code>, <code>COOPERATIVE_TRANSACTION</code>, 
     * <code>SERIALIZABLE_TRANSACTION</code> or <code>REPLICATION_SLAVE_TRANSACTION</code>
     */
    public void beginThreadTransaction(int mode);
    
    /**
     * End per-thread transaction started by beginThreadTransaction method.<br>
     * If transaction is <i>exclusive</i>, this method commits the transaction and
     * allows other thread to proceed.<br>
     * If transaction is <i>serializable</i>, this method commits sll changes done by this thread
     * and release all locks set by this thread.<br>     
     * If transaction is <i>cooperative</i>, this method decrement counter of cooperative
     * transactions and if it becomes zero - commit the work
     */
    public void endThreadTransaction(); 

    /**
     * End per-thread cooperative transaction with specified maximal delay of transaction
     * commit. When cooperative transaction is ended, data is not immediately committed to the
     * disk (because other cooperative transaction can be active at this moment of time).
     * Instead of it cooperative transaction counter is decremented. Commit is performed
     * only when this counter reaches zero value. But in case of heavy load there can be a lot of
     * requests and so a lot of active cooperative transactions. So transaction counter never reaches zero value.
     * If system crash happens a large amount of work will be lost in this case. 
     * To prevent such scenario, it is possible to specify maximal delay of pending transaction commit.
     * In this case when such timeout is expired, new cooperative transaction will be blocked until
     * transaction is committed.
     * @param maxDelay maximal delay in milliseconds of committing transaction.  Please notice, that Perst could 
     * not force other threads to commit their cooperative transactions when this timeout is expired. It will only
     * block new cooperative transactions to make it possible to current transaction to complete their work.
     * If <code>maxDelay</code> is 0, current thread will be blocked until all other cooperative trasnaction are also finished
     * and changhes will be committed to the database.
     */
    public void endThreadTransaction(int maxDelay);
   
    /**
     * Rollback per-thread transaction. It is safe to use this method only for exclusive transactions.
     * In case of cooperative transactions, this method rollback results of all transactions.
     */
    public void rollbackThreadTransaction();

    /**
     * Create JSQL query. JSQL is object oriented subset of SQL allowing
     * to specify arbitrary prdicates for selecting members of Perst collections
     * @return created query object
     */     
    public <T> Query<T> createQuery();

    /**
     * Create new peristent list. Implementation of this list is based on B-Tree so it can efficiently
     * handle large number of objects but in case of very small list memory overhead is too high.
     * @return persistent object implementing list
     */
    public <T extends IPersistent> IPersistentList<T> createList();

    /**
     * Create new scalable list of persistent objects.
     * This container can effciently handle small lists as well as large lists
     * When number of memers is small, Link class is used to store set members. 
     * When number of members exceeds some threshold, PersistentList (based on B-Tree)
     * is used instead.
     * @return scalable set implementation
     */
    public <T extends IPersistent> IPersistentList<T> createScalableList();

    /**
     * Create new scalable list of persistent objects.
     * This container can effciently handle small lists as well as large lists
     * When number of memers is small, Link class is used to store set members. 
     * When number of members exceeds some threshold, PersistentList (based on B-Tree)
     * is used instead.
     * @param initialSize initial allocated size of the list
     * @return scalable set implementation
     */
    public <T extends IPersistent> IPersistentList<T> createScalableList(int initialSize);

    /**
     * Create scalable persistent map.
     * This container can effciently handle both small and large number of members.
     * For small maps, implementation  uses sorted array. For large maps - B-Tree.
     * @param keyType map key type
     * @return scalable set implementation
     */
    public <K extends Comparable, V extends IPersistent> IPersistentMap<K,V> createMap(Class keyType);

    /**
     * Create scalable persistent map.
     * This container can effciently handle both small and large number of members.
     * For small maps, implementation  uses sorted array. For large maps - B-Tree.
     * @param keyType map key type
     * @param initialSize initial allocated size of the list
     * @return scalable set implementation
     */
    public <K extends Comparable, V extends IPersistent> IPersistentMap<K,V> createMap(Class keyType, int initialSize);

    /**
     * Create new peristent set. Implementation of this set is based on B-Tree so it can efficiently
     * handle large number of objects but in case of very small set memory overhead is too high.
     * @return persistent object implementing set
     */
    public <T extends IPersistent> IPersistentSet<T> createSet();

    /**
     * Create new scalable set references to persistent objects.
     * This container can effciently store small number of references as well as very large
     * number references. When number of memers is small, Link class is used to store 
     * set members. When number of members exceeds some threshold, PersistentSet (based on B-Tree)
     * is used instead.
     * @return scalable set implementation
     */
    public <T extends IPersistent> IPersistentSet<T> createScalableSet();

    /**
     * Create new scalable set references to persistent objects.
     * This container can effciently store small number of references as well as very large
     * number references. When number of memers is small, Link class is used to store 
     * set members. When number of members exceeds some threshold, PersistentSet (based on B-Tree)
     * is used instead.
     * @param initialSize initial size of the set
     * @return scalable set implementation
     */