Core ORM interface for object-to-database mapping and SQL query generation. More...

#include <IDatabaseObjectDelegate.h>

Inheritance diagram for imtdb::IDatabaseObjectDelegate:

Classes
struct	NewObjectQuery
	Result of CreateNewObjectQuery containing SQL and metadata for object insertion. More...

Public Member Functions
virtual const iprm::IOptionsList *	GetObjectTypeInfos () const =0
	Gets information about object types supported by this delegate.

virtual QByteArray	GetObjectTypeId (const QByteArray &objectId) const =0
	Gets the type ID for a specific object.

virtual QByteArray	GetCountQuery (const iprm::IParamsSet *paramsPtr=nullptr) const =0
	Generates SQL query to count objects in collection.

virtual QByteArray	GetSelectionQuery (const QByteArray &objectId=QByteArray(), int offset=0, int count=-1, const iprm::IParamsSet *paramsPtr=nullptr) const =0
	Generates SQL SELECT query for retrieving objects.

virtual NewObjectQuery	CreateNewObjectQuery (const QByteArray &typeId, const QByteArray &proposedObjectId, const QString &objectName, const QString &objectDescription, const istd::IChangeable valuePtr, const imtbase::IOperationContext operationContextPtr) const =0
	Creates SQL query for inserting a new object.

virtual QByteArray	CreateDeleteObjectsQuery (const imtbase::IObjectCollection &collection, const imtbase::ICollectionInfo::Ids &objectIds, const imtbase::IOperationContext *operationContextPtr) const =0
	Creates SQL query for deleting objects.

virtual QByteArray	CreateDeleteObjectSetQuery (const imtbase::IObjectCollection &collection, const iprm::IParamsSet paramsPtr=nullptr, const imtbase::IOperationContext operationContextPtr=nullptr) const =0
	Creates SQL query for deleting objects matching filter criteria.

virtual QByteArray	CreateRestoreObjectsQuery (const imtbase::IObjectCollection &collection, const imtbase::ICollectionInfo::Ids &objectIds, const imtbase::IOperationContext *operationContextPtr=nullptr) const =0
	Creates SQL query for restoring soft-deleted objects.

virtual QByteArray	CreateRestoreObjectSetQuery (const imtbase::IObjectCollection &collection, const iprm::IParamsSet paramsPtr=nullptr, const imtbase::IOperationContext operationContextPtr=nullptr) const =0
	Creates SQL query for restoring objects matching filter criteria.

virtual QByteArray	CreateUpdateObjectQuery (const imtbase::IObjectCollection &collection, const QByteArray &objectId, const istd::IChangeable &object, const imtbase::IOperationContext *operationContextPtr, bool useExternDelegate=true) const =0
	Creates SQL query for updating an existing object.

virtual QByteArray	CreateRenameObjectQuery (const imtbase::IObjectCollection &collection, const QByteArray &objectId, const QString &newObjectName, const imtbase::IOperationContext *operationContextPtr) const =0
	Creates SQL query for renaming an object.

virtual QByteArray	CreateDescriptionObjectQuery (const imtbase::IObjectCollection &collection, const QByteArray &objectId, const QString &description, const imtbase::IOperationContext *operationContextPtr) const =0
	Creates SQL query for updating object description.

virtual QByteArray	CreateResetQuery (const imtbase::IObjectCollection &collection) const =0
	Creates SQL query for clearing all objects from collection.

virtual QByteArray	CreateDataMetaInfoQuery (const imtbase::IObjectCollection &collection, const QByteArray &objectId, const idoc::IDocumentMetaInfo *dataMetaInfoPtr) const =0
	Creates SQL query for updating object data metadata.

virtual QByteArray	CreateCollectionItemMetaInfoQuery (const imtbase::IObjectCollection &collection, const QByteArray &objectId, const idoc::IDocumentMetaInfo *collectionItemMetaInfoPtr) const =0
	Creates SQL query for updating collection-related metadata.

