View Javadoc
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  
25  package sun.jvm.hotspot.types;
26  
27  import 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]).  */
61  public 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 }