Package com.tangosol.persistence

Class CachePersistenceHelper

  • public class CachePersistenceHelper
extends Object
    Static helper methods used in the persistence of a partitioned cache.
    Author:
    rhl 2012.08.15
    API Note:
    this helper is intended for internal use only

    • Field Detail

      • LONG_CONVERTER_DOWN

        public static final Converter<Long,​ReadBuffer> LONG_CONVERTER_DOWN
        A converter that converts from a Long to a ReadBuffer. Note: this intentionally uses BDB's serialized form of a long and *not* Coherence's form of a long.

      • LONG_CONVERTER_UP

        public static final Converter<ReadBuffer,​Long> LONG_CONVERTER_UP
        A converter that converts from a ReadBuffer to a Long. Note: this intentionally converts from a BDBs serialized form of a long and *not* Coherence's serialized form of a long.

      • LAST_ENTRY

        public static final ReadBuffer LAST_ENTRY
        A constant that suggests to a PersistentStore implementation to load the last entry. This is expected to be used as a return from PersistentStore.Visitor.visitFromKey().

      • DEFAULT_BASE_DIR_PROPERTY

        public static final String DEFAULT_BASE_DIR_PROPERTY
        Default persistence directory system property.
        See Also:
        Constant Field Values

      • META_IMPL_VERSION

        public static final String META_IMPL_VERSION
        Persistence metadata property: implementation version.
        See Also:
        Constant Field Values

      • META_STORAGE_FORMAT

        public static final String META_STORAGE_FORMAT
        Persistence metadata property: storage format.
        See Also:
        Constant Field Values

      • META_STORAGE_VERSION

        public static final String META_STORAGE_VERSION
        Persistence metadata property: storage version.
        See Also:
        Constant Field Values

      • META_PARTITION_COUNT

        public static final String META_PARTITION_COUNT
        Persistence metadata property: partition count.
        See Also:
        Constant Field Values

      • META_SERVICE_VERSION

        public static final String META_SERVICE_VERSION
        Persistence metadata property: service version.
        See Also:
        Constant Field Values

      • PERSISTENCE_VERSION

        public static final int PERSISTENCE_VERSION
        Persistence protocol version.
        See Also:
        Constant Field Values

      • DEFAULT_BASE_DIR

        public static final String DEFAULT_BASE_DIR
        Default base persistence directory name.
        See Also:
        Constant Field Values

      • DEFAULT_SNAPSHOT_DIR

        public static final String DEFAULT_SNAPSHOT_DIR
        Default snapshot directory name.
        See Also:
        Constant Field Values

      • META_EXTENT

        public static final long META_EXTENT
        The extent-id used to store cache metadata.
        See Also:
        Constant Field Values

      • RESERVED_META_EXTENTS

        public static final int RESERVED_META_EXTENTS
        Reserve a certain number of extents identifiers for holding metadata.
        See Also:
        Constant Field Values

    • Constructor Detail

      • CachePersistenceHelper

        public CachePersistenceHelper()

    • Method Detail

      • ensurePersistenceException

        public static com.oracle.coherence.persistence.PersistenceException ensurePersistenceException​(Throwable eCause)
        Return a PersistenceException with the given cause. If the specified cause is an instance of PersistenceException, the given throwable will be returned as is; otherwise, a new PersistenceException will be allocated and returned.
        Parameters:
        eCause - an optional cause
        Returns:
        a PersistenceException with the given cause

      • ensurePersistenceException

        public static com.oracle.coherence.persistence.PersistenceException ensurePersistenceException​(Throwable eCause,
                                                                                               String sMessage)
        Return a PersistenceException with the given cause and detail message. If the specified cause is an instance of PersistenceException and the detail message is null, the given throwable will be returned as is; otherwise, a new PersistenceException will be allocated and returned.
        Parameters:
        eCause - an optional cause
        sMessage - an optional detail message
        Returns:
        a PersistenceException with the given cause and detail message

      • seal

        public static void seal​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                        PartitionedService service,
                        Object oToken)
        Seal the specified PersistentStore on behalf of the specified service, indicating that it is fully initialized and eligible to be recovered from this point forward.
        Parameters:
        store - the persistent store to seal
        service - the partitioned service
        oToken - batch token to use for the seal operation, or null
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • unseal

        public static void unseal​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store)
        Remove a seal from a PersistentStore.
        Parameters:
        store - the store the seal should be removed from

      • isSealed

        public static boolean isSealed​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store)
        Return true if the specified store has been sealed.
        Parameters:
        store - the persistent store to check
        Returns:
        true if the specified store has been sealed

      • writeQuorumRaw

        public static void writeQuorumRaw​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                  Binary binInfo)
        Write the current membership information in raw format to the "META" extent.
        Parameters:
        store - the store to write into
        binInfo - the Binary object to write to the "META" extent

      • writeQuorum

        public static Binary writeQuorum​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                 PartitionedService service)
        Write the current membership information to the "META" extent. Note: this method also seals the store.
        Parameters:
        store - the store to write into
        service - the service for which the information is stored
        Returns:
        the Binary object that was written to the "META" extent

      • readQuorumRaw

        public static Binary readQuorumRaw​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store)
        Read the membership information in Binary format from the "META" extent.
        Parameters:
        store - the store to read from
        Returns:
        the membership information in a Binary format

      • readQuorum

        public static com.tangosol.net.internal.QuorumInfo readQuorum​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store)
        Read the membership information from the "META" extent.
        Parameters:
        store - the store to read from
        Returns:
        the membership information

      • validate

        public static void validate​(com.oracle.coherence.persistence.PersistentStore store,
                            PartitionedService service)
        Validate the specified store to check that it has been sealed, indicating that it is eligible to be recovered by the specified service.

        Successful validation is determined by this method not appending to the provided StringBuilder. Failure to validate the store results in a description of the validation being appended to the provided StringBuilder.

        Parameters:
        store - the persistent store to validate
        service - the partitioned service
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • storeCacheNames

        public static void storeCacheNames​(com.oracle.coherence.persistence.PersistentStore store,
                                   LongArray laCaches)
        Persist the specified cache names in the persistent store.
        Parameters:
        store - the persistent store to store the cache names to
        laCaches - the LongArray of cache names, indexed by cache-id
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • getCacheNames

        public static LongArray<String> getCacheNames​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store)
        Return the cache names that have been stored in the specified store.
        Parameters:
        store - the persistent store to load the cache names from
        Returns:
        a LongArray of cache names, indexed by the cache-id
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • getPartitionCount

        public static int getPartitionCount​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store)
        Return the partition count that has been stored in the specified store.
        Parameters:
        store - the persistent store to load the partition count from
        Returns:
        the partition count or -1 if the specified store does not contain a partition count

      • getServiceVersion

        @Deprecated
