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