Briefcase

Overview

The Briefcase class provides basic support for persisting data used by client applications as a so called briefcase locally in the file system (f.e. to cache data between restarts of the application, or to avoid having to reload large portions of data from the remote Data Abstrct server). A briefcase can hold one or more Data Tables 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 (FileBriefcase) and folder-based (FolderBriefcase), 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 DA Briefcase Explorer can be used to load and inspect data in both types of briefcases.

Location


 

constructor  protected

Creates a new instance of the Briefcase class. Cannot be called directly.

 

constructor

 

Briefcase()

addTable

Adds a data table to the Briefcase.

Table name should be unique for the given Briefcase.

 

method addTable(aTable: DataTable)

 

void addTable(DataTable aTable)

Parameters:

  • aTable: Data Table to add to the Briefcase

addTables

Adds several data tables to the Briefcase.

Table name should be unique for the given Briefcase.

 

method addTables(aTables: array of DataTable)

 

void addTables(DataTable[] aTables)

Parameters:

  • aTables: An array of tables to add.

Count

Gets the count of Data Tables in the Briefcase.

 

property Count: Integer read;

 

Integer Count { __get; }

doFill  protected

Thу method where an actual reading the data and filling the table should be performed. MUST be overriden by inheritors.

 

method doFill(aTables: array of DataTable)

 

void doFill(DataTable[] aTables)

Parameters:

  • aTables: Instantiated and named DataTable instances, that are supposed to be filled by the method.

FileName

Name of the file of a folder that contain the Briefcase data

 

property FileName: String read;

 

String FileName { __get; }

fillTable

Fills the given named data table instance with the data from briefcase. Any further data changes in the given table won't be reflected in the briefcase, therefore use writeBriefcase method for this.

 

method fillTable(aTable: DataTable)

 

void fillTable(DataTable aTable)

Parameters:

  • aTable: Instantiated and named table instance to fill with data.

fillTables

Fills the given named data tables instances with the data from briefcase. Any further data changes in the given tables won't be reflected in the briefcase, therefore use writeBriefcase method for this.

 

method fillTables(aTables: array of DataTable)

 

void fillTables(DataTable[] aTables)

Parameters:

  • aTables: Instantiated and named table instances to fill with data.

Properties

Gets a Dictionary containing Briefcase's custom properties.

 

property Properties: Map<String, String> read;

 

Map<String, String> Properties { __get; }

tableNamed (String): DataTable

Returns a copy of the data table stored in the Briefcase.

Note: DataTable instance returned by this method is a clone of the original Data Table stored in the Briefcase. So any changes made to this DataTable won't affect data actually stored in the Briefcase.

 

method tableNamed(tableName: String): DataTable

 

DataTable tableNamed(String tableName)

Parameters:

  • tableName: A name of the table, that should be returned.

tableNamed (String, Boolean): DataTable

Returns a copy of the data table stored in the Briefcase.

Note: DataTable instance returned by this method is a clone of the original Data Table stored in the Briefcase. So any changes made to this DataTable won't affect data actually stored in the Briefcase.

 

method tableNamed(tableName: String; reloadData: Boolean): DataTable

 

DataTable tableNamed(String tableName, Boolean reloadData)

Parameters:

  • tableName: A name of the table, that should be returned.
  • reloadData: If true, it reloads a table with the given name from the Briefcase storage.

TableNames

Provides access to String array containing all briefcase's table names.

This property is calculated on the fly, so it is advised to cache its value in the case it should be accessed several times in a row.

 

property TableNames: array of String read;

 

String[] TableNames { __get; }

writeBriefcase

Writes Briefcase data to the relater resource.

 

method writeBriefcase

 

void writeBriefcase()

 

Count

Gets the count of Data Tables in the Briefcase.

 

property Count: Integer read;

 

Integer Count { __get; }

FileName

Name of the file of a folder that contain the Briefcase data

 

property FileName: String read;

 

String FileName { __get; }

Properties

Gets a Dictionary containing Briefcase's custom properties.

 

property Properties: Map<String, String> read;

 

Map<String, String> Properties { __get; }

TableNames

Provides access to String array containing all briefcase's table names.

This property is calculated on the fly, so it is advised to cache its value in the case it should be accessed several times in a row.

 

property TableNames: array of String read;

 

String[] TableNames { __get; }

 

constructor  protected

Creates a new instance of the Briefcase class. Cannot be called directly.

 

constructor

 

Briefcase()

addTable

Adds a data table to the Briefcase.

Table name should be unique for the given Briefcase.

 

method addTable(aTable: DataTable)

 

void addTable(DataTable aTable)

Parameters:

  • aTable: Data Table to add to the Briefcase

addTables

Adds several data tables to the Briefcase.

Table name should be unique for the given Briefcase.

 

method addTables(aTables: array of DataTable)

 

void addTables(DataTable[] aTables)

Parameters:

  • aTables: An array of tables to add.

doFill  protected

Thу method where an actual reading the data and filling the table should be performed. MUST be overriden by inheritors.

 

method doFill(aTables: array of DataTable)

 

void doFill(DataTable[] aTables)

Parameters:

  • aTables: Instantiated and named DataTable instances, that are supposed to be filled by the method.

fillTable

Fills the given named data table instance with the data from briefcase. Any further data changes in the given table won't be reflected in the briefcase, therefore use writeBriefcase method for this.

 

method fillTable(aTable: DataTable)

 

void fillTable(DataTable aTable)

Parameters:

  • aTable: Instantiated and named table instance to fill with data.

fillTables

Fills the given named data tables instances with the data from briefcase. Any further data changes in the given tables won't be reflected in the briefcase, therefore use writeBriefcase method for this.

 

method fillTables(aTables: array of DataTable)

 

void fillTables(DataTable[] aTables)

Parameters:

  • aTables: Instantiated and named table instances to fill with data.

tableNamed (String): DataTable

Returns a copy of the data table stored in the Briefcase.

Note: DataTable instance returned by this method is a clone of the original Data Table stored in the Briefcase. So any changes made to this DataTable won't affect data actually stored in the Briefcase.

 

method tableNamed(tableName: String): DataTable

 

DataTable tableNamed(String tableName)

Parameters:

  • tableName: A name of the table, that should be returned.

tableNamed (String, Boolean): DataTable

Returns a copy of the data table stored in the Briefcase.

Note: DataTable instance returned by this method is a clone of the original Data Table stored in the Briefcase. So any changes made to this DataTable won't affect data actually stored in the Briefcase.

 

method tableNamed(tableName: String; reloadData: Boolean): DataTable

 

DataTable tableNamed(String tableName, Boolean reloadData)

Parameters:

  • tableName: A name of the table, that should be returned.
  • reloadData: If true, it reloads a table with the given name from the Briefcase storage.

writeBriefcase

Writes Briefcase data to the relater resource.

 

method writeBriefcase

 

void writeBriefcase()