Package com.tangosol.persistence

Class AbstractPersistenceManager.AbstractPersistentStore

    • Field Detail

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

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

      • 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