## 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
`<clinit>, 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:
  - The corresponding class hasn't been loaded. the method returns normally.
  - The class has been loaded, and the resolution is successful. The method returns normally, having set the isResolved flag in this class
  - The class has been loaded, but there was an error trying to resolve this spec. An exception is raised, and is caught in this method. This spec is then removed from the spec list kept in the Application object, and jde informed that this spec could not be resolved, so that the UI can take appropriate actions (for example removing the highlighting of a breakpoint)

### 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)