TBoldSystem¶

The implementation of an object space

Declaration¶

TBoldSystem = class(TBoldDomainElement)

Hierarchy¶

TObject
TBoldMemoryManagedObject
TBoldFlaggedObject
TBoldSubscribableObject
TBoldElement
TBoldDomainElement
TBoldSystem

Description¶

This is the implementation of an object space. It holds all object instances for a model.

Properties¶

Name	Summary	Notes
AsIBoldvalueSpace	The value space view of the system	read-only
BoldSystemTypeInfo	The run-time model for the system	read-only
ClassByExpressionName	Gets the list of all instances of a given class.	read-only
Classes	The lists of all instances of the classes	read-only
DirtyObjects	All objects that have changed in memory	read-only
EnsuredLocatorByID	The TBoldObjectLocator for the Bold object corresponding to ObjectID	read-only
IsDefault	If the system is the default system
Locators	All loaded locators in the system	read-only
NewDirtyList	List that catches modified objects
NewModifiedList	List that catches modified objects
OnPreUpdate
OptimisticLockHandler	Bold-internal	read-only
PersistenceController	The persistence controller of the system	read-only
PessimisticLockHandler	Used for pessimistic locking
RegionFactory	Bold-internal	read-only
SystemPersistenceHandler	For internal use	protected, read-only
TimeForTimestamp	When a specified time stamp occurred.	read-only
TimestampForTime	What time stamp occurred at a specified time.	read-only
TimeStampOfLatestUpdate	The time stamp associated with the latest update operation performed on the system.	read-only
TransactionMode	How the system uses transactions internally
UndoHandler	Bold-internal	read-only
UndoHandlerInterface	The interface to Undo/Redo functionality of the system	read-only

AsIBoldvalueSpace¶

property AsIBoldvalueSpace[Mode:TBoldDomainElementProxyMode]: IBoldvalueSpace;

Use this property to get an IBoldValueSpace interface to the system. This is used internally.

BoldSystemTypeInfo¶

property BoldSystemTypeInfo: TBoldSystemTypeInfo;

The run-time model for the system

ClassByExpressionName¶

property ClassByExpressionName[constExpressionName:string]: TBoldObjectList;

Gets the list of all instances of a given class.

Classes¶

property Classes[index:Integer]: TBoldObjectList;

Gets the list of all instances of a class with a given topsorted index.

DirtyObjects¶

property DirtyObjects: TList;

This list contains all objects, for this system, that have changed in memory, and needs to be updated in the persistent storage.

EnsuredLocatorByID¶

property EnsuredLocatorByID[ObjectID:TBoldObjectId]: TBoldObjectLocator;

The TBoldObjectLocator for the Bold object corresponding to ObjectID. If none exists, the system creates one.

IsDefault¶

property IsDefault: Boolean;

The default system is the system returned by DefaultSystem. Calling MakeDefault makes a system the default system.

Locators¶

property Locators: TBoldSystemLocatorList;

This list contains all the locators that have been fetched, even if their objects have not.

NewDirtyList¶

property NewDirtyList: TBoldObjectList;

This property is typically assigned by the user from the OnActivate event of a form. The list will then contain all objects that have been made dirty by that form. Note that this is different from the NewModifiedList in that objects are added only when they first become dirty.

NewModifiedList¶

property NewModifiedList: TBoldObjectList;

This property is typically assigned by the user from the OnActivate event of a form. The list will then contain all objects that have been modfied by that form. Note that this is different from the NewDirtyList in that objects are added even if they were already dirty.

OnPreUpdate¶

property OnPreUpdate: TNotifyEvent;

OptimisticLockHandler¶

property OptimisticLockHandler: TBoldAbstractOptimisticLockHandler;

Bold-internal

PersistenceController¶

property PersistenceController: TBoldPersistenceController;

The persistence controller of the system. If PersistenceController is **nil** the system is transient.

PessimisticLockHandler¶

property PessimisticLockHandler: TBoldAbstractPessimisticLockHandler;

