jde.debugger.spec
Class EventRequestSpec

java.lang.Object
  |
  +--jde.debugger.spec.EventRequestSpec
Direct Known Subclasses:
BreakpointSpec, ExceptionSpec, WatchpointSpec

public abstract class EventRequestSpec
extends java.lang.Object
implements Protocol

EventRequestSpec.java

A request specification. This is used for watchpoints, exception-catches, and breakpoints, and provides a mechanism for implementing deferral.

The intuition is that the user should be allowed to specify things like breakpoints, even though the corresponding classes haven't been loaded yet.

When the user does a, for example, "break on_line test.Test 42", jdebug tries to find if test.Test has been loaded. If it has, it tries to set the breakpoint, and sends an error on failure.

If, however, no class matching test.Test exists, jdebug places this "spec" in a list, and each time a class is prepared, matches the class with the spec. If the spec matches, it tries to set the breakpoint / watchpoint / exception-catch. If it works, fine, else it sends the error over to jde.

This also allows for neat things like setting breakpoints on source file + line number combinations, since each reference type (given it was compiled with debug info) also contains the source file name in it.

Information that would normally be stuck right into the actual requests, for example a thread filter, is stored in the spec until the time it can resolve the request. At that time, it is set in setRequest(com.sun.jdi.request.EventRequest).

XXX

Note that as of now, when the doc is being written, there is no way of ascertaining if the user mistyped the referencetype name/pattern, since jdebug will just wait ad infinitum for that class to be prepared.

Created: Thu Jul 15 12:17:34 1999

Since:
0.1

Field Summary
(package private)  Application app
          The Application for which we're toiling so much
private  java.util.List classExFilters
          Stores a list of class exclusion filters that are to be applied to the event request when it gets resolved.
private  java.util.List classFilters
          Stores a list of class filters that are to be applied to the event request when it gets resolved.
private  java.lang.String expr
           
static java.lang.Object expressionKey
          While setting some specs, the user is allowed to specify a boolean expression that must evaluate to true if the event is to be passed on to the user.
