Rice Pastry API

rice.persistence
Class PersistentStorage

java.lang.Object
  extended by rice.persistence.PersistentStorage
All Implemented Interfaces:
Catalog, Storage

public class PersistentStorage
extends java.lang.Object
implements Storage

This class is an implementation of Storage which provides persistent storage to disk. This class also guarantees that the data will be consistent, even after a crash. This class also provides these services is a non-blocking fashion by launching a separate thread which is tasked with actually writing the data to disk. This class was initially designed to support only Ids whose toString() method returns a String of constant length. It has been extended to support variable-length toString()s, but we have the caveat that not toString() can be a substring of another toString() - this will cause undefined behavior. Additionally, the toString() method on the key Ids *CANNOT* have the period ('.') or exclamation point ('!') characters in them - these are used for internal purposes. The serialized objects are stored on-disk in a GZIPed XML format, which provides extensibility with reasonable storage and processing costs. Additionally, any metadata, if provided, is also stored in the on-disk file. The format of the file is [Key, Object, Version, Gzipped XML] [Metadata, Gzipped XML] [persistence magic number, long] [persistence version, long] [persistence revision, long] [metadata length, long] The persistence package is set up to automatically upgrade older versions of the on-disk format as new data is written under the key. Persistence also supports the metadata interface specified in the Catalog interface. All metadata is guaranteed to be stored in memory, so fetching the metadata of a given key is an efficient operation.


Field Summary
static java.lang.String BACKUP_DIRECTORY
          Static variables which define the location of the storage root
static java.lang.String LOST_AND_FOUND_DIRECTORY
           
static int MAX_DIRECTORIES
          The maximum number of subdirectories in a directory before splitting
static int MAX_FILES
          The splitting factor, or the number of files in one directory
static java.lang.String METADATA_FILENAME
           
static int METADATA_SYNC_TIME
          The amount of time before re-writing the metadata file
static long PERSISTENCE_MAGIC_NUMBER
          Static variables defining the layout of the on-disk storage
static long PERSISTENCE_REVISION_2_0
           
static long PERSISTENCE_REVISION_2_1
           
static long PERSISTENCE_VERSION_2
           
static java.lang.String ZERO_LENGTH_NAME
          Special placeholder for the file whose name should be zero-length
 
Constructor Summary
PersistentStorage(IdFactory factory, java.lang.String rootDir, long size, Environment env)
          Builds a PersistentStorage given a root directory in which to persist the data.
PersistentStorage(IdFactory factory, java.lang.String name, java.lang.String rootDir, long size, boolean index, Environment env)
          Builds a PersistentStorage given and an instance name and a root directory in which to persist the data.
PersistentStorage(IdFactory factory, java.lang.String name, java.lang.String rootDir, long size, Environment env)
          Builds a PersistentStorage given and an instance name and a root directory in which to persist the data.
 
Method Summary
 boolean exists(Id id)
          Returns whether or not an object is present in the location id.
 void flush(Continuation c)
          Method which is used to erase all data stored in the Catalog.
 java.io.Serializable getMetadata(Id id)
          Returns the metadata associated with the provided object, or null if no metadata exists.
 java.lang.String getName()
          Gets the name of this instance
 void getObject(Id id, Continuation c)
          Returns the object identified by the given id.
protected  IdRange getRangeForDirectory(java.io.File dir)
          Utility function which returns the range of keys which a directory corresponds to.
 java.lang.String getRoot()
          gets the root directory that the persistence Manager uses
 int getSize()
          Returns the number of Ids currently stored in the catalog
 long getStorageSize()
          gets the amount of storage that the persistence Manager uses
 long getTotalSize()
          Returns the total size of the stored data in bytes.The result is returned via the receiveResult method on the provided Continuation with an Integer representing the size.
 void rename(Id oldId, Id newId, Continuation c)
          Renames the given object to the new id.
 IdSet scan()
          Return the objects identified by the given range of ids.
 IdSet scan(IdRange range)
          Return the objects identified by the given range of ids.
 java.util.SortedMap scanMetadata()
          Returns a map which contains keys mapping ids to the associated metadata.
 java.util.SortedMap scanMetadata(IdRange range)
          Returns a map which contains keys mapping ids to the associated metadata.
 java.util.SortedMap scanMetadataValuesHead(java.lang.Object value)
          Returns the submapping of ids which have metadata less than the provided value.
 java.util.SortedMap scanMetadataValuesNull()
          Returns the submapping of ids which have metadata null
 void setMetadata(Id id, java.io.Serializable metadata, Continuation c)
          Updates the metadata stored under the given key to be the provided value.
 boolean setRoot(java.lang.String dir)
          Sets the root directory that the persistence Manager uses
 boolean setStorageSize(long size)
          Sets the amount of storage that the persistence Manager uses
 void setTimer(Timer timer)
          Method which allows the persistence root to schedule an event which will tell it to sync the metadata cached.
 void store(Id id, java.io.Serializable metadata, java.io.Serializable obj, Continuation c)
          Makes the object persistent to disk and stored permanantly If the object is already persistent, this method will simply update the object's serialized image.
 void unstore(Id id, Continuation c)
          Request to remove the object from the list of persistend objects.
