storage.java

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

    public <T extends IPersistent> IPersistentSet<T> createScalableSet(int initialSize);

    /**
     * Create new index
     * @param type type of the index key (you should path here <code>String.class</code>, 
     * <code>int.class</code>, ...)
     * @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 <T extends IPersistent> Index<T> createIndex(Class type, boolean unique);

    /**
     * Create new compound index
     * @param types types of the index compound key components 
     * @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 <T extends IPersistent> Index<T> createIndex(Class[] types, boolean unique);

    /**
     * Create new think index (index with large number of duplicated keys)
     * @param type type of the index key (you should path here <code>String.class</code>, 
     * <code>int.class</code>, ...)
     * @return persistent object implementing index
     * @exception StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if 
     * specified key type is not supported by implementation.
     */
    public <T extends IPersistent> Index<T> createThickIndex(Class 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 <T extends IPersistent> BitIndex<T> createBitIndex();

    /**
     * Create new field index
     * @param type objects of which type (or derived from which type) will be included in the index
     * @param fieldName name of the index field. Field with such name should be present in specified class <code>type</code>
     * @param unique whether index is unique (duplicate value of keys are not allowed)
     * @return persistent object implementing field index
     * @exception StorageError(StorageError.INDEXED_FIELD_NOT_FOUND) if there is no such field in specified class,<BR> 
     * StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if type of specified field is not supported by implementation
     */
    public <T extends IPersistent> FieldIndex<T> createFieldIndex(Class type, String fieldName, boolean unique);
    /**
     * Create new mutlifield index
     * @param type objects of which type (or derived from which type) will be included in the index
     * @param fieldNames names of the index fields. Fields with such name should be present in specified class <code>type</code>
     * @param unique whether index is unique (duplicate value of keys are not allowed)
     * @return persistent object implementing field index
     * @exception StorageError(StorageError.INDEXED_FIELD_NOT_FOUND) if there is no such field in specified class,<BR> 
     * StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if type of specified field is not supported by implementation
     */
    public <T extends IPersistent> FieldIndex<T> createFieldIndex(Class type, String[] fieldNames, boolean unique);

    /**
     * Create new index optimized for access by element position.
     * @param type type of the index key (you should path here <code>String.class</code>, 
     * <code>int.class</code>, ...)
     * @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 <T extends IPersistent> Index<T> createRandomAccessIndex(Class type, boolean unique);

    /**
     * Create new compound index optimized for access by element position.
     * @param types types of the index compound key components 
     * @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 <T extends IPersistent> Index<T> createRandomAccessIndex(Class[] types, boolean unique);

    /**
     * Create new field index optimized for access by element position.
     * @param type objects of which type (or derived from which type) will be included in the index
     * @param fieldName name of the index field. Field with such name should be present in specified class <code>type</code>
     * @param unique whether index is unique (duplicate value of keys are not allowed)
     * @return persistent object implementing field index
     * @exception StorageError(StorageError.INDEXED_FIELD_NOT_FOUND) if there is no such field in specified class,<BR> 
     * StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if type of specified field is not supported by implementation
     */
    public <T extends IPersistent> FieldIndex<T> createRandomAccessFieldIndex(Class type, String fieldName, boolean unique);
    /**
     * Create new mutlifield index optimized for access by element position.
     * @param type objects of which type (or derived from which type) will be included in the index
     * @param fieldNames names of the index fields. Fields with such name should be present in specified class <code>type</code>
     * @param unique whether index is unique (duplicate value of keys are not allowed)
     * @return persistent object implementing field index
     * @exception StorageError(StorageError.INDEXED_FIELD_NOT_FOUND) if there is no such field in specified class,<BR> 
     * StorageError(StorageError.UNSUPPORTED_INDEX_TYPE) exception if type of specified field is not supported by implementation
     */
    public <T extends IPersistent> FieldIndex<T> createRandomAccessFieldIndex(Class type, String[] fieldNames, boolean unique);
     /**
     * Create new spatial index with integer coordinates
     * @return persistent object implementing spatial index
     */
    public <T extends IPersistent> SpatialIndex<T> createSpatialIndex();

    /**
     * Create new R2 spatial index 
     * @return persistent object implementing spatial index
     */
    public<T extends IPersistent>  SpatialIndexR2<T> createSpatialIndexR2();

    /**
     * Create new sorted collection
     * @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 <T extends IPersistent> SortedCollection<T> createSortedCollection(PersistentComparator<T> comparator, boolean unique);

    /**
     * Create one-to-many link.
     * @return new empty link, new members can be added to the link later.
     */
    public <T extends IPersistent> Link<T> createLink();
    
    /**
     * Create one-to-many link with specified initialy alloced size.
     * @param initialSize initial size of array
     * @return new empty link, new members can be added to the link later.
     */
    public <T extends IPersistent> Link<T> 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 <M extends IPersistent, O extends IPersistent> Relation<M,O> createRelation(O 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 <T extends TimeSeries.Tick> TimeSeries<T> createTimeSeries(Class 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 <T extends IPersistent> PatriciaTrie<T> createPatriciaTrie();

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

    /**
     * Set threshold for initiation of garbage collection. By default garbage collection is disable (threshold is set to
     * Long.MAX_VALUE). If it is set to the value different from Long.MAX_VALUE, GC will be started each time when
     * delta between total size of allocated and deallocated objects exceeds specified threashold OR
     * after reaching end of allocation bitmap in allocator. 
     * @param allocatedDelta delta between total size of allocated and deallocated object since last GC 
     * or storage opening 
     */
    public void setGcThreshold(long allocatedDelta);

    /**
     * Explicit start of garbage collector
     * @return number of collected (deallocated) objects
     */
    public int gc();

    /**
     * Export database in XML format 
     * @param writer writer for generated XML document
     */
    public void exportXML(java.io.Writer writer) throws java.io.IOException;

    /**
     * Import data from XML file
     * @param reader XML document reader
     */
    public void importXML(java.io.Reader reader) throws XMLImportException;

    /**
     * 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.implicit.values</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>Treate any class not derived from IPersistent as <i>value</i>. 
     * This object will be embedded inside persistent object containing reference to this object.
     * If this object is referenced from N persistent object, N instances of this object
     * will be stored in the database and after loading there will be N instances in memory. 
     * As well as persistent capable classes, value classes should have default constructor (constructor
     * with empty list of parameters) or has no constructors at all. For example <code>Integer</code>
     * class can not be stored as value in PERST because it has no such constructor. In this case 
     * serialization mechanism can be used (see below)
     * </TD></TR>
     * <TR><TD><code>perst.serialize.transient.objects</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>Serialize any class not derived from IPersistent or IValue using standard Java serialization
     * mechanism. Packed object closure is stored in database as byte array. Latter the same mechanism is used
     * to unpack the objects. To be able to use this mechanism object and all objects referenced from it
     * should implement <code>java.io.Serializable</code> interface and should not contain references
     * to persistent objects. If such object is referenced from N persistent object, N instances of this object
     * will be stored in the database and after loading there will be N instances in memory.
     * </TD></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.kind</code></TD><TD>String</TD><TD>"lru"</TD>
     * <TD>Kind of object cache. The following values are supported:
     * "strong", "weak", "soft",  "pinned", "lru". <B>Strong</B> cache uses strong (normal) 
     * references to refer persistent objects. Thus none of loaded persistent objects
     * can be deallocated by GC. <B>Weak</B> cache use weak references and
     * soft cache - <B>soft</B> references. The main difference between soft and weak references is
     * that garbage collector is not required to remove soft referenced objects immediately
     * when object is detected to be <i>soft referenced</i>, so it may improve caching of objects. 
     * But it also may increase amount of memory
     * used  by application, and as far as persistent object requires finalization
     * it can cause memory overflow even though garbage collector is required
     * to clear all soft references before throwing OutOfMemoryException.<br>
     * But Java specification says nothing about the policy used by GC for soft references
     * (except the rule mentioned above). Unlike it <B>lru</B> cache provide determined behavior, 
     * pinning most recently used objects in memory. Number of pinned objects is determined 
     * for lru cache by <code>perst.object.index.init.size</code> parameter (it can be 0).<br>
     * Pinned object cache pin in memory all modified objects while using weak referenced for 
     * non-modified objects. This kind of cache eliminate need in finalization mechanism - all modified
     * objects are kept in memory and are flushed to the disk only at the end of transaction. 
     * So the size of transaction is limited by amount of main memory. Non-modified objects are accessed only 
     * through weak references so them are not protected from GC and can be thrown away.    
     * </TD></TR>