Application Connector

The application Connector is a component designed to manage the start up sequence of an application and provide some general application functionality. It covers tasks from application initialisation, registration/licensing and database log in and log out, to retrieval of key application parameter values, passwords and quitting the application. A range of fail states indicate any problems preventing successful opening of the application (to an "idle" state) or issues with subsequent processing, allowing appropriate processing.

The Connector is one of several integrated components and forms working together to underpin application setup, application parameter storage and retrieval, string encryption and decryption, credential (password) management, database user security, database maintenance... and more.

This page is under construction

General Connector Usage

In terms of "connecting" to an application, the following snippets demonstrate the basic usage of a Connector. This by no means covers all that might be done with the Connector, or cover any of the many other procedures and functions the Connector provides "on demand". The samples use an instance of the Connector called SysConnector, which has been placed in the data module dmMainData.

1. OPENING: The connector is typically initialised (or "opened") when the main form is activated at start up. This cycles through a comprehensive sequence of events preparing the application for first use. See the description of Connector States below for more details.

procedure TfMain.FormActivate(Sender: TObject);


//initialise connection...



2. SETUP: On first use (FirstIdle := True) an application might configure available options with respect to the logged in users permissions or role.

procedure TfMain.SysConnectorIdle(Connector: TCustomConnector; FirstIdle: Boolean);



//eg adjust visibility of menu items


//eg take some default action such as retrieve a users diary items for today



3. CLOSING: The application can be terminated explicitly using the Connectors Quit method.

If the user closes the main form, FormCloseQuery can call the Connectors Disconnect(Quitting: Boolean) method to implement the close down instead. To disconnect without terminating the application, use Quitting := False. Otherwise, terminate the application using Quitting := True. Either way, a "clean shutdown" is performed.

procedure TfMain.FormCloseQuery(Sender: TObject; ; var CanClose: Boolean);


CanClose := dmMainData.SysConnector.Disconnect(True);


Both these methods fire the Connectors OnCloseQuery event, which can also be directly called via the SysConnector.CloseQuery method. If CanClose := False, details of the issue can be returned and (automatically) incorporated into a compound error message (as a qualifying "detail").

NOTE: Care must be taken to avoid a situation where it becomes impossible to disconnect the Connector (ie where CanClose is always False and always prevents terminating the application). This might be managed by presenting a "close down anyway" prompt.

Connector States

The Connector cycles through a sequence of "states" describing the start up procedure for an application. The states are represented by an enumerated type. Events are fired throughout the cycle allowing appropriate responses to each action implied by the various states.

A good way to start understanding the Connector is to trace the progression of the state sequence via the enumerated type (TConnectorState). Where applicable, the event used to implement the corresponding action and the fail state associated it is listed.


1. Primary Connection Sequence States
csInitialise Initialise the connector and proceed with the connection. OnInitialise csFailInitialise
csRegister Validate application registration/licensing if used. OnRegister csFailRegister
csConnectPrepare Prepare for database connection - retrieve stored connection parameters. OnConnectionPrepare csFailConnectPrepare
csConnectSetup Optional (prompted) user access to connection setup to correct or provide missing connection information.1 n/a n/a
csLogin Database login prompt.   csFailLogin
csConnect Connect to database.2   csFailConnect
csConnectedCheck Confirm or validate that a connection has been established to the database.   csFailConnectedCheck
csConnectionValidation Confirm the established database connection is acceptable.    csFailConnectionValidation
csUserStorage Optionally store user login details.    csFailUserStorage
csUserValidation Validate the user with respect to the active database connection.    csFailUserValidation
csApplicationPrepare Retrieve global parameters or otherwise prepare for application use.   csFailApplicationPrepare
csApplicationSetup Proceed to application setup (eg where saved connection details are missing or invalid).    ??

1. A connection action is returned by OnConnectionPrepare: caRejectSetup triggers the fail state csFailConnectionPrepare; in the absence of valid connection parameters, caSetup allows the user optional (prompted) access to a connection setup procedure; caLogin proceeds to a log in prompt; caConnect proceeds to an unprompted log in; caConnectionNA can be used where no connection is required by the application.

2. A TConnector descendant appropriate to the database server being used "knows" how to connect and the connection components to use. eg TIBXConnector connects to InterBase using the Interbase Express components. TIBFConnector uses FireDAC to connect to Interbase.


2. Log Out Request States
csLogOutIdle Log out, but do not terminate the application (idle in csIdle state instead).
csLogOutAdministrator Auto-logout Administrator after successful connection.
csLogOutToNewConnection Log out, retrieve connection details again and establish a completely new connection.
csLogOutToSameConnection Log out and reconnect using the same connection parameters.
csLogOutQuitting Log out because the application is terminating (by user closing main form). 
csLogOutQuit Log out and terminate the application. 


3. Idle State (Concluding Connection Sequence)
csIdle Connection sequence has been completed. Application awaits user input.

4. Other Error States
csFailAdminLogin abc
csFailResidualConnection A connection is prevented by a pre-existing active connection.
csFailCloseQuery Application termination is prevented by the CloseQuery check.
csFailDisconnect Disconnection failed before quitting.


5. Other States
csQuit Terminates the application.
csEndProcessing Internal marker for terminating the connection cycle.