storage.cs

Perst开源实时数据库

namespace Perst
{
    using System;
    using System.Collections;
#if USE_GENERICS
    using System.Collections.Generic;
#endif

    public enum TransactionMode
    { 
        /// <summary>
        /// Exclusive per-thread transaction: each thread access database in exclusive mode
        /// </summary>
        Exclusive,
        /// <summary>
        /// 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. 
        /// </summary>
        Cooperative,
        /// <summary>
        /// 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.
        /// </summary>
        Serializable,
        /// <summary>
        /// Read only transaction which can be started at replicastion slave node.
        /// It runs concurrently with receiving updates from master node.
        /// </summary>
        ReplicationSlave
    };
	
	
    /// <summary> Object storage
    /// </summary>
    public interface Storage
    {
        /// <summary> Get/set 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.
        /// Previous reference to the root object is rewritten but old root is not automatically deallocated.
        /// </summary>
        IPersistent Root {get; set;}
      
        /// <summary> Open the storage
        /// </summary>
        /// <param name="filePath">path to the database file
        /// </param>
        /// <param name="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). If value of pagePoolSize is 0, then page pool will be
        /// unlimited - dynamically extended to conatins all database file pages.
        /// </param>
        void  Open(String filePath, int pagePoolSize);
		
        /// <summary> Open the storage with default page pool size
        /// </summary>
        /// <param name="filePath">path to the database file
        /// 
        /// </param>
        void  Open(String filePath);
		
        /// <summary> Open the storage
        /// </summary>
        /// <param name="file">user specific implementation of IFile interface
        /// </param>
        /// <param name="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>
        void  Open(IFile file, int pagePoolSize);
		
        /// <summary> Open the storage with default page pool size
        /// </summary>
        /// <param name="file">user specific implementation of IFile interface
        /// </param>
        void  Open(IFile file);

        /// <summary> Open the encrypted storage
        /// </summary>
        /// <param name="filePath">path to the database file
        /// </param>
        /// <param name="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>
        /// <param name="cipherKey">cipher key</param>
        void  Open(String filePath, int pagePoolSize, String cipherKey);

        
        /// <summary>Check if database is opened
        /// </summary>
        /// <returns><code>true</code> if database was opened by <code>open</code> method, 
        /// <code>false</code> otherwise
        /// </returns>        
        bool IsOpened();
		
        /// <summary> Commit changes done by the last transaction. Transaction is started implcitlely with forst update
        /// opertation.
        /// </summary>
        void  Commit();
		
        /// <summary> Rollback changes made by the last transaction
        /// </summary>
        void  Rollback();
		
        /// <summary>
        /// Backup current state of database
        /// </summary>
        /// <param name="stream">output stream to which backup is done</param>
        void Backup( System.IO.Stream stream);

        /// <summary> Create JSQL query. JSQL is object oriented subset of SQL allowing
        /// to specify arbitrary prdicates for selecting members of Perst collections
        /// </summary>
        /// <returns> created query object
        /// </returns>
#if USE_GENERICS
        Query<T> CreateQuery<T>();
#else
        Query CreateQuery();
#endif
        
#if USE_GENERICS
        /// <summary> Create new index. K parameter specifies key type, V - associated object type.
        /// </summary>
        /// <param name="unique">whether index is unique (duplicate value of keys are not allowed)
        /// </param>
        /// <returns>persistent object implementing index
        /// </returns>
        /// <exception cref="Perst.StorageError">StorageError(StorageError.ErrorCode.UNSUPPORTED_INDEX_TYPE) exception if 
        /// specified key type is not supported by implementation.
        /// </exception>
        Index<K,V> CreateIndex<K,V>(bool unique) where V:class,IPersistent;
#else
        /// <summary> Create new index
        /// </summary>
        /// <param name="type">type of the index key (you should path here <code>String.class</code>, 
        /// <code>int.class</code>, ...)
        /// </param>
        /// <param name="unique">whether index is unique (duplicate value of keys are not allowed)
        /// </param>
        /// <returns>persistent object implementing index
        /// </returns>
        /// <exception cref="Perst.StorageError">StorageError(StorageError.ErrorCode.UNSUPPORTED_INDEX_TYPE) exception if 
        /// specified key type is not supported by implementation.
        /// 
        /// </exception>
        Index CreateIndex(Type type, bool unique);
#endif
		
        /// <summary> Create new compound index.
        /// </summary>
        /// <param name="types">types of components of compund key
        /// </param>
        /// <param name="unique">whether index is unique (duplicate value of keys are not allowed)
        /// </param>
        /// <returns>persistent object implementing index
        /// </returns>
        /// <exception cref="Perst.StorageError">StorageError(StorageError.ErrorCode.UNSUPPORTED_INDEX_TYPE) exception if 
        /// specified key type is not supported by implementation.
        /// </exception>
#if USE_GENERICS
        CompoundIndex<V> CreateIndex<V>(Type[] types, bool unique) where V:class,IPersistent;
#else
        CompoundIndex    CreateIndex(Type[] types, bool unique);
#endif
		
#if USE_GENERICS
        /// <summary> Create new thick index (index with large number of duplicated keys).
        /// K parameter specifies key type, V - associated object type.
        /// </summary>
        /// <returns>persistent object implementing thick index
        /// </returns>
        /// <exception cref="Perst.StorageError">StorageError(StorageError.ErrorCode.UNSUPPORTED_INDEX_TYPE) exception if 
        /// specified key type is not supported by implementation.
        /// 
        /// </exception>
        Index<K,V> CreateThickIndex<K,V>() where V:class,IPersistent;
#else
        /// <summary> Create new thick index (index with large number of duplicated keys)
        /// </summary>
        /// <param name="type">type of the index key (you should path here <code>String.class</code>, 
        /// <code>int.class</code>, ...)
        /// </param>
        /// <returns>persistent object implementing thick index
        /// </returns>
        /// <exception cref="Perst.StorageError">StorageError(StorageError.ErrorCode.UNSUPPORTED_INDEX_TYPE) exception if 
        /// specified key type is not supported by implementation.
        /// 
        /// </exception>
        Index CreateThickIndex(Type type);
#endif
	
#if USE_GENERICS
        /// <summary> 
        /// Create new field index
        /// K parameter specifies key type, V - associated object type.
        /// </summary>
        /// <param name="fieldName">name of the index field. Field with such name should be present in specified class <code>type</code>
        /// </param>
        /// <param name="unique">whether index is unique (duplicate value of keys are not allowed)
        /// </param>
        /// <returns>persistent object implementing field index
        /// </returns>
        /// <exception cref="Perst.StorageError">StorageError(StorageError.INDEXED_FIELD_NOT_FOUND) if there is no such field in specified class,
        /// StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if type of specified field is not supported by implementation
        /// </exception>
        FieldIndex<K,V> CreateFieldIndex<K,V>(string fieldName, bool unique) where V:class,IPersistent;
#else
        /// <summary> 
        /// Create new field index
        /// </summary>
        /// <param name="type">objects of which type (or derived from which type) will be included in the index
        /// </param>
        /// <param name="fieldName">name of the index field. Field with such name should be present in specified class <code>type</code>
        /// </param>
        /// <param name="unique">whether index is unique (duplicate value of keys are not allowed)
        /// </param>
        /// <returns>persistent object implementing field index
        /// </returns>
        /// <exception cref="Perst.StorageError">StorageError(StorageError.INDEXED_FIELD_NOT_FOUND) if there is no such field in specified class,
        /// StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if type of specified field is not supported by implementation
        /// </exception>
        FieldIndex CreateFieldIndex(Type type, string fieldName, bool unique);
#endif