Ferreteria/v0.5/portbank

Data Object Management

v0.5 includes a significant refactoring of how database-related objects are managed. The goal was to simplify access to global singleton objects in general, and databases and tabloids in particular, while retaining flexibility (e.g. for different applications to determine the database in which each table is stored).

Databases

Creating a database requires a database spec (ferret\data\cDatabaseSpec descendant). (yes, I know this bit is hopelessly incomplete)

PortBanks

PortBanks are a new set of classes designed to automate format-conversion when reading or writing structured data from/to an external interface (database, display).

Structure

• A PortBank is a Table-configured object which contains a set of PortRows (which, by default, it creates). Each PortRow has a Type string. In theory there can be any number of these for different types of I/O, but in practice (caPortIOBank) there are 3 types:
  • Native, which is used only for internal calculations (no I/O)
  • Storage, which converts to and from SQL (or, in theory, any other database-storage format)
  • Display, which converts to and from HTML (or, in theory, any other display markup)
• A PortRow contains a set of PortUnits, one for each field in the Table.

Access

• Each PortRow keeps a pointer to its containing PortBank object. All access to other PortRow types in the PortBank is via the PortBank.
• A specialized PortBank class, called a SpaceIOBank, expects a Space object in its constructor, and retains it. This provides access to the parent Table and the current Rowset and Record, where applicable. (Pretty much everything descends from SpaceIOBank rather than PortBank.)
• The Native PortRow has the ability (in MakeIOUnit()) to create I/O Units for known fields by fetching the default I/O Unit class from the corresponding Native Unit.

Data

• There is one PortBank per Table.
  • We don't create additional PortBanks to retain values for rows other than the current one. This is mainly to avoid having to repeatedly execute all of the setup that goes into creating a PortBank and all its contents (Rows, Units).
• PortRows:
  • The PortRow class has an OnCursorSet() event which should be called whenever the current row changes. (2021-12-07 It's not clear whether this is actually in use.)
  • A PortRow creates its own objects, but by default it needs to know the name and class to use for each one.
    • A descendant class, PortRowInternalDirect, has a default Unit class to use if one is not specified.
  • The PortIORow class adds the ability to render all the Unit values as a single string, based on a template. This is so far only used for Display output (HTML), but could theoretically also be used to render SQL for inserting or updating a record.

Flow

Data flow management is a feature wherein each PortBank keeps track of which of its PortRows is the current data-row source, from which PortUnit objects in other PortRows may populate missing values. This makes it unnecessary for value-retrieval code to be aware of the current state of data-retrieval operations (i.e. where should we look for source data in order to calculate missing values), or to enforce a particular state (e.g. always convert/load all Storage values from the db into Native and then into Display before doing Display-related calculations -- which assumes that we are currently reading data into Storage, and not parsing form input into Display or generating new data into Native).