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);
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.
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.
|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.
|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.|
|csIdle||Connection sequence has been completed. Application awaits user input.|
|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.|
|csQuit||Terminates the application.|
|csEndProcessing||Internal marker for terminating the connection cycle.|