Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Rice Pastry API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## rice.persistence
Class PersistentStorage

    java.lang.Object
      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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Rice Pastry API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2005 - Rice Pastry.