blob: 77c0e02c97a879d86fed2e360996c7c96b088f77 [file] [log] [blame]
J. Duke319a3b92007-12-01 00:00:00 +00001/*
2 * Copyright 1998-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26package com.sun.jdi;
27
28/**
29 * The mirror for a value in the target VM.
30 * This interface is the root of a
31 * value hierarchy encompassing primitive values and object values.
32 * <P>
33 * Some examples of where values may be accessed:
34 * <BLOCKQUOTE><TABLE SUMMARY="layout">
35 * <TR>
36 * <TD>{@link ObjectReference#getValue(com.sun.jdi.Field)
37 * ObjectReference.getValue(Field)}
38 * <TD>- value of a field
39 * <TR>
40 * <TD>{@link StackFrame#getValue(com.sun.jdi.LocalVariable)
41 * StackFrame.getValue(LocalVariable)}
42 * <TD>- value of a variable
43 * <TR>
44 * <TD>{@link VirtualMachine#mirrorOf(double)
45 * VirtualMachine.mirrorOf(double)}
46 * <TD>- created in the target VM by the JDI client
47 * <TR>
48 * <TD>{@link com.sun.jdi.event.ModificationWatchpointEvent#valueToBe()
49 * ModificationWatchpointEvent.valueToBe()}
50 * <TD>- returned with an event
51 * </TABLE></BLOCKQUOTE>
52 * <P>
53 * The following table illustrates which subinterfaces of Value
54 * are used to mirror values in the target VM --
55 * <TABLE BORDER=1 SUMMARY="Maps each kind of value to a mirrored
56 * instance of a subinterface of Value">
57 * <TR BGCOLOR="#EEEEFF">
58 * <TH id="primval" colspan=4>Subinterfaces of {@link PrimitiveValue}</TH>
59 * <TR BGCOLOR="#EEEEFF">
60 * <TH id="kind" align="left">Kind of value</TH>
61 * <TH id="example" align="left">For example -<br>expression in target</TH>
62 * <TH id="mirrored" align="left">Is mirrored as an<br>instance of</TH>
63 * <TH id="type" align="left">{@link Type} of value<br>{@link #type() Value.type()}</TH>
64 * <TR>
65 * <TD headers="primval kind"> a boolean</TD>
66 * <TD headers="primval example"> <CODE>true</CODE></TD>
67 * <TD headers="primval mirrored"> {@link BooleanValue}</TD>
68 * <TD headers="primval type"> {@link BooleanType}</TD>
69 * <TR>
70 * <TD headers="primval kind"> a byte</TD>
71 * <TD headers="primval example"> <CODE>(byte)4</CODE></TD>
72 * <TD headers="primval mirrored"> {@link ByteValue}</TD>
73 * <TD headers="primval type"> {@link ByteType}</TD>
74 * <TR>
75 * <TD headers="primval kind"> a char</TD>
76 * <TD headers="primval example"> <CODE>'a'</CODE></TD>
77 * <TD headers="primval mirrored"> {@link CharValue}</TD>
78 * <TD headers="primval type"> {@link CharType}</TD>
79 * <TR>
80 * <TD headers="primval kind"> a double</TD>
81 * <TD headers="primval example"> <CODE>3.1415926</CODE></TD>
82 * <TD headers="primval mirrored"> {@link DoubleValue}</TD>
83 * <TD headers="primval type"> {@link DoubleType}</TD>
84 * <TR>
85 * <TD headers="primval kind"> a float</TD>
86 * <TD headers="primval example"> <CODE>2.5f</CODE></TD>
87 * <TD headers="primval mirrored"> {@link FloatValue}</TD>
88 * <TD headers="primval type"> {@link FloatType}</TD>
89 * <TR>
90 * <TD headers="primval kind"> an int</TD>
91 * <TD headers="primval example"> <CODE>22</CODE></TD>
92 * <TD headers="primval mirrored"> {@link IntegerValue}</TD>
93 * <TD headers="primval type"> {@link IntegerType}</TD>
94 * <TR>
95 * <TD headers="primval kind"> a long</TD>
96 * <TD headers="primval example"> <CODE>1024L</CODE></TD>
97 * <TD headers="primval mirrored"> {@link LongValue}</TD>
98 * <TD headers="primval type"> {@link LongType}</TD>
99 * <TR>
100 * <TD headers="primval kind"> a short</TD>
101 * <TD headers="primval example"> <CODE>(short)12</CODE></TD>
102 * <TD headers="primval mirrored"> {@link ShortValue}</TD>
103 * <TD headers="primval type"> {@link ShortType}</TD>
104 * <TR>
105 * <TD headers="primval kind"> a void</TD>
106 * <TD headers="primval example"> <CODE>&nbsp;</CODE></TD>
107 * <TD headers="primval mirrored"> {@link VoidValue}</TD>
108 * <TD headers="primval type"> {@link VoidType}</TD>
109 * <TR BGCOLOR="#EEEEFF">
110 * <TH id="objref" colspan=4>Subinterfaces of {@link ObjectReference}</TH>
111 * <TR BGCOLOR="#EEEEFF">
112 * <TH id="kind2" align="left">Kind of value</TH>
113 * <TH id="example2" align="left">For example -<br>expression in target</TH>
114 * <TH id="mirrored2" align="left">Is mirrored as an<br>instance of</TH>
115 * <TH id="type2" align="left">{@link Type} of value<br>{@link #type() Value.type()}</TH>
116 * <TR>
117 * <TD headers="objref kind2"> a class instance</TD>
118 * <TD headers="objref example2"> <CODE>this</CODE></TD>
119 * <TD headers="objref mirrored2"> {@link ObjectReference}</TD>
120 * <TD headers="objref type2"> {@link ClassType}</TD>
121 * <TR>
122 * <TD headers="objref kind2"> an array</TD>
123 * <TD headers="objref example2"> <CODE>new int[5]</CODE></TD>
124 * <TD headers="objref mirrored2"> {@link ArrayReference}</TD>
125 * <TD headers="objref type2"> {@link ArrayType}</TD>
126 * <TR>
127 * <TD headers="objref kind2"> a string</TD>
128 * <TD headers="objref example2"> <CODE>"hello"</CODE></TD>
129 * <TD headers="objref mirrored2"> {@link StringReference}</TD>
130 * <TD headers="objref type2"> {@link ClassType}</TD>
131 * <TR>
132 * <TD headers="objref kind2"> a thread</TD>
133 * <TD headers="objref example2"> <CODE>Thread.currentThread()</CODE></TD>
134 * <TD headers="objref mirrored2"> {@link ThreadReference}</TD>
135 * <TD headers="objref type2"> {@link ClassType}</TD>
136 * <TR>
137 * <TD headers="objref kind2"> a thread group</TD>
138 * <TD headers="objref example2"> <CODE>Thread.currentThread()<br>&nbsp;&nbsp;.getThreadGroup()</CODE></TD>
139 * <TD headers="objref mirrored2"> {@link ThreadGroupReference}</TD>
140 * <TD headers="objref type2"> {@link ClassType}</TD>
141 * <TR>
142 * <TD headers="objref kind2"> a <CODE>java.lang.Class</CODE><br>instance</TD>
143 * <TD headers="objref example2"> <CODE>this.getClass()</CODE></TD>
144 * <TD headers="objref mirrored2"> {@link ClassObjectReference}</TD>
145 * <TD headers="objref type2"> {@link ClassType}</TD>
146 * <TR>
147 * <TD headers="objref kind2"> a class loader</TD>
148 * <TD headers="objref example2"> <CODE>this.getClass()<br>&nbsp;&nbsp;.getClassLoader() </CODE></TD>
149 * <TD headers="objref mirrored2"> {@link ClassLoaderReference}</TD>
150 * <TD headers="objref type2"> {@link ClassType}</TD>
151 * <TR BGCOLOR="#EEEEFF">
152 * <TH id="other" colspan=4>Other</TH>
153 * <TR BGCOLOR="#EEEEFF">
154 * <TH id="kind3" align="left">Kind of value</TD>
155 * <TH id="example3" align="left">For example -<br>expression in target</TD>
156 * <TH id="mirrored3" align="left">Is mirrored as</TD>
157 * <TH id="type3" align="left">{@link Type} of value</TD>
158 * <TR>
159 * <TD headers="other kind3"> null</TD>
160 * <TD headers="other example3"> <CODE>null</CODE></TD>
161 * <TD headers="other mirrored3"> <CODE>null</CODE></TD>
162 * <TD headers="other type3"> n/a</TD>
163 * </TABLE>
164 *
165 * @author Robert Field
166 * @author Gordon Hirsch
167 * @author James McIlree
168 * @since 1.3
169 */
170
171public interface Value extends Mirror
172{
173 /**
174 * Returns the run-time type of this value.
175 *
176 * @see Type
177 * @return a {@link Type} which mirrors the value's type in the
178 * target VM.
179 */
180 Type type();
181}