storage.java

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

    /**
     * Create new R2 spatial index 
     * @return persistent object implementing spatial index
     */
    public SpatialIndexR2 createSpatialIndexR2();

    /**
     * Create new sorted collection with specified comparator
     * @param comparator comparator class specifying order in the collection
     * @param unique whether index is collection (members with the same key value are not allowed)
     * @return persistent object implementing sorted collection
     */
    public SortedCollection createSortedCollection(PersistentComparator comparator, boolean unique);

    /**
     * Create new sorted collection. Members of this collections should implement 
     * <code>java.lang.Comparable</code> interface and make it possible to compare collection members
     * with each other as well as with serch key.
     * @param unique whether index is collection (members with the same key value are not allowed)
     * @return persistent object implementing sorted collection
     */
    public SortedCollection createSortedCollection(boolean unique);

    /**
     * Create one-to-many link.
     * @return new empty link, new members can be added to the link later.
     */
    public Link createLink();
    
    /**
     * Create one-to-many link with specified initially allocated size.
     * @param initialSize initial size of array
     * @return new empty link, new members can be added to the link later.
     */
    public Link createLink(int initialSize);
    
    /**
     * Create relation object. Unlike link which represent embedded relation and stored
     * inside owner object, this Relation object is standalone persisitent object
     * containing references to owner and members of the relation
     * @param owner owner of the relation
     * @return object representing empty relation (relation with specified owner and no members), 
     * new members can be added to the link later.
     */
    public Relation createRelation(IPersistent owner);


    /**
     * Create new BLOB. Create object for storing large binary data.
     * @return empty BLOB
     */
    public Blob createBlob();

    /**
     * Create new time series object. 
     * @param blockClass class derived from TimeSeries.Block
     * @param maxBlockTimeInterval maximal difference in milliseconds between timestamps 
     * of the first and the last elements in a block. 
     * If value of this parameter is too small, then most blocks will contains less elements 
     * than preallocated. 
     * If it is too large, then searching of block will be inefficient, because index search 
     * will select a lot of extra blocks which do not contain any element from the 
     * specified range.
     * Usually the value of this parameter should be set as
     * (number of elements in block)*(tick interval)*2. 
     * Coefficient 2 here is used to compencate possible holes in time series.
     * For example, if we collect stocks data, we will have data only for working hours.
     * If number of element in block is 100, time series period is 1 day, then
     * value of maxBlockTimeInterval can be set as 100*(24*60*60*1000)*2
     * @return new empty time series
     */
    public TimeSeries createTimeSeries(String blockClass, long maxBlockTimeInterval);


    /**
     * Create PATRICIA trie (Practical Algorithm To Retrieve Information Coded In Alphanumeric)
     * Tries are a kind of tree where each node holds a common part of one or more keys. 
     * PATRICIA trie is one of the many existing variants of the trie, which adds path compression 
     * by grouping common sequences of nodes together.<BR>
     * This structure provides a very efficient way of storing values while maintaining the lookup time 
     * for a key in O(N) in the worst case, where N is the length of the longest key. 
     * This structure has it's main use in IP routing software, but can provide an interesting alternative 
     * to other structures such as hashtables when memory space is of concern.
     * @return created PATRICIA trie
     */
    public PatriciaTrie createPatriciaTrie();

    /**
     * Commit transaction (if needed) and close the storage
     */
    public void close();

    /**
     * Retrieve object by OID. This method should be used with care because
     * if object is deallocated, its OID can be reused. In this case
     * getObjectByOID will return reference to the new object with may be
     * different type.
     * @param oid object oid
     * @return reference to the object with specified OID
     */
    public IPersistent getObjectByOID(int oid);

    /**
     * Explicitely make object peristent. Usually objects are made persistent
     * implicitlely using "persistency on reachability apporach", but this
     * method allows to do it explicitly. If object is already persistent, execution of
     * this method has no effect.
     * @param obj object to be made persistent
     * @return OID assigned to the object  
     */
    public int makePersistent(IPersistent obj);

 
    /**
     * Set database property. This method should be invoked before opening database. 
     * Currently the following boolean properties are supported:
     * <TABLE><TR><TH>Property name</TH><TH>Parameter type</TH><TH>Default value</TH><TH>Description</TH></TR>
     * <TR><TD><code>perst.object.cache.init.size</code></TD><TD>Integer</TD><TD>1319</TD>
     * <TD>Initial size of object cache
     * </TD></TR>
     * <TR><TD><code>perst.object.cache.pin.count</code></TD><TD>Integer</TD><TD>0</TD>
     * <TD>Number of objects pinned in object cache after cache clear
     * </TD></TR>
     * <TR><TD><code>perst.object.index.init.size</code></TD><TD>Integer</TD><TD>1024</TD>
     * <TD>Initial size of object index (specifying large value increase initial size of database, but reduce
     * number of index reallocations)
     * </TD></TR>
     * <TR><TD><code>perst.extension.quantum</code></TD><TD>Long</TD><TD>1048576</TD>
     * <TD>Object allocation bitmap extension quantum. Memory is allocate by scanning bitmap. If there is no
     * large enough hole, then database is extended by the value of dbDefaultExtensionQuantum. 
     * This parameter should not be smaller than 64Kb.
     * </TD></TR>
     * <TR><TD><code>perst.file.readonly</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>Database file should be opened in read-only mode.
     * </TD></TR>
     * <TR><TD><code>perst.file.noflush</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>Do not flush file during transaction commit. It will greatly increase performance because
     * eliminate synchronous write to the disk (when program has to wait until all changed
     * are actually written to the disk). But it can cause database corruption in case of 
     * OS or power failure (but abnormal termination of application itself should not cause
     * the problem, because all data which were written to the file, but is not yet saved to the disk is 
     * stored in OS file buffers and sooner or later them will be written to the disk)
     * </TD></TR>
     * <TR><TD><code>perst.alternative.btree</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>Use aternative implementation of B-Tree (not using direct access to database
     * file pages). This implementation should be used in case of serialized per thread transctions.
     * New implementation of B-Tree will be used instead of old implementation
     * if "perst.alternative.btree" property is set. New B-Tree has incompatible format with 
     * old B-Tree, so you could not use old database or XML export file with new indices. 
     * Alternative B-Tree is needed to provide serializable transaction (old one could not be used).
     * Also it provides better performance (about 3 times comaring with old implementation) because
     * of object caching. And B-Tree supports keys of user defined types. 
     * </TD></TR>
     * <TR><TD><code>perst.string.encoding</code></TD><TD>String</TD><TD>null</TD>
     * <TD>Specifies encoding of storing strings in the database. By default Perst stores 
     * strings as sequence of chars (two bytes per char). If all strings in application are in 
     * the same language, then using encoding  can signifficantly reduce space needed
     * to store string (about two times). But please notice, that this option has influence
     * on all strings  stored in database. So if you already have some data in the storage
     * and then change encoding, then it can cause incorrect fetching of strings and even database crash.
     * </TD></TR>
     * <TR><TD><code>perst.concurrent.iterator</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>By default iterator will throw ConcurrentModificationException if iterated collection
     * was changed outside iterator, when the value of this property is true then iterator will 
     * try to restore current position and continue iteration
     * </TD></TR>
     * <TR><TD><code>perst.force.store</code></TD><TD>Boolean</TD><TD>true</TD>
     * <TD>When the value of this parameter is true Storage.makePersistent method
     * cause immediate storing of object in the storage, otherwise object is assigned OID and is marked 
     * as modified. Storage.makePersistent method is mostly used when object is inserted in B-Tree.
     * If application put in index object referencing a large number of other objects which also has to 
     * be made persistent, then marking object as modified instead of immediate storing may cause
     * memory overflow because garbage collector and finalization threads will store objects
     * with less speed than application creates new ones.
     * But if object will be updated after been placed in B-Tree, then immediate store will just cause
     * cause extra overhead, because object has to be stored twice. 
     * </TD></TR>
     * </TABLE>
     * @param name name of the property
     * @param value value of the property (for boolean properties pass <code>java.lang.Boolean.TRUE</code>
     * and <code>java.lang.Boolean.FALSE</code>
     */
    public void setProperty(String name, Object value);

   /**
     * Set database properties. This method should be invoked before opening database. 
     * For list of supported properties please see <code>setProperty</code> command. 
     * All not recognized properties are ignored.
     */
    public void setProperties(Hashtable props);

    /**
     * Get property value.
     * @param name property name
     * @return value of the property previously assigned by setProperty or setProperties method
     * or <code>null</code> if property was not set
     */
    public Object getProperty(String name);

    /**
     * Get all set properties
     * @return all properties set by setProperty or setProperties method
     */
    public Hashtable getProperties();
    
    /**
     * Merge results of several index searches. This method efficiently merge selections without loading objects themselve
     * @param selections selections to be merged
     * @return Iterator through merged result
     */
    public Iterator merge(Iterator[] selections);

    
    /**
     * Join results of several index searches. This method efficiently join selections without loading objects themselve
     * @param selections selections to be merged
     * @return Iterator through joineded result
     */
    public Iterator join(Iterator[] selections);
 
    /**
     * Set storage listener.
     * @param listener new storage listener (may be null)
     * @return previous storage listener
     */
    public StorageListener setListener(StorageListener listener);

    /**
     * Get total size of all allocated objects in the database
     */
    public long getUsedSize();

    /**
     * Get size of the database
     */
    public long getDatabaseSize();

    /**
     * This method is used internally by Perst to get transaction context associated with current thread.
     * But it can be also used by application to get transaction context, store it in some variable and
     * use in another thread. I will make it possible to share one transaction between multiple threads.
     * @return transaction context associated with current thread
     */     
    public ThreadTransactionContext getTransactionContext();

    /**
     * Associate transaction context with the thread
     * This method can be used by application to share the same transaction between multiple threads
     * @param ctx new transaction context 
     * @return transaction context previously associated with this thread
     */     
    public ThreadTransactionContext setTransactionContext(ThreadTransactionContext ctx);

    /**
     * Get storage version
     * @return storage version ID previosly assigned by setVersion. If it was not assigned, then
     * 0 is returned.
     */
    public int getVersion();

    /**
     * Set storage version. It case be used to handle database schema evolution.
     * @param version new storage version ID. 
     */
    public void setVersion(int version);


    // Internal methods (I have to made them public to be used by AspectJ API)

    public void deallocateObject(IPersistent obj);

    public void storeObject(IPersistent obj);

    public void modifyObject(IPersistent obj);

    public void loadObject(IPersistent obj);

    public boolean lockObject(IPersistent obj);

    public void throwObject(IPersistent obj);
}