Briefcase

Overview

The Briefcase class provides basic support for persisting data used by client applications as a so called Briefcase file 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(filename: String)

 

Briefcase(String filename)

 

Sub New(filename As String)

Parameters:

  • filename: Name of the file or the folder that contains the briefcase data

AddTable

Adds a Data Table to the Briefcase.

Table name should be unique for the given Briefcase.

 

method AddTable(table: DataTable)

 

void AddTable(DataTable table)

 

Sub AddTable(table As DataTable)

Parameters:

  • table: Data Table to add to the Briefcase

AddTablePlaceholder  protected

Registers a table name in the Briefcase. The table itself will be loaded from the briefcase on first attempt to access it.

 

method AddTablePlaceholder(name: String)

 

void AddTablePlaceholder(String name)

 

Sub AddTablePlaceholder(name As String)

Parameters:

  • name: Data Table name

Clear

Clears the Briefcase. All Data Tables and custom properties are removed from the Briefcase.

 

method Clear

 

void Clear()

 

Sub Clear()

Count

Gets the count of Data Tables in the Briefcase.

 

property Count: Int32 read;

 

Int32 Count { get; }

 

ReadOnly Property Count() As Int32

FileName

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

 

property FileName: String read;

 

String FileName { get; }

 

ReadOnly Property FileName() As String

Fill (DataSet)

Adds all Data Tables from the briefcase into the provided DataSet.

Note: Data Table instances added to the dataset are clones of the original Data Tables stored in the Briefcase. So any changes made to the Data Tables of the dataset won't affect data actually stored in the Briefcase.

 

method Fill(dataset: DataSet)

 

void Fill(DataSet dataset)

 

Sub Fill(dataset As DataSet)

Parameters:

  • dataset: DataSet that will contain all Briefcase DataTables

Fill (DataSet, array of String)

Adds requested Data Tables from the briefcase into the provided DataSet.

Note: Data Table instances added to the dataset are clones of the original Data Tables stored in the Briefcase. So any changes made to the Data Tables of the dataset won't affect data actually stored in the Briefcase.

 

method Fill(dataset: DataSet; tables: array of String)

 

void Fill(DataSet dataset, String[] tables)

 

Sub Fill(dataset As DataSet, tables As String())

Parameters:

  • dataset: DataSet that will contain all Briefcase DataTables
  • tables: Names of Briefcase tables that should be added to the target DataSet

FindTable

Returns a copy of the Data Table stored in the Briefcase.

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

 

method FindTable(name: String): DataTable

 

DataTable FindTable(String name)

 

Function FindTable(name As String) As DataTable

Parameters:

  • name: Name of the requested Briefcase table

IsDataTableLoaded  protected

Returns true if the Briefcase table with provided name was already deserialized from the Briefcase file.

 

method IsDataTableLoaded(name: String): Boolean

 

Boolean IsDataTableLoaded(String name)

 

Function IsDataTableLoaded(name As String) As Boolean

Parameters:

  • name: Name of the Briefcase table to check

LoadTable  protected

Loads a table with given name from the Briefcase storage (either Briefcase file or Briefcase folder).

 

method LoadTable(name: String): DataTable

 

DataTable LoadTable(String name)

 

Function LoadTable(name As String) As DataTable

Parameters:

  • name: Name of the Briefcase table to load

Properties

Gets a Dictionary containing Briefcase's custom properties.

 

property Properties: IDictionary<String, String> read;

 

IDictionary<String, String> Properties { get; }

 

ReadOnly Property Properties() As IDictionary<String, String>

ReadBriefcase

Loads Briefcase data from the disk.

 

method ReadBriefcase

 

void ReadBriefcase()

 

Sub ReadBriefcase()

RemoveTable

Removes a table with provided name from the Briefcase.

 

method RemoveTable(name: String)

 

void RemoveTable(String name)

 

Sub RemoveTable(name As String)

Parameters:

  • name: Name of the table to remove from the Briefcase

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; }

 

ReadOnly Property TableNames() As String()

WriteBriefcase

Writes Briefcase data to the disk.

 

method WriteBriefcase

 

void WriteBriefcase()

 

