Back to index...

	/*
	* Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package com.sun.jdi.request;

	import com.sun.jdi.*;

	import java.util.List;

	/**
	* Manages the creation and deletion of {@link EventRequest}s. A single
	* implementor of this interface exists in a particuar VM and
	* is accessed through {@link VirtualMachine#eventRequestManager()}
	*
	* @see EventRequest
	* @see com.sun.jdi.event.Event
	* @see BreakpointRequest
	* @see com.sun.jdi.event.BreakpointEvent
	* @see VirtualMachine
	*
	* @author Robert Field
	* @since 1.3
	*/

	@jdk.Exported
	public interface EventRequestManager extends Mirror {

	/**
	* Creates a new disabled {@link ClassPrepareRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* @return the created {@link ClassPrepareRequest}
	*/
	ClassPrepareRequest createClassPrepareRequest();

	/**
	* Creates a new disabled {@link ClassUnloadRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* @return the created {@link ClassUnloadRequest}
	*/
	ClassUnloadRequest createClassUnloadRequest();

	/**
	* Creates a new disabled {@link ThreadStartRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* @return the created {@link ThreadStartRequest}
	*/
	ThreadStartRequest createThreadStartRequest();

	/**
	* Creates a new disabled {@link ThreadDeathRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* @return the created {@link ThreadDeathRequest}
	*/
	ThreadDeathRequest createThreadDeathRequest();

	/**
	* Creates a new disabled {@link ExceptionRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	* <P>
	* A specific exception type and its subclasses can be selected
	* for exception events. Caught exceptions, uncaught exceptions,
	* or both can be selected. Note, however, that
	* at the time an exception is thrown, it is not always
	* possible to determine whether it is truly caught. See
	* {@link com.sun.jdi.event.ExceptionEvent#catchLocation} for
	* details.
	* @param refType If non-null, specifies that exceptions which are
	* instances of refType will be reported. Note: this
	* will include instances of sub-types. If null,
	* all instances will be reported
	* @param notifyCaught If true, caught exceptions will be reported.
	* @param notifyUncaught If true, uncaught exceptions will be reported.
	*
	* @return the created {@link ExceptionRequest}
	*/
	ExceptionRequest createExceptionRequest(ReferenceType refType,
	boolean notifyCaught,
	boolean notifyUncaught);

	/**
	* Creates a new disabled {@link MethodEntryRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* @return the created {@link MethodEntryRequest}
	*/
	MethodEntryRequest createMethodEntryRequest();

	/**
	* Creates a new disabled {@link MethodExitRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* @return the created {@link MethodExitRequest}
	*/
	MethodExitRequest createMethodExitRequest();

	/**
	* Creates a new disabled {@link MonitorContendedEnterRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* Not all target virtual machines support this operation.
	* Use {@link VirtualMachine#canRequestMonitorEvents()}
	* to determine if the operation is supported.
	*
	* @return the created {@link MonitorContendedEnterRequest}
	* @throws java.lang.UnsupportedOperationException if
	* the target VM does not support this
	* operation.
	*
	* @since 1.6
	*/
	MonitorContendedEnterRequest createMonitorContendedEnterRequest();

	/**
	* Creates a new disabled {@link MonitorContendedEnteredRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* Not all target virtual machines support this operation.
	* Use {@link VirtualMachine#canRequestMonitorEvents()}
	* to determine if the operation is supported.
	*
	* @return the created {@link MonitorContendedEnteredRequest}
	* @throws java.lang.UnsupportedOperationException if
	* the target VM does not support this
	* operation.
	*
	* @since 1.6
	*/

	MonitorContendedEnteredRequest createMonitorContendedEnteredRequest();

	/**
	* Creates a new disabled {@link MonitorWaitRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* Not all target virtual machines support this operation.
	* Use {@link VirtualMachine#canRequestMonitorEvents()}
	* to determine if the operation is supported.
	*
	* @return the created {@link MonitorWaitRequest}
	* @throws java.lang.UnsupportedOperationException if
	* the target VM does not support this
	* operation.
	*
	* @since 1.6
	*/
	MonitorWaitRequest createMonitorWaitRequest();

	/**
	* Creates a new disabled {@link MonitorWaitedRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* Not all target virtual machines support this operation.
	* Use {@link VirtualMachine#canRequestMonitorEvents()}
	* to determine if the operation is supported.
	*
	* @return the created {@link MonitorWaitedRequest}
	* @throws java.lang.UnsupportedOperationException if
	* the target VM does not support this
	* operation.
	*
	* @since 1.6
	*/
	MonitorWaitedRequest createMonitorWaitedRequest();

	/**
	* Creates a new disabled {@link StepRequest}.
	* The new event request is added to the list managed by this
	* EventRequestManager. Use {@link EventRequest#enable()} to
	* activate this event request.
	* <p>
	* The returned request will control stepping only in the specified
	* <code>thread</code>; all other threads will be unaffected.
	* A <code>size</code>value of {@link com.sun.jdi.request.StepRequest#STEP_MIN} will generate a
	* step event each time the code index changes. It represents the
	* smallest step size available and often maps to the instruction
	* level.
	* A <code>size</code> value of {@link com.sun.jdi.request.StepRequest#STEP_LINE} will generate a
	* step event each time the source line changes unless line number information is not available,
	* in which case a STEP_MIN will be done instead. For example, no line number information is
	* available during the execution of a method that has been rendered obsolete by
	* by a {@link com.sun.jdi.VirtualMachine#redefineClasses} operation.
	* A <code>depth</code> value of {@link com.sun.jdi.request.StepRequest#STEP_INTO} will generate
	* step events in any called methods. A <code>depth</code> value
	* of {@link com.sun.jdi.request.StepRequest#STEP_OVER} restricts step events to the current frame
	* or caller frames. A <code>depth</code> value of {@link com.sun.jdi.request.StepRequest#STEP_OUT}
	* restricts step events to caller frames only. All depth
	* restrictions are relative to the call stack immediately before the
	* step takes place.
	* <p>
	* Only one pending step request is allowed per thread.
	* <p>
	* Note that a typical debugger will want to cancel stepping
	* after the first step is detected. Thus a next line method
	* would do the following:
	* <code>
	* <pre>
	* EventRequestManager mgr = myVM.{@link VirtualMachine#eventRequestManager eventRequestManager}();
	* StepRequest request = mgr.createStepRequest(myThread,
	* StepRequest.{@link StepRequest#STEP_LINE STEP_LINE},
	* StepRequest.{@link StepRequest#STEP_OVER STEP_OVER});
	* request.{@link EventRequest#addCountFilter addCountFilter}(1); // next step only
	* request.enable();
	* myVM.{@link VirtualMachine#resume resume}();
	* </pre>
	* </code>
	*
	* @param thread the thread in which to step
	* @param depth the step depth
	* @param size the step size
	* @return the created {@link StepRequest}
	* @throws DuplicateRequestException if there is already a pending
	* step request for the specified thread.
	* @throws IllegalArgumentException if the size or depth arguments
	* contain illegal values.
	*/
	StepRequest createStepRequest(ThreadReference thread,
	int size,
	int depth);

	/**
	* Creates a new disabled {@link BreakpointRequest}.
	* The given {@link Location} must have a valid
	* (that is, non-negative) code index. The new
	* breakpoint is added to the list managed by this
	* EventRequestManager. Multiple breakpoints at the
	* same location are permitted. Use {@link EventRequest#enable()} to
	* activate this event request.
	*
	* @param location the location of the new breakpoint.
	* @return the created {@link BreakpointRequest}
	* @throws NativeMethodException if location is within a native method.
	*/
	BreakpointRequest createBreakpointRequest(Location location);

	/**
	* Creates a new disabled watchpoint which watches accesses to the
	* specified field. The new
	* watchpoint is added to the list managed by this
	* EventRequestManager. Multiple watchpoints on the
	* same field are permitted.
	* Use {@link EventRequest#enable()} to
	* activate this event request.
	* <P>
	* Not all target virtual machines support this operation.
	* Use {@link VirtualMachine#canWatchFieldAccess()}
	* to determine if the operation is supported.
	*
	* @param field the field to watch
	* @return the created watchpoint
	* @throws java.lang.UnsupportedOperationException if
	* the target virtual machine does not support this
	* operation.
	*/
	AccessWatchpointRequest createAccessWatchpointRequest(Field field);

	/**
	* Creates a new disabled watchpoint which watches accesses to the
	* specified field. The new
	* watchpoint is added to the list managed by this
	* EventRequestManager. Multiple watchpoints on the
	* same field are permitted.
	* Use {@link EventRequest#enable()} to
	* activate this event request.
	* <P>
	* Not all target virtual machines support this operation.
	* Use {@link VirtualMachine#canWatchFieldModification()}
	* to determine if the operation is supported.
	*
	* @param field the field to watch
	* @return the created watchpoint
	* @throws java.lang.UnsupportedOperationException if
	* the target virtual machine does not support this
	* operation.
	*/
	ModificationWatchpointRequest createModificationWatchpointRequest(Field field);

	/**
	* Creates a new disabled {@link VMDeathRequest}.
	* The new request is added to the list managed by this
	* EventRequestManager.
	* Use {@link EventRequest#enable()} to
	* activate this event request.
	* <P>
	* This request (if enabled) will cause a
	* {@link com.sun.jdi.event.VMDeathEvent}
	* to be sent on termination of the target VM.
	* <P>
	* A VMDeathRequest with a suspend policy of
	* {@link EventRequest#SUSPEND_ALL SUSPEND_ALL}
	* can be used to assure processing of incoming
	* {@link EventRequest#SUSPEND_NONE SUSPEND_NONE} or
	* {@link EventRequest#SUSPEND_EVENT_THREAD SUSPEND_EVENT_THREAD}
	* events before VM death. If all event processing is being
	* done in the same thread as event sets are being read,
	* enabling the request is all that is needed since the VM
	* will be suspended until the {@link com.sun.jdi.event.EventSet}
	* containing the {@link com.sun.jdi.event.VMDeathEvent}
	* is resumed.
	* <P>
	* Not all target virtual machines support this operation.
	* Use {@link VirtualMachine#canRequestVMDeathEvent()}
	* to determine if the operation is supported.
	*
	* @return the created request
	* @throws java.lang.UnsupportedOperationException if
	* the target VM does not support this
	* operation.
	*
	* @since 1.4
	*/
	VMDeathRequest createVMDeathRequest();

	/**
	* Removes an eventRequest. The eventRequest is disabled and
	* the removed from the requests managed by this
	* EventRequestManager. Once the eventRequest is deleted, no
	* operations (for example, {@link EventRequest#setEnabled})
	* are permitted - attempts to do so will generally cause an
	* {@link InvalidRequestStateException}.
	* No other eventRequests are effected.
	* <P>
	* Because this method changes the underlying lists of event
	* requests, attempting to directly delete from a list returned
	* by a request accessor (e.g. below):
	* <PRE>
	* Iterator iter = requestManager.stepRequests().iterator();
	* while (iter.hasNext()) {
	* requestManager.deleteEventRequest(iter.next());
	* }
	* </PRE>
	* may cause a {@link java.util.ConcurrentModificationException}.
	* Instead use
	* {@link #deleteEventRequests(List) deleteEventRequests(List)}
	* or copy the list before iterating.
	*
	* @param eventRequest the eventRequest to remove
	*/
	void deleteEventRequest(EventRequest eventRequest);

	/**
	* Removes a list of {@link EventRequest}s.
	*
	* @see #deleteEventRequest(EventRequest)
	*
	* @param eventRequests the list of eventRequests to remove
	*/
	void deleteEventRequests(List<? extends EventRequest> eventRequests);

	/**
	* Remove all breakpoints managed by this EventRequestManager.
	*
	* @see #deleteEventRequest(EventRequest)
	*/
	void deleteAllBreakpoints();

	/**
	* Return an unmodifiable list of the enabled and disabled step requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the all {@link StepRequest} objects.
	*/
	List<StepRequest> stepRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled class prepare requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the all {@link ClassPrepareRequest} objects.
	*/
	List<ClassPrepareRequest> classPrepareRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled class unload requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the all {@link ClassUnloadRequest} objects.
	*/
	List<ClassUnloadRequest> classUnloadRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled thread start requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the all {@link ThreadStartRequest} objects.
	*/
	List<ThreadStartRequest> threadStartRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled thread death requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the all {@link ThreadDeathRequest} objects.
	*/
	List<ThreadDeathRequest> threadDeathRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled exception requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the all {@link ExceptionRequest} objects.
	*/
	List<ExceptionRequest> exceptionRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled breakpoint requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the list of all {@link BreakpointRequest} objects.
	*/
	List<BreakpointRequest> breakpointRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled access
	* watchpoint requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the all {@link AccessWatchpointRequest} objects.
	*/
	List<AccessWatchpointRequest> accessWatchpointRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled modification
	* watchpoint requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the all {@link ModificationWatchpointRequest} objects.
	*/
	List<ModificationWatchpointRequest> modificationWatchpointRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled method entry requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the list of all {@link MethodEntryRequest} objects.
	*/
	List<MethodEntryRequest> methodEntryRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled method exit requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the list of all {@link MethodExitRequest} objects.
	*/
	List<MethodExitRequest> methodExitRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled monitor contended enter requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the list of all {@link MonitorContendedEnterRequest} objects.
	*
	* @since 1.6
	*/
	List<MonitorContendedEnterRequest> monitorContendedEnterRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled monitor contended entered requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the list of all {@link MonitorContendedEnteredRequest} objects.
	*
	* @since 1.6
	*/
	List<MonitorContendedEnteredRequest> monitorContendedEnteredRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled monitor wait requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the list of all {@link MonitorWaitRequest} objects.
	*
	* @since 1.6
	*/
	List<MonitorWaitRequest> monitorWaitRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled monitor waited requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* @return the list of all {@link MonitorWaitedRequest} objects.
	*
	* @since 1.6
	*/
	List<MonitorWaitedRequest> monitorWaitedRequests();

	/**
	* Return an unmodifiable list of the enabled and disabled VM death requests.
	* This list is a live view of these requests and thus changes as requests
	* are added and deleted.
	* Note: the unsolicited VMDeathEvent does not have a
	* corresponding request.
	* @return the list of all {@link VMDeathRequest} objects.
	*
	* @since 1.4
	*/
	List<VMDeathRequest> vmDeathRequests();
	}

Back to index...