hs30

InstantObjects project structure

The following notes document the structure of the InstantObjects tree as stored in Git, explaining what each folder is for.

Modules

Currently InstantObjects is made up of 5 (mostly independent) modules; future versions might be organized differently. Here is a list of the 5 modules:

Demos: contains demo projects aimed at the InstantObject newbie. There is a subfolder for each applciation:

• Intro: the bare bones demo application, whose building process is shown in the famous InstantObject introductory video.

• PrimerCross: the cross-database-platform version of the more juicy Primer example. This folder also contains a PrimerExternal.dpr project that makes use of external storage.

• PrimerFireMonkey: a simple example for using InstantObject with FireMonkey (using INSTANTOBECTS_FMX compiler directive)

• Pump: a straightforward application that shows how to use the InstantPump component.

• Test: in a subfolder called BuildPrimerDatabase you'll find a console application that demonstrates building and populating an InstantObjects database.

• ConsoleApp: an example of a console application

• EvolveTest: an example of evolving database structure

The Demos folder must be a sibling of the Source folder (they're not completely independent).

Docs: Here you'll find some developer and user docs, mostly in the form of txt files. User docs here are in their primal form, not intended for direct user consumption but rather as the basis for the help maintainers and docs for testers. This folder might use a restructure.

Help: sources for the InstantObject user docs/help.

Test: The InstantObject test infrastructure makes use of the open source ubmock unit test framework. This folder contains the InstantObject specific unit test stuff. Currently the unit testing effort has just started, so we have just a handful of tests. Additions (in the form of new tests) are very welcome.

Source: here is where all the InstantObject code is stored. The Source folder has a number of subfolders each containing a different part of the code base. I'll document the inner structure of the folders in later sections, but here is a summary:

• Brokers: base folder for all the persistence brokers (one subfolder each).
• Catalogs: folder for mapping InstantObject datatypes with database vendor field types.
• Core: the core run time stuff, or the heart of InstantObject.
• Design: the design-time companion (Model Explorer, etc.).
• PackageGroups: contains package groups for easy installation of all the packages

The Source\Brokers folder

Here we have a subfolder for each supported broker. A broker is a means for InstantObject to use as storage a particular database engine through a particular middleware. There are two main kinds of InstantObject object brokers: dataset-based and SQL-based; the latter offer better performance and additional features (like external storage) when you use a SQL-enabled database engine. Here is a list of the currently supported brokers:

FireDAC: a SQL-based broker to use Embarcadero FireDac: is the best choice for all SQL databases.

AnyDAC: a SQL-based broker to use AnyDac, the previous commercial component of FireDAC: not maintained.

ADO: for MS Access (table-based) and MS SQL Server (SQL-based) through ADO/OLEDB. Makes use of the Delphi support for ADO (ADOExpress/dbGo).

ADS: removed!

BDE: removed!

DBISAM: removed!

DBX: a SQL-based broker to use Borland dbExpress (DBX): we encourage to use FireDAC Broker.

FlashFiler: removed!

IBX: a SQL-based broker for the open source Delphi IBX components (for InterBase and, if you're daring, Firebird). Generally requires the latest IBX update. IBX is available out of the box, updates from Borland CodeCentral.

NexusDb & NexusDbSQL: removed!

UIB: not maintained!

XML: a lightweight XML-based broker which uses plain XML files as storage. Currently it does not support filtering.

Template: an example do-nothing dataset-based broker to use as template to build your own. My own advice, if you want to develop a new broker, is to rather clone & modify a real (possibly similar) broker than starting from the template.

Each broker's subfolder contains the common source files plus a subfolder for each supported Delphi Version (DXE7, DXE8, D10_3). This subfolder contains the package source files plus any additional platform specific files. Not all brokers are supported on all platforms. If a platform is missing, the reason might be one of these:

• Missing maintainer: we haven't found anyone to maintain and keep the broker up-to-date on that particular platform.

The Source\Core folder

This is the core (IOCore.dpk) of InstantObjects; it is used by all the brokers and by the design time stuff. The subfolders here have the same meaning as those in the brokers folders.

The Source\Design folder

This is where the InstantObject design time stuff (DclIOCore.dpk) lives. The subfolders here have the same meaning as those in the brokers folders.