// -*- mode: c++; c-basic-offset:4 -*-

// This file is part of libdap, A C++ implementation of the OPeNDAP Data

// Access Protocol.

// Copyright (c) 2002,2003 OPeNDAP, Inc.

// Author: James Gallagher <jgallagher@opendap.org>

//

// This library 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.1 of the License, or (at your option) any later version.

//

// This library 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 library; if not, write to the Free Software

// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

//

// You can contact OPeNDAP, Inc. at PO Box 112, Saunderstown, RI. 02874-0112.

#include "config.h"

// #define DODS_DEBUG

// #define DODS_DEBUG2

#undef USE_GETENV

#include <pthread.h>

#include <limits.h>

#include <unistd.h>   // for stat

#include <sys/types.h>  // for stat and mkdir

#include <sys/stat.h>

#include <cstring>

#include <cerrno>

#include <iostream>

#include <sstream>

#include <algorithm>

#include <iterator>

#include <set>

#include "Error.h"

#include "InternalErr.h"

#include "ResponseTooBigErr.h"

#ifndef WIN32

#include "SignalHandler.h"

#endif

#include "HTTPCacheInterruptHandler.h"

#include "HTTPCacheTable.h"

#include "HTTPCache.h"

#include "HTTPCacheMacros.h"

#include "SignalHandlerRegisteredErr.h"

#include "util_mit.h"

#include "debug.h"

using namespace std;