public static String getServiceVersion​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store)
        Deprecated.
        use getPersistenceVersion(PersistentStore) instead
        Return the service version that has been stored in the specified store.
        Parameters:
        store - the persistent store to load the service version from
        Returns:
        the service version or "<none> if the specified store does not contain a service version

      • getPersistenceVersion

        public static int getPersistenceVersion​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store)
        Return the persistence version the provided store was written with.
        Parameters:
        store - the persistent store to load the persistence version from
        Returns:
        the persistence version or 0 if the specified store does not contain a persistence version

      • isGlobalPartitioningSchemePID

        public static boolean isGlobalPartitioningSchemePID​(int nPartition)
        Return true iff the specified partition-id is to be used to persist (meta-)data that is logically "global".

        In an ideal implementation, these (meta)-data would belong to a separate partitioning-scheme of a single partition (and many replicas), however today we "fake it" by artificially assigning them to a single well-known partition.

        Parameters:
        nPartition - the partition-id
        Returns:
        true iff the specified partition is to be used to persist global meta-data

      • getGlobalPartitions

        public static PartitionSet getGlobalPartitions​(PartitionedService service)
        Return a PartitionSet that contains partitions to be used to persist (meta-)data that is logically "global".
        Parameters:
        service - the service for which the global partitions are requested
        Returns:
        the PartitionSet containing global partition ids

      • deleteExtents

        public static void deleteExtents​(com.oracle.coherence.persistence.PersistentStore store,
                                 long lExtentId)
        Delete the provided extent from the specified store and all associated extents (meta extents).
        Parameters:
        store - the PersistenceStore
        lExtentId - the extent id

      • moveExtents

        public static void moveExtents​(com.oracle.coherence.persistence.PersistentStore store,
                               long lOldExtentId,
                               long lNewExtentId)
        Move the old extent to the new extent in the specified store including all associated extents (meta extents).
        Parameters:
        store - the PersistenceStore
        lOldExtentId - the old extent id
        lNewExtentId - the new extent id

      • readMetadata

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

        public static void writeMetadata​(File fileDir,
                                 Properties prop)
                          throws IOException
        Write persistence metadata to the specified directory.
        Parameters:
        fileDir - the directory to write metadata to
        prop - the metadata to write
        Throws:
        IOException - on error writing the metadata file

      • copyMetadata

        public static void copyMetadata​(File fileDirFrom,
                                File fileDirTo)
                         throws IOException
        Copy the metadata file from one directory to another.
        Parameters:
        fileDirFrom - the directory to copy from
        fileDirTo - the directory to copy to
        Throws:
        IOException - on copying the metadata

      • isMetadataComplete

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

        public static boolean isMetadataCompatible​(Properties prop,
                                           int nImplVersion,
                                           String sStorageFormat,
                                           int nStorageVersion)
        Determine if the given metadata in the Properties is compatible with the metadata supplied.
        Parameters:
        prop - the metadata to analyze
        nImplVersion - the impl version to compare
        sStorageFormat - the storage format to compare
        nStorageVersion - the storage version to compare
        Returns:
        true if the given metadata is compatible; false otherwise

      • getListenerExtentId

        protected static long getListenerExtentId​(long lCacheId)
        Return the extent identifier that contains listener registration information for the cache with the given identifier.
        Parameters:
        lCacheId - the cacheId
        Returns:
        the listener extent identifier

      • createListenerRegistrationKey

        protected static ReadBuffer createListenerRegistrationKey​(long lMemberId,
                                                          long lCacheId,
                                                          Binary binKey)
        Create a key representing a cache listener registration.
        Parameters:
        lMemberId - the unique service-identifier of the listening member
        lCacheId - the cache-id
        binKey - the key to listen to
        Returns:
        a ReadBuffer representing the listener registration

      • registerListener

        public static void registerListener​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                    long lCacheId,
                                    Binary binKey,
                                    long lListenerId,
                                    boolean fLite,
                                    Object oToken)
        Store the listener registration in the specified persistent store.
        Parameters:
        store - the PersistentStore to store the listener registration
        lCacheId - the cache-id
        binKey - the key to listen on
        lListenerId - the unique service-identifier of the listening member
        fLite - true iff the listener expects "lite" events
        oToken - batch token to use for the store operation, or null
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • unregisterListener

        public static void unregisterListener​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                      long lCacheId,
                                      Binary binKey,
                                      long lListenerId,
                                      Object oToken)
        Clear the listener registration from the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache-id
        binKey - the key
        lListenerId - the unique service-identifier of the listening member
        oToken - batch token to use for the store operation, or null
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • unregisterListeners

        public static void unregisterListeners​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                       long lCacheId)
        Clear all listener registrations for the specified cache from the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache-id
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • getLockExtentId

        protected static long getLockExtentId​(long lCacheId)
        Return the extent identifier that contains lock registration information for the cache with the given identifier.
        Parameters:
        lCacheId - the cacheId
        Returns:
        the lock extent identifier

      • createLockRegistrationKey

        protected static ReadBuffer createLockRegistrationKey​(long lHolderId,
                                                      long lHolderThreadId,
                                                      long lCacheId,
                                                      Binary binKey)
        Create a key representing a cache entry lock.
        Parameters:
        lHolderId - the unique service-identifier of the listening member
        lHolderThreadId - the thread-id of the lock holder
        lCacheId - the cache-id
        binKey - the locked key
        Returns:
        a ReadBuffer representing the cache entry lock

      • registerLock

        public static void registerLock​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                long lCacheId,
                                Binary binKey,
                                long lHolderId,
                                long lHolderThreadId,
                                Object oToken)
        Store the cache entry lock in the specified persistent store.
        Parameters:
        store - the PersistentStore to store the lock
        lCacheId - the cache-id
        binKey - the locked key
        lHolderId - the unique service-identifier of the lock holder
        lHolderThreadId - the thread-id of the lock holder
        oToken - batch token to use for the store operation, or null
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • unregisterLock

        public static void unregisterLock​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                  long lCacheId,
                                  Binary binKey,
                                  long lHolderId,
                                  long lHolderThreadId,
                                  Object oToken)
        Clear the cache entry lock from the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache-id
        binKey - the key
        lHolderId - the unique service-identifier of the lock holder
        lHolderThreadId - the thread-id of the lock holder
        oToken - batch token to use for the store operation, or null
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • unregisterLocks

        public static void unregisterLocks​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                   long lCacheId)
        Clear all cache entry locks for the specified cache from the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache-id
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • getIndexExtentId

        protected static long getIndexExtentId​(long lCacheId)
        Return the extent identifier that contains index registration information for the cache with the given identifier.
        Parameters:
        lCacheId - the cacheId
        Returns:
        the index extent identifier

      • createIndexRegistrationKey

        protected static ReadBuffer createIndexRegistrationKey​(long lCacheId,
                                                       Binary binExtractor)
        Create a key representing an index registration.
        Parameters:
        lCacheId - the cache-id
        binExtractor - the index extractor
        Returns:
        a ReadBuffer representing the index registration

      • registerIndex

        public static void registerIndex​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                 long lCacheId,
                                 Binary binExtractor,
                                 Binary binComparator,
                                 Object oToken)
        Store the index registration in the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache id
        binExtractor - the index extractor
        binComparator - the index comparator
        oToken - batch token to use for the store operation, or null
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • unregisterIndex

        public static void unregisterIndex​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                   long lCacheId,
                                   Binary binExtractor,
                                   Object oToken)
        Clear the index registration from the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache id
        binExtractor - the index extractor
        oToken - batch token to use for the store operation, or null
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • unregisterIndices

        public static void unregisterIndices​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                     long lCacheId)
        Clear all index registrations for the specified cache from the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache-id
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • getTriggerExtentId

        protected static long getTriggerExtentId​(long lCacheId)
        Return the extent identifier that contains trigger registration information for the cache with the given identifier.
        Parameters:
        lCacheId - the cacheId
        Returns:
        the trigger extent identifier

      • createTriggerRegistrationKey

        protected static ReadBuffer createTriggerRegistrationKey​(long lCacheId,
                                                         Binary binTrigger)
        Create a key representing an trigger registration.
        Parameters:
        lCacheId - the cache-id
        binTrigger - the trigger
        Returns:
        a ReadBuffer representing the trigger registration

      • registerTrigger

        public static void registerTrigger​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                   long lCacheId,
                                   Binary binTrigger,
                                   Object oToken)
        Store the trigger registration in the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache id
        binTrigger - the trigger
        oToken - batch token to use for the store operation, or null
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • unregisterTrigger

        public static void unregisterTrigger​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                     long lCacheId,
                                     Binary binTrigger,
                                     Object oToken)
        Clear the trigger registration from the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache id
        binTrigger - the trigger
        oToken - batch token to use for the store operation, or null
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • unregisterTriggers

        public static void unregisterTriggers​(com.oracle.coherence.persistence.PersistentStore<ReadBuffer> store,
                                      long lCacheId)
        Clear all trigger registrations for the specified cache from the specified persistent store.
        Parameters:
        store - the persistent store
        lCacheId - the cache-id
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if the persistent store operations fail

      • resumeService

        public static void resumeService​(Cluster cluster,
                                 String sServiceName)
        Resume a service on a separate thread and wait for the resume to complete.
        Parameters:
        cluster - the cluster to resume service for
        sServiceName - the service to resume

      • getSnapshotPersistenceTools

        public static com.oracle.datagrid.persistence.PersistenceTools getSnapshotPersistenceTools​(File dirSnapshot)
        Return an implementation specific instance of PersistenceTools for the given local snapshot directory.
        Parameters:
        dirSnapshot - the snapshot directory to get tools for
        Returns:
        an implementation specific instance of PersistenceTools
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if any errors

      • getArchiverPersistenceTools

        public static com.oracle.datagrid.persistence.PersistenceTools getArchiverPersistenceTools​(ExtensibleConfigurableCacheFactory eccf,
                                                                                           String sSnapshotName,
                                                                                           String sServiceName)
        Return an implementation specific instance of PersistenceTools for the given archived snapshot.
        Parameters:
        eccf - ExtensibleConfigurableCacheFactory to use
        sSnapshotName - the snapshot to get tools
        sServiceName - the service name to get tools
        Returns:
        an implementation specific instance of PersistenceTools
        Throws:
        com.oracle.coherence.persistence.PersistenceException - if any errors

      • getClusterName

        protected static String getClusterName()
        Return the cluster name without starting the cluster service.
        Returns:
        the name of the cluster

      • instantiatePersistenceVisitor

        public static com.oracle.coherence.persistence.PersistentStore.Visitor<ReadBuffer> instantiatePersistenceVisitor​(CachePersistenceHelper.Visitor visitorCache)
        Instantiate a visitor for the PersistentStore backed by the
        Parameters:
        visitorCache - the cache visitor to delegate to
        Returns:
        a visitor for the PersistentStore

      • getMBeanName

        public static String getMBeanName​(String sService)
        Obtain the PersistenceManagerMBean name for a given service.
        Parameters:
        sService - the service name
        Returns:
        the MBean name

      • instantiateEventsVisitor

        public static com.oracle.coherence.persistence.PersistentStore.Visitor<ReadBuffer> instantiateEventsVisitor​(long lExtentId,
                                                                                                            Set setKeys,
                                                                                                            long lVersion,
                                                                                                            Map<Long,​MapEvent> mapEvents,
                                                                                                            Converter<Long,​ReadBuffer> convKeyDown,
                                                                                                            Converter<ReadBuffer,​Long> convKeyUp,
                                                                                                            Converter<Object,​ReadBuffer> convDown,
                                                                                                            Converter<ReadBuffer,​Object> convUp)
        Create a PersistentStore.Visitor that can read a PersistentStore and populate the provided mapEvents with events that are larger than the provided version (inclusive) and within the given set of keys.
        Parameters:
        lExtentId - the extent id to interrogate
        setKeys - a set of keys the MapEvent should be raised within
        lVersion - the version that all events should be larger than (inclusive)
        mapEvents - a Map to store the MapEvents
        convKeyDown - a converter that can convert a version to a binary
        convKeyUp - a converter that can convert a binary to a version
        convDown - a converter that can convert an MapEvent to a binary
        convUp - a converter that can convert an MapEvent to a binary
        Returns:
        a Visitor that can read a PersistentStore and populate the provided map of events

      • instantiateEventsVisitor

        public static com.oracle.coherence.persistence.PersistentStore.Visitor<ReadBuffer> instantiateEventsVisitor​(long lExtentId,
                                                                                                            Filter filter,
                                                                                                            long lVersion,
                                                                                                            Map<Long,​MapEvent> mapEvents,
                                                                                                            Converter<Long,​ReadBuffer> convKeyDown,
                                                                                                            Converter<ReadBuffer,​Long> convKeyUp,
                                                                                                            Converter<Object,​ReadBuffer> convDown,
                                                                                                            Converter<ReadBuffer,​Object> convUp)
        Create a PersistentStore.Visitor that can read a PersistentStore and populate the provided mapEvents with events that are larger than the provided version (inclusive) and match the given Filter.
        Parameters:
        lExtentId - the extent id to interrogate
        filter - a Filter to test the MapEvents against
        lVersion - the version that all events should be larger than (inclusive)
        mapEvents - a Map to store the MapEvents
        convKeyDown - a converter that can convert a version to a binary
        convKeyUp - a converter that can convert a binary to a version
        convDown - a converter that can convert an MapEvent to a binary
        convUp - a converter that can convert an MapEvent to a binary
        Returns:
        a Visitor that can read a PersistentStore and populate the provided map of events