Sub WriteBriefcase()

 

Count

Gets the count of Data Tables in the Briefcase.

 

property Count: Int32 read;

 

Int32 Count { get; }

 

ReadOnly Property Count() As Int32

FileName

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

 

property FileName: String read;

 

String FileName { get; }

 

ReadOnly Property FileName() As String

Properties

Gets a Dictionary containing Briefcase's custom properties.

 

property Properties: IDictionary<String, String> read;

 

IDictionary<String, String> Properties { get; }

 

ReadOnly Property Properties() As IDictionary<String, String>

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; }

 

ReadOnly Property TableNames() As String()

 

constructor  protected

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

 

constructor(filename: String)

 

Briefcase(String filename)

 

Sub New(filename As String)

Parameters:

  • filename: Name of the file or the folder that contains the briefcase data

AddTable

Adds a Data Table to the Briefcase.

Table name should be unique for the given Briefcase.

 

method AddTable(table: DataTable)

 

void AddTable(DataTable table)

 

Sub AddTable(table As DataTable)

Parameters:

  • table: Data Table to add to the Briefcase

AddTablePlaceholder  protected

Registers a table name in the Briefcase. The table itself will be loaded from the briefcase on first attempt to access it.

 

method AddTablePlaceholder(name: String)

 

void AddTablePlaceholder(String name)

 

Sub AddTablePlaceholder(name As String)

Parameters:

  • name: Data Table name

Clear

Clears the Briefcase. All Data Tables and custom properties are removed from the Briefcase.

 

method Clear

 

void Clear()

 

Sub Clear()

Fill (DataSet)

Adds all Data Tables from the briefcase into the provided DataSet.

Note: Data Table instances added to the dataset are clones of the original Data Tables stored in the Briefcase. So any changes made to the Data Tables of the dataset won't affect data actually stored in the Briefcase.

 

method Fill(dataset: DataSet)

 

void Fill(DataSet dataset)

 

Sub Fill(dataset As DataSet)

Parameters:

  • dataset: DataSet that will contain all Briefcase DataTables

Fill (DataSet, array of String)

Adds requested Data Tables from the briefcase into the provided DataSet.

Note: Data Table instances added to the dataset are clones of the original Data Tables stored in the Briefcase. So any changes made to the Data Tables of the dataset won't affect data actually stored in the Briefcase.

 

method Fill(dataset: DataSet; tables: array of String)

 

void Fill(DataSet dataset, String[] tables)

 

Sub Fill(dataset As DataSet, tables As String())

Parameters:

  • dataset: DataSet that will contain all Briefcase DataTables
  • tables: Names of Briefcase tables that should be added to the target DataSet

FindTable

Returns a copy of the Data Table stored in the Briefcase.

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

 

method FindTable(name: String): DataTable

 

DataTable FindTable(String name)

 

Function FindTable(name As String) As DataTable

Parameters:

  • name: Name of the requested Briefcase table

IsDataTableLoaded  protected

Returns true if the Briefcase table with provided name was already deserialized from the Briefcase file.

 

method IsDataTableLoaded(name: String): Boolean

 

Boolean IsDataTableLoaded(String name)

 

Function IsDataTableLoaded(name As String) As Boolean

Parameters:

  • name: Name of the Briefcase table to check

LoadTable  protected

Loads a table with given name from the Briefcase storage (either Briefcase file or Briefcase folder).

 

method LoadTable(name: String): DataTable

 

DataTable LoadTable(String name)

 

Function LoadTable(name As String) As DataTable

Parameters:

  • name: Name of the Briefcase table to load

ReadBriefcase

Loads Briefcase data from the disk.

 

method ReadBriefcase

 

void ReadBriefcase()

 

Sub ReadBriefcase()

RemoveTable

Removes a table with provided name from the Briefcase.

 

method RemoveTable(name: String)

 

void RemoveTable(String name)

 

Sub RemoveTable(name As String)

Parameters:

  • name: Name of the table to remove from the Briefcase

WriteBriefcase

Writes Briefcase data to the disk.

 

method WriteBriefcase

 

void WriteBriefcase()

 

Sub WriteBriefcase()