namespace libdap {

HTTPCache *HTTPCache::_instance = 0;

// instance_mutex is used to ensure that only one instance is created.

// That is, it protects the body of the HTTPCache::instance() method. This

// mutex is initialized from within the static function once_init_routine()

// and the call to that takes place using pthread_once_init() where the mutex

// once_block is used to protect that call. All of this ensures that no matter

// how many threads call the instance() method, only one instance is ever

// made.

static pthread_mutex_t instance_mutex;

static pthread_once_t once_block = PTHREAD_ONCE_INIT;

#define NO_LM_EXPIRATION 24*3600 // 24 hours

#define DUMP_FREQUENCY 10 // Dump index every x loads

#define MEGA 0x100000L

#define CACHE_TOTAL_SIZE 20 // Default cache size is 20M

#define CACHE_FOLDER_PCT 10 // 10% of cache size for metainfo etc.

#define CACHE_GC_PCT 10  // 10% of cache size free after GC

#define MIN_CACHE_TOTAL_SIZE 5 // 5M Min cache size

#define MAX_CACHE_ENTRY_SIZE 3 // 3M Max size of single cached entry

static void

once_init_routine()

{

    int status;

    status = INIT(&instance_mutex);

    if (status != 0)

        throw InternalErr(__FILE__, __LINE__, "Could not initialize the HTTP Cache mutex. Exiting.");

}

/** Get a pointer to the HTTP 1.1 compliant cache. If not already

    instantiated, this creates an instance of the HTTP cache object and

    initializes it to use \c cache_root as the location of the persistent

    store. If there's an index (\c .index) file in that directory, it is read

    as part of the initialization. If the cache has already been initialized,

    this method returns a pointer to that instance. Note HTTPCache uses the

    singleton pattern; A process may have only one instance of this object.

    Also note that HTTPCache is MT-safe. However, if the \c force parameter

    is set to true, it may be possible for two or more processes to access

    the persistent store at the same time resulting in undefined behavior.

    Default values: is_cache_enabled(): true, is_cache_protected(): false,

    is_expire_ignored(): false, the total size of the cache is 20M, 2M of that

    is reserved for response headers, during GC the cache is reduced to at

    least 18M (total size - 10% of the total size), and the max size for an

    individual entry is 3M. It is possible to change the size of the cache,

    but not to make it smaller than 5M. If expiration information is not sent

    with a response, it is assumed to expire in 24 hours.

    @param cache_root The fully qualified pathname of the directory which

    will hold the cache data (i.e., the persistent store).

    @param force Force access to the persistent store if true. By default

    false. Use this only if you're sure no one else is using the same cache

    root! This is included so that programs may use a cache that was

    left in an inconsistent state.

    @return A pointer to the HTTPCache object.

    @exception Error thrown if the cache root cannot set. */

HTTPCache *

HTTPCache::instance(const string &cache_root, bool force)

{

    int status = pthread_once(&once_block, once_init_routine);

    if (status != 0)

        throw InternalErr(__FILE__, __LINE__, "Could not initialize the HTTP Cache mutex. Exiting.");

    LOCK(&instance_mutex);

    DBG(cerr << "Entering instance(); (" << hex << _instance << dec << ")" << "... ");

    try {

        if (!_instance) {

            _instance = new HTTPCache(cache_root, force);

            DBG(cerr << "New instance: " << _instance << ", cache root: "

                << _instance->d_cache_root << endl);

            atexit(delete_instance);

#ifndef WIN32

            // Register the interrupt handler. If we've already registered

            // one, barf. If this becomes a problem, hack SignalHandler so

            // that we can chain these handlers... 02/10/04 jhrg

            //

            // Technically we're leaking memory here. However, since this

            // class is a singleton, we know that only three objects will

            // ever be created and they will all exist until the process

            // exits. We can let this slide... 02/12/04 jhrg

            EventHandler *old_eh = SignalHandler::instance()->register_handler(SIGINT, new HTTPCacheInterruptHandler, true);

            if (old_eh) {

                SignalHandler::instance()->register_handler(SIGINT, old_eh);

                throw SignalHandlerRegisteredErr(

                    "Could not register event handler for SIGINT without superseding an existing one.");

            }

            old_eh = SignalHandler::instance()->register_handler(SIGPIPE, new HTTPCacheInterruptHandler, true);

            if (old_eh) {

                SignalHandler::instance()->register_handler(SIGPIPE, old_eh);

                throw SignalHandlerRegisteredErr(

                    "Could not register event handler for SIGPIPE without superseding an existing one.");

            }

            old_eh = SignalHandler::instance()->register_handler(SIGTERM, new HTTPCacheInterruptHandler, true);

            if (old_eh) {

                SignalHandler::instance()->register_handler(SIGTERM, old_eh);

                throw SignalHandlerRegisteredErr(

                    "Could not register event handler for SIGTERM without superseding an existing one.");

            }

#endif

        }

    }

    catch (...) {

        DBG2(cerr << "The constructor threw an Error!" << endl);

        UNLOCK(&instance_mutex);

        throw;

    }

    UNLOCK(&instance_mutex);

    DBGN(cerr << "returning " << hex << _instance << dec << endl);

    return _instance;

}

/** This static method is called using atexit(). It deletes the singleton;

    see ~HTTPCache for all that implies. */

void

HTTPCache::delete_instance()

{

    DBG(cerr << "Entering delete_instance()..." << endl);

    if (HTTPCache::_instance) {

        DBG(cerr << "Deleting the cache: " << HTTPCache::_instance << endl);

        delete HTTPCache::_instance;

        HTTPCache::_instance = 0;

        //Now remove the signal handlers

        delete SignalHandler::instance()->remove_handler(SIGINT);

        delete SignalHandler::instance()->remove_handler(SIGPIPE);

        delete SignalHandler::instance()->remove_handler(SIGTERM);

    }

    DBG(cerr << "Exiting delete_instance()" << endl);

}

/** Create an instance of the HTTP 1.1 compliant cache. This initializes the

    both the cache root and the path to the index file. It then reads the

    cache index file if one is present.

    A private method.

    @note This assumes that the cache directory structure should be created!

    @param cache_root The fully qualified pathname of the directory which

    will hold the cache data.

    @param force Force access to the persistent store!

    @exception Error Thrown if the single user/process lock for the

    persistent store cannot be obtained.

    @see cache_index_read */

HTTPCache::HTTPCache(string cache_root, bool force) :

        d_locked_open_file(0),

        d_cache_enabled(false),

        d_cache_protected(false),

        d_cache_disconnected(DISCONNECT_NONE),

        d_expire_ignored(false),

        d_always_validate(false),

        d_total_size(CACHE_TOTAL_SIZE * MEGA),

        d_folder_size(CACHE_TOTAL_SIZE / CACHE_FOLDER_PCT),

        d_gc_buffer(CACHE_TOTAL_SIZE / CACHE_GC_PCT),

        d_max_entry_size(MAX_CACHE_ENTRY_SIZE * MEGA),

        d_default_expiration(NO_LM_EXPIRATION),

        d_max_age(-1),

        d_max_stale(-1),

        d_min_fresh(-1),

