Package com.tangosol.persistence

Class AbstractPersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>

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

  • Field Details

    • NO_LONGS

      protected static final long[] NO_LONGS
      An empty long array (by definition immutable).

    • NO_STRINGS

      protected static final String[] NO_STRINGS
      An empty String array (by definition immutable).

    • STORE_STATE_INITIALIZED

      protected static final int STORE_STATE_INITIALIZED
      The initial state of a PersistenceStore.
      See Also:

    • STORE_STATE_OPENING

      protected static final int STORE_STATE_OPENING
      The state of a PersistenceStore when it is in the process of being opened.
      See Also:

    • STORE_STATE_READY

      protected static final int STORE_STATE_READY
      The state of a PersistenceStore once it has been opened and is ready to process requests.
      See Also:

    • STORE_STATE_CLOSED

      protected static final int STORE_STATE_CLOSED
      The state of a PersistenceStore once it has been released and closed.
      See Also:

    • f_dirData

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

    • f_dirTrash

      protected final File f_dirTrash
      The directory used to store "safe-deleted" data.

    • f_dirLock

      protected final File f_dirLock
      The directory used to store lock files (to protect against multi-process file system clean up).

    • f_sName

      protected final String f_sName
      The name of this AbstractPersistenceManager.

    • f_mapStores

      protected final ConcurrentMap<String,PS extends AbstractPersistenceManager.AbstractPersistentStore> f_mapStores
      Map of open AbstractPersistentStore instances.

    • f_setTasks

      protected final Set<AbstractPersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>.Task> f_setTasks
      Set of outstanding tasks.

    • m_fReleased

      protected volatile boolean m_fReleased
      Whether this PersistenceManager has been released.

    • m_env

      protected AbstractPersistenceEnvironment m_env
      The environment that created this AbstractPersistenceManager.

    • m_pool

      protected com.tangosol.internal.util.DaemonPool m_pool
      An optional DaemonPool used to execute tasks.

  • Constructor Details

    • AbstractPersistenceManager

      public AbstractPersistenceManager(File fileData, File fileTrash, String sName) throws IOException
      Create a new AbstractPersistenceManager.
      Parameters:
      fileData - the directory used to store persisted data
      fileTrash - an optional trash directory
      sName - an optional name to give the new manager
      Throws:
      IOException - on error creating the data or trash directory

  • Method Details

    • getName

      public String getName()
      Return the name of this manager.
      Specified by:
      getName in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Returns:
      the name of this manager

    • createStore

      public PS createStore(String sId)
      Create a PersistentStore associated with the specified identifier.

      Creation of a store suggests its registration but has no usage until it transitions into a state of open. The implementation may choose to forgo any resource allocation until the caller opens the same identifier.

      Specified by:
      createStore in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Parameters:
      sId - a unique identifier of the store
      Returns:
      a persistent store

    • open

      public com.oracle.coherence.persistence.PersistentStore<ReadBuffer> open(String sId, com.oracle.coherence.persistence.PersistentStore<ReadBuffer> storeFrom)
      Open or create a PersistentStore associated with the specified identifier and based on the provided store.

      Upon a new store being created the provided store should be used as the basis for the new store such that the extents and associated data is available in the returned store. This provides an opportunity for an implementation to optimize initializing the new store based upon knowledge of the storage mechanics.

      Specified by:
      open in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Parameters:
      sId - a unique identifier for the store
      storeFrom - the PersistenceStore the new store should be based upon
      Returns:
      a PersistentStore associated with the specified identifier

    • open

      public com.oracle.coherence.persistence.PersistentStore<ReadBuffer> open(String sId, com.oracle.coherence.persistence.PersistentStore<ReadBuffer> storeFrom, Collector<Object> collector)
      Open or create a PersistentStore associated with the specified identifier and based on the provided store.

      Upon a new store being created the provided store should be used as the basis for the new store such that the extents and associated data is available in the returned store. This provides an opportunity for an implementation to optimize initializing the new store based upon knowledge of the storage mechanics.

      Providing a Collector allows the open operation to be performed asynchronously. This may be desirable when the calling thread can not be blocked on IO operations that are required when creating a new store based on an old store (storeFrom). Open is only non-blocking when both an old store and a Collector are provided. Upon completion of an asynchronous open request the provided Collector is called with either a String (GUID) or an AsyncPersistenceException, thus notifying the collector of success of failure respectively.

      Note: the behavior of a returned store that has not been opened is undefined.

      Specified by:
      open in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Parameters:
      sId - a unique identifier for the store
      storeFrom - the PersistenceStore the new store should be based upon
      collector - the Collector to notify once the store has been opened or failed to open; the collector will either receive a String (GUID) or an AsyncPersistenceException
      Returns:
      a PersistentStore associated with the specified identifier

    • close

      public void close(String sId)
      Close the associated PersistentStore and release exclusive access to the associated resources.
      Specified by:
      close in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Parameters:
      sId - a unique identifier of the store to close

    • delete

      public boolean delete(String sId, boolean fSafe)
      Remove the PersistentStore associated with the specified identifier.
      Specified by:
      delete in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Parameters:
      sId - a unique identifier of the store to remove
      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 removed, false otherwise

    • list

      public String[] list()
      Return the identifiers of the PersistentStores known to this manager.
      Specified by:
      list in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Returns:
      a list of the known store identifiers

    • contains

      public boolean contains(String sGUID)
      Description copied from interface: com.oracle.coherence.persistence.PersistenceManager
      Return the identifiers of the PersistentStores known to this manager.
      Specified by:
      contains in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Returns:
      a list of the known store identifiers

    • listOpen

      public String[] listOpen()
      Return the identifiers of PersistentStores that are currently open.
      Specified by:
      listOpen in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Returns:
      a list of the open store identifiers

    • read

      public void read(String sId, ReadBuffer.BufferInput in) throws IOException
      Read the PersistenceStore associated with the specified identifier from the given input stream, making it available to this manager.
      Specified by:
      read in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Parameters:
      sId - a unique identifier of the store to read
      in - the stream to read from
      Throws:
      IOException - if an error occurred while reading from the stream

    • write

      public void write(String sId, WriteBuffer.BufferOutput out) throws IOException
      Write the PersistentStore associated with the specified identifier to the given output buffer.
      Specified by:
      write in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Parameters:
      sId - a unique identifier of the store to write
      out - the output buffer to write to
      Throws:
      IOException - if an error occurred while writing to the stream

    • release

      public void release()
      Release all resources held by this manager. Note that the behavior of all other methods on this manager is undefined after this method is called.
      Specified by:
      release in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>

    • getPersistenceTools

      public com.oracle.coherence.persistence.PersistenceTools getPersistenceTools()
      Description copied from interface: com.oracle.coherence.persistence.PersistenceManager
      Return an instance of PersistenceTools allowing offline operations to be performed against the associated PersistenceManager and appropriate PersistentStore.
      Specified by:
      getPersistenceTools in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>
      Returns:
      a PersistenceTools implementation

    • writeSafe

      public void writeSafe(String sId)
      Copy the PersistentStore associated with the specified identifier to the configured safe area.
      Specified by:
      writeSafe in interface com.oracle.coherence.persistence.PersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>

    • toString

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

    • getMetadata

      protected Properties getMetadata()
      Return metadata for this manager.
      Returns:
      the metadata for this manager

    • readMetadata

      protected Properties readMetadata(File fileDir) throws IOException
      Read persistence metadata from the specified directory.
      Parameters:
      fileDir - the directory to read metadata from
      Returns:
      the metadata
      Throws:
      IOException - on error reading the metadata file

    • writeMetadata

      protected void writeMetadata(File fileDir) throws IOException
      Write persistence metadata for this manager to the specified directory.
      Parameters:
      fileDir - the directory to write metadata to
      Throws:
      IOException - on error writing the metadata file

    • isMetadataComplete

      protected boolean isMetadataComplete(Properties prop)
      Determine if the given metadata in the Properties is complete.
      Parameters:
      prop - the metadata to analyze
      Returns:
      true if the given metadata is complete; false otherwise

    • isMetadataCompatible

      protected boolean isMetadataCompatible(Properties prop)
      Determine if the given metadata is compatible with this manager.
      Parameters:
      prop - the metadata to analyze
      Returns:
      true if the given metadata is compatible with this manager; false otherwise

    • getImplVersion

      protected abstract int getImplVersion()
      Return the implementation version of this manager.
      Returns:
      the implementation version of this manager

    • getStorageFormat

      protected abstract String getStorageFormat()
      Return the storage format used by this manager.
      Returns:
      the storage format used by this manager

    • getStorageVersion

      protected abstract int getStorageVersion()
      Return the version of the storage format used by this manager.
      Returns:
      the version of the storage format used by this manager

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

    • ensureActive

      protected void ensureActive()
      Return control if this PersistenceManager is still active, otherwise throw an exception.
      Throws:
      IllegalStateException - if this PersistenceManager has been released

    • ensureTrashDir

      protected File ensureTrashDir() throws IOException
      Ensure trash directory is created.
      Returns:
      the configured trash directory
      Throws:
      IOException

    • submitTasks

      protected void submitTasks(List<? extends AbstractPersistenceManager<PS>.Task> listTasks)
      Submit the provided list of tasks for execution to the pool or execute directly.
      Parameters:
      listTasks - the tasks to execute

    • validatePersistentStoreId

      public String validatePersistentStoreId(String sId)
      Validate that the given identifier can be used for a persistent store.
      Parameters:
      sId - the identifier to check
      Returns:
      the validated identifier

    • submitTask

      protected void submitTask(AbstractPersistenceManager<PS>.Task task)
      Submit the given task for execution by the daemon pool.
      Parameters:
      task - the task to submit

    • addTask

      protected void addTask(AbstractPersistenceManager<PS>.Task task)
      Add the provided task to the set of tasks.
      Parameters:
      task - the task to add

    • executeTask

      protected void executeTask(AbstractPersistenceManager<PS>.Task task)
      Execute the specified task with the calling thread.
      Parameters:
      task - the task to execute

    • executeTaskExclusive

      protected void executeTaskExclusive(AbstractPersistenceManager<PS>.Task task)
      Execute the specified task with the calling thread. No other access to this manager or any of its persistent stores is guaranteed to occur while the task is being executed.
      Parameters:
      task - the task to execute

    • instantiatePersistentStore

      protected abstract PS instantiatePersistentStore(String sId)
      Factory method for PersistentStore implementations managed by this PersistenceManager.
      Parameters:
      sId - the identifier of the store to create
      Returns:
      a new AbstractPersistentStore with the given identifier

    • instantiatePersistenceTools

      protected abstract com.oracle.coherence.persistence.PersistenceTools instantiatePersistenceTools(com.oracle.coherence.persistence.OfflinePersistenceInfo info)
      Factory method to create a PersistenceTools implementation.
      Parameters:
      info - the OfflinePersistenceInfo relevant to the PersistenceTools
      Returns:
      a new PersistenceTools implementation

    • getDaemonPool

      public com.tangosol.internal.util.DaemonPool getDaemonPool()
      Return the optional DaemonPool used to execute tasks.
      Returns:
      the DaemonPool or null if one hasn't been configured

    • setDaemonPool

      public void setDaemonPool(com.tangosol.internal.util.DaemonPool pool)
      Configure the DaemonPool used to execute tasks.
      Parameters:
      pool - the DaemonPool

    • getDataDirectory

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

    • getTrashDirectory

      public File getTrashDirectory()
      Return the directory used to store "safe-deleted" persisted data.
      Returns:
      the trash storage directory

    • getLockDirectory

      protected File getLockDirectory()
      Return the directory used to store lock files.
      Returns:
      the directory used to store lock files

    • getPersistenceEnvironment

      protected AbstractPersistenceEnvironment getPersistenceEnvironment()
      Return the environment that created this manager.
      Returns:
      the environment that created this manager

    • setPersistenceEnvironment

      protected void setPersistenceEnvironment(AbstractPersistenceEnvironment env)
      Configure the environment that created this manager.
      Parameters:
      env - the environment that created this manager

    • getPersistentStoreMap

      public Map<String,PS> getPersistentStoreMap()
      Return the map of open PersistentStore instances keyed by their identifiers.

      Note: The return map is "live". Any attempt to access or mutate it should be done while holding a monitor on this manager.

      Returns:
      the map of open PersistentStore instances