DAFileBriefcase

Overview

The DAFileBriefcase 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 DADataTables with original data and pending Delta Changes that have not been applied yet. Also a 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 DAFileBriefcase is stored using the DABin2DataStreamer.

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

Files created using DAFileBriefcase usually have a .daBriefcase extension.

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

Location


 

addTable:    (declared in DABriefcase)

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

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

+ (InstanceType) briefcaseWithFile:(NSString *)fileName

Parameters:

  • fileName:

briefcaseWithFile:forReading:    (declared in DABriefcase)

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

Parameters:

  • fileName:
  • forReading:

briefcaseWithFileName:    (declared in DABriefcase)

+ (InstanceType) briefcaseWithFileName:(NSString *)fileName

Parameters:

  • fileName:

briefcaseWithFileName:forReading:    (declared in DABriefcase)

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

Parameters:

  • fileName:
  • forReading:

briefcaseWithFolder:    (declared in DABriefcase)

+ (InstanceType) briefcaseWithFolder:(NSString *)fileName

Parameters:

  • fileName:

clearTablesCache    (declared in DABriefcase)

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

- (NSString *) defaultExtension

delete    (declared in DABriefcase)

method removes whole briefcase file.

- (void) delete

fileName    (declared in DABriefcase)

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

@property (readonly) NSString *fileName

initWithFile:forReading:    (declared in DABriefcase)

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

Parameters:

  • fileName:
  • forReading:

initWithFolder:    (declared in DABriefcase)

- (InstanceType) initWithFolder:(NSString *)fileName

Parameters:

  • fileName:

loadData: loadData:(NSData *)     (declared in DABriefcase)

- (void) loadData:(NSData *)aData

Parameters:

  • aData:

loadData: loadData:(NSData *) 

- (void) loadData:(NSData *)data

Parameters:

  • data:

properties    (declared in DABriefcase)

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

@property (readonly) NSMutableDictionary *properties

removeAllTables    (declared in DABriefcase)

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

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

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

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

Returns an array of names all tables in the briefcase.

- (NSArray *) tableNames

writeBriefcase    (declared in DABriefcase)

- (void) writeBriefcase

writeBriefcaseHeaderToData: writeBriefcaseHeaderToData:(NSMutableData *)     (declared in DABriefcase)

- (void) writeBriefcaseHeaderToData:(NSMutableData *)aData

Parameters:

  • aData:

writeBriefcaseHeaderToData: writeBriefcaseHeaderToData:(NSMutableData *) 

- (void) writeBriefcaseHeaderToData:(NSMutableData *)data

Parameters:

  • data:

 

fileName    (declared in DABriefcase)

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

@property (readonly) NSString *fileName

properties    (declared in DABriefcase)

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

@property (readonly) NSMutableDictionary *properties

 

briefcaseWithFile:    (declared in DABriefcase)

+ (InstanceType) briefcaseWithFile:(NSString *)fileName

Parameters:

  • fileName:

briefcaseWithFile:forReading:    (declared in DABriefcase)

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

Parameters:

  • fileName:
  • forReading:

briefcaseWithFileName:    (declared in DABriefcase)

+ (InstanceType) briefcaseWithFileName:(NSString *)fileName

Parameters:

  • fileName:

briefcaseWithFileName:forReading:    (declared in DABriefcase)

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

Parameters:

  • fileName:
  • forReading:

briefcaseWithFolder:    (declared in DABriefcase)

+ (InstanceType) briefcaseWithFolder:(NSString *)fileName

Parameters:

  • fileName:

 

addTable:    (declared in DABriefcase)

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

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

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

- (NSString *) defaultExtension

delete    (declared in DABriefcase)

method removes whole briefcase file.

- (void) delete

initWithFile:forReading:    (declared in DABriefcase)

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

Parameters:

  • fileName:
  • forReading:

initWithFolder:    (declared in DABriefcase)

- (InstanceType) initWithFolder:(NSString *)fileName

Parameters:

  • fileName:

loadData: loadData:(NSData *)     (declared in DABriefcase)

- (void) loadData:(NSData *)aData

Parameters:

  • aData:

loadData: loadData:(NSData *) 

- (void) loadData:(NSData *)data

Parameters:

  • data:

removeAllTables    (declared in DABriefcase)

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

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

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

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

Returns an array of names all tables in the briefcase.

- (NSArray *) tableNames

writeBriefcase    (declared in DABriefcase)

- (void) writeBriefcase

writeBriefcaseHeaderToData: writeBriefcaseHeaderToData:(NSMutableData *)     (declared in DABriefcase)

- (void) writeBriefcaseHeaderToData:(NSMutableData *)aData

Parameters:

  • aData:

writeBriefcaseHeaderToData: writeBriefcaseHeaderToData:(NSMutableData *) 

- (void) writeBriefcaseHeaderToData:(NSMutableData *)data

Parameters:

  • data: