Primer Demo: Introduction

The Primer Demo is the flagship demonstration application for InstantObjects, showcasing real-world usage of the framework's features. It provides practical examples of how to build a complete database-driven application using persistent business objects.

Overview

The Primer Demo comes in several variations, each demonstrating different aspects and capabilities of InstantObjects:

PrimerCross (Main Demo)

Located in Demos\PrimerCross\, this is the primary demonstration application that works with all supported brokers (cross-database compatible).

Features Demonstrated:

• Complete contact management system
• Multiple database broker support (ADO, IBX, DBX, FireDAC, XML, JSON)
• External and internal storage modes
• Query testing and IQL (InstantObjects Query Language)
• Performance benchmarking
• Connection Manager usage
• Import/Export functionality

Project Files:

• Primer_D13.dpr - Delphi 13 version
• Primer_D12.dpr - Delphi 12 version
• Primer_D11.dpr - Delphi 11 version
• Primer_D10_4.dpr - Delphi 10.4 version
• PrimerExternal.dpr - External storage variant

PrimerFireMonkey

Located in Demos\PrimerFireMonkey\, demonstrates InstantObjects with FireMonkey (cross-platform UI).

Features:

• Cross-platform UI (Windows, macOS, Linux, iOS, Android)
• Mobile-optimized interface
• FireDAC broker integration
• Touch-friendly controls

PrimerWiRLServer (NEW)

Located in Demos\PrimerWiRLServer\, demonstrates REST API server using WiRL framework.

Features:

• RESTful web services
• JSON serialization with Neon
• JWT authentication
• CRUD operations via HTTP
• Swagger/OpenAPI documentation
• See WiRL REST Server for details

PrimerRESTServer

Located in Demos\PrimerRESTServer\, demonstrates REST API using MARS Curiosity framework.

Features:

• MARS REST server integration
• Alternative REST framework
• JSON-based API

PrimerCross Main Application

The main PrimerCross demo is organized into several functional areas:

1. Contact Book

The core of the application is a contact management system where you can:

• Manage Contacts - Add, edit, delete persons and companies
• Categorize - Organize contacts by categories
• Multiple Addresses - Support for multiple addresses per contact
• Phone Numbers - Multiple phone numbers with types (Home, Mobile, Office)
• Email Addresses - Multiple email addresses per contact

The contact edit form demonstrates:

• Master-detail relationships
• Embedded objects (addresses, phones, emails)
• Reference attributes (category)
• Data validation
• Grid editing

2. Query Tester

The query tester allows you to:

• Write IQL Queries - Test InstantObjects Query Language
• Execute SQL - Direct SQL queries (for SQL brokers)
• Example Queries - Pre-built query examples
• Result Inspection - View query results in grid
• Query Parameters - Test parameterized queries

Example Queries Available:

-- All contacts
SELECT * FROM TContact

-- Contacts in category
SELECT * FROM TContact WHERE Category.Name = 'Customer'

-- Persons only
SELECT * FROM TPerson

-- Companies with contacts
SELECT * FROM TCompany WHERE ContactCount > 0

-- Recent contacts
SELECT * FROM TContact ORDER BY Id DESC

3. Performance Tester

The performance tester helps you:

• Compare Brokers - Test different database backends
• Benchmark Operations - Insert, update, delete, retrieve
• Measure Speed - Operations per second metrics
• Test Scenarios - Various data volumes and patterns
• Optimization - Test caching, statement cache, etc.

Test Scenarios:

• Bulk Insert - Creating many objects
• Sequential Retrieval - Reading objects one by one
• Query Retrieval - Fetching via queries
• Update Performance - Modifying existing objects
• Delete Performance - Removing objects
• Cache Impact - With/without object caching

4. Connection Manager

The demo uses TInstantConnectionManager to support multiple brokers without recompilation:

• Multiple Profiles - Save different database connections
• Runtime Selection - Choose broker at application startup
• Database Building - Create database schema from model
• Database Evolution - Update schema for model changes
• Connection Files - Save/load connection definitions (.con or .xml)

Supported Brokers in Demo:

• ADO (MS SQL Server, MS Access)
• IBX (InterBase, Firebird)
• DBX (Multiple databases via dbExpress)
• FireDAC (Universal - InterBase, Firebird, MS SQL, MySQL, PostgreSQL, SQLite)
• XML (File-based, no database required)
• JSON (File-based with JSON format, no database required)

5. Data Import/Export

The demo includes functionality to:

• Export to XML - Save contacts as XML files
• Import from XML - Load contacts from XML
• Export to JSON - Modern JSON format (with Neon)
• Backup/Restore - Full database backup and restore
• Cross-Broker Transfer - Copy data between different databases

The Business Model

The Primer demo implements a realistic contact management model:

Class Hierarchy:

TInstantObject
  ├── TContact (abstract)
  │   ├── TPerson
  │   └── TCompany
  ├── TCategory
  ├── TCountry
  ├── TAddress
  ├── TPhone
  ├── TEmail
  ├── TProfile
  └── TUser

