com.glaivestone.javax.execution
Class SessionManager

java.lang.Object
  |
  +--com.glaivestone.javax.util.EventManager
        |
        +--com.glaivestone.javax.execution.SessionManager

Direct Known Subclasses:

UISessionManager

public class SessionManager

extends EventManager

The session manager provides life cycle support and general utility services for an application execution session. Participants in the session reference the current session manager by the expression SessionManager.current.

Application components can register to receive notifications of session life cycle events by configuring event handlers on the SessionManager.current. Session startup event listeners are notified in registration order, on the assumption that lower layers of the system are loaded first and thus register their event handlers before those of higher levels in the system. On the same principle, session shutdown events are notified in reverse order of registration to enable higher levels of the application to perform their shutdown processing before lower levels of the system.

The session manager provides a storage mechanism for session options which manages settings and objects of general interest to components in the application session. Options are identified by a string name. Application components should use option naming conventions similar to the qualified naming convention of Java packages to manage the options name space.

Usage Notes

Applications which use a session manager should use the session shutdown services rather than the underlying System.exit operation. The protocol to terminate a session is to invoke SessionManager.current.shutdown, which triggers the session shutdown confirmation event and ends the session if the proposed shutdown has not been vetoed. To forcibly terminate the session without allowing session participants the opportunity to refuse to allow shutdown, invoke the SessionManager.current.exit service.

The session manager is not able to automatically hook itself into the underlying Java runtime system startup processing. Consequently, application developers are responsible for providing startup logic in their application which initiates and manages the session startup cycle and triggers the associated notification events through the services provided by SessionManager.current.

Origins

The session manager mechanism, along with the session life events and the notion of a registry for session options, is derived from concepts in Visual Smalltalk (the SessionModel mechanism).

Author:

Deb Lewis

See Also:

SessionEventListener, SessionEvent

Field Summary

static SessionManager	current The session manager for the current application session.
static java.io.File	DEFAULT_DIRECTORY The file system directory when the session was initiated.
static java.lang.Object	NULL_VALUE A standard null value instance.

Method Summary

void	addFirstSessionListener(SessionEventListener aListener) Register a session event listener at the head of the listener list.
void	addSessionListener(SessionEventListener aListener) Register a session event listener.
void	exit() Terminate the session unconditionally.
void	fireAboutToStartSession() Notify listeners that session startup processing is about to be initiated.
void	fireSessionStarted() Notify listeners that session startup processing has completed.
java.lang.Object	getOption(java.lang.String name) Answer the value of the specified session option.
java.lang.Object	getOption(java.lang.String name, java.lang.Object valueIfAbsent) Answer the value of the specified session option.
java.net.URL	getSystemResource(java.lang.String reference) Resolve a reference to a resource on the classpath.
boolean	hasOption(java.lang.String name) Answer whether the specified session option is registered.
void	registerOption(java.lang.String name, java.lang.Object value) Register an option in the session option settings table.
void	removeOption(java.lang.String name) Remove an option from the session option settings table.
void	removeSessionListener(SessionEventListener aListener) Removes a session event listener.
void	shutdown() Terminate the session, subject to concurrence by interested listeners.
java.lang.String	toString() Answer a string describing the receiver.

Methods inherited from class com.glaivestone.javax.util.EventManager

addFirstListener, addListener, getEventTable, getEventTableForEdit, getListeners, removeListener

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

current

public static SessionManager current

The session manager for the current application session.

DEFAULT_DIRECTORY

public static final java.io.File DEFAULT_DIRECTORY

The file system directory when the session was initiated.

This directory is used by the base system File services to resolve relative path names when no directory is specified on construction services.

NULL_VALUE

public static final java.lang.Object NULL_VALUE

A standard null value instance.

Clients can use this for the not-found value when using getOption to retrieve session options.

Method Detail

addFirstSessionListener

public void addFirstSessionListener(SessionEventListener aListener)

Register a session event listener at the head of the listener list. The listener will now be the first to receive startup notifications and the last to receiver shutdown notifications.

Note:This service should be used with care.

Parameters:

aListener - the session event listener

addSessionListener

public void addSessionListener(SessionEventListener aListener)

Register a session event listener.

Parameters:

aListener - the session event listener

exit

public void exit()

Terminate the session unconditionally.

Does not return if the session is successfully shut down.

fireAboutToStartSession

public void fireAboutToStartSession()

Notify listeners that session startup processing is about to be initiated.

Listeners are notified in first-to-last (registration) order, presumably reflecting lower-to-higher startup order of system layers.

Because we don't have the right hooks to get into the underlying Java runtime startup processing, this service must be invoked by the main application startup processing logic. Should be called exactly once per session.

fireSessionStarted

public void fireSessionStarted()

Notify listeners that session startup processing has completed.

Listeners are notified in first-to-last (registration) order, presumably reflecting lower-to-higher startup order of system layers.

Because we don't have the right hooks to get into the underlying Java runtime startup processing, this service must be invoked by the main application startup processing logic. Should be called exactly once per session.

getOption

public java.lang.Object getOption(java.lang.String name)

Answer the value of the specified session option. Returns null if the option is not registered or has value null.

getOption

public java.lang.Object getOption(java.lang.String name,
                                  java.lang.Object valueIfAbsent)

Answer the value of the specified session option. Returns the specified value if the option is not registered.

getSystemResource

public java.net.URL getSystemResource(java.lang.String reference)

Resolve a reference to a resource on the classpath.

hasOption

public boolean hasOption(java.lang.String name)

Answer whether the specified session option is registered.

registerOption

public void registerOption(java.lang.String name,
                           java.lang.Object value)

Register an option in the session option settings table.

removeOption

public void removeOption(java.lang.String name)

Remove an option from the session option settings table.

removeSessionListener

public void removeSessionListener(SessionEventListener aListener)

Removes a session event listener.

Parameters:

aListener - the session event listener

shutdown

public void shutdown()

Terminate the session, subject to concurrence by interested listeners.

Does not return if the session is successfully shut down. Returns to the caller if shutdown was vetoed and has not been performed.

toString

public java.lang.String toString()

Answer a string describing the receiver.

Overrides:

toString in class java.lang.Object