1 /*
   2  * Copyright (c) 1998, 2006, 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;
  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 
 171 @jdk.Supported
 172 public interface Value extends Mirror {
 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 }