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 Data Abstract 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)

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

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

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

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)

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

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

 

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)

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

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

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:    (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

delete    (declared in DABriefcase)

method removes whole briefcase file.

- (void) delete

initWithFile:forReading:    (declared in DABriefcase)

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

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

See Also