If assigned, the elements of the system will request locks pessimistically before being modified. Do not set the property directly. Instead use a TBoldLockingHandle, and connect it to the TBoldSystemHandle.

RegionFactory¶

property RegionFactory: TBoldAbstractRegionFactory;

Bold-internal

SystemPersistenceHandler¶

property SystemPersistenceHandler: TBoldAbstractSystemPersistenceHandler;

For internal use

TimeForTimestamp¶

property TimeForTimestamp[Timestamp:TBoldTimestampType]: TDateTime;

When a specified time stamp occurred.

Note

Note! This feature is only available in the Object Versioning Extension to Bold for Delphi/Bold for C++.

TimestampForTime¶

property TimestampForTime[ClockTime:TDateTime]: TBoldTimestampType;

What time stamp occurred at a specified time.

Note

This feature is only available in the Object Versioning Extension to Bold for Delphi/Bold for C++.

TimeStampOfLatestUpdate¶

property TimeStampOfLatestUpdate: TBoldTimeStampType;

The time stamp associated with the latest update operation performed on the system. The value is -1 if no update operation has been performed yet.

Note

This feature is only available in the Object Versioning Extension to Bold for Delphi/Bold for C++.

TransactionMode¶

property TransactionMode: TBoldSystemTransactionMode;

The system uses transactions internally for various operations, such as cascading delete and manipulating associations. It is possible to optimize perfomance by setting this property to stmUnsafe. This will cause the system not to use transactions. However, should any operation fail while in unsafe mode, the system becomes potentially unstable and inconsistent.

UndoHandler¶

property UndoHandler: TBoldAbstractUndoHandler;

Bold-internal

UndoHandlerInterface¶

property UndoHandlerInterface: IBoldUndoHandler;

This interface allows the user to perform Undo/Redo of changes in the system.

Methods¶

Name	Summary	Notes
AllowObjectDestruction	Allows Bold objects to be destroyed.
AssertLinkIntegrity	Bold-internal
CommitTransaction	Commits an in-memory transaction
Create	Constructor	override
CreateExistingObjectByID	Bold-internal
CreateNewObjectByExpressionName	Creates a new Bold object
CreateWithTypeInfo	Creates a TBoldSystem instance for a given model.
DefaultSubscribe	Overrides TBoldElement.DefaultSubscribe	override
DefaultSystem	The global default Bold system, if there is one.
DelayObjectDestruction	Stops Bold objects from being destroyed.
Destroy	Destructor	override
Discard	Discards all dirty objects in the Bold system.
EnsureCanDestroy
EnsureEnclosure	Makes a list technically consistent for updating.
FetchLinksWithObjects	Optimized fetching of links
GetAllInClass	All instances of the specified class will be added to the list.
GetAllInClassWithSQL	Fills aList with all the instances of AClass that match the SQL condition WhereClause.
GetAllWithCondition	Fills List with all instances that matches the condition.
GetAsList	Overrides TBoldElement.GetAsList	override
GetBoldDirty	Overrides TBoldDomainElement.GetBoldDirty	protected, override
GetBoldType	Overrides TBoldElement.GetBoldType	protected, override
GetDisplayName	Overrides TBoldElement.GetDisplayName	protected, override
GetEvaluator	Overrides TBoldElement.GetEvaluator	protected, override
GetStringRepresentation	Overrides TBoldElement.GetStringRepresentation	protected, override
InTransaction	If the system is currently in a transaction
MakeDefault	Makes the system the default system
ProxyInterface	Overrides TBoldElement.ProxyInterface	override
ReceiveEventFromOwned	Overrides TBoldDomainElement.ReceiveEventFromOwned	protected, override
RollbackTransaction	Undoes all changes made in the system since the transaction was started.
StartTransaction	Starts an in-memory transaction
TryCommitTransaction	Commit that doesn't raise exceptions
UpdateDatabase	Write changes to persistent storage
UpdateDatabaseWithList	Write selected objects to persistent storage.

AllowObjectDestruction¶

procedure AllowObjectDestruction;

Allows Bold objects to be destroyed. This may result in the destruction of objects whose destruction was delayed. See DelayObjectDestruction for details.

