icache.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: icache.hpp,v $
 * PRODUCTION Revision 1000.3  2004/06/01 19:39:14  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.4
 * PRODUCTION
 * ===========================================================================
 */

#ifndef UTIL___ICACHE__HPP
#define UTIL___ICACHE__HPP

/*  $Id: icache.hpp,v 1000.3 2004/06/01 19:39:14 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Authors:  Anatoliy Kuznetsov
 *
 * File Description: cache interface specs.
 *
 */

/// @file icache.hpp
/// Cache interface specs. 
///
/// File describes interfaces used to create local cache of 
/// binary large objects (BLOBS).


#include <corelib/plugin_manager_impl.hpp>
#include <util/reader_writer.hpp>
#include <string>


BEGIN_NCBI_SCOPE



/// BLOB cache read/write/maintanance interface.
///
/// ICache describes caching service. Any large binary object
/// can be stored in cache and later retrived. Such cache is a 
/// temporary storage and some objects can be purged from cache based
/// on an immediate request, version or access time 
/// based replacement (or another implementation specific depreciation rule).
///
/// Cache elements are accesed by key-subkey pair. 
/// 
class ICache
{
public:
    
    /// ICache can keeps timestamps of every cache entry.
    /// This enum defines the policy how it is managed.
    /// Different policies can be combined by OR (|)
    /// @sa SetTimeStampPolicy
    enum ETimeStampPolicy {

        /// Timestamp management disabled
        fNoTimeStamp       = 0,

        /// Cache element is created with a certain timestamp (default)
        fTimeStampOnCreate = (1 << 0),

        /// Timestamp is updated every on every access (read or write)
        fTimeStampOnRead   = (1 << 1),
        
        /// Timestamp full key-subkey pair. By default only key is taken
        /// into account
        fTrackSubKey       = (1 << 2),

        /// Expire objects older than a certain time frame
        /// Example: If object is not accessed within a week it is 
        ///          droped from the cache.
        fExpireLeastFrequentlyUsed  = (1 << 3),

        /// Expired objects should be deleted on cache mount (Open)
        fPurgeOnStartup             = (1 << 4),

        /// Expiration timeout is checked on any access to cache element
        fCheckExpirationAlways      = (1 << 5)
    };

    typedef int TTimeStampFlags;

    /// Set timestamp update policy
    /// @param policy
    ///   ORed combination of TimeStampUpdatePolicy masks.
    virtual void SetTimeStampPolicy(TTimeStampFlags policy, int timeout) = 0;

    /// Get timestamp policy
    /// @return
    ///    Timestamp policy
    virtual TTimeStampFlags GetTimeStampPolicy() const = 0;

    /// Get expiration timeout
    /// @return
    ///    Expiration timeout in seconds
    /// @sa GetExpirationPolicy(), SetExpirationPolicy()
    virtual int GetTimeout() = 0;


    /// If to keep already cached versions of the BLOB when storing
    /// another version of it (not necessarily a newer one)
    /// @sa Store(), GetWriteStream()
    enum EKeepVersions {
        /// Do not delete other versions of cache entries
        eKeepAll,
        /// Delete the earlier (than the one being stored) versions of
        /// the BLOB
        eDropOlder,
        /// Delete all versions of the BLOB, even those which are newer
        /// than the one being stored
        eDropAll
    };

    /// Set version retention policy
    ///
    /// @param policy
    ///    Version retetion mode
    virtual void SetVersionRetention(EKeepVersions policy) = 0;

    /// Get version retention
    virtual EKeepVersions GetVersionRetention() const = 0;

    /// Add or replace BLOB
    ///
    /// @param key 
    ///    BLOB identification key
    /// @param key 
    ///    BLOB identification sub-key
    /// @param version 
    ///    BLOB version
    /// @param data 
    ///    pointer on data buffer
    /// @param size 
    ///    data buffer size in bytes (chars)
    /// @param flag 
    ///    indicator to keep old BLOBs or drop it from the cache
    virtual void Store(const string&  key,
                       int            version,
                       const string&  subkey,
                       const void*    data,
                       size_t         size) = 0;

    /// Check if BLOB exists, return BLOB size.
    ///
    /// @param key 
    ///    BLOB identification key
    /// @param subkey
    ///    BLOB identification subkey
    /// @param version 
    ///    BLOB version
    /// @return 
    ///    BLOB size or 0 if it doesn't exist or expired
    virtual size_t GetSize(const string&  key,
                           int            version,
                           const string&  subkey) = 0;

