FileBriefcase

Overview

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

All data in the FileBriefcase are stored using the Bin2DataStreamer streamer.

The main difference of the FileBriefcase from the FolderBriefcase is that the all data (original table data, pending changes and custom properties) are stored in the single file.

File of the FileBriefcase usually has .daBriefcase extension.

The Briefcase Explorer tool can be used to load and inspect data in the briefcase. You can see how to work with it in Data Abstract Briefcase Sample

Sample of using the FileBriefcase class:

String briefcaseName = Path.Combine(Path.GetDirectoryName(Application.ExecutablePath),"My.daBriefcase");

//-------------------------------------------------
// Writing New Briefcase

// Create new empty briefcase (note that second parameter is false)
Briefcase newBriefcase = new FileBriefcase(briefcaseName, false);
// Add table to the briefcase
newBriefcase.AddTable(myDataset.Workers);

// 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 file
newBriefcase.WriteBriefcase();

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

// Read existing briefcase
Briefcase existingBriefcase = new FileBriefcase(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.FindTable(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 was loaded.
It has 1 tables and 3 custom properties.

Tables:
----------------------
1: Workers (10 rows)

Properties:
----------------------
1: CreateDate = Friday, November 12, 2010
2: CreateTime = 9:53:06 AM
3: User = customer

*/

Location


 

constructor (String)

Creates a new instance of the FileBriefcase class. Briefcase will be loaded from (or will be saved to) the file with provided name.

 

constructor(filename: String)

 

FileBriefcase(String filename)

 

Sub New(filename As String)

Parameters:

  • filename: Name of the file that contains Briefcase data

constructor (String, Boolean)

Creates a new instance of the FileBriefcase class. Briefcase will be loaded from (or will be saved to) the file with provided name.

 

constructor(filename: String; preloadData: Boolean)

 

FileBriefcase(String filename, Boolean preloadData)

 

Sub New(filename As String, preloadData As Boolean)

Parameters:

  • filename: Name of the file that contains Briefcase data
  • preloadData: Defines whether Briefcase data sholud be deserialized from the file

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.

Note: This method is not implemented in the FileBriefcase class.

 

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 file 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

Saves the Briefcase to the file.

 

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)

Creates a new instance of the FileBriefcase class. Briefcase will be loaded from (or will be saved to) the file with provided name.

 

constructor(filename: String)

 

FileBriefcase(String filename)

 

Sub New(filename As String)

Parameters:

  • filename: Name of the file that contains Briefcase data

constructor (String, Boolean)

Creates a new instance of the FileBriefcase class. Briefcase will be loaded from (or will be saved to) the file with provided name.

 

constructor(filename: String; preloadData: Boolean)

 

FileBriefcase(String filename, Boolean preloadData)

 

Sub New(filename As String, preloadData As Boolean)

Parameters:

  • filename: Name of the file that contains Briefcase data
  • preloadData: Defines whether Briefcase data sholud be deserialized from the file

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.

Note: This method is not implemented in the FileBriefcase class.

 

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 file 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

Saves the Briefcase to the file.

 

method WriteBriefcase

 

void WriteBriefcase()

 

Sub WriteBriefcase()