        d_http_cache_table(0)

{

    DBG(cerr << "Entering the constructor for " << this << "... ");

#if 0

	int status = pthread_once(&once_block, once_init_routine);

	if (status != 0)

		throw InternalErr(__FILE__, __LINE__, "Could not initialize the HTTP Cache mutex. Exiting.");

#endif

	INIT(&d_cache_mutex);

	// This used to throw an Error object if we could not get the

	// single user lock. However, that results in an invalid object. It's

	// better to have an instance that has default values. If we cannot get

	// the lock, make sure to set the cache as *disabled*. 03/12/03 jhrg

	//

	// I fixed this block so that the cache root is set before we try to get

	// the single user lock. That was the fix for bug #661. To make that

	// work, I had to move the call to create_cache_root out of

	// set_cache_root(). 09/08/03 jhrg

	set_cache_root(cache_root);

	int block_size;

	if (!get_single_user_lock(force))

	    throw Error(internal_error, "Could not get single user lock for the cache");

#ifdef WIN32

	//  Windows is unable to provide us this information.  4096 appears

	//  a best guess.  It is likely to be in the range [2048, 8192] on

	//  windows, but will the level of truth of that statement vary over

	//  time ?

	block_size = 4096;

#else

	struct stat s;

	if (stat(cache_root.c_str(), &s) == 0)

		block_size = s.st_blksize;

	else

		throw Error(internal_error, "Could not set file system block size.");

#endif

	d_http_cache_table = new HTTPCacheTable(d_cache_root, block_size);

	d_cache_enabled = true;

	DBGN(cerr << "exiting" << endl);

}

/** Destroy an instance of HTTPCache. This writes the cache index and frees

    the in-memory cache table structure. The persistent cache (the response

    headers and bodies and the index file) are not removed. To remove those,

    either erase the directory that contains the cache using a file system

    command or use the purge_cache() method (which leaves the cache directory

    structure in place but removes all the cached information).

    This class uses the singleton pattern. Clients should \e never call this

    method. The HTTPCache::instance() method arranges to call the

    HTTPCache::delete_instance() using \c atexit(). If delete is called more

    than once, the result will likely be an index file that is corrupt. */

HTTPCache::~HTTPCache()

{

    DBG(cerr << "Entering the destructor for " << this << "... ");

    try {

        if (startGC())

            perform_garbage_collection();

        d_http_cache_table->cache_index_write();

    }

    catch (Error &e) {

        // If the cache index cannot be written, we've got problems. However,

        // unless we're debugging, still free up the cache table in memory.

        // How should we let users know they cache index is not being

        // written?? 10/03/02 jhrg

        DBG(cerr << e.get_error_message() << endl);

    }

    delete d_http_cache_table;

    release_single_user_lock();

    DBGN(cerr << "exiting destructor." << endl);

    DESTROY(&d_cache_mutex);

}

/** @name Garbage collection

    These private methods manage the garbage collection tasks for the cache. */

//@{

/** Enough removed from cache? A private method.

    @return True if enough has been removed from the cache. */

bool

HTTPCache::stopGC() const

{

    return (d_http_cache_table->get_current_size() + d_folder_size < d_total_size - d_gc_buffer);

}

/** Is there too much in the cache. A private method.

    @todo Modify this method so that it does not count locked entries. See

    the note for hits_gc().

    @return True if garbage collection should be performed. */

bool

HTTPCache::startGC() const

{

    DBG(cerr << "startGC, current_size: " << d_http_cache_table->get_current_size() << endl);

    return (d_http_cache_table->get_current_size() + d_folder_size > d_total_size);

}

/** Perform garbage collection on the cache. First, all expired responses are

    removed. Then, if the size of the cache is still too large, the cache is

    scanned for responses larger than the max_entry_size property. At the

    same time, responses are removed based on the number of cache hits. This

    process continues until the size of the cache has been reduced to 90% of

    the max_size property value. Once the garbage collection is complete,

    update the index file. Note that locked entries are not removed!

    A private method.

    @see stopGC

    @see expired_gc

    @see hits_gc */

void

HTTPCache::perform_garbage_collection()

{

    DBG(cerr << "Performing garbage collection" << endl);

    // Remove all the expired responses.

    expired_gc();

    // Remove entries larger than max_entry_size.

    too_big_gc();

    // Remove entries starting with zero hits, 1, ..., until stopGC()

    // returns true.

    hits_gc();

}

/** Scan the current cache table and remove anything that has expired. Don't

    remove locked entries.

    A private method. */

void

HTTPCache::expired_gc()

{

    if (!d_expire_ignored) {

        d_http_cache_table->delete_expired_entries();

    }

}

/** Scan the cache for entires that are larger than max_entry_size. Also

    start removing entires with low hit counts. Start looking for entries

    with zero hits, then one, and so on. Stop when the method stopGC returns

    true. Locked entries are never removed.

    @note Potential infinite loop. What if more than 80% of the cache holds

    entries that are locked? One solution is to modify startGC() so that it

    does not count locked entries.

    @todo Change this method to that it looks at the oldest entries first,

    using the CacheEntry::date to determine entry age. Using the current

    algorithm it's possible to remove the latest entry which is probably not

    what we want.

    A private method. */

void

HTTPCache::hits_gc()

{

    int hits = 0;

    if (startGC()) {

		while (!stopGC()) {

			d_http_cache_table->delete_by_hits(hits);

			hits++;

		}

	}

}

/** Scan the current cache table and remove anything that has is too big.

 	Don't remove locked entries.

    A private method. */

void HTTPCache::too_big_gc() {

	if (startGC())

		d_http_cache_table->delete_by_size(d_max_entry_size);

}

//@} End of the garbage collection methods.

/** Lock the persistent store part of the cache. Return true if the cache lock

    was acquired, false otherwise. This is a single user cache, so it

    requires locking at the process level.

    A private method.

    @param force If True force access to the persistent store. False by

    default.

    @return True if the cache was locked for our use, False otherwise. */

bool HTTPCache::get_single_user_lock(bool force) 

{

    if (!d_locked_open_file) {

	FILE * fp = NULL;

	try {

	    // It's OK to call create_cache_root if the directory already

	    // exists.

	    create_cache_root(d_cache_root);

	}

	catch (Error &e) {

	    // We need to catch and return false because this method is

	    // called from a ctor and throwing at this point will result in a

	    // partially constructed object. 01/22/04 jhrg

	    DBG(cerr << "Failure to create the cache root" << endl);

	    return false;

	}

	// Try to read the lock file. If we can open for reading, it exists.

	string lock = d_cache_root + CACHE_LOCK;

	if ((fp = fopen(lock.c_str(), "r")) != NULL) {

	    int res = fclose(fp);

	    if (res) {

		DBG(cerr << "Failed to close " << (void *)fp << endl);

	    }

	    if (force)

		REMOVE(lock.c_str());

	    else

		return false;

	}

	if ((fp = fopen(lock.c_str(), "w")) == NULL) {

	    DBG(cerr << "Could not open for write access" << endl);

	    return false;

	}

	d_locked_open_file = fp;

	return true;

    }

    DBG(cerr << "locked_open_file is true" << endl);

    return false;

}

/** Release the single user (process) lock. A private method. */

void

HTTPCache::release_single_user_lock()

{

    if (d_locked_open_file) {

        int res = fclose(d_locked_open_file);

        if (res) {

            DBG(cerr << "Failed to close " << (void *)d_locked_open_file << endl) ;

        }

        d_locked_open_file = 0;

    }

    string lock = d_cache_root + CACHE_LOCK;

    REMOVE(lock.c_str());

}

/** @name Accessors and Mutators for various properties. */

//@{

/** Get the current cache root directory.

    @return A string that contains the cache root directory. */

string

HTTPCache::get_cache_root() const

{

    return d_cache_root;

}

/** Create the cache's root directory. This is the persistent store used by

    the cache. Paths must always end in DIR_SEPARATOR_CHAR.

    A private method.

    @param cache_root The pathname to the desired cache root directory.

    @exception Error Thrown if the given pathname cannot be created. */

void

HTTPCache::create_cache_root(const string &cache_root)

{

#ifdef WIN32

    string::size_type cur = cache_root[1] == ':' ? 3 : 1;

    typedef int mode_t;

    while ((cur = cache_root.find(DIR_SEPARATOR_CHAR, cur)) != string::npos) {

        string dir = cache_root.substr(0, cur);

        struct stat stat_info;

        if (stat(dir.c_str(), &stat_info) == -1) {

            DBG2(cerr << "Cache....... Creating " << dir << endl);

            mode_t mask = UMASK(0);

            if (MKDIR(dir.c_str(), 0777) < 0) {

                DBG2(cerr << "Error: can't create." << endl);

                UMASK(mask);

                throw Error(string("Could not create the directory for the cache. Failed when building path at ") + dir + string("."));

            }

            UMASK(mask);

        }

        else {

            DBG2(cerr << "Cache....... Found " << dir << endl);

        }

        cur++;

    }

#else

    // OSX and Linux

    // Save the mask

    mode_t mask = umask(0);

    // Ignore the error if the directory exists

    errno = 0;

    if (mkdir(cache_root.c_str(), 0777) < 0 && errno != EEXIST) {

        umask(mask);

        throw Error("Could not create the directory for the cache at '" + cache_root + "' (" + strerror(errno) + ").");

    }

    // Restore themask

    umask(mask);

#endif

}

/** Set the cache's root directory to the given path. If no path is given,

    look at the DODS_CACHE, TMP and TEMP environment variables (in that

    order) to guess at a good location. If those are all NULL, use \c /tmp.

    If the cache root directory cannot be created, throw an exception.

    Note that in most cases callers should look for this path in the user's

    .dodsrc file.

    A private method.

    @see RCReader

    @param root Set the cache root to this pathname. Defaults to "".

    @exception Error Thrown if the path can neither be deduced nor created. */

void

HTTPCache::set_cache_root(const string &root)

{

    if (root != "") {

        d_cache_root = root;

        // cache root should end in /.

        if (d_cache_root[d_cache_root.size()-1] != DIR_SEPARATOR_CHAR)

            d_cache_root += DIR_SEPARATOR_CHAR;

    }

    else {

        // If no cache root has been indicated then look for a suitable

        // location.

#ifdef USE_GETENV

        char * cr = (char *) getenv("DODS_CACHE");

        if (!cr) cr = (char *) getenv("TMP");

        if (!cr) cr = (char *) getenv("TEMP");

        if (!cr) cr = (char*)CACHE_LOCATION;

        d_cache_root = cr;

#else

        d_cache_root = CACHE_LOCATION;

#endif

        if (d_cache_root[d_cache_root.size()-1] != DIR_SEPARATOR_CHAR)

            d_cache_root += DIR_SEPARATOR_CHAR;

        d_cache_root += CACHE_ROOT;

    }

    // Test d_hhtp_cache_table because this method can be called before that

    // instance is created and also can be called later to change the cache

    // root. jhrg 05.14.08

    if (d_http_cache_table)

    	d_http_cache_table->set_cache_root(d_cache_root);

}

/** Enable or disable the cache. The cache can be temporarily suspended using

    the enable/disable property. This does not prevent the cache from being

    enabled/disable at a later point in time.

    Default: yes

    This method locks the class' interface.

    @param mode True if the cache should be enabled, False if it should be

    disabled. */

void

HTTPCache::set_cache_enabled(bool mode)

{

    lock_cache_interface();

    d_cache_enabled = mode;

    unlock_cache_interface();

}

/** Is the cache currently enabled? */

bool

HTTPCache::is_cache_enabled() const

{

    DBG2(cerr << "In HTTPCache::is_cache_enabled: (" << d_cache_enabled << ")"

         << endl);

    return d_cache_enabled;

}

/** Set the cache's disconnected property. The cache can operate either

    disconnected from the network or using a proxy cache (but tell that proxy

    not to use the network).

    This method locks the class' interface.

    @param mode One of DISCONNECT_NONE, DISCONNECT_NORMAL or

    DISCONNECT_EXTERNAL.

    @see CacheDIsconnectedMode */

void

HTTPCache::set_cache_disconnected(CacheDisconnectedMode mode)

{

    lock_cache_interface();

    d_cache_disconnected = mode;

    unlock_cache_interface();

}

/** Get the cache's disconnected mode property. */

CacheDisconnectedMode

HTTPCache::get_cache_disconnected() const

{

    return d_cache_disconnected;

}

/** How should the cache handle the Expires header?

    Default: no

    This method locks the class' interface.

    @param mode True if a responses Expires header should be ignored, False

    otherwise. */

void

HTTPCache::set_expire_ignored(bool mode)

{

    lock_cache_interface();

    d_expire_ignored = mode;

    unlock_cache_interface();

}

/* Is the cache ignoring Expires headers returned with responses that have

   been cached? */

bool

HTTPCache::is_expire_ignored() const

{

    return d_expire_ignored;

}

/** Cache size management. The default cache size is 20M. The minimum size is

    5M in order not to get into weird problems while writing the cache. The

    size is indicated in Mega bytes. Note that reducing the size of the cache

    may trigger a garbage collection operation.

    @note The maximum cache size is UINT_MAX bytes (usually 4294967295 for

    32-bit computers). If \e size is larger the value will be truncated to

    the value of that constant. It seems pretty unlikely that will happen

    given that the parameter is an unsigned long. This is a fix for bug 689

    which was reported when the parameter type was signed.

    This method locks the class' interface.

    @param size The maximum size of the cache in megabytes. */

void

HTTPCache::set_max_size(unsigned long size)

{

    lock_cache_interface();

    try {

        unsigned long new_size = size < MIN_CACHE_TOTAL_SIZE ?

                                 MIN_CACHE_TOTAL_SIZE * MEGA : size * MEGA;

        unsigned long old_size = d_total_size;

        d_total_size = new_size;

        d_folder_size = d_total_size / CACHE_FOLDER_PCT;

        d_gc_buffer = d_total_size / CACHE_GC_PCT;

        if (new_size < old_size && startGC()) {

            perform_garbage_collection();

            d_http_cache_table->cache_index_write();

        }

    }

    catch (...) {

        unlock_cache_interface();

        DBGN(cerr << "Unlocking interface." << endl);

        throw;

    }

    DBG2(cerr << "Cache....... Total cache size: " << d_total_size

         << " with " << d_folder_size

         << " bytes for meta information and folders and at least "

         << d_gc_buffer << " bytes free after every gc" << endl);

    unlock_cache_interface();

}

/** How big is the cache? The value returned is the size in megabytes. */

unsigned long

HTTPCache::get_max_size() const

{

    return d_total_size / MEGA;

}

/** Set the maximum size for a single entry in the cache.

    Default: 3M

    This method locks the class' interface.

    @param size The size in megabytes. */

void

HTTPCache::set_max_entry_size(unsigned long size)

{

    lock_cache_interface();

    try {

        unsigned long new_size = size * MEGA;

        if (new_size > 0 && new_size < d_total_size - d_folder_size) {

            unsigned long old_size = d_max_entry_size;

            d_max_entry_size = new_size;

            if (new_size < old_size && startGC()) {

                perform_garbage_collection();

                d_http_cache_table->cache_index_write();

            }

        }

    }

    catch (...) {

        unlock_cache_interface();

        throw;

    }

    DBG2(cerr << "Cache...... Max entry cache size is "

         << d_max_entry_size << endl);

    unlock_cache_interface();

}

/** Get the maximum size of an individual entry in the cache.

    @return The maximum size in megabytes. */

unsigned long

HTTPCache::get_max_entry_size() const

{

    return d_max_entry_size / MEGA;

}

/** Set the default expiration time. Use the default expiration

    property to determine when a cached response becomes stale if the

    response lacks the information necessary to compute a specific value.

    Default: 24 hours (86,400 seconds)

    This method locks the class' interface.

    @param exp_time The time in seconds. */

void

HTTPCache::set_default_expiration(const int exp_time)

{

    lock_cache_interface();

    d_default_expiration = exp_time;

    unlock_cache_interface();

}

/** Get the default expiration time used by the cache. */

int

HTTPCache::get_default_expiration() const

{

    return d_default_expiration;

}

/** Should every cache entry be validated?

    @param validate True if every cache entry should be validated before

    being used. */

void

HTTPCache::set_always_validate(bool validate)

{

    d_always_validate = validate;

}

/** Should every cache entry be validated before each use?

    @return True if all cache entries require validation. */

bool

HTTPCache::get_always_validate() const

{

    return d_always_validate;

}

/** Set the request Cache-Control headers. If a request must be satisfied

    using HTTP, these headers should be included in request since they might

    be pertinent to a proxy cache.

    Ignored headers: no-transform, only-if-cached. These headers are not used

    by HTTPCache and are not recorded. However, if present in the vector

    passed to this method, they will be present in the vector returned by

    get_cache_control.

    This method locks the class' interface.

    @param cc A vector of strings, each string holds one Cache-Control

    header.

    @exception InternalErr Thrown if one of the strings in \c cc does not

    start with 'Cache-Control: '. */

void

HTTPCache::set_cache_control(const vector<string> &cc)

{

    lock_cache_interface();

    try {

        d_cache_control = cc;

        vector<string>::const_iterator i;

        for (i = cc.begin(); i != cc.end(); ++i) {