(package private)  boolean isResolved
          Unlike the original javadt (from which most of the spec code comes, we do not maintain three spec states, ie, resolved, unresolved, and error.
private  java.lang.Long myID
           
(package private)  ReferenceTypeSpec refSpec
          The reference type spec for this event request spec: this should match the ReferenceType for the spec to be "resolved"
(package private)  com.sun.jdi.request.EventRequest request
          The EventRequest corresponding to this spec.
static java.lang.Object specPropertyKey
          Used to cross-reference the EventRequest to its spec.
private  int suspendPolicy
          Determines the suspend policy for the corresponding event.
private  java.lang.Object thread
           
static java.lang.Object threadKey
          For specs that allow for it, the thread object is either null, a Long, or a String.
 
Fields inherited from interface jde.debugger.Protocol
ATTACH_SHMEM, ATTACH_SOCKET, BR, BREAK, CANCEL_TRACE_CLASSES, CANCEL_TRACE_METHODS, CANCEL_TRACE_THREADS, CLEAR, COMMAND_ERROR, COMMAND_RESULT, CONNECTED_TO_VM, DEBUG, ERROR, EVALUATE, EVENT_BREAKPOINT_HIT, EVENT_CLASS_PREPARE, EVENT_CLASS_UNLOAD, EVENT_EXCEPTION, EVENT_METHOD_ENTRY, EVENT_METHOD_EXIT, EVENT_OTHER, EVENT_STEP_COMPLETED, EVENT_THREAD_DEATH, EVENT_THREAD_START, EVENT_VM_DEATH, EVENT_VM_DISCONNECT, EVENT_VM_START, EVENT_WATCHPOINT_HIT, EVENTSET, EXIT, FINISH, GET_ARRAY, GET_LOADED_CLASSES, GET_LOCALS, GET_OBJECT, GET_OBJECT_MONITORS, GET_PATH_INFORMATION, GET_STRING, GET_THREAD, GET_THREADS, INTERRUPT, INVALID, JDE_BUG, JDE_INIT_DEBUG_SESSION, KILL_THREAD, LAUNCH, LISTEN_SHMEM, LISTEN_SOCKET, MESSAGE, QUIT, REPORT_IDS_IN_USE, RESUME, RUN, SPEC_RESOLVED, STEP, SUSPEND, TRACE_CLASSES, TRACE_EXCEPTIONS, TRACE_METHODS, TRACE_THREADS, WARNING, WATCH
 
Constructor Summary
EventRequestSpec(Application app, ReferenceTypeSpec refSpec)
           
 
Method Summary
(package private)  void attemptImmediateResolve(com.sun.jdi.VirtualMachine vm)
          Attempts to resolve the eventRequestSpec immediately.
 void attemptResolve(com.sun.jdi.ReferenceType refType)
          This function is called after each new class is loaded.
 com.sun.jdi.request.EventRequest getEventRequest()
           
 java.lang.Long getID()
          get the id corresponding to this spec
private  void installClassExFilters(com.sun.jdi.request.EventRequest request)
          Install class exclusion filters.
private  void installClassFilters(com.sun.jdi.request.EventRequest request)
          Install class filters.
(package private)  boolean isJavaIdentifier(java.lang.String s)
           
 boolean isResolved()
           
(package private) abstract  boolean resolve(com.sun.jdi.ReferenceType refType)
          This function is called to resolve an EventRequestSpec when the ReferenceType is known to match
 void setClassExFilters(java.util.List filters)
           
 void setClassFilters(java.util.List filters)
           
 void setExpression(java.lang.String expr)
           
 void setIsResolved()
          set resolved status
(package private)  void setRequest(com.sun.jdi.request.EventRequest request)
          sets the request up.
 void setSuspendPolicy(int policy)
           
 void setThread(java.lang.Object thread)
           
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

myID

private final java.lang.Long myID

expressionKey

public static final java.lang.Object expressionKey
While setting some specs, the user is allowed to specify a boolean expression that must evaluate to true if the event is to be passed on to the user. This expression is stored in the EventRequest object as a property. On an event, the EventRequest object is also passed, and the property can then be extracted, evaluated, and handled correspondingly

expr

private java.lang.String expr

threadKey

public static final java.lang.Object threadKey
For specs that allow for it, the thread object is either null, a Long, or a String. Depending on the type, it is matched at the time the breakpoint is hit. If it matches the thread, the breakpoint is deemed non-hit.

thread

private java.lang.Object thread

suspendPolicy

private int suspendPolicy
Determines the suspend policy for the corresponding event. See EventHandler for more details

Note that the request needs to be disabled for us to be able to do this


classFilters

private java.util.List classFilters
Stores a list of class filters that are to be applied to the event request when it gets resolved. This will restrict any events from being reported only if they match the class filters.

Not all event-requests support class filters. This filters will be silently ignored for event-requests that do not support them.


classExFilters

private java.util.List classExFilters
Stores a list of class exclusion filters that are to be applied to the event request when it gets resolved. This will restrict any events from being reported only if they do not match the class ex-filters.

Not all event-requests support class ex-filters. This filters will be silently ignored for event-requests that do not support them.


isResolved

boolean isResolved
Unlike the original javadt (from which most of the spec code comes, we do not maintain three spec states, ie, resolved, unresolved, and error. In our case, on an error, we simply remove the spec from the list of specs being maintained by the application, and inform the jde of this fact (that there was an error resolving the spec) (using app.removeSpecAndInformJDE(this))

XXX see if the above needs to be changed

Consequently, we only need keep track of if we're resolved yet or not.


specPropertyKey

public static final java.lang.Object specPropertyKey
Used to cross-reference the EventRequest to its spec.

app

final Application app
The Application for which we're toiling so much

refSpec

ReferenceTypeSpec refSpec
The reference type spec for this event request spec: this should match the ReferenceType for the spec to be "resolved"

request

com.sun.jdi.request.EventRequest request
The EventRequest corresponding to this spec. This is set when the spec resolves successfully.
Constructor Detail

EventRequestSpec

public EventRequestSpec(Application app,
                        ReferenceTypeSpec refSpec)
Method Detail

setExpression

public void setExpression(java.lang.String expr)

setThread

public void setThread(java.lang.Object thread)

setSuspendPolicy

public void setSuspendPolicy(int policy)

setClassFilters

public void setClassFilters(java.util.List filters)

installClassFilters

private void installClassFilters(com.sun.jdi.request.EventRequest request)
Install class filters. Note that the request needs to be disabled for us to be able to do this

setClassExFilters

public void setClassExFilters(java.util.List filters)

installClassExFilters

private void installClassExFilters(com.sun.jdi.request.EventRequest request)
Install class exclusion filters. Note that the request needs to be disabled for us to be able to do this

getID

public java.lang.Long getID()
get the id corresponding to this spec

setRequest

void setRequest(com.sun.jdi.request.EventRequest request)
sets the request up. This is called when a resolve succedes.

getEventRequest

public com.sun.jdi.request.EventRequest getEventRequest()

resolve

abstract boolean resolve(com.sun.jdi.ReferenceType refType)
                  throws JDEException
This function is called to resolve an EventRequestSpec when the ReferenceType is known to match

if any errors occur at any time during resolution of the event- requestspec, it's entry in the EventRequestSpecList is removed, and jde informed about it (through Application.removeSpecAndInformJDE(jde.debugger.spec.EventRequestSpec, java.lang.String)

Returns:
true if the resolution was successful

attemptResolve

public void attemptResolve(com.sun.jdi.ReferenceType refType)
This function is called after each new class is loaded. If this spec hasn't been resolved yet, it's attempted to be resolved. the handling is almost exactly the same as that in attemptImmediateResolve(com.sun.jdi.VirtualMachine)

Important Note: This method will always go through without raising any exceptions. As a result of trying to resolve, an exception might be raised, but that'll only result in the removal of the erring spec from the list, and possibly a message to the jde.


attemptImmediateResolve

void attemptImmediateResolve(com.sun.jdi.VirtualMachine vm)
Attempts to resolve the eventRequestSpec immediately. There are three possibilities:

isResolved

public boolean isResolved()
Returns:
true if this spec has been resolved.

setIsResolved

public void setIsResolved()
set resolved status

isJavaIdentifier

boolean isJavaIdentifier(java.lang.String s)