com.bluemarsh.jswat
Class Session

java.lang.Object
  |
  +--com.bluemarsh.jswat.Session
All Implemented Interfaces:
java.util.EventListener, VMEventListener

public class Session
extends java.lang.Object
implements VMEventListener

This class is responsible for maintaining references to all of the objects pertaining to an active debugging session. Session is used to perform some basic operations on the debugging session. Many of the useful objects in the debugging session are accessible from this Session class.

Author:
Nathan Fiedler

Field Summary
protected  UIAdapter interfaceAdapter
          Our very own user interface adapter.
protected  com.bluemarsh.jswat.SessionListenerList listenerList
          List of SessionListener objects.
protected static Category logCategory
          Reporting category.
protected  java.util.Hashtable managerTable
          Table of Manager objects keyed by their Class.
protected static int SESSION_ACTIVATING
          Session is presently activating.
protected static int SESSION_ACTIVE
          Session is active.
protected static int SESSION_CLOSED
          Session is permanently closed.
protected static int SESSION_CLOSING
          Session is presently closing.
protected static int SESSION_DEACTIVATING
          Session is presently deactivating.
protected static int SESSION_INACTIVE
          Session is inactive.
protected static int SESSION_NEW
          Session is brand new.
protected  java.util.Properties sessionProperties
          Session properties.
protected  int sessionState
          State of the Session at this time.
protected  Log statusLog
          Status log to which messages are written.
protected  VMConnection vmConnection
          VMConnection for connecting to the debuggee VM.
 
Fields inherited from interface com.bluemarsh.jswat.event.VMEventListener
PRIORITY_BREAKPOINT, PRIORITY_DEFAULT, PRIORITY_HIGH, PRIORITY_HIGHEST, PRIORITY_LOW, PRIORITY_LOWEST, PRIORITY_SESSION
 
Constructor Summary
Session()
          Creates a Session object.
 
Method Summary
 void activate(VMConnection connection)
          Activates the Session now that a connection has been made.
 void addListener(SessionListener listener)
          Adds a SessionListener to this session.
 void close()
          Shutdown the session permanently.
 void deactivate(boolean forceExit)
          Set this session inactive, clearing all the objects associated with this session.
 boolean eventOccurred(com.sun.jdi.event.Event e)
          Invoked when a VM event has occurred.
 VMConnection getConnection()
          Returns the VMConnection object for this Session, if any.
 com.sun.jdi.ThreadReference getCurrentThread()
          Returns the ThreadReference to the current thread object.
 Manager getManager(java.lang.Class managerClass)
          Retrieve an instance of a manager of the given class.
 java.lang.String getProperty(java.lang.String key)
          Searches for the property with the specified key in this property list.
 Log getStatusLog()
          Returns a reference to the Log object that receives messages.
 UIAdapter getUIAdapter()
          Returns a reference to the interface adapter associated with this session.
 com.sun.jdi.VirtualMachine getVM()
          Returns a reference to the virtual machine associated with this session.
 void handleLocatableEvent(com.sun.jdi.event.LocatableEvent event)
          Do the usual thing when a locatable event has occurred.
 void init(UIAdapter uiadapter)
          Initialize the Session by loading the session properties from disk.
 boolean isActive()
          Returns true if this session is active and attached to a virtual machine.
protected  void loadProperties()
          Load the session properties from the user's home directory.
 void removeListener(SessionListener listener)
          Removes a Session listener from this session.
 void resumeVM()
          Resume execution of the debuggee VM, from a suspended state.
protected  boolean saveProperties()
          Save the session properties to a file in the user's home directory.
 java.lang.Object setProperty(java.lang.String key, java.lang.String value)
          Stores the given value in the properties list with the given key as a reference.
 void setStatus(java.lang.String status)
          Set the status indicator using a short message.
protected  void showEventLocation(com.sun.jdi.event.LocatableEvent le)
          Shows the location of the event, including the class type, method name, and possibly the source file name and line number (if available).
protected  void showSourceFile(com.sun.jdi.Location loc)
          Show the source file for the given class.
protected  void showSourceFile(java.lang.String classname)
          Show the source file for the given class.
 void suspendVM()
          Suspend execution of the debuggee VM.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SESSION_NEW

protected static final int SESSION_NEW
Session is brand new.

SESSION_ACTIVE

protected static final int SESSION_ACTIVE
Session is active.

SESSION_INACTIVE

protected static final int SESSION_INACTIVE
Session is inactive.

SESSION_ACTIVATING

protected static final int SESSION_ACTIVATING
Session is presently activating.

SESSION_DEACTIVATING

protected static final int SESSION_DEACTIVATING
Session is presently deactivating.

SESSION_CLOSING

protected static final int SESSION_CLOSING
Session is presently closing.

SESSION_CLOSED

protected static final int SESSION_CLOSED
Session is permanently closed.

logCategory

protected static Category logCategory
Reporting category.

interfaceAdapter

protected UIAdapter interfaceAdapter
Our very own user interface adapter.

statusLog

protected Log statusLog
Status log to which messages are written.

vmConnection

protected VMConnection vmConnection
VMConnection for connecting to the debuggee VM.

managerTable

protected java.util.Hashtable managerTable
Table of Manager objects keyed by their Class. Used to retrieve managers from the Session.

listenerList

protected com.bluemarsh.jswat.SessionListenerList listenerList
List of SessionListener objects.

sessionProperties

protected java.util.Properties sessionProperties
Session properties.

sessionState

protected int sessionState
State of the Session at this time.
Constructor Detail

Session

public Session()
Creates a Session object. The session starts off in an inactive state and must be initialized using the init() method.
See Also:
init(com.bluemarsh.jswat.ui.UIAdapter)
Method Detail