virtual QByteArray	GetSelectionByMetaInfoQuery (const QByteArray &metaInfoId, const QVariant &metaInfoValue) const =0
	Creates SQL query for finding objects by metadata field value.

Detailed Description

Core ORM interface for object-to-database mapping and SQL query generation.

IDatabaseObjectDelegate is the heart of the imtdb ORM system. It acts as a bridge between C++ object representations and database tables, generating SQL queries for all CRUD operations.

Purpose

The delegate pattern separates:

Collection logic (CSqlDatabaseObjectCollectionComp) - manages object lifecycle
Database mapping (IDatabaseObjectDelegate) - generates SQL queries

This separation enables:

Multiple delegate implementations for different object types
Database-specific query generation (PostgreSQL vs SQLite)
Specialized delegates (documents, messages, hierarchies)
Easy testing through mock delegates

Query Types

The delegate generates queries for:

Selection: Retrieve objects with filtering, sorting, pagination
Insertion: Create new objects with metadata
Update: Modify existing objects
Deletion: Soft or hard delete objects
Restoration: Undelete soft-deleted objects
Metadata: Update object metadata without full object modification
Count: Efficient counting with filters

Common Implementations

CSqlDatabaseObjectDelegateCompBase: Base implementation for standard objects
CSqlDatabaseDocumentDelegateComp: Document objects with JSON metadata and revisions
CSqlJsonDatabaseDelegateComp: JSON-serialized objects
CSqlStructureDelegateComp: Hierarchical tree structures
TMessageDatabaseDelegateComp: Template-based message persistence

Usage Example

// Create delegate
auto delegate = acf::CreateComponent<CSqlDatabaseDocumentDelegateComp>();
delegate->SetTableName("users");
delegate->SetDatabaseEngine(engine);
 
// Use with collection
auto collection = acf::CreateComponent<CSqlDatabaseObjectCollectionComp>();
collection->SetDelegate(delegate);
 
// Delegate automatically generates SQL for:
collection->InsertNewObject(user, userId);     // INSERT query
collection->GetObject(userId);                 // SELECT query
collection->UpdateObject(userId, user);        // UPDATE query
collection->RemoveElements({userId});          // DELETE/UPDATE query

Note: Delegates are typically created once and reused for a collection's lifetime

See also: CSqlDatabaseObjectDelegateCompBase for base implementation; CSqlDatabaseObjectCollectionComp for usage context

Definition at line 77 of file IDatabaseObjectDelegate.h.

Member Function Documentation

◆ CreateCollectionItemMetaInfoQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateCollectionItemMetaInfoQuery	(	const imtbase::IObjectCollection &	collection,
		const QByteArray &	objectId,
		const idoc::IDocumentMetaInfo *	collectionItemMetaInfoPtr
	)		const

pure virtual

Creates SQL query for updating collection-related metadata.

Generates UPDATE query to modify metadata specific to the object's membership in this collection (distinct from the object's inherent metadata).

Parameters

collection	The collection containing the object
objectId	ID of the object
collectionItemMetaInfoPtr	Collection-specific metadata

Returns: SQL UPDATE query string

See also: CreateDataMetaInfoQuery()

◆ CreateDataMetaInfoQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateDataMetaInfoQuery	(	const imtbase::IObjectCollection &	collection,
		const QByteArray &	objectId,
		const idoc::IDocumentMetaInfo *	dataMetaInfoPtr
	)		const

pure virtual

Creates SQL query for updating object data metadata.

Generates UPDATE query to modify the DataMetaInfo JSON field without changing the object's core data.

Parameters

collection	The collection containing the object
objectId	ID of the object
dataMetaInfoPtr	New metadata to store

Returns: SQL UPDATE query string

Note: Metadata typically includes custom fields, tags, dependent references

See also: CreateCollectionItemMetaInfoQuery()

◆ CreateDeleteObjectSetQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateDeleteObjectSetQuery	(	const imtbase::IObjectCollection &	collection,
		const iprm::IParamsSet *	paramsPtr = `nullptr`,
		const imtbase::IOperationContext *	operationContextPtr = `nullptr`
	)		const

