/* -*-c++-*- */
/* osgEarth - Dynamic map generation toolkit for OpenSceneGraph
* Copyright 2008-2013 Pelican Mapping
* http://osgearth.org
*
* osgEarth is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program.  If not, see <http://www.gnu.org/licenses/>
*/
#ifndef OSGEARTH_CACHE_BIN_H
#define OSGEARTH_CACHE_BIN_H 1

#include <osgEarth/Common>
#include <osgEarth/Config>
#include <osgEarth/IOTypes>
#include <osgDB/ReaderWriter>

namespace osgEarth
{
    /**
     * CacheBin is a names container within a Cache. It allows different
     * application modules to compartmentalize their data withing a single
     * cache location.
     */
    class /*no export*/ CacheBin : public osg::Referenced
    {
    public:
        /** returned by the getRecordStatus() function */
        enum RecordStatus {
            STATUS_NOT_FOUND,   // record is not in the cache
            STATUS_OK,          // record is in the cache and newer than the test time
            STATUS_EXPIRED      // record is in the cache and older than the test time
        };

    public:
        /**
         * Constructs a caching bin.
         * @param binID  Name of this caching bin (unique withing a Cache)
         * @param driver ReaderWriter that serializes data for this caching bin.
         */
        CacheBin( const std::string& binID ) : _binID(binID) { }

        /** dtor */
        virtual ~CacheBin() { }

        /**
         * The identifier (unique withing a Cache) of this bin.
         */
        const std::string& getID() const { return _binID; }

        /**
         * Reads an object from the cache bin.
         * @param key     Lookup key to read
         * @param minTime Fail if the entry's timestamp is older than this
         */
        virtual ReadResult readObject(const std::string& key, TimeStamp minTime) =0;

        /**
         * Reads an image from the cache bin.
         * @param key     Lookup key to read
         * @param minTime Fail if the entry's timestamp is older than this
         */
        virtual ReadResult readImage(const std::string& key, TimeStamp minTime) =0;

        /**
         * Reads a string buffer from the cache bin.
         * @param key    Lookup key to read.
         * @param minTime Fail if the entry's timestamp is older than this.
         */
        virtual ReadResult readString(const std::string& key, TimeStamp minTime) =0;

        /**
         * Writes an object (or an image) to the cache bin.
         * @param key    Lookup key to write to
         * @param object Object to serialize to the cache
         */
        virtual bool write( 
            const std::string& key, 
            const osg::Object* object,
            const Config&      metadata =Config() ) =0;

        /**
         * Gets the status of a key, i.e. not found, valid or expired.
         * Pass in a minTime = 0 to simply check whether the record exists.
         * @param key     Lookup key to check for
         * @param minTime Return EXPIRED if the key exists but is older than this
         */
        virtual RecordStatus getRecordStatus(const std::string& key, TimeStamp minTime) =0;

        /**
         * Checks whether a key exists in the cache.
         * @deprecated - Please use getRecordStatus instead
         */
        //bool isCached(const std::string& key) { 
        //    return getRecordStatus(key, 0) == STATUS_OK; }

        /**
         * Purge an entry from the cache bin
         */
        virtual bool remove(const std::string& key) =0;

        /**
         * Update a record's timestamp to "now", as if it were a
         * new entry.
         */
        virtual bool touch(const std::string& key) =0;

        /**
         * Reads custom metadata from the cache.
         */
        virtual Config readMetadata() { return Config(); }

        /**
         * Writes custom metadata to the cache.
         */
        virtual bool writeMetadata( const Config& meta ) { return false; }

        /**
         * Purges all entries in the cache bin.
         */
        virtual bool purge() = 0;

        /**
         * Store this pointer in an options structure
         */
        void apply( osgDB::Options* options ) const {
            if ( options ) options->setPluginData( "osgEarth::CacheBin", (void*)this );
        }

        /**
         * Retrieve pointer from an options struture
         */
        static CacheBin* get( const osgDB::Options* options ) {
            return options ? const_cast<CacheBin*>(static_cast<const CacheBin*>(options->getPluginData("osgEarth::CacheBin"))) : 0L;
        }

    protected:
        std::string _binID;
    };
}

#endif // OSGEARTH_CACHE_BIN_H
