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
- Unit: uDABriefcase.pas
- Ancestry: TDABaseBriefcase
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
- Delphi:
- .NET:
-
Xcode:
- DABriefcase
- DAFolderBriefcase
- Java
- Briefcase Explorer