AssertLinkIntegrity¶

function AssertLinkIntegrity: Boolean;

Bold-internal

CommitTransaction¶

procedure CommitTransaction(MinimalMode: TBoldSystemTransactionMode = stmNormal);

TBoldSystem.CommitTransaction ends a transaction started with TBoldSystem.StartTransaction. If the transaction is not allowed to commit an exception is raised. There are two ways this could happen.

First, if there have been nested transactions, and one of the inner transactions failed (i.e., RollbackTransaction was called), then the entire transaction must fail, and thus CommitTransaction will raise an exception.

Second, there are a couple of places where validation rules can be inserted. There is a virtual method MayCommit on TBoldDomainElement, and an associated query-event bqMayCommit. These are called on each Bold object and Bold member that have been modified during the transaction. The system itself also sends the bqMayCommit query-event. If any of these return False then the transaction is not allowed to commit and CommitTransaction raises an exception. If there are nested transactions the validation is only performed on the outmost nesting level.

There is an alternative method TBoldSystem.TryCommitTransaction that indicates its success by returning true if the transaction could commit, or false if it failed. It also automatically performs a rollback if the transaction failed.

Create¶

constructor Create(AOwningElement: TBoldDomainElement); override; See also Ancestor Method

This constructor cannot be used to create a TBoldSystem. Instead, use CreateWithTypeInfo.

CreateExistingObjectByID¶

function CreateExistingObjectByID(BoldObjectID: TBoldObjectId): TBoldObject;

This function is used internally by Bold to create the in-memory representation of a Bold object. It does not fetch the object from the persistence layer, and all members are initialized to Invalid. For normal Bold users, there is no need to call this function directly.

CreateNewObjectByExpressionName¶

function CreateNewObjectByExpressionName(const ExpressionName: string; Persistent: Boolean = True): TBoldObject;

This method is useful for creating new Bold objects if there is no generated code. If there is generated code, the instance created will be of the correct Delphi type. Without generated code, the instance will be an instance of TBoldObject.

CreateWithTypeInfo¶

constructor CreateWithTypeInfo(AOwningElement: TBoldDomainElement; SystemTypeInfo: TBoldSystemTypeInfo; PersistenceController: TBoldPersistenceController; RegionFactory: TBoldAbstractRegionFactory = nil);

This constructor creates a TBoldSystem instance for a given model. For normal Bold users, there is no need to call this function. Use a TBoldSystemHandle component instead.

DefaultSubscribe¶

procedure DefaultSubscribe(Subscriber: TBoldSubscriber; RequestedEvent: TBoldEvent = breReEvaluate); override; See also Ancestor Method

No subscriptions are placed on a system.

See Also

Subscriptions

DefaultSystem¶

class function DefaultSystem: TBoldSystem;

If there exists (globally in the application) a Bold system with IsDefault = true, that system will be returned.

DelayObjectDestruction¶

procedure DelayObjectDestruction;

After this method is called, no instances of TBoldObject or its descendants will be destroyed until a subsequent call to AllowObjectDestruction is made. Objects that were supposed to be destroyed during this time will be queued and destoyed later. If several calls to DelayObjectDestruction are made, no objects will be destroyed until the last matching call to AllowObjectDestruction is made.

Destroy¶

destructor Destroy; override; See also Ancestor Method

Destructor

Discard¶

procedure Discard;

Discards all dirty objects in the Bold system. This method also discards all transient objects.

EnsureCanDestroy¶

procedure EnsureCanDestroy;

private

EnsureEnclosure¶

function EnsureEnclosure(ObjectList: TBoldObjectList; ValidateOnly: Boolean): Boolean;

EnsureEnclosure takes a list of objects and adds those additional objects needed to make it technically consistent for updating. For example, if an object in the list has an association to a newly created object, the new object will also be added to the list, so that the database does not contain a broken association.

EnsureEnclosure returns true if the list was already complete, and false if objects were added to make it complete.

If ValidateOnly is true the list will not actually be altered, but only the result value will be computed.

