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