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 /** 31 * Request for notification when an exception occurs in the target VM. 32 * When an enabled ExceptionRequest is satisfied, an 33 * {@link com.sun.jdi.event.EventSet event set} containing an 34 * {@link com.sun.jdi.event.ExceptionEvent ExceptionEvent} will be placed 35 * on the {@link com.sun.jdi.event.EventQueue EventQueue}. 36 * The collection of existing ExceptionRequests is 37 * managed by the {@link EventRequestManager} 38 * 39 * @see com.sun.jdi.event.ExceptionEvent 40 * @see com.sun.jdi.event.EventQueue 41 * @see EventRequestManager 42 * 43 * @author Robert Field 44 * @since 1.3 45 */ 46 @jdk.Exported 47 public interface ExceptionRequest extends EventRequest { 48 49 /** 50 * Returns exception type for which exception events are requested. 51 * @return 52 * The exception (and its subclasses) requested 53 * with {@link EventRequestManager#createExceptionRequest}, or 54 * null if, as by default, all exceptions are requested. 55 */ exception()56 ReferenceType exception(); 57 58 /** 59 * Returns whether caught exceptions of the requested type 60 * will generate events when they are thrown. 61 * <p> 62 * Note that at the time an exception is thrown, it is not always 63 * possible to determine whether it is truly caught. See 64 * {@link com.sun.jdi.event.ExceptionEvent#catchLocation} for 65 * details. 66 * @return 67 * boolean true if caught exceptions will be reported, false 68 * otherwise. 69 */ notifyCaught()70 boolean notifyCaught(); 71 72 /** 73 * Returns whether uncaught exceptions of the requested type 74 * will generate events when they are thrown. 75 * <p> 76 * Note that at the time an exception is thrown, it is not always 77 * possible to determine whether it is truly uncaught. See 78 * {@link com.sun.jdi.event.ExceptionEvent#catchLocation} for 79 * details. 80 * @return 81 * boolean true if caught exceptions will be reported, false 82 * otherwise. 83 */ notifyUncaught()84 boolean notifyUncaught(); 85 86 /** 87 * Restricts the events generated by this request to those in 88 * the given thread. 89 * @param thread the thread to filter on. 90 * @throws InvalidRequestStateException if this request is currently 91 * enabled or has been deleted. 92 * Filters may be added only to disabled requests. 93 */ addThreadFilter(ThreadReference thread)94 void addThreadFilter(ThreadReference thread); 95 96 /** 97 * Restricts the events generated by this request to those whose 98 * location is in the given reference type or any of its subtypes. 99 * An event will be generated for any location in a reference type 100 * that can be safely cast to the given reference type. 101 * 102 * @param refType the reference type to filter on. 103 * @throws InvalidRequestStateException if this request is currently 104 * enabled or has been deleted. 105 * Filters may be added only to disabled requests. 106 */ addClassFilter(ReferenceType refType)107 void addClassFilter(ReferenceType refType); 108 109 /** 110 * Restricts the events generated by this request to those 111 * whose location is in a class whose name matches a restricted 112 * regular expression. Regular expressions are limited 113 * to exact matches and patterns that begin with '*' or end with '*'; 114 * for example, "*.Foo" or "java.*". 115 * 116 * @param classPattern the pattern String to filter for. 117 * @throws InvalidRequestStateException if this request is currently 118 * enabled or has been deleted. 119 * Filters may be added only to disabled requests. 120 */ addClassFilter(String classPattern)121 void addClassFilter(String classPattern); 122 123 /** 124 * Restricts the events generated by this request to those 125 * whose location is in a class whose name does <b>not</b> match a 126 * restricted regular expression. Regular expressions are limited 127 * to exact matches and patterns that begin with '*' or end with '*'; 128 * for example, "*.Foo" or "java.*". 129 * 130 * @param classPattern the pattern String to filter against. 131 * @throws InvalidRequestStateException if this request is currently 132 * enabled or has been deleted. 133 * Filters may be added only to disabled requests. 134 */ addClassExclusionFilter(String classPattern)135 void addClassExclusionFilter(String classPattern); 136 137 /** 138 * Restricts the events generated by this request to those in 139 * which the currently executing instance ("this") is the object 140 * specified. 141 * <P> 142 * Not all targets support this operation. 143 * Use {@link VirtualMachine#canUseInstanceFilters()} 144 * to determine if the operation is supported. 145 * @since 1.4 146 * @param instance the object which must be the current instance 147 * in order to pass this filter. 148 * @throws java.lang.UnsupportedOperationException if 149 * the target virtual machine does not support this 150 * operation. 151 * @throws InvalidRequestStateException if this request is currently 152 * enabled or has been deleted. 153 * Filters may be added only to disabled requests. 154 */ addInstanceFilter(ObjectReference instance)155 void addInstanceFilter(ObjectReference instance); 156 } 157