TDAConnectionManager

Overview

The TDAConnectionManager serves two related purposes.

First, it maintains the list of connections defined for a particular server application and makes them available to the TDASchema and Schema Modeler for design-time purposes.

Secondly, it maintains pools of active connections at runtime, forming the foundation of all server-side database and connection pooling.

While you can edit the connections defined in a connection manager from code or via the Object Inspector using the Connection's collection property, you will usually edit them by double-clicking a TDASchema component that references it, to launch the Schema Modeler.

Location

Implements

 

constructor Create  override

Creates a new instance.

constructor Create(aOwner: TComponent)

Parameters:

  • aOwner: Owner.

Assign  override

Copies the contents of another, similar object.

procedure Assign(Source: TPersistent)

Parameters:

  • Source: Instance whose properties will be copied

CheckProperties

Validates the connection manager properties.

procedure CheckProperties

Clear  override

Clears all properties.

procedure Clear

ClearPool

Removes all connections from the pool. Note that calling ClearPool will not automatically close connections that are currently active; any active connections will remain active until they are released.

procedure ClearPool

Connections

Maintains the list of connections (a.k.a. connection strings) defined in the dictionary.

property Connections: TDAConnectionCollection read write

CreateNewConnection  protected

Creates a new connection with given parameters.

function CreateNewConnection(const ConnectionName: string; OpenConnection: boolean; const UserID: string; const Password: string): IDAConnection

Parameters:

  • ConnectionName: Connection name.
  • OpenConnection: Auto-open connection
  • UserID: user name
  • Password: password

DriverManager

Must reference the application's TDADriverManager instance, which maintains a list of all known database drivers, whether statically linked or dynamically loaded.

property DriverManager: TDADriverManager read write

GetDefaultConnectionName

Gets the default connection name.

function GetDefaultConnectionName: string

LoadFromFile    (declared in TDAStreamableComponent)

Restores the component data from file via LoadFromStream.

procedure LoadFromFile(const aFileName: string; aFormat: TDAPersistFormat)

Parameters:


LoadFromStream  override

Restores the component data stored in the given stream.

procedure LoadFromStream(aStream: TStream; aFormat: TDAPersistFormat)

Parameters:


LoadFromXml (ROUTF8String)  overload    (declared in TDAStreamableComponent)

Uses aXML as storage to load from.

procedure LoadFromXml(aXML: ROUTF8String)

Parameters:

  • aXML: Xml text

MaxPoolSize

Defines the maximum number of connections allows in the pool for each connection string. The value of the PoolBehaviour property will control how the pools will behave if the maximum number of connections is reached.

property MaxPoolSize: cardinal read write

NewConnection

Returns a new connection, either from the pool or a freshly created one.

function NewConnection(const aConnectionName: string; OpenConnection: boolean; const UserID: string; const Password: string): IDAConnection

Parameters:

  • aConnectionName: Connection name.
  • OpenConnection: Auto-open connection
  • UserID: user name
  • Password: password

OnConnectionAcquired

Fires whenever a connection was acquired. This connection could have been freshly created (in which case the OnConnectionCreated event will also fire), or be obtained from a pool.

property OnConnectionAcquired: TDAConnectionNotifyEvent read write
delegate: procedure OnConnectionAcquired(Sender: TDAConnectionManager; const Connection: IDAConnection)

OnConnectionCreated

Fires whenever a new connection was created. The event will not fire if a pooled connection was reused.

property OnConnectionCreated: TDAConnectionNotifyEvent read write
delegate: procedure OnConnectionCreated(Sender: TDAConnectionManager; const Connection: IDAConnection)

OnConnectionFailure

Fires if an attempt to acquire a new connection has failed, for whatever reason.

property OnConnectionFailure: TDAConnectionFailureEvent read write
delegate: procedure OnConnectionFailure(Sender: TDAConnectionManager; Ex: Exception)

OnConnectionReleased

Fires whenever a connection was released.

