|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface PersistenceStore
Provides long-term storage services for objects (identified by "item names").
Storage and retrieval can be done with ObjectSerializer
s, or as with
InputStream
and OutputStream
s. Provides locking for single
items in the store to ensure exclusive read/update, and locking over the
entire store for exclusive access and atomic read/update of multiple items.
Merge handlers may be provided during serialization for cases where the
persisted data has changed since the previous store operation. Also provides
simple migration (copy) of items from other PersistenceStore
s.
PersistenceStore
s can be used in isolation (one
PersistenceStore
maps to one one storage resource with one item
namespace), or hierarchichally (you can get PersistenceStore
s for
named children of the first one). Think of File
and
File.listFiles()
. The implementation class of a child
PersistenceStore
is always the same as its parent.
PersistenceStore
s are lazily initialized. Construction is not
guaranteed to create all underlying storage resources, but use of other
public methods is guaranteed to create resources needed for those methods.
See initialize()
.
Implementations are encouraged to take some kind of implementation-specific namespace identifier during construction and isolate storage of items within this namespace. For example, a filesystem implementation may take a filesystem directory; a database implementation may take an integer used as a key into a storage table. This tactic provides for separation between namespaces of instances, so item names don't conflict across them.
Items in a PersistenceStore
are identified by a string name (case
sensitivity and maximum length is undefined). Names cannot be the empty
string.
Method Summary | |
---|---|
boolean |
containsItem(java.lang.String itemName)
Tests whether the item exists in this store. |
boolean |
deleteItem(java.lang.String itemName)
Deletes the specified item. |
PersistenceStore |
getChildStore(java.lang.String childName)
Gets a PersistenceStore for the given child name. |
java.io.InputStream |
getItemInputStream(java.lang.String itemName)
Gets an InputStream for reading the specified item's data. |
AdvisoryFileLock |
getItemLock(java.lang.String itemName,
boolean block)
Gets a thread- and process-exclusive lock for a single item in this PersistenceStore . |
java.io.OutputStream |
getItemOutputStream(java.lang.String itemName)
Gets an OutputStream to write the specified item's data. |
AdvisoryFileLock |
getStoreLock(boolean block)
Gets a thread- and process-exclusive lock for the entire PersistenceStore . |
void |
initialize()
Creates any storage resources required by the implementation. |
boolean |
migrateItem(PersistenceStore oldStore,
java.lang.String oldItemName,
java.lang.String newItemName)
Copies the persisted item specified by oldItemName from the oldStore into this store with the newItemName. |
java.lang.Object |
retrieveItem(java.lang.String itemName,
LockMode lockMode,
MergeHandler mergeHandler,
ObjectSerializer serializer)
Retrieves an object that was previuosly stored via storeItem(String, Object, LockMode, MergeHandler, ObjectSerializer)
. |
boolean |
storeItem(java.lang.String itemName,
java.lang.Object object,
LockMode lockMode,
MergeHandler mergeHandler,
ObjectSerializer serializer)
|
boolean |
storeItem(java.lang.String itemName,
java.lang.Object object,
LockMode lockMode,
MergeHandler mergeHandler,
ObjectSerializer serializer,
PersistenceSecurity security)
Saves an object as the specified item name. |
Method Detail |
---|
void initialize() throws java.io.IOException
Creates any storage resources required by the implementation. For example, creates filesystem directories, inserts a key row into a database table, etc.
Calling this method externally is usually not required. This method is
public because some implementations of PersistenceStore
allow
users to interact directly with their storage (for example, files in a
filesystem), and this method ensures resource creation (intermediate
dirctories).
Implementations of this method must be able to be called multiple times
without error (subsequent calls must not fail). Other methods in this
class must call initialize()
before they do their work, if their
work requires initialization.
java.io.IOException
- if an exception happened creating the storage locationPersistenceStore getChildStore(java.lang.String childName)
PersistenceStore
for the given child name.
childName
- the child name (must not be null
or empty)
AdvisoryFileLock getStoreLock(boolean block) throws java.io.IOException, java.lang.InterruptedException
Gets a thread- and process-exclusive lock for the entire
PersistenceStore
. This is simply a different synchronization
point than getItemLock(String, boolean)
; a lock on the entire
PersistenceStore
does not interfere (or even interact)
with locks on items.
The lock should be released by its AdvisoryFileLock.release()
method. If you forget (you should not forget), the lock will be released
during its finalization (possibly as late as when the JVM exits).
block
- if true, this method does not return until the lock is obtained
(or the controlling thread is interrupted). If false, the method
returns immediately; the value is null if the lock was not
immediately available or a AdvisoryFileLock
if it was.
AdvisoryFileLock
, initially owned. Returns null if and
only if block was set to false and the lock was not immediately
available.
java.io.IOException
- if an exception occured creating or acquiring the underlying lock
java.lang.InterruptedException
- if this thread was interrupted while waiting to acquire the lock.AdvisoryFileLock getItemLock(java.lang.String itemName, boolean block) throws java.io.IOException, java.lang.InterruptedException
Gets a thread- and process-exclusive lock for a single item in this
PersistenceStore
. A lock on an item is not prevented by a lock on
the entire store. See getStoreLock(boolean)
for details.
The lock should be released by its AdvisoryFileLock.release()
method. If you forget (you should not forget), the lock will be released
during its finalization (possibly as late as when the JVM exits).
itemName
- the item to get a lock for (must not be null
or
empty)block
- if true, this method does not return until the lock is obtained
(or the controlling thread is interrupted). If false, the method
returns immediately; the value is null if the lock was not
immediately available or a AdvisoryFileLock
if it was.
AdvisoryFileLock
, initially owned. Returns null if and
only if block was set to false and the lock was not immediately
available.
java.io.IOException
- if an exception occured creating or acquiring the underlying lock
java.lang.InterruptedException
- if this thread was interrupted while waiting to acquire the lock.boolean containsItem(java.lang.String itemName) throws java.io.IOException
itemName
- the item to test for existence (must not be null
or
empty)
java.io.IOException
- if there was an error testing whether the item was contained in
this storeboolean deleteItem(java.lang.String itemName) throws java.io.IOException
itemName
- the item to delete (must not be null
or empty)
java.io.IOException
- if an error occurred deleting the item, but not thrown if the
item did not existboolean migrateItem(PersistenceStore oldStore, java.lang.String oldItemName, java.lang.String newItemName)
Copies the persisted item specified by oldItemName from the oldStore into this store with the newItemName. If the newItemName already exists in this store, it must not be overwritten. Data is only read from the old store, and it is not translated during copying.
Implementations should not rethrow exceptions encountered during migration to make the caller's work easier. They should simply return false.
oldStore
- the store to migrate the old item from (not
NullPointerException
, but may be this
PersistenceStore
)oldItemName
- the item to copy from the old store (must not be null
or empty)newItemName
- the item to copy into this store (must not be null
or
empty)
java.io.IOException
- if an error ocurred reading or writing persistence data from the
old store or to the new storeboolean storeItem(java.lang.String itemName, java.lang.Object object, LockMode lockMode, MergeHandler mergeHandler, ObjectSerializer serializer) throws java.io.IOException, java.lang.InterruptedException
storeItem(itemName, object, lockMode, mergeHandler, serializer, PersistenceSecurity.PUBLIC)
java.io.IOException
java.lang.InterruptedException
boolean storeItem(java.lang.String itemName, java.lang.Object object, LockMode lockMode, MergeHandler mergeHandler, ObjectSerializer serializer, PersistenceSecurity security) throws java.io.IOException, java.lang.InterruptedException
retrieveItem(String, LockMode, MergeHandler, ObjectSerializer)
,
by passing the same item name.
itemName
- the desired name for the object (must not be null
or
empty)object
- the object to serialize. Access to the Java object is not
synchronized by this method during serialization. If
synchronization is required, it is the responsibility of the
caller (must not be null
)lockMode
- if LockMode.NONE
, no locking is performed. If
LockMode.WAIT_FOREVER
, a lock is obtained and held for the
identifier during the operation (and unlocked before this method
returns). If LockMode.NO_WAIT
, locking is attempted, but
if the lock was not immediately available this method must not
write the serialized object and returns false (must not be
null
)mergeHandler
- if not null
, this MergeHandler
is used to
detect and resolve merge conflicts in the persistence store. If
null, no merging is done: the given component instance will always
overwrite an existing serialized component file on disk.serializer
- specifies the serializer to use (must not be null
)security
- specifies the security with which this item will be saved.
PersistenceSecurity.PUBLIC
indicates that no effort will
be taken by the persistence store to prevent other users from
accessing this data. PersistenceStore#PRIVATE
indicates
that the persistence store will attempt to prevent other users
from accessing this data using the underlying permission model of
the persistence store. (must not be null
)
LockMode.NO_WAIT
was given and the lock could not be
obtained
java.io.IOException
- if an error occurred writing the persistent data (implementation
specific; perhaps insufficient permissions, out of disk space,
etc.).
java.lang.InterruptedException
- if this thread was interrupted while waiting on a lock when the
LockMode
specifies waiting, or while waiting on some
other resourcejava.lang.Object retrieveItem(java.lang.String itemName, LockMode lockMode, MergeHandler mergeHandler, ObjectSerializer serializer) throws java.io.IOException, java.lang.InterruptedException
storeItem(String, Object, LockMode, MergeHandler, ObjectSerializer)
.
itemName
- the name of the object. (must not be null
or empty)lockMode
- if LockMode.NONE
, no locking is performed. If
LockMode.WAIT_FOREVER
, a lock is obtained and held for the
componentName in this store's settings location during the
operation (and unlocked before this method returns). If
LockMode.NO_WAIT
, locking is attempted, but if the lock
was not immediately available this method does not read the file
and returns false. (must not be null
)mergeHandler
- if not null
, this MergeHandler
is given the
last modification date of the persisted object when it is read, so
the handler can handle future merges. If null, no such
notification is performed and the resource is still read normally.serializer
- specifies the serializer to use (must not be null
)
null
if and only if
LockMode.NO_WAIT
was given and the lock could not be
obtained
java.io.IOException
- if an error occurred reading the persistent data (implementation
specific; perhaps insufficient permissions, out of disk space,
etc.).
java.lang.InterruptedException
- if this thread was interrupted while waiting on a lock when the
LockMode
specifies waiting, or while waiting on some
other resourcejava.io.InputStream getItemInputStream(java.lang.String itemName) throws java.io.IOException
Gets an InputStream
for reading the specified item's data. No
locking is done by this method.
The behavior of opening an InputStream
for an item that does not
exist is unspecified.
itemName
- the item to read (must not be null
or empty)
InputStream
open for reading the item
java.io.IOException
- if an error occurred opening the item for readjava.io.OutputStream getItemOutputStream(java.lang.String itemName) throws java.io.IOException
Gets an OutputStream
to write the specified item's data. No
locking is done by this method.
Getting an OutputStream
for a valid item name that does not yet
exist in the store should succeed (it should be created).
itemName
- the item to write (must not be null
or empty)
OutputStream
open for writing the item
java.io.IOException
- if an error occurred opening the item for write
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |