FolderBriefcase

Overview

The FolderBriefcase class provides support for persisting client data stored in a folder 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 DataTables 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.

The main difference between FolderBriefcase and FileBriefcase briefcases is that all data (original table data, pending changes and custom properties) in the FolderBriefcase briefcase isstored in separate files: .plist file is used to store custom properties and .daBriefcase files - for data tables. FileBriefcase briefcase stores data in single file with .daBriefcase extension.

The DA Briefcase Explorer tool can be used to load and inspect data in the briefcase. Also Briefcase sample may be useful to investigate how FileBriefcase and FolderBriefcase classes are used to work with briefcases.

Sample of using FolderBriefcase:

// Create new empty briefcase
Briefcase newBriefcase = new FolderBriefcase(briefcaseName);
// Add table to the briefcase
newBriefcase.AddTable(myDataset.Customers);

// Add some custom properties
newBriefcase.Properties.Add("CreateDate", DateTime.Now.ToLongDateString());
newBriefcase.Properties.Add("CreateTime", DateTime.Now.ToLongTimeString());
newBriefcase.Properties.Add("User", Environment.UserName);

// Write briefcase to the folder
newBriefcase.WriteBriefcase();

//-------------------------------------------------
// Reading Briefcase

// Read existing briefcase
Briefcase existingBriefcase = new FolderBriefcase(briefcaseName, true);

// Write some info about loaded briefcase to console
System.Console.WriteLine("Briefcase {0} was loaded.\nIt has {1} tables and {2} custom properties.",
                           existingBriefcase.FileName,
                           existingBriefcase.TableNames.GetLength(0),
existingBriefcase.Properties.Count);
System.Console.WriteLine();
System.Console.WriteLine("Tables:");
System.Console.WriteLine("----------------------");
int idx = 0;
foreach (String tableName in existingBriefcase.TableNames)
    System.Console.WriteLine("{0}: {1} ({2} rows)", ++idx, tableName, existingBriefcase.TableNamed(tableName).Rows.Count);
System.Console.WriteLine();
System.Console.WriteLine("Properties:");
System.Console.WriteLine("----------------------");
idx = 0;
foreach (String key in existingBriefcase.Properties.Keys)
    System.Console.WriteLine("{0}: {1} = {2}", ++idx, key, existingBriefcase.Properties[key]);
System.Console.WriteLine();

/*
OUTPUT

Briefcase c:\...\My.daBriefcase.Briefcase 
was loaded.
It has 1 tables and 3 custom properties.

Tables:
----------------------
1: Customers (0 rows)

Properties:
----------------------
1: CreateDate = Friday, June 17, 2011
2: CreateTime = 3:16:15 PM
3: User = customer
*/

Location


 

constructor (String)  protected    (declared in Briefcase)

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

 

constructor(filename: String)

 

FolderBriefcase(String filename)

 

Sub New(filename As String)

Parameters:

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

constructor (String)

Creates a new instance of the FolderBriefcase class. Briefcase will be loaded from (or will be saved to) the folder with provided name. If folder doesn't exist then it is automatically created.

 

constructor(folderName: String)

 

FolderBriefcase(String folderName)

 

Sub New(folderName As String)

Parameters:

  • folderName: Folder that stores Briefcase data

constructor (String, Boolean) beta

Creates a new instance of the FolderBriefcase class. Briefcase will be loaded from (or will be saved to) the folder with provided name. If folder doesn't exist then it is automatically created.

If the latter constructor parameter is set to true then Briefcase tables will be deserialized immediately. Otherwise Briefcase will store only their names, while data itself will be deserilaized on first request. Such lazy loading can save memory of the Briefcase contains large yet rarely used tables.

 

constructor(folderName: String; preloadData: Boolean)

 

FolderBriefcase(String folderName, Boolean preloadData)

 

Sub New(folderName As String, preloadData As Boolean)

Parameters:

  • folderName: Folder that stores Briefcase data
  • preloadData: Defines whether Briefcase data sholud be deserialized

AddTable    (declared in Briefcase)

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    (declared in Briefcase)

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    (declared in Briefcase)

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

 

method Clear

 

void Clear()

 

Sub Clear()

Count    (declared in Briefcase)

Gets the count of Data Tables in the Briefcase.

 

property Count: Int32 read;

 

Int32 Count { get; }

 

ReadOnly Property Count() As Int32

FileName    (declared in Briefcase)

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)    (declared in Briefcase)

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)    (declared in Briefcase)

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    (declared in Briefcase)

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    (declared in Briefcase)

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 beta

Loads the Briefcase table from the filesystem.

This method is used internally by the FindTable method to lazily load Briefcase data tables, if needed.

 

method LoadTable(name: String): DataTable

 

DataTable LoadTable(String name)

 

Function LoadTable(name As String) As DataTable

Parameters:

  • name: Briefcase table name

Properties    (declared in Briefcase)

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 beta

Reads the Briefcase from the file.

There is no need to call this method explicitly if the Briefcase was created with preloadData constructor parameter set, unless the Briefcase files on the disk was changed and should be reloaded.

 

method ReadBriefcase

 

void ReadBriefcase()

 

Sub ReadBriefcase()

RemoveTable    (declared in Briefcase)

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    (declared in Briefcase)

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 whole Briefcase (custom properties and data tables) into files (.plist file is used to store custom properties and .daBriefcase file is used to store data tables). If Briefcase folder doesn't exist then an exception is raised.

 

method WriteBriefcase

 

void WriteBriefcase()

 

Sub WriteBriefcase()

 

Count    (declared in Briefcase)

Gets the count of Data Tables in the Briefcase.

 

property Count: Int32 read;

 

Int32 Count { get; }

 

ReadOnly Property Count() As Int32

FileName    (declared in Briefcase)

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    (declared in Briefcase)

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    (declared in Briefcase)

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 (String)  protected    (declared in Briefcase)

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

 

constructor(filename: String)

 

FolderBriefcase(String filename)

 

Sub New(filename As String)

Parameters:

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

constructor (String)

Creates a new instance of the FolderBriefcase class. Briefcase will be loaded from (or will be saved to) the folder with provided name. If folder doesn't exist then it is automatically created.

 

constructor(folderName: String)

 

FolderBriefcase(String folderName)

 

Sub New(folderName As String)

Parameters:

  • folderName: Folder that stores Briefcase data

constructor (String, Boolean) beta

Creates a new instance of the FolderBriefcase class. Briefcase will be loaded from (or will be saved to) the folder with provided name. If folder doesn't exist then it is automatically created.

If the latter constructor parameter is set to true then Briefcase tables will be deserialized immediately. Otherwise Briefcase will store only their names, while data itself will be deserilaized on first request. Such lazy loading can save memory of the Briefcase contains large yet rarely used tables.

 

constructor(folderName: String; preloadData: Boolean)

 

FolderBriefcase(String folderName, Boolean preloadData)

 

Sub New(folderName As String, preloadData As Boolean)

Parameters:

  • folderName: Folder that stores Briefcase data
  • preloadData: Defines whether Briefcase data sholud be deserialized

AddTable    (declared in Briefcase)

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    (declared in Briefcase)

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    (declared in Briefcase)

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

 

method Clear

 

void Clear()

 

Sub Clear()

Fill (DataSet)    (declared in Briefcase)

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)    (declared in Briefcase)

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    (declared in Briefcase)

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    (declared in Briefcase)

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 beta

Loads the Briefcase table from the filesystem.

This method is used internally by the FindTable method to lazily load Briefcase data tables, if needed.

 

method LoadTable(name: String): DataTable

 

DataTable LoadTable(String name)

 

Function LoadTable(name As String) As DataTable

Parameters:

  • name: Briefcase table name

ReadBriefcase beta

Reads the Briefcase from the file.

There is no need to call this method explicitly if the Briefcase was created with preloadData constructor parameter set, unless the Briefcase files on the disk was changed and should be reloaded.

 

method ReadBriefcase

 

void ReadBriefcase()

 

Sub ReadBriefcase()

RemoveTable    (declared in Briefcase)

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 whole Briefcase (custom properties and data tables) into files (.plist file is used to store custom properties and .daBriefcase file is used to store data tables). If Briefcase folder doesn't exist then an exception is raised.

 

method WriteBriefcase

 

void WriteBriefcase()

 

Sub WriteBriefcase()