1 /*
   2  * Copyright 2000-2008 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.
   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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  20  * CA 95054 USA or visit www.sun.com if you need additional information or
  21  * have any 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 symbolOop'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 }