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


 

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