DABriefcase Class
From RemObjects Wiki
This is a Library topic for Data Abstract for Xcode
This page is generated from external data, please do not update
Contents |
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 DADataBrowser 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
DataAbstract/DataAbstract.h
- NSObject
- DABriefcase
Properties
| fileName |
|---|
|
File (or folder, in case of a folder-based briefcase) name and path of the briefcase.
|
| properties |
|
Dictionary of custom application-defined properties that will be stored alongside the briefcase data.
|
Class Methods
| 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
|
| 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.
|
| 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.
|
Instance Methods
| 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.
|
| 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.
|
| clearTablesCache |
|
|
| 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.
|
| 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.
|
| 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.
|
| 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.
|
| tableAtIndex: |
|
|
| 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.
|
| tableNames |
|
Returns an array of names all tables in the briefcase.
|
See Also
- Delphi:
- .NET:
- Xcode:
- Lists
- Data Abstract for Xcode: Protocols – Classes – Enums
- RemObjects SDK for Xcode: Protocols – Classes – Enums
- Data Abstract shared: Data Types – File Types
- other editions
- Data Abstract for .NET: Namespaces – Interfaces – Classes – Enums
- Data Abstract for Delphi: Interfaces – Classes – Enums
- Data Abstract for JavaScript: Objects
Product: RemObjects Data Abstract
Available Editions: Data Abstract for .NET, Delphi and Xcode
