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:

  1. 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.
  2. "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.
  3. Open the cache by setting the Location and CacheName properties, and then calling the OpenCache method.
  4. 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.
  5. To create or open a file in the cache (AKA, a cached file), call the OpenFile method.
  6. 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.

ActiveWhether the file cache is open.
AutoFlushEnabledWhether automatic flushing is enabled.
CacheNameThe name of the file cache.
CacheSizeThe current size of the cache.
CacheSizeLimitThe maximum size of the cache's storage file.
CompressedWhether the cache's storage file should be compressed.
CurrentFileIdThe file being currently read or written by the cache.
CurrentOperationThe operation currently being performed by the cache.
FlushAfterCloseDelayThe number of seconds to delay flushing for after a file is closed.
FlushAfterSizeThe amount of data that must be changed for flushing to begin.
FlushAfterTimeThe inactivity timeout that must elapse for flushing to begin.
FlushPolicyThe file flushing strategy that the cache should use.
HasOrphansWhether the cache contains any orphan files.
LocationThe directory in which the cache's storage file is located.
MaxCachedFileSizeThe maximum amount of data that should be cached for any given file.
PurgeAfterCloseDelayThe number of seconds to delay purging for after a file is closed.
PurgeAfterTimeThe inactivity timeout that must elapse for purging to begin.
PurgePolicyThe file block purging strategy that the cache should use.
ReadBlockSizeThe block size to use when reading file data from external storage.
ReadingCapabilitiesThe reading capabilities supported by the external storage.
ResizingCapabilitiesThe file resizing capabilities supported by the external storage.
StatsRefreshIntervalMinimum time period between cache statistics refreshes.
TagStores application-defined data specific to this instance of the component.
TotalDataTotal amount of data present in the cache.
UnflushedDataAmount of unflushed data present in the cache.
UnflushedFilesNumber of unflushed files present in the cache.
WriteBlockSizeThe block size to use when writing file data to external storage.
WritingCapabilitiesThe 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.

CancelCleanupCancels a background cleanup operation, if necessary.
ChangeFileIdChanges the Id of a cached file.
CleanupStarts a background cleanup operation to remove unused files from the cache.
ClearRemoves files from the cache.
CloseCacheCloses the cache.
CloseEnumerationCloses the given file enumeration.
CloseFileCloses a cached file.
CloseFileExCloses a cached file, specifying flushing and purging behaviors explicitly.
ConfigSets or retrieves a configuration setting.
DeleteCacheDeletes the cache completely.
DeleteFileDeletes a file from the cache.
EnumerateCachedFilesEnumerates the files in the cache.
FileExistsChecks if a file with the given Id is present in the cache.
FlushFileFlushes the specified file's modified blocks out to external storage.
GetFileSizeGets the "real size" of a cached file.
GetNextEnumeratedFileReturns the next file in the list of enumeration results.
OpenCacheOpens the cache.
OpenFileOpens the specified cached file, creating it if necessary.
ReadFileReads the specified part of a cached file.
RefreshStatisticsForces a refresh of the cache's statistics.
ResetExternalErrorResets any outstanding external storage error.
ResetFileErrorsResets any outstanding errors for a file.
SetFileSizeSets the "real size" of a cached file.
TouchFileTouches a range of data in a cached file.
WriteFileWrites 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.

ErrorFires if an unhandled error occurs during an event.
ProgressFires to report the progress of an operation.
ReadDataFires when the cache needs to read file data from external storage.
StatusFires to report the latest cache statistics.
WriteDataFires 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.

BlockSizeThe size of the block, used to store the data.
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

 
 
Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Cache 2020 .NET Edition - Version 20.0 [Build 7647]