Session Startup/Shutdown and Event Handlers

The initialization and shutdown sequence information below, in combination with other event handler guidelines, will help you develop event handlers that override or extend standard model behavior.

Model Loading and Unloading

The behavior for model loading and unloading within the Design Tool differs slightly from the same sequence in the Session Server.

Model Loading

When a model is loaded in either the Design Tool or the Session Server, the following sequence occurs:

1. The Design Tool copies all JAR files in the model's \scripts\lib directory to a temporary working area. On the Session Server, the deployment directory is the working area.
2. Host Integrator notifies the script manager of the new model configuration, passing the model name, model directory, and the location of the working area. The Session Server also passes a copy of all model metadata to be cached in the script manager.
3. An infrastructure, consisting of the created data accessible through the ModelContext interface and a class loader for the JARs in each model's working area, is built.
4. Each JAR file in the event handler working area is inspected for classes that extend an event handler. For any class that is found, the methods and applicable timeout overrides are catalogued for return to Host Integrator.
5. Upon return, if the model implements the Model Loaded event, that event is fired.
   • All errors returned by this event are reported and then ignored in the Design Tool.
   • In the Session Server, errors can cause the model load to fail. The model is then unavailable for pools or dedicated sessions.

Model Unloading

Design Tool: You unload a model when you close the Design Tool or open a new model. The act of opening a new model over an existing model causes the existing model to be unloaded. Reloading event handlers (for example, after a rebuild) also causes a model unload.

Session Server: The Session Server unloads a model during shutdown and when it is removed from or updated in the server configuration. The following steps take place:

1. Each host session is instructed to log out when the current client finishes. The host session is then destroyed.
2. Once all sessions have been destroyed, the Model Unloaded event is fired.
3. The command to remove the model is sent to the script manager. Among other actions, this includes destroying the Java class loader that was used to access the model's script manager work area.
4. The deployment directory is made available for clean up.

A change in the version of a model deployed to a Session Server results in a model unload/load sequence. This means that model versions can be changed and new versions of event handlers loaded without restarting the server.

Creating and Destroying Host Sessions

Whenever a host session is created by Host Integrator, the Host Session Created event is fired. Similarly, when a session is destroyed, the Host Session Destroyed event is fired.

Design Tool: You create a host session when you load a new model. Whenever you unload a model, the existing host session is destroyed.

Session Server: On the Session Server, all of the existing rules about configuration changes to models and session pools still apply. Host sessions are created at startup and destroyed on shutdown for session pools. When a new model version is loaded, any existing host sessions with that model are destroyed and recreated. Changing pool sizes up or down can also result in sessions being created or destroyed. Most other changes do not result in host sessions being created or destroyed.

Sessions are created when a client connects using the connectToModel API. The Host Session Destroyed event never fires when a client is actually connected to the host session.

Client Sessions and Authentication

The client session represents a client program accessing Host Integrator.

Design Tool: As long as there is a model loaded, there is always a single simulated client session. The Authenticate User and Client Session Created events are fired when you load the model, and the Client Session Destroyed event is fired when you unload the model. You are informed of any errors generated by the Authenticate User event via the Java console, but this does not prevent the client session from being created.

In the Design Tool, the Client Connected event and the Client Disconnected event are attached to login and logout buttons to approximate the behavior of a client connecting to and disconnecting from a session. In this setting, a login process may be executed twice without an intervening logout process. However, after an initial login and associated Client Connected event fires, no additional Client Connected event will fire until a logout occurs.

Session Server: Each session spans one client connection. The Authenticate User event fires when a host session is allocated to an incoming client. If the Authenticate User event returns an error, the client session is not created. Otherwise, the client session is created and the Client Session Created event is fired. The Client Session Destroyed event is fired after the client has disconnected. If the Client Session Created event or Client Session Destroyed event fails, the client connection fails.

© 1999-2007 Attachmate Corporation. All rights reserved. Terms of Use.