TDABaseBriefcase

Overview

The TDABaseBriefcase provides basic support for persisting data used by client applications as a so called Briefcase file locally on your file system, for example to cache it between restarts of your application, or to avoid having to reload large portions of data. A briefcase can hold one or more TDADataTables and will persist the original data, as well as any information about pending Delta Changes that have not been applied yet.

In addition, a set of custom, application-specific string properties can be stored alongside the data. This can be useful, for example, for storing the version number of the data format, to ensure newer versions of your application can reload the data correctly, if data formats change over time. (It is not recommended, though, to use this space for general application settings that are not directly related to the data.)

A common scenario for briefcase files are applications that need to function without a persistent connection to the middle-tier server being available at all time. The briefcases model will allow you to store the user's data and changes on the local hard disk , while offline. Once a connection to the server is established, data can be loaded back from disk and changes can be sent to the server.

Briefcase Formats

DABriefcase support is implemented as a class cluster, supporting two different models of briefcase files - single files (TDAFileBriefcase) and folder-based (TDAFolderBriefcase), respectively.

In single file mode, all data tables and custom properties are streamed into one single file (commonly with a .daBriefcase extension). This provides convenient storage and makes it easy for users to handle briefcase files (if necessary) and to share them between platforms, but imposes some restrictions on the flexibility with which individual data tables can be read from and written to the file.

In folder mode, each table is written to an individual file inside a briefcase folder (usually with a .briefcase extension). This allows more flexible access for reading and updating individual tables. In both cases, the data is stored usingn the highly efficient binary format of the Bin2DataStreamer, which is also used for client/server transfer of data. In folder briefcase mode, each individual table is stored internally as a single-file briefcase and custom properties are stored in a separate .plist file.

The Briefcase Explorer tool or the Briefcase Explorer sample can be used to load and inspect data in both types of briefcases.

Location


 

constructor Create (string, Boolean)  overload

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

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

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

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

Specifies briefcase type.

property BriefcaseType: TDABriefcaseType read

CheckFileName  protected virtual abstract

Checks the name of briefcase and adds file extension if needed

function CheckFileName(const aFileName: string): string

Parameters:

  • aFileName: File name

Clear

Clears content of briefcase in memory. WriteBriefcase should be called for changing briefcase on disk.

procedure Clear

ClearProperties

Removes all properties

procedure ClearProperties

DeleteProperty

Deletes specified property

procedure DeleteProperty(const aName: UnicodeString)

Parameters:

  • aName: Property name

DeleteTable  deprecated

Calls RemoveTable

procedure DeleteTable(aIndex: Integer)

Parameters:

  • aIndex: index

FileName

File (or folder, in case of a folder-based briefcase) name and path of the briefcase.

property FileName: string read

Fill

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

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

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

Returns name of property based on index.

function GetPropName(aIndex: Integer): UnicodeString

Parameters:

  • aIndex: index

GetPropValue

Returns value of specified property.

function GetPropValue(const aName: UnicodeString): UnicodeString

Parameters:

  • aName: Property name

isBriefcaseExists  protected virtual abstract

Checks a presence of briefcase on disk.

function isBriefcaseExists: Boolean

LegacyBriefcaseFormat

Specifies how to delta will be read/written into briefcase. Default value is true

property LegacyBriefcaseFormat: Boolean read write

LoadAllTables

Loads all tables of briefcase into memory

procedure LoadAllTables

LoadProperties  protected virtual abstract

Loads the briefcase's properties

procedure LoadProperties

LoadTable  protected virtual abstract

Loads table from disk

function LoadTable(const aTableName: string): TDADataTable

Parameters:

  • aTableName: Table name

LoadTables  protected virtual abstract

Initializes table's place holders or loads briefcase's tables into memory

procedure LoadTables(const aLoadOnDemand: Boolean)

Parameters:

  • aLoadOnDemand: Specifies mode of loading

PropCount

Returns count of properties.

function PropCount: Integer

PropNames

Returns name of property based on index.

property PropNames[Index: Integer]: UnicodeString read

PropValueFromIndex

Sets or returns value of specified property based on it's index.

property PropValueFromIndex[Index: Integer]: UnicodeString read write

PropValues

Sets or returns value of specified property.

property PropValues[Name: UnicodeString]: UnicodeString read write

ReadBriefcase

Reads briefcase into memory. Note: all unsaved changes will be lost.

procedure ReadBriefcase

RemoveTable (Integer)  overload

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

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

