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