storage.java

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

package org.garret.perst;

import java.util.*;
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 = 64*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;

    /** 
     * 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>, 
     * or <code>SERIALIZABLE_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 new peristent set
     * @return persistent object implementing set
     */
    public IPersistentSet createSet();

    /**
     * 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 IPersistentList createList();

    /**
     * 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 exceed some threshold, PersistentSet (based on B-Tree)
     * is used instead.
     * @return scalable set implementation
     */
    public IPersistentSet 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 exceed some threshold, PersistentSet (based on B-Tree)
     * is used instead.
     * @param initialSize initial size of the set
     * @return scalable set implementation
     */
    public IPersistentSet createScalableSet(int initialSize);

    /**
     * Create new index
     * @param type type of the index key (org.garret.perst.Types enumeration)
     * @param unique whether index is unique (duplicate value of keys are not allowed)
     * @return persistent object implementing index
     * @exception StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if 
     * specified key type is not supported by implementation.
     */
    public Index createIndex(int type, boolean unique);

    /**
     * Create new compound index
     * @param types types of the index compound key components  (org.garret.perst.Types enumeration)
     * @param unique whether index is unique (duplicate value of keys are not allowed)
     * @return persistent object implementing compound index
     * @exception StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if 
     * specified key type is not supported by implementation.
     */
    public Index createIndex(int[] types, boolean unique);

    /**
     * Create new thick index (index with large number of duplicated keys)
     * @param type type of the index key (org.garret.perst.Types enumeration)
     * @return persistent object implementing index
     * @exception StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if 
     * specified key type is not supported by implementation.
     */
    public Index createThickIndex(int type);

    /**
     * Create new bit index. Bit index is used to select object 
     * with specified set of (boolean) properties.
     * @return persistent object implementing bit index
     */
    public BitIndex createBitIndex();

    /**
     * Create new index optimized for access by element position.
     * @param type type of the index key (org.garret.perst.Types enumeration)
     * @param unique whether index is unique (duplicate value of keys are not allowed)
     * @return persistent object implementing index
     * @exception StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if 
     * specified key type is not supported by implementation.
     */
    public Index createRandomAccessIndex(int type, boolean unique);

    /**
     * Create new spatial index with integer coordinates
     * @return persistent object implementing spatial index
     */
    public SpatialIndex createSpatialIndex();