Console Sample
The Briefcase Console sample demonstrates using the FileBriefcase class to store and then load two DataTables that have changes that are waiting to be sent to the server.
The Briefcase can be helpful for situations where there isn't a persistent connection to the server and the user needs to be able to quit your app or otherwise work in an offline fashion. Another use of a it might be to aid in the application start-up process, as you can load the data from disk without needing to rely on the server being available.
Getting Started
The sample is typically located in C:\Users\Public\Public Documents\RemObjects Samples\Data Abstract for .NET\C#\Briefcase (Console), though you may have installed the Data Abstract for .NET SDK and it's samples in another location.
To build it, you will of course need Visual Studio, and like all the samples provided with Data Abstract for .NET you will need to be running the Relativity Server with the DASamples Domain and the Simple Schema available.
Included with the sample is a DataTableExtension class which has a single public static method (LogToString) that takes a DataTable object and creates a nicely formatted string representation of the table that can be printed to the Console which can be useful for debugging purposes. (An example of its output can be seen at the end of this document)
Running the Sample
The sample when run sets up a connection to the Relativity Server (STEP 1) and then retrieves a limited set of data from two DataTables using an SQL statement to do the filtering (STEP 2). The first table is the Orders table, where we are only interested in the rows that match particular order ids. The second table is the OrderDetails table, where we are only interested in the rows where the value in the Order column matches the order id.
Having retrieved the tables, we make minor modifications to them so that they are different than the server versions so we can see see that when we reload the data from the briefcase; specifically we increase the value in the Amount column of the OrderDetails table (STEP 3). The newly modified tables are then saved to disk in a briefcase file with some properties set that will be printed when the briefcase is later reloaded (STEP 4).
The briefcase is then reloaded from disk and the contents printed to the console (STEP 5), before the changes are then applied back to the server and stored to disk once again.
Once the sample is finished if you navigate to the C:\Users\Public\Documents\RemObjects Samples\Data Abstract for .NET\C#\Briefcase (Console)\Briefcase\bin\Debug folder in Explorer, you will see the briefcase file (BriefcaseSample.daBriefcase) that was written to disk at the end of the samples run. That single file contains the two DataTables and the briefcase properties and if you double click on it the Briefcase Explorer will open and display the contents of the briefcase for examination.
Examining the Code
The code for creating the connection to the server, retrieving and modifying the data are covered by other samples. In this section we shall focus solely on steps 4 and 5 that handle the creation of the briefcase, storing the tables in it and then reloading those tables back from disk.
Store the tables in a new briefcase
As noted in the Briefcase Overview, briefcases can be stored in one of two formats; either as a single .daBriefcase which will contain all of the tables and properties that you set or as a package (folder) where each table is stored in its own .daBriefcase file and the properties are stored in a .plist file. This sample uses the single file version, but if you want folder format simply replace the two instances of FileBriefcase with FolderBriefcase.
The constructor for FileBriefcase takes two arguments, the first is a string which is used as the filename and location to store the briefcase file. If the filename is simply a filename specified without a location, then the briefcase will be stored in the folder in which the sample is being run, otherwise the FileBriefcase will attempt to store the file in the specified location. The second argument is a boolean which indicates if the FileBriefcase should deserialize its contents immediately on opening, this allows you to do lazy loading which can save memory. As we intend to only store contents in the briefcase wiping out anything that was stored there before, we pass in false
Properties are stored in a dictionary (IDictionary), so we can set and retrieve a property by passing its name to the properties object. Here we set two properties, the first is a version number which could be used to prevent loading a briefcase from an old version of the application, and the second is the data at which the briefcase contents were updated. To add a property to a briefcase, you simply need to use the Add() method of the Properties property. It takes two string arguments, the first of which is the name of the property and the second are the contents of the property.
To add a table to the briefcase, we call the AddTable method which takes a DataTable as an argument. This adds the table to the briefcase and if a table with the same name is already there, it will be replaced with this new table.
At this stage, the tables only exist in the briefcase in memory, we need to use the WriteBriefcase method to actually write it to the filesystem.
Briefcase lBriefcace = new FileBriefcase(BRIEFCASE_FILENAME, false);
lBriefcace.Properties.Add("UpdateDate", "");
lBriefcace.Properties.Add("Version", BRIEFCASE_VERSION);
Console.WriteLine(String.Format("Briefcase: {0}", Path.GetFullPath(lBriefcace.FileName)));
Console.WriteLine("Added tables: OrderDetails, Orders");
lBriefcace.AddTable(lTableOrder);
lBriefcace.AddTable(lTableOrderDetails);
Console.WriteLine("Writting briefcase to file system...");
lBriefcace.Properties["UpdateDate"] = DateTime.Now.ToString();
lBriefcace.WriteBriefcase();
Loading the briefcase from disk and retrieving the tables
As before we pass the BRIEFCASE_FILENAME to the FileBriefcase constructor (note that this time we pass in TRUE because we are opening for reading a briefcase file we know exists and we want to pre-load the data).
The briefcase is loaded back into memory from disk, and we can immediately start retrieving the properties and tables that were stored in it. Properties are retrieved by passing the name of the property to Properties[], and a copy of the stored DataTable is retrieved using the FindTable method. Here we retrieve the Version and UpdateDate properties and print them to the console and then we loop on the array of TableNames that the briefcase contains and print each table to the console to demonstrate that the tables contain the changes made in Step 3.
lBriefcace = new FileBriefcase(BRIEFCASE_FILENAME, true);
Console.WriteLine("Briefcase version is: {0}", lBriefcace.Properties["Version"]);
Console.WriteLine("Briefcase update date is: {0}", lBriefcace.Properties["UpdateDate"]);
foreach (String tableName in lBriefcace.TableNames)
{
Console.Write(lBriefcace.FindTable(tableName).LogToString());
}
Typical Output
This is a typical output from the sample after it has been run. As you can see it clearly calls out each step as it is processed. You can see that the values in the Amount column are increased by 1 between when they are first retrieved from the server in Step 2 and when they are loaded back from the briefcase in Step 5.
Breifcase sample has been started.
Target URL is http://localhost:7099/bin
RO SDK layer is configured.
RO DataAbstract layer is configured.
STEP 1: Login to DataService
Login string is UserId="simple";Password="simple";Domain="DASamples";Schema="Simple"
Login has been successful. Going further...
STEP 2. Select some data (certain orders and their details) to store as briefcase...
Table: Orders (3 rows from 3)
|--------------------------------------------------------------------------------|
| Id | Date | Status | Type | Contractor | Manager |
|--------------------------------------------------------------------------------|
| 20 | 03/01/2014... | 0 | 2 | 21 | 8 |
| 22 | 03/01/2014... | 0 | 2 | 22 | 8 |
| 24 | 04/01/2014... | 0 | 2 | 22 | 8 |
|--------------------------------------------------------------------------------|
Table: OrderDetails (5 rows from 5)
|--------------------------------------------------------------------------|
| Id | Order | Product | Amount | Price |
|--------------------------------------------------------------------------|
| 129 | 20 | 79 | 2 | 357 |
| 132 | 22 | 16 | 3 | 360 |
| 135 | 24 | 37 | 3 | 23 |
| 136 | 24 | 24 | 3 | 347 |
| 137 | 24 | 86 | 2 | 17 |
|--------------------------------------------------------------------------|
STEP 3. Make some changes but does not apply them ...
Table: Orders (3 rows from 3)
|--------------------------------------------------------------------------------|
| Id | Date | Status | Type | Contractor | Manager |
|--------------------------------------------------------------------------------|
| 20 | 03/01/2014... | 0 | 2 | 21 | 8 |
| 22 | 03/01/2014... | 0 | 2 | 22 | 8 |
| 24 | 04/01/2014... | 0 | 2 | 22 | 8 |
|--------------------------------------------------------------------------------|
Table: OrderDetails (5 rows from 5)
|--------------------------------------------------------------------------|
| Id | Order | Product | Amount | Price |
|--------------------------------------------------------------------------|
| 129 | 20 | 79 | 3 | 357 |
| 132 | 22 | 16 | 4 | 360 |
| 135 | 24 | 37 | 4 | 23 |
| 136 | 24 | 24 | 4 | 347 |
| 137 | 24 | 86 | 3 | 17 |
|--------------------------------------------------------------------------|
STEP 4. Prepare briefcase and store tables there ...
Briefcase: C:\Users\Public\Documents\RemObjects Samples\Data Abstract for .NET\C#\Briefcase (Console)\Briefcase\bin\Debug\BriefcaseSample.daBriefcase
Added tables: OrderDetails, Orders
Writting briefcase to file system...
STEP 5. Read briefcase from file system with its pending changes ...
Briefcase version is: v.0.1
Briefcase update date is: 27/01/2016 18:15:10
Table: Orders (3 rows from 3)
|--------------------------------------------------------------------------------|
| Id | Date | Status | Type | Contractor | Manager |
|--------------------------------------------------------------------------------|
| 20 | 03/01/2014... | 0 | 2 | 21 | 8 |
| 22 | 03/01/2014... | 0 | 2 | 22 | 8 |
| 24 | 04/01/2014... | 0 | 2 | 22 | 8 |
|--------------------------------------------------------------------------------|
Table: OrderDetails (5 rows from 5)
|--------------------------------------------------------------------------|
| Id | Order | Product | Amount | Price |
|--------------------------------------------------------------------------|
| 129 | 20 | 79 | 3 | 357 |
| 132 | 22 | 16 | 4 | 360 |
| 135 | 24 | 37 | 4 | 23 |
| 136 | 24 | 24 | 4 | 347 |
| 137 | 24 | 86 | 3 | 17 |
|--------------------------------------------------------------------------|
Apply pending changes to the server and update briefcase....
Done!