157N/A * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 157N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 157N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 157N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 157N/A * or visit www.oracle.com if you need additional information or have any 0N/A * Represents a request for notification of an event. Examples include 0N/A * {@link BreakpointRequest} and {@link ExceptionRequest}. 0N/A * When an event occurs for which an enabled request is present, 0N/A * an {@link com.sun.jdi.event.EventSet EventSet} will 0N/A * be placed on the {@link com.sun.jdi.event.EventQueue EventQueue}. 0N/A * The collection of existing event requests is 0N/A * managed by the {@link EventRequestManager}. 0N/A * The number of events generated for an event request can be controlled 0N/A * through filters. Filters provide additional constraints that an event 0N/A * must satisfy before it is placed on the event queue. Multiple filters can 0N/A * be used by making multiple calls to filter addition methods such as 0N/A * {@link ExceptionRequest#addClassFilter(java.lang.String classPattern)}. 0N/A * Filters are added to an event one at a time only while the event is 0N/A * disabled. Multiple filters are applied with CUT-OFF AND, in the order 0N/A * it was added to the request. Only events that satisfy all filters are 0N/A * placed in the event queue. 0N/A * The set of available filters is dependent on the event request, 0N/A * some examples of filters are: 0N/A * <li>Thread filters allow control over the thread for which events are 0N/A * <li>Class filters allow control over the class in which the event 0N/A * <li>Instance filters allow control over the instance in which 0N/A * <li>Count filters allow control over the number of times an event 0N/A * Filters can dramatically improve debugger performance by reducing the 0N/A * amount of event traffic sent from the target VM to the debugger VM. 0N/A * Any method on <code>EventRequest</code> which 0N/A * takes <code>EventRequest</code> as an parameter may throw 0N/A * {@link com.sun.jdi.VMDisconnectedException} if the target VM is 0N/A * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is 0N/A * available to be read from the {@link com.sun.jdi.event.EventQueue}. 0N/A * Any method on <code>EventRequest</code> which 0N/A * takes <code>EventRequest</code> as an parameter may throw 0N/A * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory. 0N/A * @see com.sun.jdi.event.BreakpointEvent 0N/A * @see com.sun.jdi.event.EventQueue 0N/A * @see EventRequestManager 0N/A * @author Robert Field 0N/A * Determines if this event request is currently enabled. 0N/A * @return <code>true</code> if enabled; 0N/A * <code>false</code> otherwise. 0N/A * Enables or disables this event request. While this event request is 0N/A * disabled, the event request will be ignored and the target VM 0N/A * will not be stopped if any of its threads reaches the 0N/A * event request. Disabled event requests still exist, 0N/A * and are included in event request lists such as 0N/A * {@link EventRequestManager#breakpointRequests()}. 0N/A * @param val <code>true</code> if the event request is to be enabled; 0N/A * <code>false</code> otherwise. 0N/A * @throws InvalidRequestStateException if this request 0N/A * @throws IllegalThreadStateException if this is a StepRequest, 0N/A * <code>val</code> is <code>true</code>, and the 0N/A * thread named in the request has died. 0N/A * Same as {@link #setEnabled <CODE>setEnabled(true)</CODE>}. 0N/A * @throws InvalidRequestStateException if this request 0N/A * @throws IllegalThreadStateException if this is a StepRequest 0N/A * and the thread named in the request has died. 0N/A * Same as {@link #setEnabled <CODE>setEnabled(false)</CODE>}. 0N/A * @throws InvalidRequestStateException if this request 0N/A * Limit the requested event to be reported at most once after a 0N/A * given number of occurrences. The event is not reported 0N/A * the first <code>count - 1</code> times this filter is reached. 0N/A * To request a one-off event, call this method with a count of 1. 0N/A * Once the count reaches 0, any subsequent filters in this request 0N/A * are applied. If none of those filters cause the event to be 0N/A * suppressed, the event is reported. Otherwise, the event is not 0N/A * reported. In either case subsequent events are never reported for 0N/A * @param count the number of ocurrences before generating an event. 0N/A * @throws InvalidRequestStateException if this request is currently 0N/A * enabled or has been deleted. 0N/A * Filters may be added only to disabled requests. 0N/A * @throws IllegalArgumentException if <CODE>count</CODE> 0N/A /** Suspend no threads when the event occurs */ 0N/A /** Suspend only the thread which generated the event when the event occurs */ 0N/A /** Suspend all threads when the event occurs */ 0N/A * Determines the threads to suspend when the requested event occurs 0N/A * in the target VM. Use {@link #SUSPEND_ALL} to suspend all 0N/A * threads in the target VM (the default). Use {@link #SUSPEND_EVENT_THREAD} 0N/A * to suspend only the thread which generated the event. Use 0N/A * {@link #SUSPEND_NONE} to suspend no threads. 0N/A * Thread suspensions through events have the same functionality 0N/A * as explicitly requested suspensions. See 0N/A * {@link com.sun.jdi.ThreadReference#suspend} and 0N/A * {@link com.sun.jdi.VirtualMachine#suspend} for details. 0N/A * @param policy the selected suspend policy. 0N/A * @throws InvalidRequestStateException if this request is currently 0N/A * enabled or has been deleted. 0N/A * Suspend policy may only be set in disabled requests. 0N/A * @throws IllegalArgumentException if the policy argument 0N/A * contains an illegal value. 0N/A * Returns a value which describes the threads to suspend when the 0N/A * requested event occurs in the target VM. 0N/A * The returned value is {@link #SUSPEND_ALL}, 0N/A * {@link #SUSPEND_EVENT_THREAD}, or {@link #SUSPEND_NONE}. 0N/A * @return the current suspend mode for this request 0N/A * Add an arbitrary key/value "property" to this request. 0N/A * The property can be used by a client of the JDI to 0N/A * associate application information with the request; 0N/A * These client-set properties are not used internally 0N/A * a small per-instance map. This is <b>not</b> to be confused 0N/A * If value is null this method will remove the property. 0N/A * Returns the value of the property with the specified key. Only 0N/A * properties added with {@link #putProperty} will return 0N/A * @return the value of this property or null