Package com.tangosol.persistence

Class AbstractPersistenceManager<PS extends AbstractPersistenceManager.AbstractPersistentStore>

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

    • Field Detail

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • STORE_STATE_CLOSED

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

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

      • m_fReleased

        protected volatile boolean m_fReleased
        Whether this PersistenceManager has been released.

      • m_pool

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

    • Constructor Detail

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

      • 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

      • 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.datagrid.persistence.PersistenceTools getPersistenceTools()
        Description copied from interface: com.oracle.datagrid.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>
        Specified by:
        getPersistenceTools in interface com.oracle.datagrid.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.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.Task task)
        Submit the given task for execution by the daemon pool.
        Parameters:
        task - the task to submit

      • executeTask

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

      • executeTaskExclusive

        protected void executeTaskExclusive​(AbstractPersistenceManager.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.datagrid.persistence.PersistenceTools instantiatePersistenceTools​(com.oracle.datagrid.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