property OnConnectionReleased: TDAConnectionNotifyEvent read write
delegate: procedure OnConnectionReleased(Sender: TDAConnectionManager; const Connection: IDAConnection)

OnConnectionTimedOut

Fires when a pooled connection has timed out and will be removed from the pool.

property OnConnectionTimedOut: TDAConnectionTimeoutEvent read write
delegate: procedure OnConnectionTimedOut(Sender: TDAConnectionManager)

OnCustomPoolTransactionBehavior

Allows to perform commit or rollback manually at releasing of connection.

property OnCustomPoolTransactionBehavior: TDAConnectionNotifyEvent read write
delegate: procedure OnCustomPoolTransactionBehavior(Sender: TDAConnectionManager; const Connection: IDAConnection)

OnTimerTick  protected dynamic

This procedure maintains cleanup of cached connections.

procedure OnTimerTick(CurrentTickCount: cardinal)

Parameters:

  • CurrentTickCount: not used

OnUnknownMacroVariable

Fires when unknown macro variable is found. it can be usable when user-defined variables are used inside sql or Dynamic Where expression.

property OnUnknownMacroVariable: TDAUnknownMacroVariableEvent read write
delegate: procedure OnUnknownMacroVariable(Sender: TObject; const Name: string; var Value: string)

PoolBehaviour

Manages the pool behavior when the maximum number of connections has been reached. The three available options include: *The call to NewConnection will fail with an exception. *The call to NewConnection will wait until another connection is freed, and it will then return a connection. *The call to NewConnection will return nil.

property PoolBehaviour: TDAPoolBehaviour read write

PoolingEnabled

Enables connection pooling. Default is true. If enabled, the connection manager will maintain a pool of reusable connections, to avoid the overhead of creating and destroying database connections for each request. If disabled, each call to NewConnection will create a new connection to the back-end database, which will be closed when it is released.

property PoolingEnabled: boolean read write

PoolSize

Returns the current size of the connection pool.

property PoolSize: Integer read write

PoolTimeoutSeconds

After this number seconds of inactivity old connections will be removed from the pool and closed. Default is 60 seconds.

property PoolTimeoutSeconds: cardinal read write

PoolTransactionBehaviour

Decides how the pool handles connections that are returned to the pool with an active transaction. The three available options include: *No action will be taken. *The transaction will be rolled back, losing all changes (recommended). *The transaction will be committed, applying all changes to the underlying database.

property PoolTransactionBehaviour: TDAPoolTransactionBehaviour read write

ReleaseConnection  protected

Releases given connection.

procedure ReleaseConnection(const Conn: IDAConnection)

Parameters:

  • Conn: Given connection.

RestoreNonStreamableProperties  protected override

Restores specific information not accessible as usual properties.

procedure RestoreNonStreamableProperties(const TempStorage: TPointerArray)

Parameters:

  • TempStorage: Array to point to additional values

ROFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned RO components.

procedure ROFreeNotification(AComponent: TComponent)

Parameters:

  • AComponent: component

RORemoveFreeNotification    (declared in TROComponent)

Disables destruction notification for specified RO component.

procedure RORemoveFreeNotification(AComponent: TComponent)

Parameters:

  • AComponent: component

SaveNonStreamableProperties  protected override

Stores specific information not accessible as usual properties.

procedure SaveNonStreamableProperties(var TempStorage: TPointerArray)

Parameters:

  • TempStorage: Array to point to additional values

SaveToFile    (declared in TDAStreamableComponent)

Stores the component data into file via SaveToStream.

procedure SaveToFile(const aFileName: string; aFormat: TDAPersistFormat)

Parameters:


SaveToStream  override

Stores the component data into the given stream.

procedure SaveToStream(aStream: TStream; aFormat: TDAPersistFormat)

Parameters:


Strategy

Specifies default strategy - First In, First Out (FIFO) or Last In, First Out (LIFO)

property Strategy: TConnectionManagerStrategy read write

