Life Cycle Events

The events available for creating life cycle event handlers are described below.

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. See ScriptHostSession API for restrictions when using these events.

Model Loaded/Unloaded

Host Session Created/Destroyed

Authenticate User

Client Session Created/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:

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 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:

Notes:

The normal Host Integrator security infrastructure is administered independently of this event.

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:

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.

Related Topics
Bullet Event handler guidelines
Bullet Event handler API overview