pure virtual

Creates SQL query for deleting objects matching filter criteria.

Generates DELETE or UPDATE query that removes objects matching the specified filter parameters, without needing to know specific object IDs.

Parameters

collection	The collection containing the objects
paramsPtr	Filter parameters defining which objects to delete
operationContextPtr	Context for audit trail

Returns: SQL DELETE or UPDATE query string

// Delete all inactive users older than 1 year
auto params = acf::CreateComponent<iprm::CParamsSetComp>();
params->SetValue("Status", "inactive");
params->SetValue("LastLogin", oneYearAgo, iprm::CT_LESS_THAN);
QByteArray deleteQuery = delegate->CreateDeleteObjectSetQuery(
    collection, params.get(), operationContext
);

Warning: Be careful with filters - incorrect criteria could delete wrong objects

See also: CreateDeleteObjectsQuery()

◆ CreateDeleteObjectsQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateDeleteObjectsQuery	(	const imtbase::IObjectCollection &	collection,
		const imtbase::ICollectionInfo::Ids &	objectIds,
		const imtbase::IOperationContext *	operationContextPtr
	)		const

pure virtual

Creates SQL query for deleting objects.

Generates DELETE or UPDATE query (for soft delete) to remove objects by their IDs. Soft delete typically sets a State column to indicate deletion without removing data.

Parameters

collection	The collection containing the objects
objectIds	List of object IDs to delete
operationContextPtr	Context for audit trail (who, when, why)

Returns: SQL DELETE or UPDATE query string

imtbase::ICollectionInfo::Ids idsToDelete = {"user-1", "user-2", "user-3"};
QByteArray deleteQuery = delegate->CreateDeleteObjectsQuery(
    collection,
    idsToDelete,
    operationContext
);

Note: Many implementations use soft delete (UPDATE State = 'deleted')

See also: CreateRestoreObjectsQuery(), CreateDeleteObjectSetQuery()

◆ CreateDescriptionObjectQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateDescriptionObjectQuery	(	const imtbase::IObjectCollection &	collection,
		const QByteArray &	objectId,
		const QString &	description,
		const imtbase::IOperationContext *	operationContextPtr
	)		const

pure virtual

Creates SQL query for updating object description.

Generates UPDATE query to change only the Description field of an object.

Parameters

collection	The collection containing the object
objectId	ID of the object to update
description	New description text
operationContextPtr	Context for audit trail

Returns: SQL UPDATE query string

◆ CreateNewObjectQuery()

virtual NewObjectQuery imtdb::IDatabaseObjectDelegate::CreateNewObjectQuery	(	const QByteArray &	typeId,
		const QByteArray &	proposedObjectId,
		const QString &	objectName,
		const QString &	objectDescription,
		const istd::IChangeable *	valuePtr,
		const imtbase::IOperationContext *	operationContextPtr
	)		const

pure virtual

Creates SQL query for inserting a new object.

Generates INSERT query with all necessary fields: ID, TypeId, Name, Description, serialized data, metadata, timestamps, and operation context.

Parameters

typeId	Object type identifier (for polymorphic collections)
proposedObjectId	Suggested ID (may be auto-generated if empty)
objectName	Display name for the object
objectDescription	Optional description text
valuePtr	Object data to serialize into database
operationContextPtr	Context information (user, timestamp, operation description)

Returns: NewObjectQuery struct containing SQL, object name, and parameter bindings

auto user = std::make_shared<User>();
auto context = acf::CreateComponent<COperationContextComp>();
context->SetUserId("admin");
 
auto newQuery = delegate->CreateNewObjectQuery(
    "user",                    // typeId
    QByteArray(),              // auto-generate ID
    "John Doe",                // name
    "System administrator",    // description
    user.get(),                // object data
    context.get()              // operation context
);
 
engine->ExecSqlQuery(newQuery.query, newQuery.bindValues);

See also: CreateUpdateObjectQuery()