WaitIntervalSeconds

Sets the number of seconds that NewConnection will wait between attempts to acquire a new connection, if the pool ix maximized out and PoolBehaviour is set to pbWait.

property WaitIntervalSeconds: cardinal read write

 

Connections

Maintains the list of connections (a.k.a. connection strings) defined in the dictionary.

property Connections: TDAConnectionCollection read write

DriverManager

Must reference the application's TDADriverManager instance, which maintains a list of all known database drivers, whether statically linked or dynamically loaded.

property DriverManager: TDADriverManager read write

MaxPoolSize

Defines the maximum number of connections allows in the pool for each connection string. The value of the PoolBehaviour property will control how the pools will behave if the maximum number of connections is reached.

property MaxPoolSize: cardinal read write

PoolBehaviour

Manages the pool behavior when the maximum number of connections has been reached. The three available options include: *The call to NewConnection will fail with an exception. *The call to NewConnection will wait until another connection is freed, and it will then return a connection. *The call to NewConnection will return nil.

property PoolBehaviour: TDAPoolBehaviour read write

PoolingEnabled

Enables connection pooling. Default is true. If enabled, the connection manager will maintain a pool of reusable connections, to avoid the overhead of creating and destroying database connections for each request. If disabled, each call to NewConnection will create a new connection to the back-end database, which will be closed when it is released.

property PoolingEnabled: boolean read write

PoolSize

Returns the current size of the connection pool.

property PoolSize: Integer read write

PoolTimeoutSeconds

After this number seconds of inactivity old connections will be removed from the pool and closed. Default is 60 seconds.

property PoolTimeoutSeconds: cardinal read write

PoolTransactionBehaviour

Decides how the pool handles connections that are returned to the pool with an active transaction. The three available options include: *No action will be taken. *The transaction will be rolled back, losing all changes (recommended). *The transaction will be committed, applying all changes to the underlying database.

property PoolTransactionBehaviour: TDAPoolTransactionBehaviour read write

Strategy

Specifies default strategy - First In, First Out (FIFO) or Last In, First Out (LIFO)

property Strategy: TConnectionManagerStrategy read write

WaitIntervalSeconds

Sets the number of seconds that NewConnection will wait between attempts to acquire a new connection, if the pool ix maximized out and PoolBehaviour is set to pbWait.

property WaitIntervalSeconds: cardinal read write

 

constructor Create  override

Creates a new instance.

constructor Create(aOwner: TComponent)

Parameters:

  • aOwner: Owner.

Assign  override

Copies the contents of another, similar object.

procedure Assign(Source: TPersistent)

Parameters:

  • Source: Instance whose properties will be copied

CheckProperties

Validates the connection manager properties.

procedure CheckProperties

Clear  override

Clears all properties.

procedure Clear

ClearPool

Removes all connections from the pool. Note that calling ClearPool will not automatically close connections that are currently active; any active connections will remain active until they are released.

procedure ClearPool

CreateNewConnection  protected

Creates a new connection with given parameters.

function CreateNewConnection(const ConnectionName: string; OpenConnection: boolean; const UserID: string; const Password: string): IDAConnection

Parameters:

  • ConnectionName: Connection name.
  • OpenConnection: Auto-open connection
  • UserID: user name
  • Password: password

GetDefaultConnectionName

Gets the default connection name.

function GetDefaultConnectionName: string

LoadFromFile    (declared in TDAStreamableComponent)

Restores the component data from file via LoadFromStream.

procedure LoadFromFile(const aFileName: string; aFormat: TDAPersistFormat)

Parameters:


LoadFromStream  override

Restores the component data stored in the given stream.

procedure LoadFromStream(aStream: TStream; aFormat: TDAPersistFormat)

Parameters:


LoadFromXml (ROUTF8String)  overload    (declared in TDAStreamableComponent)

Uses aXML as storage to load from.

procedure LoadFromXml(aXML: ROUTF8String)

