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 com.sun.jdi.ObjectReference; 29import com.sun.jdi.ReferenceType; 30import com.sun.jdi.ThreadReference; 31import com.sun.jdi.VirtualMachine; 32import com.sun.jdi.event.EventQueue; 33import com.sun.jdi.event.EventSet; 34import com.sun.jdi.event.MethodExitEvent; 35 36/** 37 * Request for notification when a method returns in the target VM. 38 * When an enabled MethodExitRequest is hit, an 39 * {@link EventSet event set} containing a 40 * {@link MethodExitEvent MethodExitEvent} 41 * will be placed on the {@link EventQueue EventQueue}. 42 * The collection of existing MethodExitRequests is 43 * managed by the {@link EventRequestManager} 44 * 45 * @see MethodExitEvent 46 * @see EventQueue 47 * @see EventRequestManager 48 * 49 * @author Robert Field 50 * @since 1.3 51 */ 52public interface MethodExitRequest extends EventRequest { 53 54 /** 55 * Restricts the events generated by this request to those in 56 * the given thread. 57 * @param thread the thread to filter on. 58 * @throws InvalidRequestStateException if this request is currently 59 * enabled or has been deleted. 60 * Filters may be added only to disabled requests. 61 */ 62 void addThreadFilter(ThreadReference thread); 63 64 /** 65 * Restricts the events generated by this request to those whose 66 * method is in the given reference type or any of its subtypes. 67 * An event will be generated for any location in a reference type 68 * that can be safely cast to the given reference type. 69 * 70 * @param refType the reference type to filter on. 71 * @throws InvalidRequestStateException if this request is currently 72 * enabled or has been deleted. 73 * Filters may be added only to disabled requests. 74 */ 75 void addClassFilter(ReferenceType refType); 76 77 /** 78 * Restricts the events generated by this request to those 79 * whose method is in a class whose name matches a restricted 80 * regular expression. Regular expressions are limited 81 * to exact matches and patterns that begin with '*' or end with '*'; 82 * for example, "*.Foo" or "java.*". 83 * 84 * @param classPattern the pattern String to filter for. 85 * @throws InvalidRequestStateException if this request is currently 86 * enabled or has been deleted. 87 * Filters may be added only to disabled requests. 88 */ 89 void addClassFilter(String classPattern); 90 91 /** 92 * Restricts the events generated by this request to those 93 * whose method is in a class whose name does <b>not</b> match this 94 * restricted regular expression. Regular expressions are limited 95 * to exact matches and patterns that begin with '*' or end with '*'; 96 * for example, "*.Foo" or "java.*". 97 * 98 * @param classPattern the pattern String to filter against. 99 * @throws InvalidRequestStateException if this request is currently 100 * enabled or has been deleted. 101 * Filters may be added only to disabled requests. 102 */ 103 void addClassExclusionFilter(String classPattern); 104 105 /** 106 * Restricts the events generated by this request to those in 107 * which the currently executing instance ("this") is the object 108 * specified. 109 * <P> 110 * Not all targets support this operation. 111 * Use {@link VirtualMachine#canUseInstanceFilters()} 112 * to determine if the operation is supported. 113 * @since 1.4 114 * @param instance the object which must be the current instance 115 * in order to pass this filter. 116 * @throws java.lang.UnsupportedOperationException if 117 * the target virtual machine does not support this 118 * operation. 119 * @throws InvalidRequestStateException if this request is currently 120 * enabled or has been deleted. 121 * Filters may be added only to disabled requests. 122 */ 123 void addInstanceFilter(ObjectReference instance); 124} 125