FetchLinksWithObjects¶

procedure FetchLinksWithObjects(ObjectList: TBoldObjectList; const LinkName: string);

Use this method to optimize the fetching of objects from the persistent storage. The OCL-evaluator will do this whenever possible. It will ensure that all objects in the list will have the named relation fetched, and all related objects in this association will also be fetched.

GetAllInClass¶

procedure GetAllInClass(aList: TBoldObjectList; AClass: TBoldObjectClass);

All instances of the specified class will be added to the list.

GetAllInClassWithSQL¶

procedure GetAllInClassWithSQL(aList: TBoldObjectList; AClass: TBoldObjectClass; WhereClause, OrderByClause: String; Params: TParams = nil; JoinInheritedTables: Boolean = true; MaxAnswers: integer = -1; Offset: integer = -1);

Fills aList with all the instances of AClass that match the SQL condition WhereClause. The condition will be evaluated in the persistent storage, therefore changes in the system that has not been stored may not be reflected in the result.

An easier way to use this method is to use the TBoldSQLHandle component

Parameters

aList	The list to be filled with the resulting objects
aClass	The class from which you want your result such as "`TPerson`"
WhereClause	a SQL-fragment that restricts the objects based on their attributes or relations. This can be arbitrarily complex and may contain nested select-statements
OrderByClause	a SQL-fragment (optionally empty) that specifies the order of the objects
Params	If the SQLfragment contains values such as dates, it is good to send these values as params instead of as text (since many databases rely on the operating system to decide the string format of a date). Give the parameter a name, and refer to the value using ":name" in your `WhereClause`
JoinInheritedTables	If the `WhereClause` contains references to inherited attributes or relations, then this property must be `true`, so that the tables from the super classes are joined in the query. This will normally decrease performance
MaxAnswer	If you are not sure how many objects will be returned by your query, you can restrict the number in the result set by providing a value for the `MaxAnswer` parameter.
Offset	If you want to skip initial objects (perhaps becayuse they have already been retrieved with a previous call to this method with a restriction in `MaxAnswer`) you can provide a value for the `Offset` parameter

GetAllWithCondition¶

procedure GetAllWithCondition(aList: TBoldObjectList; Condition: TBoldCondition);

Fills List with all instances that matches the condition. The condition will be evaluated in the persistent storage, therefore changes in the system that has not been stored may not be reflected in the result.

GetAsList¶

procedure GetAsList(ResultList: TBoldIndirectElement); override; See also Ancestor Method

The list representation of a system is a TBoldMemberList containing object lists with all instances of all classes in the system.

GetBoldDirty¶

function GetBoldDirty: Boolean; override; See also Ancestor Method

A system is dirty if it contains any dirty objects.

GetBoldType¶

function GetBoldType: TBoldElementTypeInfo; override; See also Ancestor Method

The BoldType of a system is its SystemTypeInfo, i.e. the run-time representation of the model.

GetDisplayName¶

function GetDisplayName: String; override; See also Ancestor Method

The display name of a system is the name of the model.

GetEvaluator¶

function GetEvaluator: TBoldEvaluator; override; See also Ancestor Method

Overrides GetEvaluator

GetStringRepresentation¶

function GetStringRepresentation(Representation: TBoldRepresentation): string; override; See also Ancestor Method

The string representation of a system is the expression name of the model.

InTransaction¶

function InTransaction: boolean;

If there is an open transaction in the system, i.e. if a call to StartTransaction has been made without a matching call to CommitTransaction or RollbackTransaction.

MakeDefault¶

procedure MakeDefault;

Makes the system the default system. See DefaultSystem.

ProxyInterface¶

function ProxyInterface(const IId: TGUID; Mode: TBoldDomainElementProxyMode; out Obj): Boolean; override; See also Ancestor Method

Overrides ProxyInterface

ReceiveEventFromOwned¶

procedure ReceiveEventFromOwned(originator: TObject; originalEvent: TBoldEvent); override; See also Ancestor Method

Overrides ReceiveEventFromOwned

RollbackTransaction¶

