storage.java

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

     * <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.gc.threshold</code></TD><TD>Long</TD><TD>Long.MAX_VALUE</TD>
     * <TD>Threshold for initiation of garbage collection. 
     * 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.
     * </TD></TR>
     * <TR><TD><code>perst.lock.file</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>Lock database file to prevent concurrent access to the database by 
     * more than one application.
     * </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.background.gc</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>Perform garbage collection in separate thread without blocking the main application.
     * </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 will cause database crash.
     * </TD></TR>
     * <TR><TD><code>perst.replication.ack</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>Request acknowledgement from slave that it receives all data before transaction
     * commit. If this option is not set, then replication master node just writes
     * data to the socket not warring whether it reaches slave node or not.
     * When this option is set to true, master not will wait during each transaction commit acknowledgement
     * from slave node. Please notice that this option should be either set or not set both
     * at slave and master node. If it is set only on one of this nodes then behavior of
     * the system is unpredicted. This option can be used both in synchronous and asynchronous replication
     * mode. The only difference is that in first case main application thread will be blocked waiting
     * for acknowledgment, while in the asynchronous mode special replication thread will be blocked
     * allowing thread performing commit to proceed.
     * </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.slave.connection.timeout</code></TD><TD>Integer</TD><TD>60</TD>
     * <TD>Timeout in seconds during which mastr node will try to establish connection with slave node. 
     * If connection can not be established within specified time, then master will not perform 
     * replication to this slave node
     * </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>
     * <TR><TD><code>perst.page.pool.lru.limit</code></TD><TD>Long</TD><TD>1L << 60</TD>
     * <TD>Set boundary for caching database pages in page pool. 
     * By default Perst is using LRU algorithm for finding candidate for replacement.
     * But for example for BLOBs this strategy is not optimal and fetching BLOB can
     * cause flushing the whole page pool if LRU discipline is used. And with high
     * probability fetched BLOB pages will no be used any more. So it is preferable not
     * to cache BLOB pages at all (throw away such page immediately when it is not used any more).
     * This parameter in conjunction with custom allocator allows to disable caching
     * for BLOB objects. If you set value of "perst.page.lru.scope" property equal
     * to base address of custom allocator (which will be used to allocate BLOBs), 
     * then page containing objects allocated by this allocator will not be cached in page pool.
     * </TD></TR>
     * <TR><TD><code>perst.multiclient.support</code></TD><TD>Boolean</TD><TD>false</TD>
     * <TD>Supports access to the same database file by multiple applications.
     * In this case Perst will use file locking to synchronize access to the database file.
     * An application MUST wrap any access to the database with  beginThreadThreansaction/endThreadTransaction 
     * methods. For read only access use READ_ONLY_TRANSACTION mode and if transaction may modify database then
     * READ_WRITE_TRANSACTION mode should be used.
     * </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(java.util.Properties 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 java.util.Properties 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 database memory dump. This function returns hashmap which key is classes
     * of stored objects and value - MemoryUsage object which specifies number of instances
     * of particular class in the storage and total size of memory used by these instance.
     * Size of internal database structures (object index,* memory allocation bitmap) is associated with 
     * <code>Storage</code> class. Size of class descriptors  - with <code>java.lang.Class</code> class.
     * <p>This method traverse the storage as garbage collection do - starting from the root object
     * and recursively visiting all reachable objects. So it reports statistic only for visible objects.
     * If total database size is significantly larger than total size of all instances reported
     * by this method, it means that there is garbage in the database. You can explicitly invoke
     * garbage collector in this case.</p> 
     */
    public java.util.HashMap<Class,MemoryUsage> getMemoryDump();
    
    /**
     * Get total size of all allocated objects in the database
     */
    public long getUsedSize();

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

 
    /**
     * Set class loader. This class loader will be used to locate classes for 
     * loaded class descriptors. If class loader is not specified or
     * it did find the class, then <code>Class.forName()</code> method
     * will be used to get class for the specified name.
     * @param loader class loader
     * @return previous class loader or null if not specified
     */
    public ClassLoader setClassLoader(ClassLoader loader);

    /**
     * Get class loader used to locate classes for 
     * loaded class descriptors.
     * @return class loader previously set by <code>setClassLoader</code>
     * method or <code>null</code> if not specified. 
     */
    public ClassLoader getClassLoader();

    /**
     * Register named class loader in the storage. Mechanism of named class loaders
     * allows to store in database association between class and its class loader.
     * All named class loaders should be registered before database open.
     * @param loader registered named class loader
     */
    public void registerClassLoader(INamedClassLoader loader);

    /**
     * Find registered class loaders by name
     * @param name class loader name
     * @return class loader with such name or numm if no class loader is found
     */
    public ClassLoader findClassLoader(String name);

    /**
     * Register custom allocator for specified class. Instances of this and derived classes 
     * will be allocated in the storage using specified allocator. 
     * @param cls class of the persistent object which instances will be allocated using this allocator
     * @param allocator custom allocator
     */
    public void registerCustomAllocator(Class cls, CustomAllocator allocator);

    /**
     * Create bitmap custom allocator
     * @param quantum size in bytes of allocation quantum. Should be power of two.
     * @param base base address for allocator (it should match offset of multifile segment)
     * @param extension size by which space mapped by allocator is extended each time when 
     * no suitable hole is found in bitmap (it should be large enough to improve allocation speed and locality 
     * of references)
     * @param limit maximal size of memory allocated by this allocator (pass Long.MAX_VALUE if you do not 
     * want to limit space)
     * @return created allocator
     */
    public CustomAllocator createBitmapAllocator(int quantum, long base, long extension, long limit);

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

    /**
     * Set custom serializer used fot packing/unpacking fields of persistent objects which types implemplemet 
     * CustomSerializable interface
     */
    public void setCustomSerializer(CustomSerializer serializer);

    /**
     * Clear database object cache. This method can be used with "strong" object cache to avoid memory overflow.
     * It is no valid to invoke this method when there are some uncommitted changes in the database
     * (some modified objects). Also all variables containing references to persistent object should be reset after
     * invocation of this method - it is not correct to accessed object directly though such variables, objects
     * has to be reloaded from the storage
     */
    public void clearObjectCache();


    // Internal methods

    public void deallocateObject(IPersistent obj);

    public void storeObject(IPersistent obj);

    public void storeFinalizedObject(IPersistent obj);

    public void modifyObject(IPersistent obj);

    public void loadObject(IPersistent obj);

    public boolean lockObject(IPersistent obj);

    public void throwObject(IPersistent obj);
}