◆ CreateRenameObjectQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateRenameObjectQuery	(	const imtbase::IObjectCollection &	collection,
		const QByteArray &	objectId,
		const QString &	newObjectName,
		const imtbase::IOperationContext *	operationContextPtr
	)		const

pure virtual

Creates SQL query for renaming an object.

Generates UPDATE query to change only the Name field of an object, without modifying other data.

Parameters

collection	The collection containing the object
objectId	ID of the object to rename
newObjectName	New name for the object
operationContextPtr	Context for audit trail

Returns: SQL UPDATE query string

Note: More efficient than full update when only name changes

◆ CreateResetQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateResetQuery ( const imtbase::IObjectCollection & collection ) const

pure virtual

Creates SQL query for clearing all objects from collection.

Generates TRUNCATE or DELETE query to remove all objects from the collection's table.

Parameters

collection The collection to reset

Returns: SQL TRUNCATE or DELETE query string

Warning: This is destructive and typically cannot be undone; May not work if foreign key constraints exist

◆ CreateRestoreObjectSetQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateRestoreObjectSetQuery	(	const imtbase::IObjectCollection &	collection,
		const iprm::IParamsSet *	paramsPtr = `nullptr`,
		const imtbase::IOperationContext *	operationContextPtr = `nullptr`
	)		const

pure virtual

Creates SQL query for restoring objects matching filter criteria.

Generates UPDATE query to restore soft-deleted objects that match the specified filter parameters.

Parameters

collection	The collection containing the objects
paramsPtr	Filter parameters defining which objects to restore
operationContextPtr	Context for audit trail

Returns: SQL UPDATE query string

See also: CreateRestoreObjectsQuery(), CreateDeleteObjectSetQuery()

◆ CreateRestoreObjectsQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateRestoreObjectsQuery	(	const imtbase::IObjectCollection &	collection,
		const imtbase::ICollectionInfo::Ids &	objectIds,
		const imtbase::IOperationContext *	operationContextPtr = `nullptr`
	)		const

pure virtual

Creates SQL query for restoring soft-deleted objects.

Generates UPDATE query to restore objects that were previously soft-deleted, typically by changing State column back to active.

Parameters

collection	The collection containing the objects
objectIds	List of object IDs to restore
operationContextPtr	Context for audit trail

Returns: SQL UPDATE query string

Note: Only applicable if soft delete is used

See also: CreateDeleteObjectsQuery()

◆ CreateUpdateObjectQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::CreateUpdateObjectQuery	(	const imtbase::IObjectCollection &	collection,
		const QByteArray &	objectId,
		const istd::IChangeable &	object,
		const imtbase::IOperationContext *	operationContextPtr,
		bool	useExternDelegate = `true`
	)		const

pure virtual

Creates SQL query for updating an existing object.

Generates UPDATE query to modify object data, metadata, and timestamps.

Parameters

collection	The collection containing the object
objectId	ID of the object to update
object	New object data
operationContextPtr	Context for audit trail
useExternDelegate	Whether to use external delegate for serialization (advanced)

Returns: SQL UPDATE query string

user->SetEmail("newemail@example.com");
QByteArray updateQuery = delegate->CreateUpdateObjectQuery(
    collection,
    userId,
    *user,
    operationContext
);

See also: CreateNewObjectQuery()

◆ GetCountQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::GetCountQuery ( const iprm::IParamsSet * paramsPtr = nullptr ) const

pure virtual

Generates SQL query to count objects in collection.

Creates a COUNT query, optionally filtered by criteria specified in paramsPtr. This is more efficient than retrieving all objects and counting in application code.

Parameters

paramsPtr Optional filter parameters (WHERE clause conditions)

Returns: SQL COUNT query string

// Count all users
QByteArray countAll = delegate->GetCountQuery();
 
// Count users over 18
auto params = acf::CreateComponent<iprm::CParamsSetComp>();
params->SetValue("Age", 18, iprm::CT_GREATER_THAN);
QByteArray countFiltered = delegate->GetCountQuery(params.get());

See also: GetSelectionQuery()

◆ GetObjectTypeId()

