DABriefcase

Overview

The DABriefcase provides support for persisting data used by client applications as a so called Briefcase file locally on your file system, for example to cache it between restarts of your application, or to avoid having to reload large portions of data. A briefcase can hold one or more DADataTables 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 (or the iPhone's persistent memory), 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 and folder-based, 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, which causes it to appear as a Mac OS X package file in Finder). 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 Server Explorer tool can be used to load and inspect data in both types of briefcases.

.daBriefcase Binary Layout

While this information is not needed for general use of Data Abstract, as all the reading and writing of briefcase files is encapsulated in the DABriefcase classes, the following describes the format layout of binary .daBriefcase files:

  • The first 8 bytes are occupied by the briefcase header and version number, currently "DABRC600", indicating Version 6.0 of Data Abstract.
  • The next 4 bytes contain an int32 value that represents the offset, within the file, of the actual briefcase data.
  • Next, custom string properties are encoded, starting with an int32 indicating the number of properties, followed by each property as a name/value pair, both encoded as BinMessage UTF-8 strings.
  • Finally, the data and delta follows, in regular Bin2DataStreamer format.

Location


 

addTable:

Adds a DADataTable to the briefcase. Adding table will not cause the briefcase to be written to the disk immediately, it merely adds the table to the list of tables to be written. This list is maintained by table name, so each table added to a briefcase must have a unique name, or it will replace whatever other table by the same name has been added prior. Use saveBriefcase to persist the briefcase and all its data to disk.

- (void) addTable:(DADataTable *)table

Parameters:

  • table: Reference to the table to be added to the briefcase.

addTables:

Adds an NSArray of DADataTables to the briefcase. Adding table will not cause the briefcase to be written to disk immediately, it merely adds the table to the list of tables to be written. This list is maintained by table name, so each table added to a briefcase must have a unique name, or it will replace whatever other table by the same name has been added prior. Use saveBriefcase to persist the briefcase and all its data to disk.

- (void) addTables:(NSArray *)tables

Parameters:

  • tables: Array of tables to be added to the briefcase. All elements in this array must be of type DADataTable.

briefcaseWithFile:

+ (InstanceType) briefcaseWithFile:(NSString *)fileName

Parameters:

  • fileName:

briefcaseWithFile:forReading:

+ (InstanceType) briefcaseWithFile:(NSString *)fileName forReading:(BOOL)forReading

Parameters:

  • fileName:
  • forReading:

briefcaseWithFileName:

+ (InstanceType) briefcaseWithFileName:(NSString *)fileName

Parameters:

  • fileName:

briefcaseWithFileName:forReading:

+ (InstanceType) briefcaseWithFileName:(NSString *)fileName forReading:(BOOL)forReading

Parameters:

  • fileName:
  • forReading:

briefcaseWithFolder:

+ (InstanceType) briefcaseWithFolder:(NSString *)fileName

Parameters:

  • fileName:

clearTablesCache

Each briefcase has its own cache which holds the data we read previously. So when we second time will try to get the same table it will be obtained from the cache (not from the file at disk). In some cases we may need to re-read data from the file, and here the clearTablesCache method allows us to invalidate current cache and read data again from the file

- (void) clearTablesCache

defaultExtension

- (NSString *) defaultExtension

delete

method removes whole briefcase file.

- (void) delete

fileName

File (or folder, in case of a folder-based briefcase) name and path of the briefcase.

@property (readonly) NSString *fileName

initWithFile:forReading:

- (InstanceType) initWithFile:(NSString *)fileName forReading:(BOOL)forReading

Parameters:

  • fileName:
  • forReading:

initWithFolder:

- (InstanceType) initWithFolder:(NSString *)fileName

Parameters:

  • fileName:

loadData:

- (void) loadData:(NSData *)aData

Parameters:

  • aData:

properties

Dictionary of custom application-defined properties that will be stored alongside the briefcase data.

@property (readonly) NSMutableDictionary *properties

removeAllTables

Removes all tables from the briefcase. Note that sending this message will not immediately remove the tables from disk; this happens when saveBriefcase is sent to write the entire briefcase back to disk.

- (void) removeAllTables

removeTableNamed:

Removes the table with the given name from the briefcase. Note that sending this message will not immediately remove the table from disk; this happens when saveBriefcase is sent to write the entire briefcase back to disk.

- (void) removeTableNamed:(NSString *)name

Parameters:

  • name: Name of the table we want to remove from the briefcase.

tableAtIndex:

Returns reference to the table stored in the briefcase at given index. If not loaded from disk yet, sending this message will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.

- (DADataTable *) tableAtIndex:(int)index

Parameters:

  • index: index of the table we want to retrieve from the briefcase

tableNamed:

Returns reference to the table with the given name, as stored in the briefcase. If not loaded from disk yet, sending this message will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.

- (DADataTable *) tableNamed:(NSString *)name

Parameters:

  • name: Name of the table to obtain.

tableNames

Returns an array of names all tables in the briefcase.

- (NSArray *) tableNames

writeBriefcase

- (void) writeBriefcase

writeBriefcaseHeaderToData:

- (void) writeBriefcaseHeaderToData:(NSMutableData *)aData

Parameters:

  • aData:

 

fileName

File (or folder, in case of a folder-based briefcase) name and path of the briefcase.

@property (readonly) NSString *fileName

properties

Dictionary of custom application-defined properties that will be stored alongside the briefcase data.

@property (readonly) NSMutableDictionary *properties

 

briefcaseWithFile:

+ (InstanceType) briefcaseWithFile:(NSString *)fileName

Parameters:

  • fileName:

briefcaseWithFile:forReading:

+ (InstanceType) briefcaseWithFile:(NSString *)fileName forReading:(BOOL)forReading

Parameters:

  • fileName:
  • forReading:

briefcaseWithFileName:

+ (InstanceType) briefcaseWithFileName:(NSString *)fileName

Parameters:

  • fileName:

briefcaseWithFileName:forReading:

+ (InstanceType) briefcaseWithFileName:(NSString *)fileName forReading:(BOOL)forReading

Parameters:

  • fileName:
  • forReading:

briefcaseWithFolder:

+ (InstanceType) briefcaseWithFolder:(NSString *)fileName

Parameters:

  • fileName:

 

addTable:

Adds a DADataTable to the briefcase. Adding table will not cause the briefcase to be written to the disk immediately, it merely adds the table to the list of tables to be written. This list is maintained by table name, so each table added to a briefcase must have a unique name, or it will replace whatever other table by the same name has been added prior. Use saveBriefcase to persist the briefcase and all its data to disk.

- (void) addTable:(DADataTable *)table

Parameters:

  • table: Reference to the table to be added to the briefcase.

addTables:

Adds an NSArray of DADataTables to the briefcase. Adding table will not cause the briefcase to be written to disk immediately, it merely adds the table to the list of tables to be written. This list is maintained by table name, so each table added to a briefcase must have a unique name, or it will replace whatever other table by the same name has been added prior. Use saveBriefcase to persist the briefcase and all its data to disk.

- (void) addTables:(NSArray *)tables

Parameters:

  • tables: Array of tables to be added to the briefcase. All elements in this array must be of type DADataTable.

clearTablesCache

Each briefcase has its own cache which holds the data we read previously. So when we second time will try to get the same table it will be obtained from the cache (not from the file at disk). In some cases we may need to re-read data from the file, and here the clearTablesCache method allows us to invalidate current cache and read data again from the file

- (void) clearTablesCache

defaultExtension

- (NSString *) defaultExtension

delete

method removes whole briefcase file.

- (void) delete

initWithFile:forReading:

- (InstanceType) initWithFile:(NSString *)fileName forReading:(BOOL)forReading

Parameters:

  • fileName:
  • forReading:

initWithFolder:

- (InstanceType) initWithFolder:(NSString *)fileName

Parameters:

  • fileName:

loadData:

- (void) loadData:(NSData *)aData

Parameters:

  • aData:

removeAllTables

Removes all tables from the briefcase. Note that sending this message will not immediately remove the tables from disk; this happens when saveBriefcase is sent to write the entire briefcase back to disk.

- (void) removeAllTables

removeTableNamed:

Removes the table with the given name from the briefcase. Note that sending this message will not immediately remove the table from disk; this happens when saveBriefcase is sent to write the entire briefcase back to disk.

- (void) removeTableNamed:(NSString *)name

Parameters:

  • name: Name of the table we want to remove from the briefcase.

tableAtIndex:

Returns reference to the table stored in the briefcase at given index. If not loaded from disk yet, sending this message will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.

- (DADataTable *) tableAtIndex:(int)index

Parameters:

  • index: index of the table we want to retrieve from the briefcase

tableNamed:

Returns reference to the table with the given name, as stored in the briefcase. If not loaded from disk yet, sending this message will automatically load the table into memory. Subsequent requests for the same table name will return the same table reference, unless the briefcase itself is released and reloaded.

- (DADataTable *) tableNamed:(NSString *)name

Parameters:

  • name: Name of the table to obtain.

tableNames

Returns an array of names all tables in the briefcase.

- (NSArray *) tableNames

writeBriefcase

- (void) writeBriefcase

writeBriefcaseHeaderToData:

- (void) writeBriefcaseHeaderToData:(NSMutableData *)aData

Parameters:

  • aData: