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:

Opens a new instance of a single-file briefcase for reading and initializes it with data from an existing briefcase with a given name. If no briefcase with the given name is found, an exception will be thrown. If you don't want to read existing briefcase data, call briefcaseWithFile:forReading: overload instead.

Sending this message is equivalent to sendind briefcaseWithFile:... forReading:YES

+ (id) briefcaseWithFile:(NSString *)fileName

Parameters:

  • fileName: File name of the file briefcase. If the filename does not end with the default extension (.daBriefcase for file briefcases), the extension will be added automatically.

briefcaseWithFile:forReading:

Creates and initializes a new instance of single-file briefcase. In contrast to the previous method, the additional forReading parameter controls whether to open an existing briefcase for reading, of create a new briefcase for writing/replacing the old one. This method can be useful if you want to completely overwrite all data in an existing briefcase with new data, by calling it with a value of NO for forReading.

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

Parameters:

  • fileName: File name of the file briefcase. If the filename does not end with the default extension (.daBriefcase for file briefcases), the extension will be added automatically.
  • forReading: BOOL flag that specifies whether to open an existing briefcase (YES) or write a new one (NO).

briefcaseWithFolder:

Creates and initializes a new instance of a folder-based briefcase. Folder-based briefcases always support reading and writing; if no briefcase with the given file name exists, a new briefcase will be created.

+ (id) briefcaseWithFolder:(NSString *)fileName

Parameters:

  • fileName: Full path to the folder briefcase. If the filename does not end with the default extension (.briefcase for folder briefcases), the extension will be added automatically.

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

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:

Initializes a new instance of a single-file briefcase for reading and initializes it with data from an existing briefcase with a given name. The additional forReading parameter controls whether to open an existing briefcase for reading, of create a new briefcase for writing/replacing the old one. This method can be useful if you want to completely overwrite all data in an existing briefcase with new data, by calling it with a value of NO for forReading.

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

Parameters:

  • fileName: File name of the file briefcase. If the filename does not end with the default extension (.daBriefcase for file briefcases), the extension will be added automatically.
  • forReading: BOOL flag that specifies whether to open an existing briefcase (YES) or write a new one (NO).

initWithFolder:

Initializes a new instance of a folder-based briefcase. Folder-based briefcases always support reading and writing; if no briefcase with the given file name exists, a new briefcase will be created.

- (id) initWithFolder:(NSString *)fileName

Parameters:

  • fileName: Full path to the folder briefcase. If the filename does not end with the default extension (.briefcase for folder briefcases), the extension will be added automatically.

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

 

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:

Opens a new instance of a single-file briefcase for reading and initializes it with data from an existing briefcase with a given name. If no briefcase with the given name is found, an exception will be thrown. If you don't want to read existing briefcase data, call briefcaseWithFile:forReading: overload instead.

Sending this message is equivalent to sendind briefcaseWithFile:... forReading:YES

+ (id) briefcaseWithFile:(NSString *)fileName

Parameters:

  • fileName: File name of the file briefcase. If the filename does not end with the default extension (.daBriefcase for file briefcases), the extension will be added automatically.

briefcaseWithFile:forReading:

Creates and initializes a new instance of single-file briefcase. In contrast to the previous method, the additional forReading parameter controls whether to open an existing briefcase for reading, of create a new briefcase for writing/replacing the old one. This method can be useful if you want to completely overwrite all data in an existing briefcase with new data, by calling it with a value of NO for forReading.

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

Parameters:

  • fileName: File name of the file briefcase. If the filename does not end with the default extension (.daBriefcase for file briefcases), the extension will be added automatically.
  • forReading: BOOL flag that specifies whether to open an existing briefcase (YES) or write a new one (NO).

briefcaseWithFolder:

Creates and initializes a new instance of a folder-based briefcase. Folder-based briefcases always support reading and writing; if no briefcase with the given file name exists, a new briefcase will be created.

+ (id) briefcaseWithFolder:(NSString *)fileName

Parameters:

  • fileName: Full path to the folder briefcase. If the filename does not end with the default extension (.briefcase for folder briefcases), the extension will be added automatically.

 

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

delete

method removes whole briefcase file.

- (void) delete

initWithFile:forReading:

Initializes a new instance of a single-file briefcase for reading and initializes it with data from an existing briefcase with a given name. The additional forReading parameter controls whether to open an existing briefcase for reading, of create a new briefcase for writing/replacing the old one. This method can be useful if you want to completely overwrite all data in an existing briefcase with new data, by calling it with a value of NO for forReading.

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

Parameters:

  • fileName: File name of the file briefcase. If the filename does not end with the default extension (.daBriefcase for file briefcases), the extension will be added automatically.
  • forReading: BOOL flag that specifies whether to open an existing briefcase (YES) or write a new one (NO).

initWithFolder:

Initializes a new instance of a folder-based briefcase. Folder-based briefcases always support reading and writing; if no briefcase with the given file name exists, a new briefcase will be created.

- (id) initWithFolder:(NSString *)fileName

Parameters:

  • fileName: Full path to the folder briefcase. If the filename does not end with the default extension (.briefcase for folder briefcases), the extension will be added automatically.

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

Descendants

See Also