/*
 * Copyright (c) 2000, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 *
 */

package sun.jvm.hotspot.types;

import sun.jvm.hotspot.debugger.*;

 This is the basic interface which describes a field in a C/C++
data structure or a Java object. 
 The accessors in this class are designed to allow manual
coercion of the data within the field, which is often necessary
when interfacing with C programs. Therefore, the accessors here do
not perform any type checking. Specializations of the Field
interface, such as JByteField, provide getValue() methods which
both perform type checking and return the appropriate specialized
type. 
 See @see CIntegerType for a description of why all C integer
types are bundled into the category "CIntegerType". 
 As an example, coercing a pointer field into an int can be
done in the following fashion (assuming the application has
registered an integer type in the type database called
"intptr_t"): 
{
...
Address myObject = ...;
CIntegerType intptr_tType = (CIntegerType) db.lookupType("intptr_t");
long addrVal = field.getCInteger(myObject, intptr_tType);
...
}

FIXME: among other things, this interface is not sufficient to
describe fields which are themselves arrays (like Symbol's
u1 _body[1]).  /** <P> This is the basic interface which describes a field in a C/C++
    data structure or a Java object. </P>

    <P> The accessors in this class are designed to allow manual
    coercion of the data within the field, which is often necessary
    when interfacing with C programs. Therefore, the accessors here do
    not perform any type checking. Specializations of the Field
    interface, such as JByteField, provide getValue() methods which
    both perform type checking and return the appropriate specialized
    type. </P>

    <P> See @see CIntegerType for a description of why all C integer
    types are bundled into the category "CIntegerType". </P>

    <P> As an example, coercing a pointer field into an int can be
    done in the following fashion (assuming the application has
    registered an integer type in the type database called
    "intptr_t"): </P>

    <PRE>
    {
      ...
      Address myObject = ...;
      CIntegerType intptr_tType = (CIntegerType) db.lookupType("intptr_t");
      long addrVal = field.getCInteger(myObject, intptr_tType);
      ...
    }
    </PRE>

    FIXME: among other things, this interface is not sufficient to
    describe fields which are themselves arrays (like Symbol's
    u1 _body[1]).  */
public interface Field {
  
Get the name of this field /** Get the name of this field */
  public String getName();

  
Get the type of this field /** Get the type of this field */
  public Type getType();

  
Get the size, in bytes, of this field. Used for manual data
structure traversal where necessary. /** Get the size, in bytes, of this field. Used for manual data
      structure traversal where necessary. */
  public long getSize();

  
Is this a static field? /** Is this a static field? */
  public boolean isStatic();

  
The offset of this field, in bytes, in its containing data
structure, if nonstatic. If this is a static field, throws a
WrongTypeException. /** The offset of this field, in bytes, in its containing data
      structure, if nonstatic. If this is a static field, throws a
      WrongTypeException. */
  public long getOffset() throws WrongTypeException;

  
The address of this field, if it is a static field. If this is a
nonstatic field, throws a WrongTypeException. /** The address of this field, if it is a static field. If this is a
      nonstatic field, throws a WrongTypeException. */
  public Address getStaticFieldAddress() throws WrongTypeException;

  
 These accessors require that the field be nonstatic;
otherwise, a WrongTypeException will be thrown. Note that type
checking is not performed by these accessors in order to allow
manual type coercion of field data. For better protection when
accessing primitive fields, use the get(Type)Field accessors in
Type.java. 
 NOTE that the Address passed in to these routines may, in
fact, be an OopHandle. Specifically, in a reflective system,
dereferencing operations applied to the OopHandle must be
performed atomically with respect to GC. 
 See @see CIntegerType for a description of why all C integer
types are bundled into the category "CIntegerType". 
/** <P> These accessors require that the field be nonstatic;
      otherwise, a WrongTypeException will be thrown. Note that type
      checking is not performed by these accessors in order to allow
      manual type coercion of field data. For better protection when
      accessing primitive fields, use the get(Type)Field accessors in
      Type.java. </P>

      <P> NOTE that the Address passed in to these routines may, in
      fact, be an OopHandle. Specifically, in a reflective system,
      dereferencing operations applied to the OopHandle must be
      performed atomically with respect to GC. </P>

      <P> See @see CIntegerType for a description of why all C integer
      types are bundled into the category "CIntegerType". </P>
  */
  public boolean   getJBoolean (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public byte      getJByte    (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public char      getJChar    (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public short     getJShort   (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public int       getJInt     (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public long      getJLong    (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public float     getJFloat   (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public double    getJDouble  (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public long      getCInteger (Address addr, CIntegerType type)
    throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public Address   getAddress  (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public OopHandle getOopHandle(Address addr)
    throws UnmappedAddressException, UnalignedAddressException, WrongTypeException, NotInHeapException;
  public OopHandle getNarrowOopHandle(Address addr)
    throws UnmappedAddressException, UnalignedAddressException, WrongTypeException, NotInHeapException;

  
 These accessors require that the field be static; otherwise,
a WrongTypeException will be thrown. Note that type checking is
not performed by these accessors in order to allow manual type
coercion of field data. For better protection when accessing
primitive fields, use the get(Type)Field accessors in
Type.java. 
 NOTE that the Address passed in to these routines may, in
fact, be an OopHandle. Specifically, in a reflective system,
dereferencing operations applied to the OopHandle must be
performed atomically with respect to GC. 
 See @see CIntegerType for a description of why all C integer
types are bundled into the category "CIntegerType". 
/** <P> These accessors require that the field be static; otherwise,
      a WrongTypeException will be thrown. Note that type checking is
      not performed by these accessors in order to allow manual type
      coercion of field data. For better protection when accessing
      primitive fields, use the get(Type)Field accessors in
      Type.java. </P>

      <P> NOTE that the Address passed in to these routines may, in
      fact, be an OopHandle. Specifically, in a reflective system,
      dereferencing operations applied to the OopHandle must be
      performed atomically with respect to GC. </P>

      <P> See @see CIntegerType for a description of why all C integer
      types are bundled into the category "CIntegerType". </P>
  */
  public boolean   getJBoolean () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public byte      getJByte    () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public char      getJChar    () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public float     getJFloat   () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public double    getJDouble  () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public int       getJInt     () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public long      getJLong    () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public short     getJShort   () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public long      getCInteger (CIntegerType type)
    throws UnmappedAddressException, UnalignedAddressException, WrongTypeException;
  public Address   getAddress  () throws UnmappedAddressException, UnalignedAddressException;
  public OopHandle getOopHandle()
    throws UnmappedAddressException, UnalignedAddressException, NotInHeapException;
  public OopHandle getNarrowOopHandle()
    throws UnmappedAddressException, UnalignedAddressException, NotInHeapException;
}