Location: PHPKode > scripts > File cache class > file-cache-class/datacacheclass.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Class: Data cache class</title>
</head>
<body>
<center><h1>Class: Data cache class</h1></center>
<hr />
<ul>
<p><b>Version:</b> <tt>@(#) $Id: datacacheclass.class,v 1.28 2003/11/21 07:50:44 mlemos Exp $</tt></p>
<h2><a name="table_of_contents">Contents</a></h2>
<ul>
<li><a href="#2.1.1">Summary</a></li>
<ul>
<li><a href="#3.2.0">Name</a></li>
<li><a href="#3.2.0.0">Author</a></li>
<li><a href="#3.2.0.1">Copyright</a></li>
<li><a href="#3.2.0.2">Version</a></li>
<li><a href="#3.2.0.3">Purpose</a></li>
<li><a href="#3.2.0.4">Usage</a></li>
</ul>
<li><a href="#4.1.1">Variables</a></li>
<ul>
<li><a href="#5.2.7">error</a></li>
<li><a href="#5.2.8">reopenupdatedcache</a></li>
<li><a href="#5.2.9">headers</a></li>
<li><a href="#5.2.10">cache_buffer_length</a></li>
<li><a href="#5.2.11">automatic_headers</a></li>
<li><a href="#5.2.12">verify_headers</a></li>
</ul>
<li><a href="#6.1.1">Functions</a></li>
<ul>
<li><a href="#7.2.10">setheader</a></li>
<li><a href="#9.2.11">verifycache</a></li>
<li><a href="#11.2.12">setexpirydate</a></li>
<li><a href="#13.2.13">setexpirytime</a></li>
<li><a href="#15.2.14">storedata</a></li>
<li><a href="#17.2.15">retrievefromcache</a></li>
<li><a href="#19.2.16">closecache</a></li>
<li><a href="#19.2.17">voidcache</a></li>
<li><a href="#19.2.18">updating</a></li>
</ul>
</ul>
<p><a href="#table_of_contents">Top of the table of contents</a></p>
</ul>
<hr />
<ul>
<h2><li><a name="2.1.1">Summary</a></li></h2>
<ul>
<h3><a name="3.2.0">Name</a></h3>
<p>Data cache class</p>
<h3><a name="3.2.0.0">Author</a></h3>
<p>Manuel Lemos (<a href="mailto:hide@address.com">hide@address.com</a>)</p>
<h3><a name="3.2.0.1">Copyright</a></h3>
<p>Copyright &copy; (C) Manuel Lemos 2001-2003</p>
<h3><a name="3.2.0.2">Version</a></h3>
<p>@(#) $Id: datacacheclass.class,v 1.28 2003/11/21 07:50:44 mlemos Exp $</p>
<h3><a name="3.2.0.3">Purpose</a></h3>
<p>Caching any type of data in storage containers.</p>
<h3><a name="3.2.0.4">Usage</a></h3>
<p>This is an abstract class and so it is not meant to be instantiated directly. To use it, you need to define a sub-class that that implements the behaviour of the functions that store and retrieve cached data from specific storage containers like disk files, shared memory, databases, etc..</p>
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>
<hr />
<ul>
<h2><li><a name="variables"></a><a name="4.1.1">Variables</a></li></h2>
<ul>
<li><tt><a href="#variable_error">error</a></tt></li><br />
<li><tt><a href="#variable_reopenupdatedcache">reopenupdatedcache</a></tt></li><br />
<li><tt><a href="#variable_headers">headers</a></tt></li><br />
<li><tt><a href="#variable_cache_buffer_length">cache_buffer_length</a></tt></li><br />
<li><tt><a href="#variable_automatic_headers">automatic_headers</a></tt></li><br />
<li><tt><a href="#variable_verify_headers">verify_headers</a></tt></li><br />
<p><a href="#table_of_contents">Table of contents</a></p>
<h3><a name="variable_error"></a><li><a name="5.2.7">error</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>''</tt></p>
<h3>Purpose</h3>
<p>Contains the error message that explains the reason of failure of certain class functions.</p>
<h3>Usage</h3>
<p>Check this variable when a given class function fails.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_reopenupdatedcache"></a><li><a name="5.2.8">reopenupdatedcache</a></li></h3>
<h3>Type</h3>
<p><tt><i>bool</i></tt></p>
<h3>Default value</h3>
<p><tt>1</tt></p>
<h3>Purpose</h3>
<p>Determine whether the cache will be left open for reading right after it was updated with the <tt><a href="#function_storedata">storedata</a></tt> function.</p>
<h3>Usage</h3>
<p>Set this variable to <tt>1</tt> if you need to reread the cache contents, eventually because you no longer have a full copy of the data that was stored in the cache, so you need to retrieve the data again from the just updated cache.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_headers"></a><li><a name="5.2.9">headers</a></li></h3>
<h3>Type</h3>
<p><tt><i>array</i></tt></p>
<h3>Default value</h3>
<p><tt>array()</tt></p>
<h3>Purpose</h3>
<p>Keep a copy of the headers of a cache that was determined to be upto date by the function <tt><a href="#function_verifycache">verifycache</a></tt>.</p>
<h3>Usage</h3>
<p>Check this variable to retrieve the values of the headers read from the cache.</p>
<p> Do not use this variable to set values of the headers that will be written to a cache that is going to be updated with the function <tt><a href="#function_storedata">storedata</a></tt>.  Use the function <tt><a href="#function_setheader">setheader</a></tt> instead for that purpose.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_cache_buffer_length"></a><li><a name="5.2.10">cache_buffer_length</a></li></h3>
<h3>Type</h3>
<p><tt><i>int</i></tt></p>
<h3>Default value</h3>
<p><tt>100000</tt></p>
<h3>Purpose</h3>
<p>Size of the buffer that will be used to read from a cache.</p>
<h3>Usage</h3>
<p>Set this variable to a buffer size that is suitable for the type of data that you want to cache.  If you set this variable to <tt>0</tt>, the class functions will use the current length of the cache as buffer size.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_automatic_headers"></a><li><a name="5.2.11">automatic_headers</a></li></h3>
<h3>Type</h3>
<p><tt><i>bool</i></tt></p>
<h3>Default value</h3>
<p><tt>1</tt></p>
<h3>Purpose</h3>
<p>Determine whether the class will automatically generate some cache headers when possible.</p>
<p> If this variable is set to <tt>1</tt>, the class will set the headers: <tt>date:</tt>, <tt>etag:</tt>, <tt>expires:</tt> and <tt>content-length:</tt>. These tags are generated according to HTTP 1.1 protocol specification (<a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>).</p>
<p> The class generates the <tt>expires:</tt> automatic header when the functions <tt><a href="#function_setexpirydate">setexpirydate</a></tt> or <tt><a href="#function_setexpirytime">setexpirytime</a></tt> are called.</p>
<p> The class only generates automatically the header <tt>content-length:</tt> if the <tt><a href="#function_storedata">storedata</a></tt> function is only called once to write the cache with the <tt><a href="#argument_storedata_endofcache">endofcache</a></tt> argument set to <tt>1</tt>.</p>
<h3>Usage</h3>
<p>Leave this variable set to <tt>1</tt> unless you have a special reason to not want the class to generate headers automatically.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_verify_headers"></a><li><a name="5.2.12">verify_headers</a></li></h3>
<h3>Type</h3>
<p><tt><i>array</i></tt></p>
<h3>Default value</h3>
<p><tt>array()</tt></p>
<h3>Purpose</h3>
<p>Specify verification headers that must be stored with given the cached data. When the cache is checked with <tt><a href="#function_verifycache">verifycache</a></tt> function, the class verifies if these headers are present and their values match. If any of the specified headers is not present in the stored cache or is present but has a different value, the cache is considered to be invalid and so it needs to be updated.</p>
<h3>Usage</h3>
<p>If the cached data is built using configuration information that may change, add entries to this variable that define the names and the values of that configuration information, so the class also considers those values when verifying if the cache is still valid.</p>
<p><a href="#variables">Variables</a></p>
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>
<hr />
<ul>
<h2><li><a name="functions"></a><a name="6.1.1">Functions</a></li></h2>
<ul>
<li><tt><a href="#function_setheader">setheader</a></tt></li><br />
<li><tt><a href="#function_verifycache">verifycache</a></tt></li><br />
<li><tt><a href="#function_setexpirydate">setexpirydate</a></tt></li><br />
<li><tt><a href="#function_setexpirytime">setexpirytime</a></tt></li><br />
<li><tt><a href="#function_storedata">storedata</a></tt></li><br />
<li><tt><a href="#function_retrievefromcache">retrievefromcache</a></tt></li><br />
<li><tt><a href="#function_closecache">closecache</a></tt></li><br />
<li><tt><a href="#function_voidcache">voidcache</a></tt></li><br />
<li><tt><a href="#function_updating">updating</a></tt></li><br />
<p><a href="#table_of_contents">Table of contents</a></p>
<h3><a name="function_setheader"></a><li><a name="7.2.10">setheader</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> setheader(</tt><ul>
<tt><i>string</i> </tt><tt><a href="#argument_setheader_header">header</a></tt><tt>,<br />
</tt><tt><i>string</i> </tt><tt><a href="#argument_setheader_value">value</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Define a header name and the respective value that will be stored in the cache.</p>
<h3>Usage</h3>
<p>Use this function right before calling the function <tt><a href="#function_storedata">storedata</a></tt> for the first time to start storing the cache data.</p>
<p> Call the <tt><a href="#function_setheader">setheader</a></tt> function for each header that you want to define.</p>
<p> You may only define once a header with a given name.  Notice that some headers may be defined automatically if the variable <tt><a href="#variable_automatic_headers">automatic_headers</a></tt> is set to <tt>1</tt>.</p>
<p> The class stores the cache data in files that have two sections, almost like the data that is served by HTTP servers:  the headers part and the body part.</p>
<p> The headers part is generated by the class itself.  It serves to store some control data, like the cache data size or the cache expiry information.</p>
<p> Programmers may use this part to store additional information using custom headers.  By convention, custom header names should start with the <tt>x-</tt> prefix.</p>
<p> Each header is stored in individual lines terminated with the <tt>&quot;\r\n&quot;</tt> sequence.</p>
<p> The body part is made of the data that is passed to the <tt><a href="#function_storedata">storedata</a></tt> function.  The body part is separated from the header part with an empty line also terminated with the <tt>&quot;\r\n&quot;</tt> sequence.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_setheader_header">header</a></b></tt> - Name of the header that is being defined.</p>
<p> The class will output the header names separated from the respective header values using a single space character.  Thus, header names should not have spaces in them.</p>
<p> If you need to specify a header that uses <tt>:</tt> as separator, pass a header name ending with the <tt>:</tt>.</p>
<p><tt><b><a name="argument_setheader_value">value</a></b></tt> - Value of the header that is being defined.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag. If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.  This return value may be safely ignored if the function call arguments are correctly defined.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_verifycache"></a><li><a name="9.2.11">verifycache</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> verifycache(</tt><ul>
<tt>(output) <i>bool &amp;</i> </tt><tt><a href="#argument_verifycache_updated">updated</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Verify if the cache is upto date. See sub-class documentation for implementation details.</p>
<h3>Usage</h3>
<p>Use this function first to figure whether you can already retrieve the cached data or otherwise you need to regenerate the data to store in the cache.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_verifycache_updated">updated</a></b></tt> - Reference to a variable that will hold a flag value that tells whether the cache exists and is upto date.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_setexpirydate"></a><li><a name="11.2.12">setexpirydate</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> setexpirydate(</tt><ul>
<tt><i>string</i> </tt><tt><a href="#argument_setexpirydate_date">date</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Define the date and time that will expire the cache data that is about to be stored. The expiry date will be stored in a header named <tt>x-expires:</tt>.</p>
<p> If the variable <tt><a href="#variable_automatic_headers">automatic_headers</a></tt> is set to <tt>1</tt> then a header named <tt>expires:</tt> is also defined according to HTTP 1.0 protocol specification (<a href="http://www.ietf.org/rfc/rfc1945.txt">RFC 1945</a>).</p>
<h3>Usage</h3>
<p>Use this function right before calling the function <tt><a href="#function_storedata">storedata</a></tt> to set the cache expiry date.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_setexpirydate_date">date</a></b></tt> - String that represents the cache expiry date and time in the <i>ISO 9601</i> format (<tt>'YYYY-MM-DD HH:MM:SS'</tt>).</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.  This return value may be safely ignored if the function call arguments are correctly defined.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_setexpirytime"></a><li><a name="13.2.13">setexpirytime</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> setexpirytime(</tt><ul>
<tt><i>int</i> </tt><tt><a href="#argument_setexpirytime_time">time</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Define the period of time for which the cache will be valid. This function uses the <tt><a href="#function_setexpirydate">setexpirydate</a></tt> to set the expiry headers.</p>
<h3>Usage</h3>
<p>Use this function right before calling the function <tt><a href="#function_storedata">storedata</a></tt> to set the cache expiry time period.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_setexpirytime_time">time</a></b></tt> - Number of seconds of the period for which the cache will be valid starting from the moment that this function is called.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.  This return value may be safely ignored if the function call arguments are correctly defined.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_storedata"></a><li><a name="15.2.14">storedata</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> storedata(</tt><ul>
<tt>(input and output) <i>string &amp;</i> </tt><tt><a href="#argument_storedata_data">data</a></tt><tt>,<br />
</tt><tt><i>bool</i> </tt><tt><a href="#argument_storedata_endofcache">endofcache</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Store data in the cache.</p>
<h3>Usage</h3>
<p>Use this function after calling the <tt><a href="#function_verifycache">verifycache</a></tt> function if it has returned the information that the cache is not upto date.</p>
<p> If this function fails to write to the cache, it will attempt to delete it to minimize the chances that a partially written data be later mistaken as an upto date cache.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_storedata_data">data</a></b></tt> - Reference to a variable that contains the data that is meant to be stored in the cache.</p>
<p><tt><b><a name="argument_storedata_endofcache">endofcache</a></b></tt> - Flag value that indicates whether the data being passed is the last chunk of data to be stored in the cache, or otherwise there is still more data to be passed in subsequent calls to this function.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_retrievefromcache"></a><li><a name="17.2.15">retrievefromcache</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> retrievefromcache(</tt><ul>
<tt>(output) <i>string &amp;</i> </tt><tt><a href="#argument_retrievefromcache_data">data</a></tt><tt>,<br />
</tt><tt>(output) <i>bool &amp;</i> </tt><tt><a href="#argument_retrievefromcache_endofcache">endofcache</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Retrieve data from the cache.</p>
<h3>Usage</h3>
<p>Use this function after calling the <tt><a href="#function_verifycache">verifycache</a></tt> function if it has returned that the cache is upto date.</p>
<p> This function may also be called after having stored all cache data with the function <tt><a href="#function_storedata">storedata</a></tt>, if the variable <tt><a href="#variable_reopenupdatedcache">reopenupdatedcache</a></tt> is set to <tt>1.</tt></p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_retrievefromcache_data">data</a></b></tt> - Reference to a variable that will contain the data that is retrieved from the cache.</p>
<p><tt><b><a name="argument_retrievefromcache_endofcache">endofcache</a></b></tt> - Flag value that indicates whether the data retrieved from the cache is the last chunk of data, or otherwise there is still more data to be retrieved with subsequent calls to this function.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_closecache"></a><li><a name="19.2.16">closecache</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i></i> closecache(</tt><tt>)</tt></p>
<h3>Purpose</h3>
<p>Close any cache resources that were left open for update or for retrieving.</p>
<h3>Usage</h3>
<p>Use this function to close the cache resource that may have been left open after <tt><a href="#function_verifycache">verifycache</a></tt> and for some reason your program will not finish updating the cache with the <tt><a href="#function_storedata">storedata</a></tt> function or retrieve its contents to the end with <tt><a href="#function_retrievefromcache">retrievefromcache</a></tt>.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_voidcache"></a><li><a name="19.2.17">voidcache</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> voidcache(</tt><tt>)</tt></p>
<h3>Purpose</h3>
<p>Safely invalidate the cache if it exists to make sure that next time it is accessed it will need to be regenerated.</p>
<h3>Usage</h3>
<p>Use this function to void the cache at any time except after it has been opened by the function <tt><a href="#function_verifycache">verifycache</a></tt> and until it has been closed by the functions <tt><a href="#function_storedata">storedata</a></tt> or <tt><a href="#function_retrievefromcache">retrievefromcache</a></tt>.</p>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_updating"></a><li><a name="19.2.18">updating</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> updating(</tt><ul>
<tt>(output) <i>bool &amp;</i> </tt><tt><a href="#argument_updating_updating">updating</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Determine whether the cache is being locked for update by a concurrent process. This function may be useful when you want to take a different action because the process that updates the cache may take a long time to finish.</p>
<h3>Usage</h3>
<p>Call this function when you need to determine if the cache is accessible for reading or updating.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_updating_updating">updating</a></b></tt> - Flag value that indicates whether the cache is being updated by a concurrent process.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>

<hr />
<address>Manuel Lemos (<a href="mailto:hide@address.com">hide@address.com</a>)</address>
</body>
</html>
Return current item: File cache class