Package org.apache.manifoldcf.core.interfaces

Interface ICacheManager

  • All Known Implementing Classes:
    CacheManager
    public interface ICacheManager
    This interface describes the functionality in the cache manager. It is not meant to have multiple implementations, but merely to provide general abstract cross-cluster cache management services.

    • Method Detail

      • findObjectsAndExecute

        void findObjectsAndExecute​(ICacheDescription[] locateObjectDescriptions,
                           StringSet invalidateKeys,
                           ICacheExecutor execObject,
                           java.lang.String transactionID)
                    throws ManifoldCFException
        Locate or create a set of objects in the cached object pool, and/or destroy and invalidate the same or other objects. For each "locate" object described below, one of two things will happen: the execObject's exists() method will be called (if the object exists in the cache already), or the execObject's create*() family of methods will be called. When all objects have been declared to the execObject, finally the execute() method will be called. In both cases, all objects are considered to be locked, and cannot be invalidated until the lock is cleared (after the end of the called method). For the invalidation descriptions, the execObject's destroy() method will be called instead. The object will be invalidated from the cache at the end of the findObjectsAndExecute() operation. It is perfectly legal to include an object that will be invalidated in the locate set! If an error occurs during object creation, the execute() method will NOT be called. If the execute() method has an error, the objects that were created will still be recorded in the cache.
        Parameters:
        locateObjectDescriptions - is a set of description objects that uniquely describe the objects needed. May be null if no objects are desired.
        invalidateKeys - are the keys to invalidate after successful execution. May be null.
        execObject - is the cache execution object whose create() or execute() methods will be called. May be null if no in-section logic is desired, and no objects are specified.
        transactionID - is the current transaction identifier, or null. Objects created within this call will be associated with this transaction; they will be purged from the cache should the transaction be rolled back.
        Throws:
        ManifoldCFException

      • enterCache

        ICacheHandle enterCache​(ICacheDescription[] locateObjectDescriptions,
                        StringSet invalidateKeys,
                        java.lang.String transactionID)
                 throws ManifoldCFException
        Second way of doing cache management. Basically, this approach breaks the findObjectsAndExecute() method down into bite-sized chunks. The goal is additional flexibility, and an executor object does not need to be defined. Pretty much everything else is identical. The objects returned by the manager methods provide context control and enforce the proper ordering and nesting. This method enters the cacher and builds a cache handle. Once a cache handle is returned, the calling code MUST, under all circumstances, leave the cache using the same handle.
        Parameters:
        locateObjectDescriptions - is a set of description objects that uniquely describe the objects needed. May be null if no objects are desired.
        invalidateKeys - are the keys to invalidate after successful execution. May be null.
        transactionID - is the current transaction identifier, or null. Objects created within this block will be associated with this transaction; they will be purged from the cache should the transaction be rolled back.
        Returns:
        a cache handle.
        Throws:
        ManifoldCFException

      • enterCreateSection

        ICacheCreateHandle enterCreateSection​(ICacheHandle handle)
                               throws ManifoldCFException
        Enter a creation critical section. This insures that only one thread is creating the specified objects at a time. This MUST be paired with a leaveCreateSection() method call, whatever happens.
        Parameters:
        handle - is the cache handle.
        Throws:
        ManifoldCFException

      • lookupObject

        java.lang.Object lookupObject​(ICacheCreateHandle handle,
                              ICacheDescription objectDescription)
                       throws ManifoldCFException
        Lookup an object. Returns null if object not found. If it is found, object's LRU and expiration info are updated. The objectDescription passed MUST be one of the ones specified in the enclosing enterCache() method.
        Parameters:
        handle - is the handle to use for the create.
        objectDescription - is the description of the object to look up.
        Throws:
        ManifoldCFException

      • saveObject

        void saveObject​(ICacheCreateHandle handle,
                ICacheDescription objectDescription,
                java.lang.Object object)
         throws ManifoldCFException
        Save a newly created object. The object MUST be one of those identified in the enterCache() method.
        Parameters:
        handle - is the create handle.
        objectDescription - is the object description.
        object - is the object.
        Throws:
        ManifoldCFException

      • invalidateKeys

        void invalidateKeys​(ICacheHandle handle)
             throws ManifoldCFException
        Invalidate keys. The keys invalidated are what got passed to the enterCache() method.
        Parameters:
        handle - is the cache handle. Does nothing if a null set of keys was passed in.
        Throws:
        ManifoldCFException

      • startTransaction

        void startTransaction​(java.lang.String startingTransactionID,
                      java.lang.String enclosingTransactionID)
               throws ManifoldCFException
        Begin a cache transaction. This keeps track of the relationship between objects cached within transactions.
        Parameters:
        startingTransactionID - is the id of the transaction that is starting.
        enclosingTransactionID - is the id of the transaction that is in effect, or null.
        Throws:
        ManifoldCFException

      • commitTransaction

        void commitTransaction​(java.lang.String transactionID)
                throws ManifoldCFException
        Commit a cache transaction. This method MUST be called when a transaction successfully ends, or open locks will not be closed!!! All cache activity that has taken place inside the transaction will be resolved, and the cache locks held open will be released.
        Parameters:
        transactionID - is the id of the transaction that is ending.
        Throws:
        ManifoldCFException

      • rollbackTransaction

        void rollbackTransaction​(java.lang.String transactionID)
                  throws ManifoldCFException
        Roll back a cache transaction. This method releases all objects cached against the ending transaction ID, and releases all locks held for the transaction.
        Parameters:
        transactionID - is the id of the transaction that is ending.
        Throws:
        ManifoldCFException

      • expireObjects

        void expireObjects​(long currentTimestamp)
            throws ManifoldCFException
        Timed invalidation. Call this periodically to get rid of all objects that have expired.
        Parameters:
        currentTimestamp - is the current time in milliseconds since epoch.
        Throws:
        ManifoldCFException