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