/* -*-c++-*- */
/* osgEarth - Dynamic map generation toolkit for OpenSceneGraph
* Copyright 2015 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.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
* IN THE SOFTWARE.
*
* 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), _hashKeys(false), _minTime(0) { }

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

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

        /**
         * Whether the implemention should hash record keys instead of using
         * them directly. Default = false.
         */
        void setHashKeys(bool value) { _hashKeys = value; }
        bool getHashKeys() const { return _hashKeys; }

        /**
         * Reads an object from the cache bin.
         * @param key     Lookup key to read         
         */
        virtual ReadResult readObject(const std::string& key) =0;

        /**
         * Reads an image from the cache bin.
         * @param key     Lookup key to read         
         */
        virtual ReadResult readImage(const std::string& key) =0;

        /**
         * Reads a string buffer from the cache bin.
         * @param key    Lookup key to read.
         */
        virtual ReadResult readString(const std::string& key) =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         
         */
        virtual RecordStatus getRecordStatus(const std::string& key) =0;

        /**
         * 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 clear() { return false; }

        /**
         * Compacts the cache bin (where applicable)
         */
        virtual bool compact() { return false; }

        /**
         * Returns the approximate disk space being used by this cache,
         * or 0 if unavailable.
         */
        virtual unsigned getStorageSize() { return 0u; }

        /**
         * 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;
        }


    public: //deprecated

        /** @deprecated - use clear */
        bool purge() { return clear(); } // backwards compatibility


    protected:
        std::string _binID;
        bool        _hashKeys;
        TimeStamp   _minTime;
    };
}

#endif // OSGEARTH_CACHE_BIN_H
