DAFolderBriefcase

Overview

The DAFolderBriefcase class represents a Folder Briefcase, which is part of the DABriefcase class cluster. A Folder Briefcase holds all its tables and custom properties as separate files inside a single folder.

This approach offers certain benefits if you need to work with big briefcases or your resources are limited (for example when programming for the iPhone). You do not need to operate with a single huge file when you only need small part of data in it. With the Folder Briefcase you can Read/Write only the data you really need.

In the Finder what looks like a single file with a ".briefcase" extension is actually the package. You can browse its content if you perform a right mouse button click and select "Show Package Contents".

Since a Folder Briefcase keeps each table data in a separate file, it provides some additional methods for writing properties and any given table separately.

The Server Explorer tool can be used to load and the inspect data in the briefcase.

Using a Folder Briefcase is rather simple.

 

objc
 //Assuming we already have a "MyBriefcase.briefcase" briefcase in our file system 
 //and it already holds a "MyTable" DADataTable and a "My Custom Property #1" property
 NSString *briefcaseName = @"MyBriefcase";
 
 // initialize briefcase
 DABriefcase *briefcase =  [DABriefcase briefcaseWithFolder: briefcaseName];
 
 // get custom property
 NSString *customPropertyValue = [briefcase.properties valueForKey:@"My Custom Property #1"];
 
 // add new custom property
 [briefcase.properties setValue:propertyValue valueForKey:propertyName]; 
 
 // get table by name
 DADataTable *myTable = [briefcase tableNamed:@"MyTable"];
 
 // add new table
 [briefcase addTable:workersTable];
    
 // write briefcase to the file system
 [briefcase writeBriefcase];

 

swift
//Assuming we already have a "MyBriefcase.briefcase" briefcase in our file system 
//and it already holds a "MyTable" DADataTable and a "My Custom Property #1" property
let briefcaseName = "MyBriefcase.briefcase"

// initialize briefcase
let briefcase:DABriefcase = DABriefcase.briefcaseWithFile(briefcaseName)

// get custom property
let customPropertyValue = briefcase.properties.valueForKey("My Custom Property #1")

// add new custom property
briefcase.properties.setValue(propertyValue, forKey: propertyName)

// get table by name
let myTable:DADataTable = briefcase.tableNamed("MyTable")

// add new table
briefcase.addTable(workersTable)
 
// write briefcase to the file system
briefcase.writeBriefcase()

 

oxygene

 

csharp
//Assuming we already have a "MyBriefcase.briefcase" briefcase in our file system 
//and it already holds a "MyTable" DADataTable and a "My Custom Property #1" property
var briefcaseName = "MyBriefcase.briefcase";

// initialize briefcase
var briefcase = DABriefcase.briefcaseWithFile(briefcaseName);

// get custom property
var customPropertyValue = briefcase.properties.valueForKey("My Custom Property #1");

// add new custom property
briefcase.properties.setValue(propertyValue) forKey(propertyName);  

// get table by name
var myTable = briefcase.tableNamed("MyTable");

// add new table
briefcase.addTable(workersTable);

// write briefcase to the file system
briefcase.writeBriefcase();

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

- (void) loadData:(NSData *)aData

Parameters:

  • aData:

properties    (declared in DABriefcase)

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

@property (readonly) NSMutableDictionary *properties

reloadTableNamed:

This method releases the current table with the given name and reads it again.

The Folder briefcase reads each table only once, when we request it. All future requests just return the cached table. This method can be useful if we need to reload the cached table (for example, if we changed the table but then need to cancel all changes and continue work from scratch).

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

Parameters:

  • name: Name of the table we want to reload.

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

- (void) writeBriefcaseHeaderToData:(NSMutableData *)aData

Parameters:

  • aData:

writeProperties

This method writes custom properties to the briefcase.

The Folder Briefcase stores its custom properties in XML format in a separate file called "Properties.plist".

- (void) writeProperties

writeTable:

This method writes the given table to the briefcase.

In comparison to the File Briefcase that writes all tables and properties in single file in one go, Folder Briefcase allows to write tables separately.

- (void) writeTable:(DADataTable *)table

Parameters:

  • table: Instance of DADataTable we want to add to the briefcase.

writeTables:

This method writes a given tables array to the briefcase.

This method will be useful if we need to put several tables to the briefcase in one go.

- (void) writeTables:(NSArray *)tables

Parameters:

  • tables: Array of DADataTable instances we want to add to the briefcase.

 

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

- (void) loadData:(NSData *)aData

Parameters:

  • aData:

reloadTableNamed:

This method releases the current table with the given name and reads it again.

The Folder briefcase reads each table only once, when we request it. All future requests just return the cached table. This method can be useful if we need to reload the cached table (for example, if we changed the table but then need to cancel all changes and continue work from scratch).

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

Parameters:

  • name: Name of the table we want to reload.

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

- (void) writeBriefcaseHeaderToData:(NSMutableData *)aData

Parameters:

  • aData:

writeProperties

This method writes custom properties to the briefcase.

The Folder Briefcase stores its custom properties in XML format in a separate file called "Properties.plist".

- (void) writeProperties

writeTable:

This method writes the given table to the briefcase.

In comparison to the File Briefcase that writes all tables and properties in single file in one go, Folder Briefcase allows to write tables separately.

- (void) writeTable:(DADataTable *)table

Parameters:

  • table: Instance of DADataTable we want to add to the briefcase.

writeTables:

This method writes a given tables array to the briefcase.

This method will be useful if we need to put several tables to the briefcase in one go.

- (void) writeTables:(NSArray *)tables

Parameters:

  • tables: Array of DADataTable instances we want to add to the briefcase.