1 /*
2 * Copyright (c) 1998, 2024, 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
35 * An object that currently exists in the target VM. An ObjectReference
36 * mirrors only the object itself and is not specific to any
37 * {@link Field} or {@link LocalVariable} to which it is currently
38 * assigned. An ObjectReference can have 0 or more references from
39 * field(s) and/or variable(s).
40 * <p>
41 * Any method on <code>ObjectReference</code> which directly or indirectly
42 * takes <code>ObjectReference</code> as a parameter may throw
43 * {@link VMDisconnectedException} if the target VM is disconnected and the
44 * {@link VMDisconnectEvent} has been or is available to be read from the
45 * {@link EventQueue}.
46 * <p>
47 * Any method on <code>ObjectReference</code> which directly or indirectly
48 * takes <code>ObjectReference</code> as a parameter may throw
49 * {@link VMOutOfMemoryException} if the target VM has run out of memory.
50 * <p>
51 * Any method on <code>ObjectReference</code> or which directly or indirectly
52 * takes <code>ObjectReference</code> as parameter may throw
53 * {@link ObjectCollectedException} if the mirrored object has been
54 * garbage collected.
55 *
56 * @author Robert Field
57 * @author Gordon Hirsch
58 * @author James McIlree
59 * @since 1.3
60 */
61 public interface ObjectReference extends Value {
62
63 /**
64 * Gets the {@link ReferenceType} that mirrors the type
65 * of this object. The type may be a subclass or implementor of the
66 * declared type of any field or variable which currently holds it.
67 * For example, right after the following statement.
68 * <p>
69 * <code>Object obj = new String("Hello, world!");</code>
70 * <p>
71 * The ReferenceType of obj will mirror java.lang.String and not
72 * java.lang.Object.
73 * <p>
74 * The type of an object never changes, so this method will
75 * always return the same ReferenceType over the lifetime of the
76 * mirrored object.
77 * <p>
78 * The returned ReferenceType will be a {@link ClassType} or
79 * {@link ArrayType} and never an {@link InterfaceType}.
80 *
81 * @return the {@link ReferenceType} for this object.
82 */
83 ReferenceType referenceType();
84
85 /**
86 * Gets the value of a given instance or static field in this object.
87 * The Field must be valid for this ObjectReference;
88 * that is, it must be from
89 * the mirrored object's class or a superclass of that class.
90 *
91 * @param sig the field containing the requested value
92 * @return the {@link Value} of the instance field.
93 * @throws java.lang.IllegalArgumentException if the field is not valid for
94 * this object's class.
95 */
96 Value getValue(Field sig);
97
98 /**
99 * Gets the value of multiple instance and/or static fields in this object.
100 * The Fields must be valid for this ObjectReference;
101 * that is, they must be from
102 * the mirrored object's class or a superclass of that class.
103 *
104 * @param fields a list of {@link Field} objects containing the
105 * requested values.
106 * @return a Map of the requested {@link Field} objects with
107 * their {@link Value}.
108 * @throws java.lang.IllegalArgumentException if any field is not valid for
109 * this object's class.
110 */
111 Map<Field,Value> getValues(List<? extends Field> fields);
112
113 /**
114 * Sets the value of a given instance or static field in this object.
115 * The {@link Field} must be valid for this ObjectReference; that is,
116 * it must be from the mirrored object's class or a superclass of that class.
117 * The field must not be final.
118 * <p>
119 * Object values must be assignment compatible with the field type
120 * (This implies that the field type must be loaded through the
121 * enclosing class's class loader). Primitive values must be
122 * either assignment compatible with the field type or must be
|
1 /*
2 * Copyright (c) 1998, 2026, 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
35 * An object that currently exists in the target VM. An ObjectReference
36 * mirrors only the object itself and is not specific to any
37 * {@link Field} or {@link LocalVariable} to which it is currently
38 * assigned. An ObjectReference can have 0 or more references from
39 * field(s) and/or variable(s).
40 * <p>
41 * Any method on <code>ObjectReference</code> which directly or indirectly
42 * takes <code>ObjectReference</code> as a parameter may throw
43 * {@link VMDisconnectedException} if the target VM is disconnected and the
44 * {@link VMDisconnectEvent} has been or is available to be read from the
45 * {@link EventQueue}.
46 * <p>
47 * Any method on <code>ObjectReference</code> which directly or indirectly
48 * takes <code>ObjectReference</code> as a parameter may throw
49 * {@link VMOutOfMemoryException} if the target VM has run out of memory.
50 * <p>
51 * Any method on <code>ObjectReference</code> or which directly or indirectly
52 * takes <code>ObjectReference</code> as parameter may throw
53 * {@link ObjectCollectedException} if the mirrored object has been
54 * garbage collected.
55 * <div class="preview-block">
56 * <div class="preview-comment">
57 * <h2><a id=valueObjects>Value Objects</a></h2>
58 * If preview features are enabled, JDI supports value objects and classes.
59 * However, the support does in some cases deviate from identity object
60 * support in behavior or expectations as noted below:
61 * <p>
62 * If an ObjectReference is obtained for a value object under construction,
63 * it will be for a <em>snapshot</em> of the value object at that point in time.
64 * Any further changes to the initialization state of the value object will not
65 * be reflected in this ObjectReference. A new ObjectReference would need to
66 * be obtained to see the updated state. See {@link StackFrame#thisObject}.
67 * </div>
68 * </div>
69 * @author Robert Field
70 * @author Gordon Hirsch
71 * @author James McIlree
72 * @since 1.3
73 */
74 public interface ObjectReference extends Value {
75
76 /**
77 * Gets the {@link ReferenceType} that mirrors the type
78 * of this object. The type may be a subclass or implementor of the
79 * declared type of any field or variable which currently holds it.
80 * For example, right after the following statement.
81 * <p>
82 * <code>Object obj = new String("Hello, world!");</code>
83 * <p>
84 * The ReferenceType of obj will mirror java.lang.String and not
85 * java.lang.Object.
86 * <p>
87 * The type of an object never changes, so this method will
88 * always return the same ReferenceType over the lifetime of the
89 * mirrored object.
90 * <p>
91 * The returned ReferenceType will be a {@link ClassType} or
92 * {@link ArrayType} and never an {@link InterfaceType}.
93 *
94 * @return the {@link ReferenceType} for this object.
95 */
96 ReferenceType referenceType();
97
98 /**
99 * Gets the value of a given instance or static field in this object.
100 * The Field must be valid for this ObjectReference;
101 * that is, it must be from
102 * the mirrored object's class or a superclass of that class.
103 * <div class="preview-block">
104 * <div class="preview-comment">
105 * If preview features are enabled, this method does not prevent a
106 * strictly-initialized field from being read before it has been initialized.
107 * </div>
108 * </div>
109 *
110 * @param sig the field containing the requested value
111 * @return the {@link Value} of the instance field.
112 * @throws java.lang.IllegalArgumentException if the field is not valid for
113 * this object's class.
114 */
115 Value getValue(Field sig);
116
117 /**
118 * Gets the value of multiple instance and/or static fields in this object.
119 * The Fields must be valid for this ObjectReference;
120 * that is, they must be from
121 * the mirrored object's class or a superclass of that class.
122 * <div class="preview-block">
123 * <div class="preview-comment">
124 * If preview features are enabled, this method does not prevent a
125 * strictly-initialized field from being read before it has been initialized.
126 * </div>
127 * </div>
128 *
129 * @param fields a list of {@link Field} objects containing the
130 * requested values.
131 * @return a Map of the requested {@link Field} objects with
132 * their {@link Value}.
133 * @throws java.lang.IllegalArgumentException if any field is not valid for
134 * this object's class.
135 */
136 Map<Field,Value> getValues(List<? extends Field> fields);
137
138 /**
139 * Sets the value of a given instance or static field in this object.
140 * The {@link Field} must be valid for this ObjectReference; that is,
141 * it must be from the mirrored object's class or a superclass of that class.
142 * The field must not be final.
143 * <p>
144 * Object values must be assignment compatible with the field type
145 * (This implies that the field type must be loaded through the
146 * enclosing class's class loader). Primitive values must be
147 * either assignment compatible with the field type or must be
|