Saves given briefcase as file briefcase (TDAFileBriefcase).

procedure SaveAsFileBriefcase(const aFileName: string)

Parameters:

  • aFileName: File name

SaveAsFolderBriefcase

Saves given briefcase as folder briefcase (TDAFolderBriefcase).

procedure SaveAsFolderBriefcase(const aFolderName: string)

Parameters:

  • aFolderName: Folder name

SetPropValue

Sets specified property.

procedure SetPropValue(const aName: UnicodeString; const aValue: UnicodeString)

Parameters:

  • aName: Property name
  • aValue: Property value

SortTables

Sorts tables in briefcase

procedure SortTables

TableCount

Returns count of tables in briefcase.

property TableCount: Integer read

TableName

Returns table name based on index in briefcase

property TableName[Index: Integer]: string read

TableNamed  deprecated

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

Writes briefcase to disk.

procedure WriteBriefcase

 

BriefcaseType

Specifies briefcase type.

property BriefcaseType: TDABriefcaseType read

FileName

File (or folder, in case of a folder-based briefcase) name and path of the briefcase.

property FileName: string read

LegacyBriefcaseFormat

Specifies how to delta will be read/written into briefcase. Default value is true

property LegacyBriefcaseFormat: Boolean read write

PropNames

Returns name of property based on index.

property PropNames[Index: Integer]: UnicodeString read

PropValueFromIndex

Sets or returns value of specified property based on it's index.

property PropValueFromIndex[Index: Integer]: UnicodeString read write

PropValues

Sets or returns value of specified property.

property PropValues[Name: UnicodeString]: UnicodeString read write

TableCount

Returns count of tables in briefcase.

property TableCount: Integer read

TableName

Returns table name based on index in briefcase

property TableName[Index: Integer]: string read

 

constructor Create (string, Boolean)  overload

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

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

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

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 virtual abstract

Checks the name of briefcase and adds file extension if needed

function CheckFileName(const aFileName: string): string

Parameters:

  • aFileName: File name

Clear

Clears content of briefcase in memory. WriteBriefcase should be called for changing briefcase on disk.

procedure Clear

ClearProperties

Removes all properties

procedure ClearProperties

DeleteProperty

Deletes specified property

procedure DeleteProperty(const aName: UnicodeString)

Parameters:

  • aName: Property name

DeleteTable  deprecated

Calls RemoveTable

procedure DeleteTable(aIndex: Integer)

Parameters:

  • aIndex: index

Fill

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

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

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

Returns name of property based on index.

function GetPropName(aIndex: Integer): UnicodeString

Parameters:

  • aIndex: index

GetPropValue

Returns value of specified property.

function GetPropValue(const aName: UnicodeString): UnicodeString

Parameters:

  • aName: Property name

isBriefcaseExists  protected virtual abstract

Checks a presence of briefcase on disk.

function isBriefcaseExists: Boolean

LoadAllTables

Loads all tables of briefcase into memory

procedure LoadAllTables

LoadProperties  protected virtual abstract

Loads the briefcase's properties

procedure LoadProperties

LoadTable  protected virtual abstract

Loads table from disk

function LoadTable(const aTableName: string): TDADataTable

Parameters:

  • aTableName: Table name

LoadTables  protected virtual abstract

Initializes table's place holders or loads briefcase's tables into memory

procedure LoadTables(const aLoadOnDemand: Boolean)

Parameters:

  • aLoadOnDemand: Specifies mode of loading

PropCount

Returns count of properties.

function PropCount: Integer

ReadBriefcase

Reads briefcase into memory. Note: all unsaved changes will be lost.

procedure ReadBriefcase

RemoveTable (Integer)  overload

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

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

Saves given briefcase as file briefcase (TDAFileBriefcase).

procedure SaveAsFileBriefcase(const aFileName: string)

Parameters:

  • aFileName: File name

SaveAsFolderBriefcase

Saves given briefcase as folder briefcase (TDAFolderBriefcase).

procedure SaveAsFolderBriefcase(const aFolderName: string)

Parameters:

  • aFolderName: Folder name

SetPropValue

Sets specified property.

procedure SetPropValue(const aName: UnicodeString; const aValue: UnicodeString)

Parameters:

  • aName: Property name
  • aValue: Property value

SortTables

Sorts tables in briefcase

procedure SortTables

TableNamed  deprecated

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

Writes briefcase to disk.

procedure WriteBriefcase