activate

public void activate(VMConnection connection)
Activates the Session now that a connection has been made. If the new connection is different from the previous connection, and there was a previous conneciton defined, the session properties will be erased.
Parameters:
connection - VMConnection used to represent the debuggee VM connection.
Throws:
java.lang.IllegalStateException - Thrown if the session state is not 'inactive'.

addListener

public void addListener(SessionListener listener)
Adds a SessionListener to this session. This method calls the init() method on the listener. It may also call the activate() method if the Session is already active.
Parameters:
listener - SessionListener to add to this session.

close

public void close()
Shutdown the session permanently. This will save the session properties to disk, close all the listeners, clear all lists and set all references to null.
Throws:
java.lang.IllegalStateException - Thrown if session state is not 'inactive'.

deactivate

public void deactivate(boolean forceExit)
Set this session inactive, clearing all the objects associated with this session. If the debuggee VM is active, it is brought down. If the debuggee was remote, the session disconnects but leaves the remote debuggee running, unless the 'forceExit' parameter is set to true.
Parameters:
forceExit - true to close debuggee VM forcibly in all cases; false to leave remote debuggee running.
Throws:
java.lang.IllegalStateException - Thrown if the session state is not 'active'.
See Also:
activate(com.bluemarsh.jswat.VMConnection)

eventOccurred

public boolean eventOccurred(com.sun.jdi.event.Event e)
Invoked when a VM event has occurred. The Session object listens for several VM events in order to keep up-to-date with the state of the running debuggee VM.
Specified by:
eventOccurred in interface VMEventListener
Parameters:
e - VM event
Returns:
true if debuggee VM should be resumed, false otherwise.

getConnection

public VMConnection getConnection()
Returns the VMConnection object for this Session, if any.
Returns:
VMConnection, or null if none has been made yet.

getCurrentThread

public com.sun.jdi.ThreadReference getCurrentThread()
Returns the ThreadReference to the current thread object.
Returns:
Current thread reference.

getManager

public Manager getManager(java.lang.Class managerClass)
Retrieve an instance of a manager of the given class. If one does not exist, an instance will be created.
Parameters:
managerClass - Class of Manager to retrieve.
Returns:
Manager object, or null if unlikely things happened.

getProperty

public java.lang.String getProperty(java.lang.String key)
Searches for the property with the specified key in this property list. The method returns null if the property is not found.
Parameters:
key - the property key.
Returns:
the value in this property list with the specified key value.

getStatusLog

public Log getStatusLog()
Returns a reference to the Log object that receives messages.
Returns:
Log for writing messages to.

getVM

public com.sun.jdi.VirtualMachine getVM()
Returns a reference to the virtual machine associated with this session. If the Session is not active, this will return null.
Returns:
Java virtual machine for this session, or null if not currently connected.

getUIAdapter

public UIAdapter getUIAdapter()
Returns a reference to the interface adapter associated with this session.
Returns:
interface adapter for this session.

handleLocatableEvent

public void handleLocatableEvent(com.sun.jdi.event.LocatableEvent event)
Do the usual thing when a locatable event has occurred. This involves displaying an indication of the type of event that occurred, such as setting the status indicator (title bar). Shows the location of the event that occurred. Sets the current context of the event in the ContextManager. Tries to show the source code for the event location.
Parameters:
event - locatable event.

init

public void init(UIAdapter uiadapter)
Initialize the Session by loading the session properties from disk.
Parameters:
uiadapter - interface adapter.
Throws:
java.lang.IllegalStateException - Thrown if the session state is not 'new'.

isActive

public boolean isActive()
Returns true if this session is active and attached to a virtual machine. When the session is not active, many objects will be not have been created yet.
Returns:
true if active, false otherwise
See Also:
activate(com.bluemarsh.jswat.VMConnection), deactivate(boolean)

loadProperties

protected void loadProperties()
Load the session properties from the user's home directory.

removeListener

public void removeListener(SessionListener listener)
Removes a Session listener from this session. This calls the close() method of the listener.
Parameters:
listener - SessionListener to remove from this session.

resumeVM

public void resumeVM()
              throws NotActiveException
Resume execution of the debuggee VM, from a suspended state.
Throws:
NotActiveException - Thrown if session is not actively debugging a VM.

saveProperties

protected boolean saveProperties()
Save the session properties to a file in the user's home directory.
Returns:
True if saved successfully, false if error.

setProperty

public java.lang.Object setProperty(java.lang.String key,
                                    java.lang.String value)
Stores the given value in the properties list with the given key as a reference. If the value is null, then the key and value will be removed from the properties.
Parameters:
key - the key to be placed into this property list.
value - the value corresponding to key, or null to remove the key and value from the properties.
Returns:
Previous value stored using this key.

setStatus

public void setStatus(java.lang.String status)
Set the status indicator using a short message. This will call into the interface adapter's showStatus() method. In addition, the message will be printed to the log.
Parameters:
status - short message indicating program status.

showEventLocation

protected void showEventLocation(com.sun.jdi.event.LocatableEvent le)
Shows the location of the event, including the class type, method name, and possibly the source file name and line number (if available).
Parameters:
le - LocatableEvent whose location will be displayed.

showSourceFile

protected void showSourceFile(com.sun.jdi.Location loc)
Show the source file for the given class.
Parameters:
loc - location for which to show the source.

showSourceFile

protected void showSourceFile(java.lang.String classname)
Show the source file for the given class.
Parameters:
classname - Fully-qualified name of class.

suspendVM

public void suspendVM()
               throws NotActiveException
Suspend execution of the debuggee VM.
Throws:
NotActiveException - Thrown if session is not actively debugging a VM.