1/*
2 * Copyright (c) 2000, 2011, 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.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 *
23 */
24
25package sun.jvm.hotspot.types;
26
27import sun.jvm.hotspot.debugger.*;
28
29/** <P> This is the basic interface which describes a field in a C/C++
30    data structure or a Java object. </P>
31
32    <P> The accessors in this class are designed to allow manual
33    coercion of the data within the field, which is often necessary
34    when interfacing with C programs. Therefore, the accessors here do
35    not perform any type checking. Specializations of the Field
36    interface, such as JByteField, provide getValue() methods which
37    both perform type checking and return the appropriate specialized
38    type. </P>
39
40    <P> See @see CIntegerType for a description of why all C integer
41    types are bundled into the category "CIntegerType". </P>
42
43    <P> As an example, coercing a pointer field into an int can be
44    done in the following fashion (assuming the application has
45    registered an integer type in the type database called
46    "intptr_t"): </P>
47
48    <PRE>
49    {
50      ...
51      Address myObject = ...;
52      CIntegerType intptr_tType = (CIntegerType) db.lookupType("intptr_t");
53      long addrVal = field.getCInteger(myObject, intptr_tType);
54      ...
55    }
56    </PRE>
57
58    FIXME: among other things, this interface is not sufficient to
59    describe fields which are themselves arrays (like Symbol's
60    jbyte _body[1]).  */
61public interface Field {
62  /** Get the name of this field */
63  public String getName();
64
65  /** Get the type of this field */
66  public Type getType();
67
68  /** Get the size, in bytes, of this field. Used for manual data
69      structure traversal where necessary. */
70  public long getSize();
71
72  /** Is this a static field? */
73  public boolean isStatic();
74
75  /** The offset of this field, in bytes, in its containing data
76      structure, if nonstatic. If this is a static field, throws a
77      WrongTypeException. */
78  public long getOffset() throws WrongTypeException;
79
80  /** The address of this field, if it is a static field. If this is a
81      nonstatic field, throws a WrongTypeException. */
82  public Address getStaticFieldAddress() throws WrongTypeException;
83
84  /** <P> These accessors require that the field be nonstatic;
85      otherwise, a WrongTypeException will be thrown. Note that type
86      checking is not performed by these accessors in order to allow
87      manual type coercion of field data. For better protection when
88      accessing primitive fields, use the get(Type)Field accessors in
89      Type.java. </P>
90
91      <P> NOTE that the Address passed in to these routines may, in
92      fact, be an OopHandle. Specifically, in a reflective system,
93      dereferencing operations applied to the OopHandle must be
94      performed atomically with respect to GC. </P>
95
96      <P> See @see CIntegerType for a description of why all C integer
97      types are bundled into the category "CIntegerType". </P>
98  */
99  public boolean   getJBoolean (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
100  public byte      getJByte    (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
101  public char      getJChar    (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
102  public short     getJShort   (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
103  public int       getJInt     (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
104  public long      getJLong    (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
105  public float     getJFloat   (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
106  public double    getJDouble  (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
107  public long      getCInteger (Address addr, CIntegerType type)
108    throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
109  public Address   getAddress  (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
110  public OopHandle getOopHandle(Address addr)
111    throws UnmappedAddressException, UnalignedAddressException, WrongTypeException, NotInHeapException;
112  public OopHandle getNarrowOopHandle(Address addr)
113    throws UnmappedAddressException, UnalignedAddressException, WrongTypeException, NotInHeapException;
114
115  /** <P> These accessors require that the field be static; otherwise,
116      a WrongTypeException will be thrown. Note that type checking is
117      not performed by these accessors in order to allow manual type
118      coercion of field data. For better protection when accessing
119      primitive fields, use the get(Type)Field accessors in
120      Type.java. </P>
121
122      <P> NOTE that the Address passed in to these routines may, in
123      fact, be an OopHandle. Specifically, in a reflective system,
124      dereferencing operations applied to the OopHandle must be
125      performed atomically with respect to GC. </P>
126
127      <P> See @see CIntegerType for a description of why all C integer
128      types are bundled into the category "CIntegerType". </P>
129  */
130  public boolean   getJBoolean () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
131  public byte      getJByte    () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
132  public char      getJChar    () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
133  public float     getJFloat   () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
134  public double    getJDouble  () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
135  public int       getJInt     () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
136  public long      getJLong    () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
137  public short     getJShort   () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
138  public long      getCInteger (CIntegerType type)
139    throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
140  public Address   getAddress  () throws UnmappedAddressException, UnalignedAddressException;
141  public OopHandle getOopHandle()
142    throws UnmappedAddressException, UnalignedAddressException, NotInHeapException;
143  public OopHandle getNarrowOopHandle()
144    throws UnmappedAddressException, UnalignedAddressException, NotInHeapException;
145}
146