procedure RollbackTransaction(MinimalMode: TBoldSystemTransactionMode = stmNormal);

Undoes all changes made in the system since the transaction was started (with a call to StartTransaction). If the transaction is nested inside another StartTransaction/CommitTransaction pair, then the transaction is not rolled back straight away. Rather, this happens at the outmost nesting level.

StartTransaction¶

procedure StartTransaction(MinimalMode: TBoldSystemTransactionMode = stmNormal);

A series of object manipulations can be enclosed in a transaction, thus allowing them to either execute as a whole, or be rolled back. A transaction is started with a call to TBoldSystem.StartTransaction. Any subsequent changes to Bold objects in that system becomes part of the transaction. If successful, the transaction is ended with a call to TBoldSystem.CommitTransaction. If some part of the transaction fails, it can be rolled back with a call to TBoldSystem.RollbackTransaction. In that case, all changes that were made since the transaction started are undone.

You can have nested calls to StartTransaction and CommitTransaction/RollbackTransaction. In that case, the entire transaction is either commited or rolled back at the outmost level only. That is, if one of the inner transactions fail, then the entire transaction also fails.

StartTransaction ExampleThe following code structure is recommended for transactions:

aBoldSystem.StartTransaction; try ...operations that are part of the transaction... aBoldSystem.CommitTransaction; except aBoldSystem.RollbackTransaction; raise; end;

TryCommitTransaction¶

function TryCommitTransaction(MinimalMode: TBoldSystemTransactionMode = stmNormal): Boolean;

TrCommitTransaction works like CommitTransaction, but will not raise an exception if the commit fails. Instead, it will rollback the transaction and return false.

UpdateDatabase¶

procedure UpdateDatabase;

Calling this method will cause every dirty object (new objects, deleted objects or objects that have been changed) to be sent to the persistence mechanism (normally a database).

If Optimistic Locking is enabled, and this fails, an EBoldOperationFailedforObjectList exception will be raised

See Also

UpdateDatabaseWithList¶

procedure UpdateDatabaseWithList(ObjectList: TBoldObjectList);

Calling this method will cause the objects in the objectlist to be sent to the persistence mechanism (normally a database). An enclosure of objects will be added to ensure that no embedded links in the persistent storage point to invalid objects.

It's the TBoldSystemPersistenceHandler.UpdateDatabaseWithList that takes care of the actual saving of the objects in the list.

If Optimistic Locking is enabled, and this fails, an EBoldOperationFailedforObjectList exception will be raised

See Also

Events¶

Name	Summary	Notes
OnCreateApproximateObjectError	This event is raised when an object with inexact type is created
OnOptimisticLockingFailed	Called when UpdateDatabase fails because of an optimisic lock.

OnCreateApproximateObjectError¶

TBoldCreateApproximateObjectError = procedure(Obj: TBoldObject) of object;

When an object is recreated as a part of being fetched, the persistence mechanism is usually able to determine exactly what type the object should be before trying to recreate the object. If it is impossible to determine the exact type of the object (perhaps because the object has been deleted in the persistent storage), the system is unable to create the object. Normally, this will result in an exception. If this event is set, and the approximate type of the object is not an abstract type, the system will allow the creation of the superclass instead, and call this event to notify the application developer that something is wrong.

The most likely scenario when this happens is if an object has an embedded relation to another object, and this related object has subclasses, and the related object has been deleted. If the event is defined, the related object will be recreated in memory and the event will be called. Normally, the persistence mechanism will mark such an object as deleted and readonly.

Running the data integrity validator from the model-editor would normally detect this problem.

OnOptimisticLockingFailed¶

TBoldOptimisticLockingFailedEvent = procedure(UpdateList, FailureList: TBoldObjectList; const FailureReason: String) of object;

Called when UpdateDatabase fails because of an optimisic lock. See Optimistic Locking. If the event is assigned, no exception will be raised.

Generated from the Bold 4.0 help (Help/BfD.chm) by Tools/chm2mkdocs.py; member lists reflect Bold 4.0, see the source for members added since.