virtual QByteArray imtdb::IDatabaseObjectDelegate::GetObjectTypeId ( const QByteArray & objectId ) const

pure virtual

Gets the type ID for a specific object.

Retrieves the type identifier for an object, used in polymorphic collections where multiple object types are stored in the same table.

Parameters

objectId Unique identifier of the object

Returns: Type ID as a byte array

See also: GetObjectTypeInfos()

◆ GetObjectTypeInfos()

virtual const iprm::IOptionsList * imtdb::IDatabaseObjectDelegate::GetObjectTypeInfos ( ) const

pure virtual

Gets information about object types supported by this delegate.

Returns a list of object types that this delegate can handle. Each type typically has a unique type ID, name, and associated metadata.

Returns: Pointer to options list containing type information, or nullptr if not applicable

Note: Used for polymorphic collections where multiple object types share a table; Type IDs are used in the TypeId column to distinguish object types

◆ GetSelectionByMetaInfoQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::GetSelectionByMetaInfoQuery	(	const QByteArray &	metaInfoId,
		const QVariant &	metaInfoValue
	)		const

pure virtual

Creates SQL query for finding objects by metadata field value.

Generates SELECT query that searches within JSON metadata fields for specific values, enabling queries on dynamic metadata.

Parameters

metaInfoId	JSON field path within metadata (e.g., "tags[0]", "customField")
metaInfoValue	Value to search for

Returns: SQL SELECT query string using JSON operators

// Find objects with specific tag

QByteArray query = delegate->GetSelectionByMetaInfoQuery("tags", "important");

Note: Uses database-specific JSON operators (PostgreSQL JSONB or SQLite JSON functions)

See also: ISqlJsonXPathExtractor

◆ GetSelectionQuery()

virtual QByteArray imtdb::IDatabaseObjectDelegate::GetSelectionQuery	(	const QByteArray &	objectId = `QByteArray()`,
		int	offset = `0`,
		int	count = `-1`,
		const iprm::IParamsSet *	paramsPtr = `nullptr`
	)		const

pure virtual

Generates SQL SELECT query for retrieving objects.

Creates a SELECT query with optional filtering, pagination, and specific object selection. This is the primary method for retrieving objects from the database.

Parameters

objectId	If not empty, retrieves only the specified object (WHERE Id = objectId)
offset	Number of rows to skip (for pagination, e.g., OFFSET 20)
count	Maximum number of rows to return (for pagination, e.g., LIMIT 10)
paramsPtr	Additional query parameters: Filtering: WHERE clauses (e.g., Name LIKE 'John') Sorting: ORDER BY clauses (e.g., Name ASC, Age DESC) Searching: Full-text or pattern matching

Returns: SQL SELECT query string

// Get specific object
QByteArray query1 = delegate->GetSelectionQuery("user-123");
 
// Get page 3 (rows 20-29) with filter
auto params = acf::CreateComponent<iprm::CParamsSetComp>();
params->SetValue("Status", "active");
QByteArray query2 = delegate->GetSelectionQuery(QByteArray(), 20, 10, params.get());

Note: Empty objectId with offset/count=0/-1 returns all objects

See also: GetCountQuery(), CreateFilterQuery()

Classes

Public Member Functions

Detailed Description

Purpose

Query Types

Common Implementations

Usage Example

Member Function Documentation

◆ CreateCollectionItemMetaInfoQuery()

◆ CreateDataMetaInfoQuery()

◆ CreateDeleteObjectSetQuery()

◆ CreateDeleteObjectsQuery()

◆ CreateDescriptionObjectQuery()

◆ CreateNewObjectQuery()

◆ CreateRenameObjectQuery()

◆ CreateResetQuery()

◆ CreateRestoreObjectSetQuery()

◆ CreateRestoreObjectsQuery()

◆ CreateUpdateObjectQuery()

◆ GetCountQuery()

◆ GetObjectTypeId()

◆ GetObjectTypeInfos()

◆ GetSelectionByMetaInfoQuery()

◆ GetSelectionQuery()