com.microsoft.tfs.core.persistence
Interface PersistenceStore

All Known Implementing Classes:
FilesystemPersistenceStore, VersionedVendorFilesystemPersistenceStore

public interface PersistenceStore

Purpose

Provides long-term storage services for objects (identified by "item names"). Storage and retrieval can be done with ObjectSerializers, or as with InputStream and OutputStreams. 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 PersistenceStores.

PersistenceStores can be used in isolation (one PersistenceStore maps to one one storage resource with one item namespace), or hierarchichally (you can get PersistenceStores 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.

PersistenceStores 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.

Item Names

Items in a PersistenceStore are identified by a string name (case sensitivity and maximum length is undefined). Names cannot be the empty string.

Since:
TEE-SDK-10.1
Thread-safety:
thread-safe

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

initialize

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.

Throws:
java.io.IOException - if an exception happened creating the storage location

getChildStore

PersistenceStore getChildStore(java.lang.String childName)
Gets a PersistenceStore for the given child name.

Parameters:
childName - the child name (must not be null or empty)
Returns:
the new persistence store for the child

getStoreLock

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).

Parameters:
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.
Returns:
a AdvisoryFileLock, initially owned. Returns null if and only if block was set to false and the lock was not immediately available.
Throws:
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.

getItemLock

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).

Parameters:
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.
Returns:
a AdvisoryFileLock, initially owned. Returns null if and only if block was set to false and the lock was not immediately available.
Throws:
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.

containsItem

boolean containsItem(java.lang.String itemName)
                     throws java.io.IOException
Tests whether the item exists in this store. An item will exist if it was previously written to (and not deleted).

Parameters:
itemName - the item to test for existence (must not be null or empty)
Returns:
true if the item exists, false if it does not exist
Throws:
java.io.IOException - if there was an error testing whether the item was contained in this store

deleteItem

boolean deleteItem(java.lang.String itemName)
                   throws java.io.IOException
Deletes the specified item. If the item does not exist, this method should not throw an exception.

Parameters:
itemName - the item to delete (must not be null or empty)
Returns:
true if the item existed and was deleted, false if it did not exist or did exist but could not be deleted
Throws:
java.io.IOException - if an error occurred deleting the item, but not thrown if the item did not exist

migrateItem

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. 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.

Parameters:
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)
Returns:
true if the item was migrated to the new store or already existed in the new store, false if no migration happened and the new item does not exist in the new store
Throws:
java.io.IOException - if an error ocurred reading or writing persistence data from the old store or to the new store

storeItem

boolean storeItem(java.lang.String itemName,
                  java.lang.Object object,
                  LockMode lockMode,
                  MergeHandler mergeHandler,
                  ObjectSerializer serializer)
                  throws java.io.IOException,
                         java.lang.InterruptedException
Equivalent To:
storeItem(itemName, object, lockMode, mergeHandler,
             serializer, PersistenceSecurity.PUBLIC)
Throws:
java.io.IOException
java.lang.InterruptedException

storeItem

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
Saves an object as the specified item name. The object can be retrieved with retrieveItem(String, LockMode, MergeHandler, ObjectSerializer) , by passing the same item name.

Parameters:
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)
Returns:
true if the object was successfully persisted, false if and only if LockMode.NO_WAIT was given and the lock could not be obtained
Throws:
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 resource

retrieveItem

java.lang.Object retrieveItem(java.lang.String itemName,
                              LockMode lockMode,
                              MergeHandler mergeHandler,
                              ObjectSerializer serializer)
                              throws java.io.IOException,
                                     java.lang.InterruptedException
Retrieves an object that was previuosly stored via storeItem(String, Object, LockMode, MergeHandler, ObjectSerializer) .

Parameters:
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)
Returns:
the retrieved object, null if and only if LockMode.NO_WAIT was given and the lock could not be obtained
Throws:
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 resource

getItemInputStream

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

Parameters:
itemName - the item to read (must not be null or empty)
Returns:
an InputStream open for reading the item
Throws:
java.io.IOException - if an error occurred opening the item for read

getItemOutputStream

java.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).

Parameters:
itemName - the item to write (must not be null or empty)
Returns:
an OutputStream open for writing the item
Throws:
java.io.IOException - if an error occurred opening the item for write


© 2015 Microsoft. All rights reserved.