protected  void writeDirty()
          Function which writes out all of the dirty metadata files and marks them as clean.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PERSISTENCE_MAGIC_NUMBER

public static final long PERSISTENCE_MAGIC_NUMBER
Static variables defining the layout of the on-disk storage

See Also:
Constant Field Values

PERSISTENCE_VERSION_2

public static final long PERSISTENCE_VERSION_2
See Also:
Constant Field Values

PERSISTENCE_REVISION_2_0

public static final long PERSISTENCE_REVISION_2_0
See Also:
Constant Field Values

PERSISTENCE_REVISION_2_1

public static final long PERSISTENCE_REVISION_2_1
See Also:
Constant Field Values

BACKUP_DIRECTORY

public static final java.lang.String BACKUP_DIRECTORY
Static variables which define the location of the storage root

See Also:
Constant Field Values

LOST_AND_FOUND_DIRECTORY

public static final java.lang.String LOST_AND_FOUND_DIRECTORY
See Also:
Constant Field Values

METADATA_FILENAME

public static final java.lang.String METADATA_FILENAME
See Also:
Constant Field Values

MAX_FILES

public static final int MAX_FILES
The splitting factor, or the number of files in one directory

See Also:
Constant Field Values

MAX_DIRECTORIES

public static final int MAX_DIRECTORIES
The maximum number of subdirectories in a directory before splitting

See Also:
Constant Field Values

METADATA_SYNC_TIME

public static final int METADATA_SYNC_TIME
The amount of time before re-writing the metadata file

See Also:
Constant Field Values

ZERO_LENGTH_NAME

public static final java.lang.String ZERO_LENGTH_NAME
Special placeholder for the file whose name should be zero-length

See Also:
Constant Field Values
Constructor Detail

PersistentStorage

public PersistentStorage(IdFactory factory,
                         java.lang.String rootDir,
                         long size,
                         Environment env)
                  throws java.io.IOException
Builds a PersistentStorage given a root directory in which to persist the data. Uses a default instance name.

Parameters:
factory - The factory to use for creating Ids.
rootDir - The root directory of the persisted disk.
size - the size of the storage in bytes, or -1 for unlimited
Throws:
java.io.IOException

PersistentStorage

public PersistentStorage(IdFactory factory,
                         java.lang.String name,
                         java.lang.String rootDir,
                         long size,
                         Environment env)
                  throws java.io.IOException
Builds a PersistentStorage given and an instance name and a root directory in which to persist the data.

Parameters:
factory - The factory to use for creating Ids.
name - the name of this instance
rootDir - The root directory of the persisted disk.
size - the size of the storage in bytes, or -1 for unlimited
Throws:
java.io.IOException

PersistentStorage

public PersistentStorage(IdFactory factory,
                         java.lang.String name,
                         java.lang.String rootDir,
                         long size,
                         boolean index,
                         Environment env)
                  throws java.io.IOException
Builds a PersistentStorage given and an instance name and a root directory in which to persist the data.

Parameters:
factory - The factory to use for creating Ids.
name - the name of this instance
rootDir - The root directory of the persisted disk.
size - the size of the storage in bytes, or -1 for unlimited
index - Whether or not to index the objects
Throws:
java.io.IOException
Method Detail

setTimer

public void setTimer(Timer timer)
Method which allows the persistence root to schedule an event which will tell it to sync the metadata cached. Should be called exactly once after the persistence root is created.

Parameters:
timer - The timer to use to schedule the events

rename

public void rename(Id oldId,
                   Id newId,
                   Continuation c)
Renames the given object to the new id. This method is potentially faster than store/cache and unstore/uncache.

Specified by:
rename in interface Catalog
Parameters:
oldId - The id of the object in question.
newId - The new id of the object in question.
c - The command to run once the operation is complete

store

public void store(Id id,
                  java.io.Serializable metadata,
                  java.io.Serializable obj,
                  Continuation c)
Makes the object persistent to disk and stored permanantly If the object is already persistent, this method will simply update the object's serialized image. This is implemented atomically so that this may succeed and store the new object, or fail and leave the previous object intact. This method completes by calling recieveResult() of the provided continuation with the success or failure of the operation.

Specified by:
store in interface Storage
Parameters:
obj - The object to be made persistent.
id - The object's id.
metadata - The object's metadata
c - The command to run once the operation is complete

unstore

public void unstore(Id id,
                    Continuation c)
Request to remove the object from the list of persistend objects. Delete the serialized image of the object from stable storage. If necessary. If the object was not in the cached list in the first place, nothing happens and false is returned. This method also guarantees that the data on disk will remain consistent, even after a crash by performing the delete atomically. This method completes by calling recieveResult() of the provided continuation with the success or failure of the operation.

Specified by:
unstore in interface Storage
Parameters:
id - The object's persistence id
c - The command to run once the operation is complete

exists

public boolean exists(Id id)
Returns whether or not an object is present in the location id.

Specified by:
exists in interface Catalog
Parameters:
id - The id of the object in question.
Returns:
Whether or not an object is present at id.

getMetadata

public java.io.Serializable getMetadata(Id id)
Returns the metadata associated with the provided object, or null if no metadata exists. The metadata must be stored in memory, so this operation is guaranteed to be fast and non-blocking.

Specified by:
getMetadata in interface Catalog
Parameters:
id - The id for which the metadata is needed
Returns:
The metadata, or null of non exists

setMetadata

public void setMetadata(Id id,
                        java.io.Serializable metadata,
                        Continuation c)
Updates the metadata stored under the given key to be the provided value. As this may require a disk access, the requestor must also provide a continuation to return the result to.

Specified by:
setMetadata in interface Catalog
Parameters:
id - The id for the metadata
metadata - The metadata to store
c - The command to run once the operation is complete

getObject

public void getObject(Id id,
                      Continuation c)
Returns the object identified by the given id.

Specified by:
getObject in interface Catalog
Parameters:
id - The id of the object in question.
c - The command to run once the operation is complete

scan

public IdSet scan(IdRange range)
Return the objects identified by the given range of ids. The IdSet returned contains the Ids of the stored objects. The range is partially inclusive, the lower range is inclusive, and the upper exclusive. NOTE: This method blocks so if the behavior of this method changes and uses the disk, this method may be deprecated.

Specified by:
scan in interface Catalog
Parameters:
range - The range to query
Returns:
The idset containing the keys

scan

public IdSet scan()
Return the objects identified by the given range of ids. The IdSet returned contains the Ids of the stored objects. The range is partially inclusive, the lower range is inclusive, and the upper exclusive. NOTE: This method blocks so if the behavior of this method changes and uses the disk, this method may be deprecated.

Specified by:
scan in interface Catalog
Returns:
The idset containing the keys

scanMetadata

public java.util.SortedMap scanMetadata(IdRange range)
Returns a map which contains keys mapping ids to the associated metadata.

Specified by:
scanMetadata in interface Catalog
Parameters:
range - The range to query
Returns:
The map containing the keys

scanMetadata

public java.util.SortedMap scanMetadata()
Returns a map which contains keys mapping ids to the associated metadata.

Specified by:
scanMetadata in interface Catalog
Returns:
The treemap mapping ids to metadata

scanMetadataValuesHead

public java.util.SortedMap scanMetadataValuesHead(java.lang.Object value)
Returns the submapping of ids which have metadata less than the provided value.

Specified by:
scanMetadataValuesHead in interface Catalog
Parameters:
value - The maximal metadata value
Returns:
The submapping

scanMetadataValuesNull

public java.util.SortedMap scanMetadataValuesNull()
Returns the submapping of ids which have metadata null

Specified by:
scanMetadataValuesNull in interface Catalog
Returns:
The submapping

getTotalSize

public long getTotalSize()
Returns the total size of the stored data in bytes.The result is returned via the receiveResult method on the provided Continuation with an Integer representing the size.

Specified by:
getTotalSize in interface Catalog
Parameters:
c - The command to run once the operation is complete
Returns:
The total size, in bytes, of data stored.

getSize

public int getSize()
Returns the number of Ids currently stored in the catalog

Specified by:
getSize in interface Catalog
Returns:
The number of ids in the catalog

flush

public void flush(Continuation c)
Method which is used to erase all data stored in the Catalog. Use this method with care!

Specified by:
flush in interface Catalog
Parameters:
c - The command to run once done

writeDirty

protected void writeDirty()
Function which writes out all of the dirty metadata files and marks them as clean.


getRangeForDirectory

protected IdRange getRangeForDirectory(java.io.File dir)
Utility function which returns the range of keys which a directory corresponds to.

Parameters:
dir - The directory

setRoot

public boolean setRoot(java.lang.String dir)
Sets the root directory that the persistence Manager uses

Parameters:
dir - the String representing the directory to use
Returns:
boolean, true if the operation succeeds false if it doesn't

getRoot

public java.lang.String getRoot()
gets the root directory that the persistence Manager uses

Returns:
String the directory for the root

getStorageSize

public long getStorageSize()
gets the amount of storage that the persistence Manager uses

Returns:
int the amount of storage in bytes allocated for use

setStorageSize

public boolean setStorageSize(long size)
Sets the amount of storage that the persistence Manager uses

Parameters:
size - the amount of storage available to use in bytes
Returns:
boolean, true if the operation succeeds false if it doesn't

getName

public java.lang.String getName()
Gets the name of this instance

Returns:
String the name of the instance

Rice Pastry API

Copyright © 2001-2005 - Rice Pastry.


Imprint-Dataprotection