1 /* 2 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.jdi.request; 27 28 import com.sun.jdi.*; 29 30 import java.util.List; 31 32 /** 33 * Manages the creation and deletion of {@link EventRequest}s. A single 34 * implementor of this interface exists in a particuar VM and 35 * is accessed through {@link VirtualMachine#eventRequestManager()} 36 * 37 * @see EventRequest 38 * @see com.sun.jdi.event.Event 39 * @see BreakpointRequest 40 * @see com.sun.jdi.event.BreakpointEvent 41 * @see VirtualMachine 42 * 43 * @author Robert Field 44 * @since 1.3 45 */ 46 47 @jdk.Exported 48 public interface EventRequestManager extends Mirror { 49 50 /** 51 * Creates a new disabled {@link ClassPrepareRequest}. 52 * The new event request is added to the list managed by this 53 * EventRequestManager. Use {@link EventRequest#enable()} to 54 * activate this event request. 55 * 56 * @return the created {@link ClassPrepareRequest} 57 */ createClassPrepareRequest()58 ClassPrepareRequest createClassPrepareRequest(); 59 60 /** 61 * Creates a new disabled {@link ClassUnloadRequest}. 62 * The new event request is added to the list managed by this 63 * EventRequestManager. Use {@link EventRequest#enable()} to 64 * activate this event request. 65 * 66 * @return the created {@link ClassUnloadRequest} 67 */ createClassUnloadRequest()68 ClassUnloadRequest createClassUnloadRequest(); 69 70 /** 71 * Creates a new disabled {@link ThreadStartRequest}. 72 * The new event request is added to the list managed by this 73 * EventRequestManager. Use {@link EventRequest#enable()} to 74 * activate this event request. 75 * 76 * @return the created {@link ThreadStartRequest} 77 */ createThreadStartRequest()78 ThreadStartRequest createThreadStartRequest(); 79 80 /** 81 * Creates a new disabled {@link ThreadDeathRequest}. 82 * The new event request is added to the list managed by this 83 * EventRequestManager. Use {@link EventRequest#enable()} to 84 * activate this event request. 85 * 86 * @return the created {@link ThreadDeathRequest} 87 */ createThreadDeathRequest()88 ThreadDeathRequest createThreadDeathRequest(); 89 90 /** 91 * Creates a new disabled {@link ExceptionRequest}. 92 * The new event request is added to the list managed by this 93 * EventRequestManager. Use {@link EventRequest#enable()} to 94 * activate this event request. 95 * <P> 96 * A specific exception type and its subclasses can be selected 97 * for exception events. Caught exceptions, uncaught exceptions, 98 * or both can be selected. Note, however, that 99 * at the time an exception is thrown, it is not always 100 * possible to determine whether it is truly caught. See 101 * {@link com.sun.jdi.event.ExceptionEvent#catchLocation} for 102 * details. 103 * @param refType If non-null, specifies that exceptions which are 104 * instances of refType will be reported. Note: this 105 * will include instances of sub-types. If null, 106 * all instances will be reported 107 * @param notifyCaught If true, caught exceptions will be reported. 108 * @param notifyUncaught If true, uncaught exceptions will be reported. 109 * 110 * @return the created {@link ExceptionRequest} 111 */ createExceptionRequest(ReferenceType refType, boolean notifyCaught, boolean notifyUncaught)112 ExceptionRequest createExceptionRequest(ReferenceType refType, 113 boolean notifyCaught, 114 boolean notifyUncaught); 115 116 /** 117 * Creates a new disabled {@link MethodEntryRequest}. 118 * The new event request is added to the list managed by this 119 * EventRequestManager. Use {@link EventRequest#enable()} to 120 * activate this event request. 121 * 122 * @return the created {@link MethodEntryRequest} 123 */ createMethodEntryRequest()124 MethodEntryRequest createMethodEntryRequest(); 125 126 /** 127 * Creates a new disabled {@link MethodExitRequest}. 128 * The new event request is added to the list managed by this 129 * EventRequestManager. Use {@link EventRequest#enable()} to 130 * activate this event request. 131 * 132 * @return the created {@link MethodExitRequest} 133 */ createMethodExitRequest()134 MethodExitRequest createMethodExitRequest(); 135 136 /** 137 * Creates a new disabled {@link MonitorContendedEnterRequest}. 138 * The new event request is added to the list managed by this 139 * EventRequestManager. Use {@link EventRequest#enable()} to 140 * activate this event request. 141 * 142 * Not all target virtual machines support this operation. 143 * Use {@link VirtualMachine#canRequestMonitorEvents()} 144 * to determine if the operation is supported. 145 * 146 * @return the created {@link MonitorContendedEnterRequest} 147 * @throws java.lang.UnsupportedOperationException if 148 * the target VM does not support this 149 * operation. 150 * 151 * @since 1.6 152 */ createMonitorContendedEnterRequest()153 MonitorContendedEnterRequest createMonitorContendedEnterRequest(); 154 155 /** 156 * Creates a new disabled {@link MonitorContendedEnteredRequest}. 157 * The new event request is added to the list managed by this 158 * EventRequestManager. Use {@link EventRequest#enable()} to 159 * activate this event request. 160 * 161 * Not all target virtual machines support this operation. 162 * Use {@link VirtualMachine#canRequestMonitorEvents()} 163 * to determine if the operation is supported. 164 * 165 * @return the created {@link MonitorContendedEnteredRequest} 166 * @throws java.lang.UnsupportedOperationException if 167 * the target VM does not support this 168 * operation. 169 * 170 * @since 1.6 171 */ 172 createMonitorContendedEnteredRequest()173 MonitorContendedEnteredRequest createMonitorContendedEnteredRequest(); 174 175 /** 176 * Creates a new disabled {@link MonitorWaitRequest}. 177 * The new event request is added to the list managed by this 178 * EventRequestManager. Use {@link EventRequest#enable()} to 179 * activate this event request. 180 * 181 * Not all target virtual machines support this operation. 182 * Use {@link VirtualMachine#canRequestMonitorEvents()} 183 * to determine if the operation is supported. 184 * 185 * @return the created {@link MonitorWaitRequest} 186 * @throws java.lang.UnsupportedOperationException if 187 * the target VM does not support this 188 * operation. 189 * 190 * @since 1.6 191 */ createMonitorWaitRequest()192 MonitorWaitRequest createMonitorWaitRequest(); 193 194 /** 195 * Creates a new disabled {@link MonitorWaitedRequest}. 196 * The new event request is added to the list managed by this 197 * EventRequestManager. Use {@link EventRequest#enable()} to 198 * activate this event request. 199 * 200 * Not all target virtual machines support this operation. 201 * Use {@link VirtualMachine#canRequestMonitorEvents()} 202 * to determine if the operation is supported. 203 * 204 * @return the created {@link MonitorWaitedRequest} 205 * @throws java.lang.UnsupportedOperationException if 206 * the target VM does not support this 207 * operation. 208 * 209 * @since 1.6 210 */ createMonitorWaitedRequest()211 MonitorWaitedRequest createMonitorWaitedRequest(); 212 213 /** 214 * Creates a new disabled {@link StepRequest}. 215 * The new event request is added to the list managed by this 216 * EventRequestManager. Use {@link EventRequest#enable()} to 217 * activate this event request. 218 * <p> 219 * The returned request will control stepping only in the specified 220 * <code>thread</code>; all other threads will be unaffected. 221 * A <code>size</code>value of {@link com.sun.jdi.request.StepRequest#STEP_MIN} will generate a 222 * step event each time the code index changes. It represents the 223 * smallest step size available and often maps to the instruction 224 * level. 225 * A <code>size</code> value of {@link com.sun.jdi.request.StepRequest#STEP_LINE} will generate a 226 * step event each time the source line changes unless line number information is not available, 227 * in which case a STEP_MIN will be done instead. For example, no line number information is 228 * available during the execution of a method that has been rendered obsolete by 229 * by a {@link com.sun.jdi.VirtualMachine#redefineClasses} operation. 230 * A <code>depth</code> value of {@link com.sun.jdi.request.StepRequest#STEP_INTO} will generate 231 * step events in any called methods. A <code>depth</code> value 232 * of {@link com.sun.jdi.request.StepRequest#STEP_OVER} restricts step events to the current frame 233 * or caller frames. A <code>depth</code> value of {@link com.sun.jdi.request.StepRequest#STEP_OUT} 234 * restricts step events to caller frames only. All depth 235 * restrictions are relative to the call stack immediately before the 236 * step takes place. 237 * <p> 238 * Only one pending step request is allowed per thread. 239 * <p> 240 * Note that a typical debugger will want to cancel stepping 241 * after the first step is detected. Thus a next line method 242 * would do the following: 243 * <code> 244 * <pre> 245 * EventRequestManager mgr = myVM.{@link VirtualMachine#eventRequestManager eventRequestManager}(); 246 * StepRequest request = mgr.createStepRequest(myThread, 247 * StepRequest.{@link StepRequest#STEP_LINE STEP_LINE}, 248 * StepRequest.{@link StepRequest#STEP_OVER STEP_OVER}); 249 * request.{@link EventRequest#addCountFilter addCountFilter}(1); // next step only 250 * request.enable(); 251 * myVM.{@link VirtualMachine#resume resume}(); 252 * </pre> 253 * </code> 254 * 255 * @param thread the thread in which to step 256 * @param depth the step depth 257 * @param size the step size 258 * @return the created {@link StepRequest} 259 * @throws DuplicateRequestException if there is already a pending 260 * step request for the specified thread. 261 * @throws IllegalArgumentException if the size or depth arguments 262 * contain illegal values. 263 */ createStepRequest(ThreadReference thread, int size, int depth)264 StepRequest createStepRequest(ThreadReference thread, 265 int size, 266 int depth); 267 268 /** 269 * Creates a new disabled {@link BreakpointRequest}. 270 * The given {@link Location} must have a valid 271 * (that is, non-negative) code index. The new 272 * breakpoint is added to the list managed by this 273 * EventRequestManager. Multiple breakpoints at the 274 * same location are permitted. Use {@link EventRequest#enable()} to 275 * activate this event request. 276 * 277 * @param location the location of the new breakpoint. 278 * @return the created {@link BreakpointRequest} 279 * @throws NativeMethodException if location is within a native method. 280 */ createBreakpointRequest(Location location)281 BreakpointRequest createBreakpointRequest(Location location); 282 283 /** 284 * Creates a new disabled watchpoint which watches accesses to the 285 * specified field. The new 286 * watchpoint is added to the list managed by this 287 * EventRequestManager. Multiple watchpoints on the 288 * same field are permitted. 289 * Use {@link EventRequest#enable()} to 290 * activate this event request. 291 * <P> 292 * Not all target virtual machines support this operation. 293 * Use {@link VirtualMachine#canWatchFieldAccess()} 294 * to determine if the operation is supported. 295 * 296 * @param field the field to watch 297 * @return the created watchpoint 298 * @throws java.lang.UnsupportedOperationException if 299 * the target virtual machine does not support this 300 * operation. 301 */ createAccessWatchpointRequest(Field field)302 AccessWatchpointRequest createAccessWatchpointRequest(Field field); 303 304 /** 305 * Creates a new disabled watchpoint which watches accesses to the 306 * specified field. The new 307 * watchpoint is added to the list managed by this 308 * EventRequestManager. Multiple watchpoints on the 309 * same field are permitted. 310 * Use {@link EventRequest#enable()} to 311 * activate this event request. 312 * <P> 313 * Not all target virtual machines support this operation. 314 * Use {@link VirtualMachine#canWatchFieldModification()} 315 * to determine if the operation is supported. 316 * 317 * @param field the field to watch 318 * @return the created watchpoint 319 * @throws java.lang.UnsupportedOperationException if 320 * the target virtual machine does not support this 321 * operation. 322 */ createModificationWatchpointRequest(Field field)323 ModificationWatchpointRequest createModificationWatchpointRequest(Field field); 324 325 /** 326 * Creates a new disabled {@link VMDeathRequest}. 327 * The new request is added to the list managed by this 328 * EventRequestManager. 329 * Use {@link EventRequest#enable()} to 330 * activate this event request. 331 * <P> 332 * This request (if enabled) will cause a 333 * {@link com.sun.jdi.event.VMDeathEvent} 334 * to be sent on termination of the target VM. 335 * <P> 336 * A VMDeathRequest with a suspend policy of 337 * {@link EventRequest#SUSPEND_ALL SUSPEND_ALL} 338 * can be used to assure processing of incoming 339 * {@link EventRequest#SUSPEND_NONE SUSPEND_NONE} or 340 * {@link EventRequest#SUSPEND_EVENT_THREAD SUSPEND_EVENT_THREAD} 341 * events before VM death. If all event processing is being 342 * done in the same thread as event sets are being read, 343 * enabling the request is all that is needed since the VM 344 * will be suspended until the {@link com.sun.jdi.event.EventSet} 345 * containing the {@link com.sun.jdi.event.VMDeathEvent} 346 * is resumed. 347 * <P> 348 * Not all target virtual machines support this operation. 349 * Use {@link VirtualMachine#canRequestVMDeathEvent()} 350 * to determine if the operation is supported. 351 * 352 * @return the created request 353 * @throws java.lang.UnsupportedOperationException if 354 * the target VM does not support this 355 * operation. 356 * 357 * @since 1.4 358 */ createVMDeathRequest()359 VMDeathRequest createVMDeathRequest(); 360 361 /** 362 * Removes an eventRequest. The eventRequest is disabled and 363 * the removed from the requests managed by this 364 * EventRequestManager. Once the eventRequest is deleted, no 365 * operations (for example, {@link EventRequest#setEnabled}) 366 * are permitted - attempts to do so will generally cause an 367 * {@link InvalidRequestStateException}. 368 * No other eventRequests are effected. 369 * <P> 370 * Because this method changes the underlying lists of event 371 * requests, attempting to directly delete from a list returned 372 * by a request accessor (e.g. below): 373 * <PRE> 374 * Iterator iter = requestManager.stepRequests().iterator(); 375 * while (iter.hasNext()) { 376 * requestManager.deleteEventRequest(iter.next()); 377 * } 378 * </PRE> 379 * may cause a {@link java.util.ConcurrentModificationException}. 380 * Instead use 381 * {@link #deleteEventRequests(List) deleteEventRequests(List)} 382 * or copy the list before iterating. 383 * 384 * @param eventRequest the eventRequest to remove 385 */ deleteEventRequest(EventRequest eventRequest)386 void deleteEventRequest(EventRequest eventRequest); 387 388 /** 389 * Removes a list of {@link EventRequest}s. 390 * 391 * @see #deleteEventRequest(EventRequest) 392 * 393 * @param eventRequests the list of eventRequests to remove 394 */ deleteEventRequests(List<? extends EventRequest> eventRequests)395 void deleteEventRequests(List<? extends EventRequest> eventRequests); 396 397 /** 398 * Remove all breakpoints managed by this EventRequestManager. 399 * 400 * @see #deleteEventRequest(EventRequest) 401 */ deleteAllBreakpoints()402 void deleteAllBreakpoints(); 403 404 /** 405 * Return an unmodifiable list of the enabled and disabled step requests. 406 * This list is a live view of these requests and thus changes as requests 407 * are added and deleted. 408 * @return the all {@link StepRequest} objects. 409 */ stepRequests()410 List<StepRequest> stepRequests(); 411 412 /** 413 * Return an unmodifiable list of the enabled and disabled class prepare requests. 414 * This list is a live view of these requests and thus changes as requests 415 * are added and deleted. 416 * @return the all {@link ClassPrepareRequest} objects. 417 */ classPrepareRequests()418 List<ClassPrepareRequest> classPrepareRequests(); 419 420 /** 421 * Return an unmodifiable list of the enabled and disabled class unload requests. 422 * This list is a live view of these requests and thus changes as requests 423 * are added and deleted. 424 * @return the all {@link ClassUnloadRequest} objects. 425 */ classUnloadRequests()426 List<ClassUnloadRequest> classUnloadRequests(); 427 428 /** 429 * Return an unmodifiable list of the enabled and disabled thread start requests. 430 * This list is a live view of these requests and thus changes as requests 431 * are added and deleted. 432 * @return the all {@link ThreadStartRequest} objects. 433 */ threadStartRequests()434 List<ThreadStartRequest> threadStartRequests(); 435 436 /** 437 * Return an unmodifiable list of the enabled and disabled thread death requests. 438 * This list is a live view of these requests and thus changes as requests 439 * are added and deleted. 440 * @return the all {@link ThreadDeathRequest} objects. 441 */ threadDeathRequests()442 List<ThreadDeathRequest> threadDeathRequests(); 443 444 /** 445 * Return an unmodifiable list of the enabled and disabled exception requests. 446 * This list is a live view of these requests and thus changes as requests 447 * are added and deleted. 448 * @return the all {@link ExceptionRequest} objects. 449 */ exceptionRequests()450 List<ExceptionRequest> exceptionRequests(); 451 452 /** 453 * Return an unmodifiable list of the enabled and disabled breakpoint requests. 454 * This list is a live view of these requests and thus changes as requests 455 * are added and deleted. 456 * @return the list of all {@link BreakpointRequest} objects. 457 */ breakpointRequests()458 List<BreakpointRequest> breakpointRequests(); 459 460 /** 461 * Return an unmodifiable list of the enabled and disabled access 462 * watchpoint requests. 463 * This list is a live view of these requests and thus changes as requests 464 * are added and deleted. 465 * @return the all {@link AccessWatchpointRequest} objects. 466 */ accessWatchpointRequests()467 List<AccessWatchpointRequest> accessWatchpointRequests(); 468 469 /** 470 * Return an unmodifiable list of the enabled and disabled modification 471 * watchpoint requests. 472 * This list is a live view of these requests and thus changes as requests 473 * are added and deleted. 474 * @return the all {@link ModificationWatchpointRequest} objects. 475 */ modificationWatchpointRequests()476 List<ModificationWatchpointRequest> modificationWatchpointRequests(); 477 478 /** 479 * Return an unmodifiable list of the enabled and disabled method entry requests. 480 * This list is a live view of these requests and thus changes as requests 481 * are added and deleted. 482 * @return the list of all {@link MethodEntryRequest} objects. 483 */ methodEntryRequests()484 List<MethodEntryRequest> methodEntryRequests(); 485 486 /** 487 * Return an unmodifiable list of the enabled and disabled method exit requests. 488 * This list is a live view of these requests and thus changes as requests 489 * are added and deleted. 490 * @return the list of all {@link MethodExitRequest} objects. 491 */ methodExitRequests()492 List<MethodExitRequest> methodExitRequests(); 493 494 /** 495 * Return an unmodifiable list of the enabled and disabled monitor contended enter requests. 496 * This list is a live view of these requests and thus changes as requests 497 * are added and deleted. 498 * @return the list of all {@link MonitorContendedEnterRequest} objects. 499 * 500 * @since 1.6 501 */ monitorContendedEnterRequests()502 List<MonitorContendedEnterRequest> monitorContendedEnterRequests(); 503 504 /** 505 * Return an unmodifiable list of the enabled and disabled monitor contended entered requests. 506 * This list is a live view of these requests and thus changes as requests 507 * are added and deleted. 508 * @return the list of all {@link MonitorContendedEnteredRequest} objects. 509 * 510 * @since 1.6 511 */ monitorContendedEnteredRequests()512 List<MonitorContendedEnteredRequest> monitorContendedEnteredRequests(); 513 514 /** 515 * Return an unmodifiable list of the enabled and disabled monitor wait requests. 516 * This list is a live view of these requests and thus changes as requests 517 * are added and deleted. 518 * @return the list of all {@link MonitorWaitRequest} objects. 519 * 520 * @since 1.6 521 */ monitorWaitRequests()522 List<MonitorWaitRequest> monitorWaitRequests(); 523 524 /** 525 * Return an unmodifiable list of the enabled and disabled monitor waited requests. 526 * This list is a live view of these requests and thus changes as requests 527 * are added and deleted. 528 * @return the list of all {@link MonitorWaitedRequest} objects. 529 * 530 * @since 1.6 531 */ monitorWaitedRequests()532 List<MonitorWaitedRequest> monitorWaitedRequests(); 533 534 /** 535 * Return an unmodifiable list of the enabled and disabled VM death requests. 536 * This list is a live view of these requests and thus changes as requests 537 * are added and deleted. 538 * Note: the unsolicited VMDeathEvent does not have a 539 * corresponding request. 540 * @return the list of all {@link VMDeathRequest} objects. 541 * 542 * @since 1.4 543 */ vmDeathRequests()544 List<VMDeathRequest> vmDeathRequests(); 545 } 546