<?php
	/*
	 * Copyright (c) 2003 gencon Ltd, all rights reserved.
	 *
	 * This file is part of v-creator.
	 *
   * v-creator is free software; you can redistribute it and/or modify
   * it under the terms of the GNU General Public License as published by
   * the Free Software Foundation; either version 2 of the License, or
   * (at your option) any later version.
	 *
   * v-creator 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 General Public License for more details.
	 *
   * You should have received a copy of the GNU General Public License
   * along with this program; if not, write to the Free Software
   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
	 */

	require_once(VC_ROOT.'/classes/VCPage.php');

	/**
	 * @ingroup VCmodules
	 * @brief Class for caching dataSets from database modules.
	 *
	 * $Revision: 1.3 $  $Date: 2005-09-26 13:04:08 $
	 *
	 * @author Andrew 'Diddymus' Rolfe
	 *
	 * This module provides functionality for caching dataSets from database
	 * modules to increase performance and reduce database processing. To use
	 * this module the cache is first initialised using dataSetCache::load
	 *
	 * @code
	 *	// Setup normal VC_data value for dataset first
	 *	|{dataSetCache_module=MODULE}|
	 *	|{dataSetCache:load}|
	 * @endcode
	 *
	 * Where MODULE is a define for the module containing the getDataSet to be
	 * used. The dataset is then store in dataSetCache_dataSet. Multiple datasets
	 * can be used by saving and restoring this VC_data value.
	 *
	 * Once a dataSet has been cached it can be used with LOOP tags by
	 * specifiying dataSetCache as the module:
	 *
	 * @code
	 *	|{LOOP:dataSetCache}|
	 *	:
	 *	|{LEND}|
	 * @endcode
	 *
	 * @note The cached dataSet will only be cached for the time it takes to
	 * build the page.
	 *
	 * @note When using dataSetCache if the underlying database is modified the
	 * cache will not be updated. The cache must be 'manually' updated using
	 * dataSetCache::load again.
	 *
	 * @note While it is possible to push the cachedDataSet to the session it is
	 * not advised and should not be done unless you know exactly what you are
	 * doing and the implications involved!
	 */

	class dataSetCache {

		/**
		 * @brief Function to load the dataSet cache.
		 *
		 * This function calls the getDataSet method on a database module and
		 * stores the dataSet in VC_data for caching. The values returned in
		 * VC_data are:
		 *
		 * <dl>
		 *	<dt>dataSetCache_dataSet</dt>
		 *	<dd>The cached dataSet retrieved.</dd>
		 *	<dt>dataSetCache_count</dt>
		 *	<dd>Number of rows in the dataSet not including header row.</dd>
		 * </dl>
		 *
		 * The following values from VC_data will be used if available:
		 *
		 * <dl>
		 *	<dt>dataSetCache_module</dt>
		 *	<dd>The name of a module to retrieve the dataSet to be cached from.</dd>
		 * </dl>
		 *
		 * @static
		 */
		function load() {
			global $VC_data;
		
			$dataSetCacheModule = VCPage::getVC_data('dataSetCache_module');

      VCEngine::useModule($dataSetCacheModule);
      
      $dataSet = call_user_func(array($dataSetCacheModule,'getDataSet'), null);
			$VC_data['dataSetCache_dataSet'] = $dataSet;
			$VC_data['dataSetCache_count'] = count($dataSet)-1;

		}

		/**
		 * @brief Function to retrieve cached dataSets for use in LOOP tags.
		 *
		 * This function returns a cached dataSet. The following values from
		 * VC_data will be used if available:
		 *
		 * <dl>
		 *	<dt>dataSetCache_dataSet</dt>
		 *	<dd>The cached dataSet that will be returned.</dd>
		 * </dl>
		 *
		 * @static
		 */
		function getDataSet() {
			$dataSet = VCPage::getVC_data('dataSetCache_dataSet');
			return $dataSet;
		}

	}

?>