FileCache Component
Properties Methods Events Configuration Settings Errors
The FileCache component allows applications to easily cache remote file data locally.
Syntax
callback.CBFSCache.Filecache
Remarks
The FileCache component provides a local file caching implementation that helps applications easily cache the contents of files stored in some external storage, such as a cloud storage service. Once an application has informed the FileCache component of the external storage's file transfer capabilities, the hard work of reading data into and flushing data out of the cache is handled automatically.
Getting Started
Applications typically only need a single instance of the FileCache component, since it can handle caching and accessing multiple files at once in parallel. Each file in the cache is identified by its file Id, and all cached file data is stored in a single cache storage file, whose name and location are determined by the CacheName and Location properties, respectively.
In terms of application architecture, the FileCache component (or, more generally, the cache itself) should reside between application code that needs random access to files in the external storage, and the code that provides access to said external storage. The former makes use of the FileCache component's properties and methods, while the latter is "connected" via component's ReadData and WriteData events.
Here's how to get up and running:
- Implement the ReadData and WriteData events so that they provide appropriate access to the external storage. The ReadData event is mandatory. The WriteData event is only required if the FileCache component is to be in charge of flushing changed data back to external storage. Refer to these events' documentation for more information about how to correctly implement them.
- "Describe" the reading, writing, and resizing capabilities of the external storage to the FileCache component by setting the ReadingCapabilities, WritingCapabilities, and ResizingCapabilities properties. This information is used by the FileCache component to formulate a strategy for interacting with the external storage via the events mentioned in step 1.
- Open the cache by setting the Location and CacheName properties, and then calling the OpenCache method.
- If the cached being opened is one which already exists, it is recommended that applications use the EnumerateCachedFiles method to search for any Orphan Files; i.e., files which are not currently open yet have unflushed data. If any such files are found, applications may wish to open, flush, or delete them.
- To create or open a file in the cache (AKA, a cached file), call the OpenFile method.
- While a cached file is open, it can be read from or written to using the ReadFile and WriteFile methods.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
Active | Whether the file cache is open. |
AutoFlushEnabled | Whether automatic flushing is enabled. |
CacheName | The name of the file cache. |
CacheSize | The current size of the cache. |
CacheSizeLimit | The maximum size of the cache's storage file. |
Compressed | Whether the cache's storage file should be compressed. |
CurrentFileId | The file being currently read or written by the cache. |
CurrentOperation | The operation currently being performed by the cache. |
FlushAfterCloseDelay | The number of seconds to delay flushing for after a file is closed. |
FlushAfterSize | The amount of data that must be changed for flushing to begin. |
FlushAfterTime | The inactivity timeout that must elapse for flushing to begin. |
FlushPolicy | The file flushing strategy that the cache should use. |
HasOrphans | Whether the cache contains any orphan files. |
Location | The directory in which the cache's storage file is located. |
MaxCachedFileSize | The maximum amount of data that should be cached for any given file. |
PurgeAfterCloseDelay | The number of seconds to delay purging for after a file is closed. |
PurgeAfterTime | The inactivity timeout that must elapse for purging to begin. |
PurgePolicy | The file block purging strategy that the cache should use. |
ReadBlockSize | The block size to use when reading file data from external storage. |
ReadingCapabilities | The reading capabilities supported by the external storage. |
ResizingCapabilities | The file resizing capabilities supported by the external storage. |
StatsRefreshInterval | Minimum time period between cache statistics refreshes. |
Tag | Stores application-defined data specific to this instance of the component. |
TotalData | Total amount of data present in the cache. |
UnflushedData | Amount of unflushed data present in the cache. |
UnflushedFiles | Number of unflushed files present in the cache. |
WriteBlockSize | The block size to use when writing file data to external storage. |
WritingCapabilities | The writing capabilities supported by the external storage. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
CancelCleanup | Cancels a background cleanup operation, if necessary. |
ChangeFileId | Changes the Id of a cached file. |
Cleanup | Starts a background cleanup operation to remove unused files from the cache. |
Clear | Removes files from the cache. |
CloseCache | Closes the cache. |
CloseEnumeration | Closes the given file enumeration. |
CloseFile | Closes a cached file. |
CloseFileEx | Closes a cached file, specifying flushing and purging behaviors explicitly. |
Config | Sets or retrieves a configuration setting. |
DeleteCache | Deletes the cache completely. |
DeleteFile | Deletes a file from the cache. |
EnumerateCachedFiles | Enumerates the files in the cache. |
FileExists | Checks if a file with the given Id is present in the cache. |
FlushFile | Flushes the specified file's modified blocks out to external storage. |
GetFileSize | Gets the "real size" of a cached file. |
GetNextEnumeratedFile | Returns the next file in the list of enumeration results. |
OpenCache | Opens the cache. |
OpenFile | Opens the specified cached file, creating it if necessary. |
ReadFile | Reads the specified part of a cached file. |
RefreshStatistics | Forces a refresh of the cache's statistics. |
ResetExternalError | Resets any outstanding external storage error. |
ResetFileErrors | Resets any outstanding errors for a file. |
SetFileSize | Sets the "real size" of a cached file. |
TouchFile | Touches a range of data in a cached file. |
WriteFile | Writes the specified part of a cached file. |
Event List
The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.
Error | Fires if an unhandled error occurs during an event. |
Progress | Fires to report the progress of an operation. |
ReadData | Fires when the cache needs to read file data from external storage. |
Status | Fires to report the latest cache statistics. |
WriteData | Fires when the cache needs to write file data to external storage. |
Configuration Settings
The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.
BlockSize | The size of the block, used to store the data. |
BuildInfo | Information about the product's build. |
LicenseInfo | Information about the current license. |