Version: @(#) $Id: datacacheclass.class,v 1.28 2003/11/21 07:50:44 mlemos Exp $
Data cache class
Manuel Lemos (mlemos@acm.org)
Copyright © (C) Manuel Lemos 2001-2003
@(#) $Id: datacacheclass.class,v 1.28 2003/11/21 07:50:44 mlemos Exp $
Caching any type of data in storage containers.
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..
string
''
Contains the error message that explains the reason of failure of certain class functions.
Check this variable when a given class function fails.
bool
1
Determine whether the cache will be left open for reading right after it was updated with the storedata function.
Set this variable to 1 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.
array
array()
Keep a copy of the headers of a cache that was determined to be upto date by the function verifycache.
Check this variable to retrieve the values of the headers read from the cache.
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 storedata. Use the function setheader instead for that purpose.
int
100000
Size of the buffer that will be used to read from a cache.
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 0, the class functions will use the current length of the cache as buffer size.
bool
1
Determine whether the class will automatically generate some cache headers when possible.
If this variable is set to 1, the class will set the headers: date:, etag:, expires: and content-length:. These tags are generated according to HTTP 1.1 protocol specification (RFC 2068).
The class generates the expires: automatic header when the functions setexpirydate or setexpirytime are called.
The class only generates automatically the header content-length: if the storedata function is only called once to write the cache with the endofcache argument set to 1.
Leave this variable set to 1 unless you have a special reason to not want the class to generate headers automatically.
array
array()
Specify verification headers that must be stored with given the cached data. When the cache is checked with verifycache 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.
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.
bool setheader(
Define a header name and the respective value that will be stored in the cache.
Use this function right before calling the function storedata for the first time to start storing the cache data.
Call the setheader function for each header that you want to define.
You may only define once a header with a given name. Notice that some headers may be defined automatically if the variable automatic_headers is set to 1.
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.
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.
Programmers may use this part to store additional information using custom headers. By convention, custom header names should start with the x- prefix.
Each header is stored in individual lines terminated with the "\r\n" sequence.
The body part is made of the data that is passed to the storedata function. The body part is separated from the header part with an empty line also terminated with the "\r\n" sequence.
header - Name of the header that is being defined.
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.
If you need to specify a header that uses : as separator, pass a header name ending with the :.
value - Value of the header that is being defined.
Success boolean flag. If this flag is 0 then the error variable contains the error message that explains the failure. This return value may be safely ignored if the function call arguments are correctly defined.
bool verifycache(
Verify if the cache is upto date. See sub-class documentation for implementation details.
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.
updated - Reference to a variable that will hold a flag value that tells whether the cache exists and is upto date.
Success boolean flag. If this flag is 0 then the error variable contains the error message that explains the failure.
bool setexpirydate(
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 x-expires:.
If the variable automatic_headers is set to 1 then a header named expires: is also defined according to HTTP 1.0 protocol specification (RFC 1945).
Use this function right before calling the function storedata to set the cache expiry date.
date - String that represents the cache expiry date and time in the ISO 9601 format ('YYYY-MM-DD HH:MM:SS').
Success boolean flag. If this flag is 0 then the error variable contains the error message that explains the failure. This return value may be safely ignored if the function call arguments are correctly defined.
bool setexpirytime(
Define the period of time for which the cache will be valid. This function uses the setexpirydate to set the expiry headers.
Use this function right before calling the function storedata to set the cache expiry time period.
time - Number of seconds of the period for which the cache will be valid starting from the moment that this function is called.
Success boolean flag. If this flag is 0 then the error variable contains the error message that explains the failure. This return value may be safely ignored if the function call arguments are correctly defined.
bool storedata(
Store data in the cache.
Use this function after calling the verifycache function if it has returned the information that the cache is not upto date.
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.
data - Reference to a variable that contains the data that is meant to be stored in the cache.
endofcache - 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.
Success boolean flag. If this flag is 0 then the error variable contains the error message that explains the failure.
bool retrievefromcache(
Retrieve data from the cache.
Use this function after calling the verifycache function if it has returned that the cache is upto date.
This function may also be called after having stored all cache data with the function storedata, if the variable reopenupdatedcache is set to 1.
data - Reference to a variable that will contain the data that is retrieved from the cache.
endofcache - 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.
Success boolean flag. If this flag is 0 then the error variable contains the error message that explains the failure.
closecache()
Close any cache resources that were left open for update or for retrieving.
Use this function to close the cache resource that may have been left open after verifycache and for some reason your program will not finish updating the cache with the storedata function or retrieve its contents to the end with retrievefromcache.
bool voidcache()
Safely invalidate the cache if it exists to make sure that next time it is accessed it will need to be regenerated.
Use this function to void the cache at any time except after it has been opened by the function verifycache and until it has been closed by the functions storedata or retrievefromcache.
Success boolean flag. If this flag is 0 then the error variable contains the error message that explains the failure.
bool updating(
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.
Call this function when you need to determine if the cache is accessible for reading or updating.
updating - Flag value that indicates whether the cache is being updated by a concurrent process.
Success boolean flag. If this flag is 0 then the error variable contains the error message that explains the failure.