Package com.tangosol.persistence

Class AbstractPersistenceManager.AbstractPersistentStore

java.lang.Object
com.tangosol.util.Base
com.tangosol.persistence.AbstractPersistenceManager.AbstractPersistentStore
All Implemented Interfaces:
com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
Enclosing class:
AbstractPersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
public abstract class AbstractPersistenceManager.AbstractPersistentStore extends Base implements com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
Abstract implementation of a ReadBuffer-based PersistentStore.
Author:
jh 2012.10.04

  • Field Details

    • f_sId

      protected final String f_sId
      The identifier of this persistent store.

    • f_dirStore

      protected final File f_dirStore
      The directory used to store persisted data.

    • f_fileLock

      protected final File f_fileLock
      The file used to prevent concurrent access to the data directory underlying this persistent store.

    • m_nState

      protected volatile int m_nState
      The state of the PersistenceStore.

    • m_lockFile

      protected FileLock m_lockFile
      The FileLock used to prevent concurrent access to the data directory underlying this persistent store.

    • f_lock

      protected final ReadWriteLock f_lock
      The ReadWriteLock used to protect against concurrent read/write operations.

    • f_setExtentIds

      protected final Set<Long> f_setExtentIds
      The set of valid extent identifiers known to this persistent store.

    • f_setDeletedIds

      protected final Set<Long> f_setDeletedIds
      The set of extent identifiers that are in the process of being deleted.

  • Constructor Details

    • AbstractPersistentStore

      public AbstractPersistentStore(String sId)
      Create a new AbstractPersistentStore with the given identifier.
      Parameters:
      sId - the identifier for the new store
      Throws:
      IllegalArgumentException - if the identifier is invalid

  • Method Details

    • getId

      public String getId()
      Return the identifier of this store.
      Specified by:
      getId in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Returns:
      the identifier that was used to open this store

    • ensureExtent

      public boolean ensureExtent(long lExtentId)
      Ensure that an extent with the given identifier exists in the persistent store, returning true iff the extent was created.
      Specified by:
      ensureExtent in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      lExtentId - the identifier of the extent to ensure
      Returns:
      true iff the specified extent did not previously exist

    • deleteExtent

      public void deleteExtent(long lExtentId)
      Delete the specified extent from the persistent store, ensuring that any key-value mappings associated with the extent are no longer valid.

      Removal of the key-value mappings associated with the extent from the underlying storage is the responsibility of the implementation, and may (for example) be performed immediately, asynchronously, or deferred until space is required.

      Specified by:
      deleteExtent in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      lExtentId - the identifier of the extent to delete

    • moveExtent

      public void moveExtent(long lOldExtentId, long lNewExtentId)
      Move the specified extent from the old extent id to the new extent id.

      Upon control being returned the implementation guarantees that any data data that used to reside against the old extent id is accessible from new extent id using the load API. In addition, calls to store are permitted immediately after control is returned.

      Specified by:
      moveExtent in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      lOldExtentId - the old extent identifier
      lNewExtentId - the new extent identifier

    • truncateExtent

      public void truncateExtent(long lExtentId)
      Truncate the specified extent from the persistent store, ensuring that any key-value mappings associated with the extent are removed.

      Removal of the key-value mappings associated with the extent from the underlying storage is the responsibility of the implementation, and may (for example) be performed immediately, asynchronously, or deferred until space is required.

      Specified by:
      truncateExtent in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      lExtentId - the identifier of the extent to truncate

    • extents

      public long[] extents()
      Return a list of the extent identifiers in the underlying store.
      Specified by:
      extents in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Returns:
      a list of the extent identifiers in the underlying store

    • exclusively

      public AutoCloseable exclusively()
      Description copied from interface: com.oracle.coherence.persistence.PersistentStore
      Suggest to this PersistentStore that the caller requires exclusive access to this store until close is called on the returned AutoCloseable.

      Note: the caller must call close on the returned object

      Specified by:
      exclusively in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Returns:
      an AutoCloseable object that requires close to be called on it when exclusive access is no longer needed

    • load

      public ReadBuffer load(long lExtentId, ReadBuffer bufKey)
      Return the value associated with the specified key, or null if the key does not have an associated value in the underlying store.
      Specified by:
      load in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      lExtentId - the extent identifier for the key
      bufKey - key whose associated value is to be returned
      Returns:
      the value associated with the specified key, or null if no value is available for that key

    • store

      public void store(long lExtentId, ReadBuffer bufKey, ReadBuffer bufValue, Object oToken)
      Store the specified value under the specific key in the underlying store. This method is intended to support both key-value pair creation and value update for a specific key.
      Specified by:
      store in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      lExtentId - the extent identifier for the key-value pair
      bufKey - key to store the value under
      bufValue - value to be stored
      oToken - optional token that represents a set of mutating operations to be committed as an atomic unit; if null, the given key-value pair will be committed to the store automatically by this method

    • erase

      public void erase(long lExtentId, ReadBuffer bufKey, Object oToken)
      Remove the specified key from the underlying store if present.
      Specified by:
      erase in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      lExtentId - the extent identifier for the key
      bufKey - key whose mapping is to be removed
      oToken - optional token that represents a set of mutating operations to be committed as an atomic unit; if null, the removal of the given key will be committed to the store automatically by this method

    • iterate

      public void iterate(com.oracle.coherence.persistence.PersistentStore.Visitor<ReadBuffer> visitor)
      Iterate the key-value pairs in the persistent store, applying the specified visitor to each key-value pair.
      Specified by:
      iterate in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      visitor - the visitor to apply

    • begin

      public Object begin()
      Begin a new sequence of mutating operations that should be committed to the store as an atomic unit. The returned token should be passed to all mutating operations that should be part of the atomic unit. Once the sequence of operations have been performed, they must either be committed to the store or the atomic unit must be aborted.
      Specified by:
      begin in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Returns:
      a token that represents the atomic unit

    • begin

      public Object begin(Collector<Object> collector, Object oReceipt)
      Begin a new sequence of mutating operations that should be committed to the store asynchronously as an atomic unit. The returned token should be passed to all mutating operations that should be part of the atomic unit. Once the sequence of operations have been performed, they must either be committed to the store or the atomic unit must be aborted.

      If a collector is passed to this method, the specified receipt will be added to it when the unit is committed. If the operation is aborted or an error occurs during the commit, an AsyncPersistenceException that wraps the cause and specified receipt will be added. Finally, the collector will be flushed.

      Specified by:
      begin in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      collector - an optional collector
      oReceipt - a receipt to be added to the collector (if any) when the unit is committed
      Returns:
      a token representing the atomic unit that will be committed asynchronously

    • commit

      public void commit(Object oToken)
      Commit a sequence of mutating operations represented by the given token as an atomic unit.
      Specified by:
      commit in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      oToken - a token that represents the atomic unit to commit

    • abort

      public void abort(Object oToken)
      Abort an atomic sequence of mutating operations.
      Specified by:
      abort in interface com.oracle.coherence.persistence.PersistentStore<ReadBuffer>
      Parameters:
      oToken - a token that represents the atomic unit to abort

    • copyToTrash

      public void copyToTrash()
      Copy the store to trash if the meta.properties file exist.

    • submitOpen

      protected void submitOpen(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> storeFrom, Collector<Object> collector)
      Open this store either asynchronously, iff both a store to open from and a collector have been provided, or synchronously.
      Parameters:
      storeFrom - a PersistentStore to copy from
      collector - a collector to notify when the open completes

    • open

      protected boolean open(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> storeFrom)
      Open this persistent store.
      Parameters:
      storeFrom - the PersistenceStore the new store should be based upon
      Returns:
      true if the store was created

    • release

      protected void release()
      Release any resources held by this persistent store.

    • delete

      protected boolean delete(boolean fSafe)
      Release any resources held by this persistent store and delete any underlying persistent storage.
      Parameters:
      fSafe - if true, remove the store by moving it to a restorable location (if possible) rather than deleting it
      Returns:
      true if the store was successfully deleted, false otherwise

    • ensureReady

      protected void ensureReady()
      Block the calling thread until the store is either ready to accept requests or the store has been closed.
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if the store has been closed or the thread was interrupted

    • isReady

      protected boolean isReady()
      Return true if the store is ready to accept requests.
      Returns:
      true if the store is ready to accept requests

    • isClosed

      protected boolean isClosed()
      Return true if the store has been closed.
      Returns:
      true if the store has been closed

    • setState

      protected void setState(int nState)
      Set the state of this store.
      Parameters:
      nState - the state the store should be transitioned to

    • isExclusive

      protected boolean isExclusive()
      Return true if this store is in exclusive mode.
      Returns:
      true if this store is in exclusive mode

    • instantiateExclusiveClosable

      protected AutoCloseable instantiateExclusiveClosable()
      Return an AutoCloseable that will transition this PersistentStore out of exclusive mode.
      Returns:
      an AutoCloseable that will transition this PersistentStore out of exclusive mode

    • toString

      public String toString()
      Return a human readable description of this AbstractPersistentStore.
      Overrides:
      toString in class Object
      Returns:
      a human readable description

    • ensurePersistenceException

      protected com.oracle.coherence.persistence.PersistenceException ensurePersistenceException(Throwable eCause)
      Return a PersistenceException with the given cause. The returned exception is also initialized with this store, its manager, and its environment (if available).
      Parameters:
      eCause - an optional cause
      Returns:
      a PersistenceException with the given cause

    • ensurePersistenceException

      protected com.oracle.coherence.persistence.PersistenceException ensurePersistenceException(Throwable eCause, String sMessage)
      Return a PersistenceException with the given cause and detail message. The returned exception is also initialized with this store, its manager, and its environment (if available).
      Parameters:
      eCause - an optional cause
      sMessage - an optional detail message
      Returns:
      a PersistenceException with the given cause and detail message

    • lockStorage

      protected final boolean lockStorage()
      Acquire an exclusive lock on the data directory underlying this persistent store.
      Returns:
      true if an exclusive lock was obtained, false otherwise

    • unlockStorage

      protected final void unlockStorage()
      Release an exclusive lock on the data directory underlying this persistent store.

    • lockRead

      protected final void lockRead()
      Acquire a read lock on this persistent store.

    • unlockRead

      protected final void unlockRead()
      Release a read lock on this persistent store.

    • lockWrite

      protected final void lockWrite()
      Acquire a write lock on this persistent store.

    • unlockWrite

      protected final void unlockWrite()
      Release a write lock on this persistent store.

    • validateExtentId

      protected void validateExtentId(long lExtentId)
      Validate the given extent identifier.
      Parameters:
      lExtentId - the extent identifier

    • validateMetadata

      protected void validateMetadata()
      Validate the metadata

    • ensureExtentInternal

      protected boolean ensureExtentInternal(long lExtentId)
      Ensure the provided extent id has been registered and created, thus allowing subsequent load and store operations against the same extent id.

      Note: the caller is assumed to have exclusive access to this store.

      Parameters:
      lExtentId - the extent id to register and create
      Returns:
      true if the extent id was not previously registered and was successfully created

    • copyAndOpenInternal

      protected void copyAndOpenInternal(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> storeFrom)
      Copy the provided store to ensure both the contents are available in the new store and it is open thus ready to receive requests.

      Note: overriders of this method must guarantee openInternal() is called by either delegating to super or calling it directly.

      Parameters:
      storeFrom - the store to copy from

    • openInternal

      protected abstract void openInternal()
      Open the underlying persistent storage.

      Note: this method is guaranteed to only be called by a thread that holds a write lock on this persistent store.

      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • releaseInternal

      protected abstract void releaseInternal()
      Release the underlying persistent storage.

      Note: this method is guaranteed to only be called by a thread that holds a write lock on this persistent store.

      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • deleteInternal

      protected abstract boolean deleteInternal()
      Remove the underlying persistent storage.

      Note: this method is guaranteed to only be called by a thread that holds a write lock on this persistent store.

      Returns:
      true on successful removal
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • loadExtentIdsInternal

      protected abstract void loadExtentIdsInternal(Set<Long> setIds)
      Populate the given set with the identifiers of extents in the underlying persistent storage.

      Note: this method is guaranteed to only be called by a thread that holds a write lock on this persistent store.

      Parameters:
      setIds - a set of ids
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • createExtentInternal

      protected abstract void createExtentInternal(long lExtentId)
      Create the extent with the given identifier in the persistent store.

      Note: this method is guaranteed to only be called by a thread that holds a write lock on this persistent store.

      Parameters:
      lExtentId - the identifier of the extent to create
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • deleteExtentInternal

      protected abstract void deleteExtentInternal(long lExtentId)
      Delete the specified extent from the persistent store.

      Note: this method is guaranteed to only be called by a thread that holds a write lock on this persistent store.

      Parameters:
      lExtentId - the identifier of the extent to delete
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • moveExtentInternal

      protected void moveExtentInternal(long lOldExtentId, long lNewExtentId)
      Move the specified extent from the old extent id to the new extent id.

      Note: this method is guaranteed to only be called by a thread that holds a write lock on this persistent store.

      Parameters:
      lOldExtentId - the old extent identifier
      lNewExtentId - the new extent identifier
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • truncateExtentInternal

      protected abstract void truncateExtentInternal(long lExtentId)
      Truncate the specified extent from the persistent store.

      Note: this method is guaranteed to only be called by a thread that holds a write lock on this persistent store.

      Parameters:
      lExtentId - the identifier of the extent to truncate
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • loadInternal

      protected abstract ReadBuffer loadInternal(long lExtentId, ReadBuffer bufKey)
      Load and return the value associated with the specified key from the underlying persistent storage.

      Note: this method is guaranteed to only be called by a thread that holds a read lock on this persistent store.

      Parameters:
      lExtentId - the extent identifier for the key
      bufKey - key whose associated value is to be returned
      Returns:
      the value associated with the specified key, or null if no value is available for that key
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • storeInternal

      protected abstract void storeInternal(long lExtentId, ReadBuffer bufKey, ReadBuffer bufValue, Object oToken)
      Store the specified value under the specific key in the underlying persistent storage.

      Note: this method is guaranteed to only be called by a thread that holds a read lock on this persistent store.

      Parameters:
      lExtentId - the extent identifier for the key
      bufKey - key to store the value under
      bufValue - value to be stored
      oToken - a token that represents an atomic unit to commit
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs
      IllegalArgumentException - if the token is invalid

    • eraseInternal

      protected abstract void eraseInternal(long lExtentId, ReadBuffer bufKey, Object oToken)
      Remove the specified key from the underlying persistent storage if present.

      Note: this method is guaranteed to only be called by a thread that holds a read lock on this persistent store.

      Parameters:
      lExtentId - the extent identifier for the key
      bufKey - key whose mapping is to be removed from the map
      oToken - a token that represents an atomic unit to commit
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs
      IllegalArgumentException - if the token is invalid

    • iterateInternal

      protected abstract void iterateInternal(com.oracle.coherence.persistence.PersistentStore.Visitor<ReadBuffer> visitor)
      Iterate the key-value pairs in the underlying persistent storage, applying the specified visitor to each key-value pair.

      Note: this method is guaranteed to only be called by a thread that holds a read lock on this persistent store.

      Parameters:
      visitor - the visitor to apply
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • beginInternal

      protected abstract Object beginInternal()
      Begin a sequence of mutating operations that should be committed atomically and return a token that represents the atomic unit.

      Note: this method is guaranteed to only be called by a thread that holds a read lock on this persistent store.

      Returns:
      a token that represents the atomic unit to commit
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs

    • commitInternal

      protected abstract void commitInternal(Object oToken)
      Commit a sequence of mutating operations represented by the given token as an atomic unit.

      Note: this method is guaranteed to only be called by a thread that holds a read lock on this persistent store.

      Parameters:
      oToken - a token that represents the atomic unit to commit
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs
      IllegalArgumentException - if the token is invalid

    • abortInternal

      protected abstract void abortInternal(Object oToken)
      Abort an atomic sequence of mutating operations.

      Note: this method is guaranteed to only be called by a thread that holds a read lock on this persistent store.

      Parameters:
      oToken - a token that represents the atomic unit to abort
      Throws:
      com.oracle.coherence.persistence.PersistenceException - if a general persistence error occurs
      IllegalArgumentException - if the token is invalid

    • getDataDirectory

      public File getDataDirectory()
      The directory used to store persisted data.
      Returns:
      the underlying data storage directory