Package com.tangosol.persistence

Class CachePersistenceHelper

java.lang.Object
com.tangosol.persistence.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 Details

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

    • META_FILENAME

      public static final String META_FILENAME
      Persistence metadata filename.
      See Also:

    • META_IMPL_VERSION

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

    • META_STORAGE_FORMAT

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

    • META_STORAGE_VERSION

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

    • META_PARTITION_COUNT

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

    • META_SERVICE_VERSION

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

    • PERSISTENCE_VERSION

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

    • DEFAULT_BASE_DIR

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

    • DEFAULT_ACTIVE_DIR

      public static final String DEFAULT_ACTIVE_DIR
      Default active directory name.
      See Also:

    • DEFAULT_BACKUP_DIR

      public static final String DEFAULT_BACKUP_DIR
      Default backup directory name.
      See Also:

    • DEFAULT_EVENTS_DIR

      public static final String DEFAULT_EVENTS_DIR
      Default events directory name.
      See Also:

    • DEFAULT_SNAPSHOT_DIR

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

    • DEFAULT_TRASH_DIR

      public static final String DEFAULT_TRASH_DIR
      Default trash directory name.
      See Also:

    • DEFAULT_LOCK_DIR

      public static final String DEFAULT_LOCK_DIR
      Default lock directory name.
      See Also:

    • META_EXTENT

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

    • RESERVED_META_EXTENTS

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

  • Constructor Details

    • CachePersistenceHelper

      public CachePersistenceHelper()

  • Method Details

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

    • getEnvironmentInfo

      public static PersistenceEnvironmentInfo getEnvironmentInfo(ExtensibleConfigurableCacheFactory eccf, String sServiceName)
      Return the PersistenceEnvironmentInfo for a given cluster and service name using the current ConfigurableCacheFactory without starting the services.
      Parameters:
      eccf - ExtensibleConfigurableCacheFactory to use
      sServiceName - the service name to use
      Returns:
      the PersistenceEnvironmentInfo for the given service and cluster

    • 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