    /// Fetch the BLOB
    ///
    /// @param key 
    ///    BLOB identification key
    /// @param subkey
    ///    BLOB identification subkey
    /// @param version 
    ///    BLOB version
    /// @param 
    ///    buf pointer on destination buffer
    /// @param 
    ///    size buffer size in bytes (chars)
    /// @return 
    ///    FALSE if BLOB doesn't exist or expired
    ///
    /// @note Throws an exception if provided memory buffer is insufficient 
    /// to read the BLOB
    virtual bool Read(const string& key, 
                      int           version, 
                      const string& subkey,
                      void*         buf, 
                      size_t        buf_size) = 0;

    /// Return sequential stream interface to read BLOB data.
    /// 
    /// @param key 
    ///    BLOB identification key
    /// @param subkey
    ///    BLOB identification subkey
    /// @param version 
    ///    BLOB version
    /// @return Interface pointer or NULL if BLOB does not exist
    virtual IReader* GetReadStream(const string&  key, 
                                   int            version,
                                   const string&  subkey) = 0;

    /// Return sequential stream interface to write BLOB data.
    ///
    /// @param key 
    ///    BLOB identification key
    /// @param subkey
    ///    BLOB identification subkey
    /// @param version 
    ///    BLOB version
    /// @return Interface pointer or NULL if BLOB does not exist
    virtual IWriter* GetWriteStream(const string&    key,
                                    int              version,
                                    const string&    subkey) = 0;

    /// Remove all versions of the specified BLOB
    ///
    /// @param key BLOB identification key
    virtual void Remove(const string& key) = 0;

    /// Return last access time for the specified cache entry
    ///
    /// Class implementation may want to implement access time based
    /// aging scheme for cache managed objects. In this case it needs to
    /// track time of every request to BLOB data.
    ///
    /// @param key 
    ///    BLOB identification key
    /// @param subkey
    ///    BLOB identification subkey
    /// @param version 
    ///    BLOB version
    /// @return 
    ///    last access time
    /// @sa TimeStampUpdatePolicy
    virtual time_t GetAccessTime(const string&  key,
                                 int            version,
                                 const string&  subkey) = 0;

    /// Delete all BLOBs older than specified
    ///
    /// @param access_timeout
    ///    Time in seconds. All objects older than this are deleted.
    /// @param keep_last_version 
    ///    type of cleaning action
    virtual void Purge(time_t           access_timeout,
                       EKeepVersions    keep_last_version = eDropAll) = 0;

    /// Delete BLOBs with access time older than specified
    /// 
    /// Function finds all BLOB versions with the specified key
    /// and removes the old instances.
    /// @param key
    ///    BLOB key
    /// @param subkey
    ///    BLOB identification subkey
    /// @param access_timeout 
    ///    Time in seconds. All objects older than this are deleted.
    /// @param keep_last_version 
    ///    type of cleaning action
    virtual void Purge(const string&    key,
                       const string&    subkey,
                       time_t           access_timeout,
                       EKeepVersions    keep_last_version = eDropAll) = 0;


    virtual ~ICache() {}
};


NCBI_DECLARE_INTERFACE_VERSION(ICache,  "icache", 1, 1, 0);


END_NCBI_SCOPE


/*
 * ===========================================================================
 * $Log: icache.hpp,v $
 * Revision 1000.3  2004/06/01 19:39:14  gouriano
 * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.4
 *
 * Revision 1.4  2004/04/19 18:05:40  kuznets
 * Clarification in the comments department
 *
 * Revision 1.3  2003/12/08 16:11:43  kuznets
 * Added plugin mananger support
 *
 * Revision 1.2  2003/11/25 17:12:54  kuznets
 * Reworked cache maintanance methods.
 * Unified cache items expiration functions.
 *
 * Revision 1.1  2003/11/21 12:51:31  kuznets
 * Added new refactored interface for local caching.
 * It's supposed after some work to replace the existing BLOB cache and Int
 * cache and work for all our caching needs.
 * Interface is in the design stage now, all comments are welcome.
 *
 * ===========================================================================
 */

#endif  /* UTIL___BLOB_CACHE__HPP */