Key Relationships:

• Contact → Category (Reference)
• Contact → Addresses (Parts - composition)
• Contact → Phones (Parts - composition)
• Contact → Emails (Parts - composition)
• Address → Country (Reference)
• User → Profile (Reference)

Storage Modes:

• Internal - Default mode, nested objects in BLOBs
• External - PrimerExternal.dpr uses external storage with linking tables

See The Business Model for complete model details.

The User Interface

The Primer UI demonstrates best practices:

• Visual Form Inheritance - Base classes for browse and edit forms
• Frame Components - Reusable view components
• Data-Aware Controls - Standard VCL controls with Exposers/Selectors
• Master-Detail - Grid and detail editing
• Validation - Input validation and error handling

See The User Interface for complete UI architecture.

Running the Demo

Quick Start

1. Open Project:

   Demos\PrimerCross\Primer_D13.dpr

2. Build and Run:

   • Press F9 to compile and run
   • On first run, use Connection Manager to setup database

3. Choose a Broker:

   • Click "Connection Manager" button
   • Select or create a connection definition
   • For quick start, choose XML or JSON (no database needed)

4. Build Database:

   • Click "Build Database" in Connection Manager
   • Confirm the build operation
   • Database schema is created automatically

5. Populate Sample Data:

   • Use "Generate Sample Data" menu option
   • Or manually add contacts

Testing Different Brokers

To test with FireDAC and InterBase:

1. Ensure InterBase or Firebird is installed
2. Create new connection in Connection Manager
3. Select FireDAC broker
4. Configure connection:
   • Database: C:\Data\Primer.fdb
   • Protocol: InterBase or Firebird
   • User: SYSDBA
   • Password: masterkey
5. Build database
6. Run application

Performance Testing

1. Navigate to Performance tab
2. Select brokers to compare
3. Configure test parameters:
   • Number of objects
   • Test iterations
   • Enable/disable cache
4. Run tests and compare results

Advanced Features Demonstrated

External Storage

The PrimerExternal.dpr project demonstrates:

// Model with external storage
TContact = class(TInstantObject)
{IOMETADATA stored 'CONTACTS';
  Phones: Parts(TPhone) external 'CONTACT_PHONES';
  Addresses: Parts(TAddress) external 'CONTACT_ADDRESSES';
  Emails: Parts(TEmail) external 'CONTACT_EMAILS';}

Benefits:

• Better query performance
• Foreign key constraints
• Database-level referential integrity
• Easier SQL reporting

InstantQuery Usage

var
  Query: TInstantQuery;
begin
  Query := TInstantQuery.Create(nil);
  try
    Query.Connector := InstantDefaultConnector;
    Query.Command.Text := 'SELECT * FROM TContact WHERE Category.Name = :CategoryName';
    Query.Params.ParamByName('CategoryName').AsString := 'Customer';
    Query.Open;

    while not Query.EOF do
    begin
      ProcessContact(Query.CurrentObject as TContact);
      Query.Next;
    end;
  finally
    Query.Free;
  end;
end;

Exposer and Selector

// Exposing single object
ContactExposer.ObjectClass := TContact;
ContactExposer.Subject := CurrentContact;
DBGrid.DataSource := ContactExposer;

// Selecting multiple objects
ContactSelector.Command.Text := 'SELECT * FROM TPerson ORDER BY Name';
ContactSelector.Open;
DBGrid.DataSource := ContactSelector;

Learning Path

Recommended order to explore the Primer demo:

1. Start Simple - Use XML or JSON broker for easy setup
2. Explore UI - Navigate contacts, add/edit/delete
3. Examine Code - Study Model.pas for business class definitions
4. Try Queries - Use Query Tester to learn IQL
5. Test Performance - Compare different brokers
6. Advanced Storage - Try PrimerExternal.dpr for external storage
7. REST APIs - Explore PrimerWiRLServer for web services

Source Code Organization

Demos\PrimerCross\
├── Primer_D13.dpr          - Main project
├── Model\
│   └── Model.pas           - Business model classes
├── Main.pas                - Main form
├── ContactEdit.pas         - Contact editing
├── ContactView.pas         - Contact viewing frame
├── BasicEdit.pas           - Base edit form
├── BasicView.pas           - Base view frame
├── QueryView.pas           - Query tester
├── PerformanceView.pas     - Performance tester
└── Explorer.pas            - Object explorer

Related Demos

• Intro (Demos\Intro\) - Minimal example from introductory video
• Pump (Demos\Pump\) - TInstantPump usage for data migration
• EvolveTest (Demos\EvolveTest\) - Database evolution testing
• ConsoleApp (Demos\ConsoleApp\) - Console application example

See Also

• The Business Model - Detailed model explanation
• The User Interface - UI architecture details
• Persisting Objects - Object persistence patterns
• Exposing Objects - Using TInstantExposer
• Selecting Objects - Using TInstantSelector
• Connection Manager - Connection management
• WiRL REST Server - REST API demo