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.
Host Session Created
Host Session Destroyed
Client Session Created
Client Session Destroyed
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.
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.
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.
This event can be used to clean up any shared resources created during the Model Loaded event.
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.
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.
This event can be used to initialize state or other resources that will live for the lifetime of the host session.
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.
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.
This event can be used to clean up any resources that were intended to live for the duration of the host session.
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.
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.
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.
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.
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.
The Client Session Destroyed event is fired when the client has disconnected and all other client and terminal cleanup processing has been completed.
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.
This event is guaranteed to be fired after all other client session cleanup
has been completed.