Parameters:

  • aXML: Xml text

NewConnection

Returns a new connection, either from the pool or a freshly created one.

function NewConnection(const aConnectionName: string; OpenConnection: boolean; const UserID: string; const Password: string): IDAConnection

Parameters:

  • aConnectionName: Connection name.
  • OpenConnection: Auto-open connection
  • UserID: user name
  • Password: password

OnTimerTick  protected dynamic

This procedure maintains cleanup of cached connections.

procedure OnTimerTick(CurrentTickCount: cardinal)

Parameters:

  • CurrentTickCount: not used

ReleaseConnection  protected

Releases given connection.

procedure ReleaseConnection(const Conn: IDAConnection)

Parameters:

  • Conn: Given connection.

RestoreNonStreamableProperties  protected override

Restores specific information not accessible as usual properties.

procedure RestoreNonStreamableProperties(const TempStorage: TPointerArray)

Parameters:

  • TempStorage: Array to point to additional values

ROFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned RO components.

procedure ROFreeNotification(AComponent: TComponent)

Parameters:

  • AComponent: component

RORemoveFreeNotification    (declared in TROComponent)

Disables destruction notification for specified RO component.

procedure RORemoveFreeNotification(AComponent: TComponent)

Parameters:

  • AComponent: component

SaveNonStreamableProperties  protected override

Stores specific information not accessible as usual properties.

procedure SaveNonStreamableProperties(var TempStorage: TPointerArray)

Parameters:

  • TempStorage: Array to point to additional values

SaveToFile    (declared in TDAStreamableComponent)

Stores the component data into file via SaveToStream.

procedure SaveToFile(const aFileName: string; aFormat: TDAPersistFormat)

Parameters:


SaveToStream  override

Stores the component data into the given stream.

procedure SaveToStream(aStream: TStream; aFormat: TDAPersistFormat)

Parameters:

 

OnConnectionAcquired

Fires whenever a connection was acquired. This connection could have been freshly created (in which case the OnConnectionCreated event will also fire), or be obtained from a pool.

property OnConnectionAcquired: TDAConnectionNotifyEvent read write
delegate: procedure OnConnectionAcquired(Sender: TDAConnectionManager; const Connection: IDAConnection)

OnConnectionCreated

Fires whenever a new connection was created. The event will not fire if a pooled connection was reused.

property OnConnectionCreated: TDAConnectionNotifyEvent read write
delegate: procedure OnConnectionCreated(Sender: TDAConnectionManager; const Connection: IDAConnection)

OnConnectionFailure

Fires if an attempt to acquire a new connection has failed, for whatever reason.

property OnConnectionFailure: TDAConnectionFailureEvent read write
delegate: procedure OnConnectionFailure(Sender: TDAConnectionManager; Ex: Exception)

OnConnectionReleased

Fires whenever a connection was released.

property OnConnectionReleased: TDAConnectionNotifyEvent read write
delegate: procedure OnConnectionReleased(Sender: TDAConnectionManager; const Connection: IDAConnection)

OnConnectionTimedOut

Fires when a pooled connection has timed out and will be removed from the pool.

property OnConnectionTimedOut: TDAConnectionTimeoutEvent read write
delegate: procedure OnConnectionTimedOut(Sender: TDAConnectionManager)

OnCustomPoolTransactionBehavior

Allows to perform commit or rollback manually at releasing of connection.

property OnCustomPoolTransactionBehavior: TDAConnectionNotifyEvent read write
delegate: procedure OnCustomPoolTransactionBehavior(Sender: TDAConnectionManager; const Connection: IDAConnection)

OnUnknownMacroVariable

Fires when unknown macro variable is found. it can be usable when user-defined variables are used inside sql or Dynamic Where expression.

property OnUnknownMacroVariable: TDAUnknownMacroVariableEvent read write
delegate: procedure OnUnknownMacroVariable(Sender: TObject; const Name: string; var Value: string)

See Also