com.microsoft.tfs.core.persistence
Class FilesystemPersistenceStore

java.lang.Object
  extended by com.microsoft.tfs.core.persistence.FilesystemPersistenceStore
All Implemented Interfaces:
PersistenceStore
Direct Known Subclasses:
VersionedVendorFilesystemPersistenceStore

public class FilesystemPersistenceStore
extends java.lang.Object
implements PersistenceStore

Implements PersistenceStore by persisting objects to files in directories on the filesystem. Each instance can be configured to a specific directory, and item names map to file names in that directory. Children created via getChildStore(String) are always a subdirectory of the parent. Because of the way filesystems work, a FilesystemPersistenceStore cannot have a child item with the same name as a child store.

Child store and item names are case-sensitive if the underlying filesystem is.

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

Constructor Summary
FilesystemPersistenceStore(java.io.File directory)
          Creates a FilesystemPersistenceStore for the given directory.
 
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.
 boolean equals(java.lang.Object obj)
           
 PersistenceStore getChildStore(java.lang.String childName)
          Gets a PersistenceStore for the given child name.
 java.io.File getItemFile(java.lang.String itemName)
          Gets the File for the given item 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.
 java.io.File getStoreFile()
           
 AdvisoryFileLock getStoreLock(boolean block)
           Gets a thread- and process-exclusive lock for the entire PersistenceStore.
 int hashCode()
           
 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 PersistenceStore.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.
 java.lang.String toString()
          
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

FilesystemPersistenceStore

public FilesystemPersistenceStore(java.io.File directory)
Creates a FilesystemPersistenceStore for the given directory.

Parameters:
directory - the directory, which does not have to exist (must not be null)
Method Detail

getChildStore

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

Specified by:
getChildStore in interface PersistenceStore
Parameters:
childName - the child name (must not be null or empty)
Returns:
the new persistence store for the child

initialize

public 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 PersistenceStore.initialize() before they do their work, if their work requires initialization.

Specified by:
initialize in interface PersistenceStore
Throws:
java.io.IOException - if an exception happened creating the storage location

containsItem

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

Specified by:
containsItem in interface PersistenceStore
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

deleteItem

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

Specified by:
deleteItem in interface PersistenceStore
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

storeItem

public boolean storeItem(java.lang.String itemName,
                         java.lang.Object object,
                         LockMode lockMode,
                         MergeHandler mergeHandler,
                         ObjectSerializer serializer)
                  throws java.io.IOException,
                         java.lang.InterruptedException

Specified by:
storeItem in interface PersistenceStore
Throws:
java.io.IOException
java.lang.InterruptedException

storeItem

public 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 PersistenceStore.retrieveItem(String, LockMode, MergeHandler, ObjectSerializer) , by passing the same item name.

Specified by:
storeItem in interface PersistenceStore
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

public 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 PersistenceStore.storeItem(String, Object, LockMode, MergeHandler, ObjectSerializer) .

Specified by:
retrieveItem in interface PersistenceStore
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

migrateItem

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

Specified by:
migrateItem in interface PersistenceStore
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

getItemInputStream

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

Specified by:
getItemInputStream in interface PersistenceStore
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

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

Specified by:
getItemOutputStream in interface PersistenceStore
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

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object

getStoreFile

public java.io.File getStoreFile()
Returns:
the File that is the directory where this PersistenceStore saves data.

getItemFile

public java.io.File getItemFile(java.lang.String itemName)
Gets the File for the given item name.

Parameters:
itemName - the item name (must not be null or empty)
Returns:
the File for the item

getItemLock

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

Specified by:
getItemLock in interface PersistenceStore
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.

getStoreLock

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

Specified by:
getStoreLock in interface PersistenceStore
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.

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
Overrides:
equals in class java.lang.Object


© 2015 Microsoft. All rights reserved.