TDAFileBriefcase
Overview
The TDAFileBriefcase class provides support for persisting client data stored in a file and placed somewhere in the file system of the client. It can be useful in different scenarios, for example:
- You can use briefcase for saving client data including uncommitted changes between restarts of your application
- You can store some quite constant dictionary tables into briefcase and load them during application start, and thus avoid having to reload the same data from the server
- You can implement requesting only changed records for some huge table from the server side and then merge the delta with the client table loaded from the local briefcase.
A briefcase can hold one or more TDADataTables with original data and pending Delta Changes that have not been applied yet. Also briefcase can hold one or more custom application-specific string properties. This can be useful, for example, for keeping data format version, to ensure that your application can read the data correctly.
All data in the TDAFileBriefcase are encoded with help of TDABin2DataStreamer.
The main difference of the TDAFileBriefcase from the TDAFolderBriefcase is that with TDAFileBriefcase all the data (original table data, pending changes and custom properties) are stored in the single file.
File of the TDAFileBriefcase usually has .daBriefcase extension.
The Briefcase Explorer sample can be used to load and inspect data in the briefcase.
Using File Briefcase is rather simple.
// Assuming we already have a 'MyFileBriefcase.briefcase' briefcase in our file system
// and it already holds a 'MyTable' TDADataTable and a 'My Custom Property #1' property
// initialize briefcase
// note: it will adds '.briefcase' automatically when it is omitted
briefcase := TDAFileBriefcase.Create('C:\briefcases\MyFileBriefcase');
// get custom property
customPropertyValue := briefcase.PropValues['My Custom Property #1'];
// add new custom property
briefcase.PropValues['NewMyPropName'] := 'NewMyPropValue';
// get table by name
tbl_MyTable := briefcase.FindTable('MyTable');
// add new table
briefcase.AddTable(tbl_Workers,True);
// write briefcase to the file system
briefcase.WriteBriefcase;
Location
- Unit: uDABriefcase.pas
- Ancestry: TDABaseBriefcase | TDAFileBriefcase
constructor Create (string, Boolean) overload (declared in TDABaseBriefcase)
Initializes briefcase instance
constructor Create(const aFileName: string; const aOwnTables: Boolean)
Parameters:
- aFileName: file or folder name
- aOwnTables: specified who will be owner of tables: briefcase or user will manually maintains tables
constructor Create (string, Boolean, Boolean, Boolean) overload (declared in TDABaseBriefcase)
Initializes briefcase instance
constructor Create(const aFileName: string; const aPreloadData: Boolean; const aOwnTables: Boolean; aLegacyBriefcaseFormat: Boolean)
Parameters:
- aFileName: file or folder name
- aPreloadData: allows to preload tables into memory
- aOwnTables: specified who will be owner of tables: briefcase or user will manually maintains tables
- aLegacyBriefcaseFormat: specifies how to delta will be read/written into briefcase
AddTable (TDADataTable) overload deprecated (declared in TDABaseBriefcase)
Adds an TDADataTable to the briefcase. Adding table will not cause the briefcase to be written to disk immediately, it merely adds the table to the list of tables to be written. This list is maintained by table name, so each table added to a briefcase must have a unique name, or it will replace whatever other table by the same name has been added prior. Use WriteBriefcase to persist the briefcase and all its data to disk.
procedure AddTable(const aTable: TDADataTable)
Parameters:
- aTable: table that should be added in briefcase
AddTable (TDADataTable, Boolean) overload (declared in TDABaseBriefcase)
Adds an TDADataTable to the briefcase. Adding table will not cause the briefcase to be written to disk immediately, it merely adds the table to the list of tables to be written. This list is maintained by table name, so each table added to a briefcase must have a unique name, or it will replace whatever other table by the same name has been added prior. Use WriteBriefcase to persist the briefcase and all its data to disk.
procedure AddTable(const aTable: TDADataTable; const aCopyTable: Boolean)
Parameters:
- aTable: table that should be added in briefcase
- aCopyTable: specified that content of table should be copied into briefcase's table, otherwise it just replaces existing copy
BriefcaseType (declared in TDABaseBriefcase)
Specifies briefcase type.
property BriefcaseType: TDABriefcaseType read
CheckFileName protected override
Checks the name of briefcase and adds file extension if needed
function CheckFileName(const aFileName: string): string
Parameters:
- aFileName: File name
Clear (declared in TDABaseBriefcase)
Clears content of briefcase in memory. WriteBriefcase should be called for changing briefcase on disk.
procedure Clear
ClearProperties (declared in TDABaseBriefcase)
Removes all properties
procedure ClearProperties
DeleteProperty (declared in TDABaseBriefcase)
Deletes specified property
procedure DeleteProperty(const aName: UnicodeString)
Parameters:
- aName: Property name
DeleteTable deprecated (declared in TDABaseBriefcase)
Calls RemoveTable
procedure DeleteTable(aIndex: Integer)
Parameters:
- aIndex: index
FileName (declared in TDABaseBriefcase)
File (or folder, in case of a folder-based briefcase) name and path of the briefcase.
property FileName: string read
Fill (declared in TDABaseBriefcase)
Reads datatables from briefcase
procedure Fill(const aTables: array of TDADataTable; const aKeepLookups: Boolean; const aKeepCalculated: Boolean)
Parameters:
- aTables: A set of data tables to fill. All tables should be named.
- aKeepLookups: Keep lookups
- aKeepCalculated: Keep calculated
FindTable (Integer): TDADataTable overload (declared in TDABaseBriefcase)
Returns reference to the table with the given index. If not loaded from disk yet, it will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.
function FindTable(const aIndex: Integer): TDADataTable
Parameters:
- aIndex: index
FindTable (string): TDADataTable overload (declared in TDABaseBriefcase)
Returns reference to the table with the given name, as stored in the briefcase. If not loaded from disk yet, it will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.
function FindTable(const aTableName: string): TDADataTable
Parameters:
- aTableName: Table name
GetPropName (declared in TDABaseBriefcase)
Returns name of property based on index.
function GetPropName(aIndex: Integer): UnicodeString
Parameters:
- aIndex: index
GetPropValue (declared in TDABaseBriefcase)
Returns value of specified property.
function GetPropValue(const aName: UnicodeString): UnicodeString
Parameters:
- aName: Property name
isBriefcaseExists protected override
Checks a presence of briefcase on disk.
function isBriefcaseExists: Boolean
LegacyBriefcaseFormat (declared in TDABaseBriefcase)
Specifies how to delta will be read/written into briefcase. Default value is true
property LegacyBriefcaseFormat: Boolean read write
LoadAllTables (declared in TDABaseBriefcase)
Loads all tables of briefcase into memory
procedure LoadAllTables
LoadProperties protected override
Loads the briefcase's properties
procedure LoadProperties
LoadTable (string): TDADataTable protected overload override
Loads table from disk
function LoadTable(const aTableName: string): TDADataTable
Parameters:
- aTableName: Table name
LoadTables protected override
Initializes table's place holders or loads briefcase's tables into memory
procedure LoadTables(const aLoadOnDemand: Boolean)
Parameters:
- aLoadOnDemand: Specifies mode of loading
PropCount (declared in TDABaseBriefcase)
Returns count of properties.
function PropCount: Integer
PropNames (declared in TDABaseBriefcase)
Returns name of property based on index.
property PropNames[Index: Integer]: UnicodeString read
PropValueFromIndex (declared in TDABaseBriefcase)
Sets or returns value of specified property based on it's index.
property PropValueFromIndex[Index: Integer]: UnicodeString read write
PropValues (declared in TDABaseBriefcase)
Sets or returns value of specified property.
property PropValues[Name: UnicodeString]: UnicodeString read write
ReadBriefcase (declared in TDABaseBriefcase)
Reads briefcase into memory. Note: all unsaved changes will be lost.
procedure ReadBriefcase
RemoveTable (Integer) overload (declared in TDABaseBriefcase)
Removes the table with the specified index from the memory. Note that this method will not immediately remove the table from disk; this happens when WriteBriefcase is called to write the entire briefcase back to disk.
procedure RemoveTable(const aIndex: Integer)
Parameters:
- aIndex: Index
RemoveTable (string) overload (declared in TDABaseBriefcase)
Removes the table with the specified name from the memory. Note that this method will not immediately remove the table from disk; this happens when WriteBriefcase is called to write the entire briefcase back to disk.
procedure RemoveTable(const aTableName: string)
Parameters:
- aTableName: Table name
SaveAsFileBriefcase (declared in TDABaseBriefcase)
Saves given briefcase as file briefcase (TDAFileBriefcase).
procedure SaveAsFileBriefcase(const aFileName: string)
Parameters:
- aFileName: File name
SaveAsFolderBriefcase (declared in TDABaseBriefcase)
Saves given briefcase as folder briefcase (TDAFolderBriefcase).
procedure SaveAsFolderBriefcase(const aFolderName: string)
Parameters:
- aFolderName: Folder name
SetPropValue (declared in TDABaseBriefcase)
Sets specified property.
procedure SetPropValue(const aName: UnicodeString; const aValue: UnicodeString)
Parameters:
- aName: Property name
- aValue: Property value
SortTables (declared in TDABaseBriefcase)
Sorts tables in briefcase
procedure SortTables
TableCount (declared in TDABaseBriefcase)
Returns count of tables in briefcase.
property TableCount: Integer read
TableName (declared in TDABaseBriefcase)
Returns table name based on index in briefcase
property TableName[Index: Integer]: string read
TableNamed deprecated (declared in TDABaseBriefcase)
Returns reference to the table with the given name, as stored in the briefcase. If not loaded from disk yet, it will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.
function TableNamed(tableName: string): TDADataTable
Parameters:
- tableName: Name of the table to obtain.
WriteBriefcase (declared in TDABaseBriefcase)
Writes briefcase to disk.
procedure WriteBriefcase
BriefcaseType (declared in TDABaseBriefcase)
Specifies briefcase type.
property BriefcaseType: TDABriefcaseType read
FileName (declared in TDABaseBriefcase)
File (or folder, in case of a folder-based briefcase) name and path of the briefcase.
property FileName: string read
LegacyBriefcaseFormat (declared in TDABaseBriefcase)
Specifies how to delta will be read/written into briefcase. Default value is true
property LegacyBriefcaseFormat: Boolean read write
PropNames (declared in TDABaseBriefcase)
Returns name of property based on index.
property PropNames[Index: Integer]: UnicodeString read
PropValueFromIndex (declared in TDABaseBriefcase)
Sets or returns value of specified property based on it's index.
property PropValueFromIndex[Index: Integer]: UnicodeString read write
PropValues (declared in TDABaseBriefcase)
Sets or returns value of specified property.
property PropValues[Name: UnicodeString]: UnicodeString read write
TableCount (declared in TDABaseBriefcase)
Returns count of tables in briefcase.
property TableCount: Integer read
TableName (declared in TDABaseBriefcase)
Returns table name based on index in briefcase
property TableName[Index: Integer]: string read
constructor Create (string, Boolean) overload (declared in TDABaseBriefcase)
Initializes briefcase instance
constructor Create(const aFileName: string; const aOwnTables: Boolean)
Parameters:
- aFileName: file or folder name
- aOwnTables: specified who will be owner of tables: briefcase or user will manually maintains tables
constructor Create (string, Boolean, Boolean, Boolean) overload (declared in TDABaseBriefcase)
Initializes briefcase instance
constructor Create(const aFileName: string; const aPreloadData: Boolean; const aOwnTables: Boolean; aLegacyBriefcaseFormat: Boolean)
Parameters:
- aFileName: file or folder name
- aPreloadData: allows to preload tables into memory
- aOwnTables: specified who will be owner of tables: briefcase or user will manually maintains tables
- aLegacyBriefcaseFormat: specifies how to delta will be read/written into briefcase
AddTable (TDADataTable) overload deprecated (declared in TDABaseBriefcase)
Adds an TDADataTable to the briefcase. Adding table will not cause the briefcase to be written to disk immediately, it merely adds the table to the list of tables to be written. This list is maintained by table name, so each table added to a briefcase must have a unique name, or it will replace whatever other table by the same name has been added prior. Use WriteBriefcase to persist the briefcase and all its data to disk.
procedure AddTable(const aTable: TDADataTable)
Parameters:
- aTable: table that should be added in briefcase
AddTable (TDADataTable, Boolean) overload (declared in TDABaseBriefcase)
Adds an TDADataTable to the briefcase. Adding table will not cause the briefcase to be written to disk immediately, it merely adds the table to the list of tables to be written. This list is maintained by table name, so each table added to a briefcase must have a unique name, or it will replace whatever other table by the same name has been added prior. Use WriteBriefcase to persist the briefcase and all its data to disk.
procedure AddTable(const aTable: TDADataTable; const aCopyTable: Boolean)
Parameters:
- aTable: table that should be added in briefcase
- aCopyTable: specified that content of table should be copied into briefcase's table, otherwise it just replaces existing copy
CheckFileName protected override
Checks the name of briefcase and adds file extension if needed
function CheckFileName(const aFileName: string): string
Parameters:
- aFileName: File name
Clear (declared in TDABaseBriefcase)
Clears content of briefcase in memory. WriteBriefcase should be called for changing briefcase on disk.
procedure Clear
ClearProperties (declared in TDABaseBriefcase)
Removes all properties
procedure ClearProperties
DeleteProperty (declared in TDABaseBriefcase)
Deletes specified property
procedure DeleteProperty(const aName: UnicodeString)
Parameters:
- aName: Property name
DeleteTable deprecated (declared in TDABaseBriefcase)
Calls RemoveTable
procedure DeleteTable(aIndex: Integer)
Parameters:
- aIndex: index
Fill (declared in TDABaseBriefcase)
Reads datatables from briefcase
procedure Fill(const aTables: array of TDADataTable; const aKeepLookups: Boolean; const aKeepCalculated: Boolean)
Parameters:
- aTables: A set of data tables to fill. All tables should be named.
- aKeepLookups: Keep lookups
- aKeepCalculated: Keep calculated
FindTable (Integer): TDADataTable overload (declared in TDABaseBriefcase)
Returns reference to the table with the given index. If not loaded from disk yet, it will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.
function FindTable(const aIndex: Integer): TDADataTable
Parameters:
- aIndex: index
FindTable (string): TDADataTable overload (declared in TDABaseBriefcase)
Returns reference to the table with the given name, as stored in the briefcase. If not loaded from disk yet, it will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.
function FindTable(const aTableName: string): TDADataTable
Parameters:
- aTableName: Table name
GetPropName (declared in TDABaseBriefcase)
Returns name of property based on index.
function GetPropName(aIndex: Integer): UnicodeString
Parameters:
- aIndex: index
GetPropValue (declared in TDABaseBriefcase)
Returns value of specified property.
function GetPropValue(const aName: UnicodeString): UnicodeString
Parameters:
- aName: Property name
isBriefcaseExists protected override
Checks a presence of briefcase on disk.
function isBriefcaseExists: Boolean
LoadAllTables (declared in TDABaseBriefcase)
Loads all tables of briefcase into memory
procedure LoadAllTables
LoadProperties protected override
Loads the briefcase's properties
procedure LoadProperties
LoadTable (string): TDADataTable protected overload override
Loads table from disk
function LoadTable(const aTableName: string): TDADataTable
Parameters:
- aTableName: Table name
LoadTables protected override
Initializes table's place holders or loads briefcase's tables into memory
procedure LoadTables(const aLoadOnDemand: Boolean)
Parameters:
- aLoadOnDemand: Specifies mode of loading
PropCount (declared in TDABaseBriefcase)
Returns count of properties.
function PropCount: Integer
ReadBriefcase (declared in TDABaseBriefcase)
Reads briefcase into memory. Note: all unsaved changes will be lost.
procedure ReadBriefcase
RemoveTable (Integer) overload (declared in TDABaseBriefcase)
Removes the table with the specified index from the memory. Note that this method will not immediately remove the table from disk; this happens when WriteBriefcase is called to write the entire briefcase back to disk.
procedure RemoveTable(const aIndex: Integer)
Parameters:
- aIndex: Index
RemoveTable (string) overload (declared in TDABaseBriefcase)
Removes the table with the specified name from the memory. Note that this method will not immediately remove the table from disk; this happens when WriteBriefcase is called to write the entire briefcase back to disk.
procedure RemoveTable(const aTableName: string)
Parameters:
- aTableName: Table name
SaveAsFileBriefcase (declared in TDABaseBriefcase)
Saves given briefcase as file briefcase (TDAFileBriefcase).
procedure SaveAsFileBriefcase(const aFileName: string)
Parameters:
- aFileName: File name
SaveAsFolderBriefcase (declared in TDABaseBriefcase)
Saves given briefcase as folder briefcase (TDAFolderBriefcase).
procedure SaveAsFolderBriefcase(const aFolderName: string)
Parameters:
- aFolderName: Folder name
SetPropValue (declared in TDABaseBriefcase)
Sets specified property.
procedure SetPropValue(const aName: UnicodeString; const aValue: UnicodeString)
Parameters:
- aName: Property name
- aValue: Property value
SortTables (declared in TDABaseBriefcase)
Sorts tables in briefcase
procedure SortTables
TableNamed deprecated (declared in TDABaseBriefcase)
Returns reference to the table with the given name, as stored in the briefcase. If not loaded from disk yet, it will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.
function TableNamed(tableName: string): TDADataTable
Parameters:
- tableName: Name of the table to obtain.
WriteBriefcase (declared in TDABaseBriefcase)
Writes briefcase to disk.
procedure WriteBriefcase
- Delphi:
- .NET:
-
Xcode:
- DABriefcase
- DAFolderBriefcase
- Java
- Briefcase Explorer