Life Cycle Events

The events available for creating life cycle event handlers are described below. Review the API documentation for life cycle events for more information.

Note: None of the events on this interface have direct access to a terminal session. If initialization or cleanup with terminal access is needed, use model events. Callbacks are restricted when using these events.

Model Loaded

Model Unloaded

Host Session Created

Host Session Destroyed

Authenticate User

Client Session Created

Client Session Destroyed

Model Loaded

The Model Loaded event is fired whenever Host Integrator loads a new model, or an updated version of an existing model. There is one exception: when the Design Tool loads a model already loaded by another instance of the Design Tool, no events are fired for this model, including the Model Loaded event.

Possible uses:

Create shared resources—If interaction with an external system is required, a pool of shared connections can be created and stored in the state hash table for the model.
Customize model environment—This could involve anything from altering Host Integrator's model variable list configuration to establishing a local output file for auditing or debugging purposes.

Notes:

With the Host Integrator Session Server, the Model Loaded event often fires for a new version of a model before the Model Unloaded event fires for the prior version. This occurs because new clients will be given access to the new version before all existing clients are finished with the prior version, and the prior version is not unloaded until all host sessions using the model have been destroyed.

Any exception returned from this event causes the model to fail to load. In the Design Tool, these errors are reported and the model remains loaded. However, any model that fails to load on the Session Server is unavailable for client requests. If this is not a desired outcome, then the event handler should catch all "throwable" exceptions, log its own message, and then discard the exception.

Model Unloaded

The Model Unloaded event is fired when a model is unloaded by Host Integrator. This occurs for the existing model when the user exits the Design Tool or when the user loads a model. On the Session Server, this occurs when a new version of a model is activated or the server process shuts down.

Possible use:

This event can be used to clean up any shared resources created during the Model Loaded event.

Notes:

On the Server, this event may be fired after a new version of the model has already been loaded. Under normal circumstances, this should not present a significant issue because each model version has its own state hash table instance. However, statically loaded resources could be shared between model versions and should be managed accordingly.

Host Session Created

The Host Session Created event is fired each time a host session is created. In the Design Tool, this happens each time a model is loaded and when the user invokes certain tests in the Connection Events Test dialog box. On the Session Server, this occurs when a session pool is created or augmented and when a dedicated session is created in response to a client request.

Possible use:

This event can be used to initialize state or other resources that will live for the lifetime of the host session.

Notes:

For each server instance, each host session is guaranteed to have a unique identifier (obtained from the model event callback interface). This can be the key, or part of the key, to store state information in the model state hash table. The host session may span multiple clients and thus does not have access to the yet-to-be-created client hash table.

If this event returns any exception, the Host Integrator Session Server fails to create the host session and it is not made available for client access. In the Design Tool, errors are reported, but the host session creation succeeds.

Host Session Destroyed

The Host Session Destroyed event is fired each time a host session is destroyed. In the Design Tool, this happens each time a model is unloaded and when the user invokes certain tests in the Connection Events Test dialog box. On the Session Server, this occurs when a session pool is destroyed or decreased in size and after a dedicated session is released by its client.

Possible use:

This event can be used to clean up any resources that were intended to live for the duration of the host session.

Notes:

This event is guaranteed to be fired after the last client attached to this session has been cleaned up and the session has been logged out or forcibly disconnected.

Authenticate User

The Authenticate User event is fired when a client connects to a server host session to permit authentication and/or authorization beyond that provided by Host Integrator security. In the Design Tool, this event is fired when a model is loaded and when the user invokes certain tests in the Connection Events Test dialog box.

Possible uses:

Extend authentication—Set up the extended authorization to access a proprietary security system, use connection parameters beyond user id and password, or both.
Add authorization—For cases when user authentication to the larger Host Integrator system does not necessarily equate to authorization to access the model in question.
Prepare host session—This event can modify the values of the model variables to match the connection parameters or otherwise meet application requirements.

Notes:

The normal Host Integrator security infrastructure is administered independently of this event. If security is on, the client must present credentials that Host Integrator can verify before this event will be accessed. If security is off, this event will still be invoked if it is defined.

Client Session Created

The Client Session Created event is fired after a client has been granted access to a host session, but before the client is allowed to make any requests.

Possible uses:

Initialize state cache—This is the first event for a client session that has access to the client hash map. Populating the cache with needed data is the primary use of this event.
Define authorization tokens—After initializing the state cache, if you are implementing field-level security or other fine-grained authorization strategies, you can use this event to create the requisite tokens and store them in the cache.

Notes:

As with other life cycle creation events, any exception returned from this event results in the Host Integrator Server failing to create the client session. The prospective client receives the error and is denied access to a host session. In the Design Tool, unhandled exceptions are reported but the client session is created anyway.

Client Session Destroyed

The Client Session Destroyed event is fired when the client has disconnected and all other client and terminal cleanup processing has been completed.

Possible uses:

This event can be used to clean up any resources that were intended to live for the duration of the client session. The client cache will be made available for garbage collection after this event, so only orderly releases of external resources need be done with this event.

Notes:

This event is guaranteed to be fired after all other client session cleanup has been completed.