Field.java revision 9883:903a2e023ffb
190075Sobrien/* 290075Sobrien * Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved. 3169689Skan * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 490075Sobrien * 590075Sobrien * This code is free software; you can redistribute it and/or modify it 690075Sobrien * under the terms of the GNU General Public License version 2 only, as 790075Sobrien * published by the Free Software Foundation. 890075Sobrien * 9132718Skan * This code is distributed in the hope that it will be useful, but WITHOUT 1090075Sobrien * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 11132718Skan * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 12132718Skan * version 2 for more details (a copy is included in the LICENSE file that 13132718Skan * accompanied this code). 14132718Skan * 1590075Sobrien * You should have received a copy of the GNU General Public License version 16132718Skan * 2 along with this work; if not, write to the Free Software Foundation, 17132718Skan * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 18132718Skan * 19132718Skan * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2090075Sobrien * or visit www.oracle.com if you need additional information or have any 21132718Skan * questions. 22132718Skan * 23169689Skan */ 24169689Skan 2590075Sobrienpackage sun.jvm.hotspot.types; 2690075Sobrien 2790075Sobrienimport sun.jvm.hotspot.debugger.*; 2890075Sobrien 29169689Skan/** <P> This is the basic interface which describes a field in a C/C++ 30169689Skan data structure or a Java object. </P> 31169689Skan 32117395Skan <P> The accessors in this class are designed to allow manual 33117395Skan coercion of the data within the field, which is often necessary 34117395Skan when interfacing with C programs. Therefore, the accessors here do 35117395Skan not perform any type checking. Specializations of the Field 36169689Skan interface, such as JByteField, provide getValue() methods which 37169689Skan both perform type checking and return the appropriate specialized 38169689Skan type. </P> 39169689Skan 40169689Skan <P> See @see CIntegerType for a description of why all C integer 41117395Skan types are bundled into the category "CIntegerType". </P> 42117395Skan 43117395Skan <P> As an example, coercing a pointer field into an int can be 44117395Skan done in the following fashion (assuming the application has 45117395Skan registered an integer type in the type database called 46117395Skan "intptr_t"): </P> 47117395Skan 48117395Skan <PRE> 49117395Skan { 50117395Skan ... 51117395Skan Address myObject = ...; 52117395Skan CIntegerType intptr_tType = (CIntegerType) db.lookupType("intptr_t"); 53117395Skan long addrVal = field.getCInteger(myObject, intptr_tType); 54117395Skan ... 55117395Skan } 56117395Skan </PRE> 57117395Skan 58117395Skan FIXME: among other things, this interface is not sufficient to 59117395Skan describe fields which are themselves arrays (like Symbol's 60117395Skan jbyte _body[1]). */ 61169689Skanpublic interface Field { 62117395Skan /** Get the name of this field */ 63117395Skan public String getName(); 64117395Skan 65117395Skan /** Get the type of this field */ 66169689Skan public Type getType(); 67117395Skan 68117395Skan /** Get the size, in bytes, of this field. Used for manual data 69117395Skan structure traversal where necessary. */ 70117395Skan public long getSize(); 71169689Skan 72169689Skan /** Is this a static field? */ 73169689Skan public boolean isStatic(); 74169689Skan 75169689Skan /** The offset of this field, in bytes, in its containing data 76169689Skan structure, if nonstatic. If this is a static field, throws a 77169689Skan WrongTypeException. */ 78169689Skan public long getOffset() throws WrongTypeException; 79169689Skan 80169689Skan /** The address of this field, if it is a static field. If this is a 81117395Skan nonstatic field, throws a WrongTypeException. */ 82117395Skan public Address getStaticFieldAddress() throws WrongTypeException; 83169689Skan 84169689Skan /** <P> These accessors require that the field be nonstatic; 85169689Skan otherwise, a WrongTypeException will be thrown. Note that type 86169689Skan checking is not performed by these accessors in order to allow 87169689Skan manual type coercion of field data. For better protection when 88169689Skan accessing primitive fields, use the get(Type)Field accessors in 89169689Skan Type.java. </P> 90169689Skan 91169689Skan <P> NOTE that the Address passed in to these routines may, in 92169689Skan fact, be an OopHandle. Specifically, in a reflective system, 9390075Sobrien dereferencing operations applied to the OopHandle must be 94169689Skan performed atomically with respect to GC. </P> 95169689Skan 96169689Skan <P> See @see CIntegerType for a description of why all C integer 97169689Skan types are bundled into the category "CIntegerType". </P> 98169689Skan */ 99169689Skan public boolean getJBoolean (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 100169689Skan public byte getJByte (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 101169689Skan public char getJChar (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 102169689Skan public short getJShort (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 103169689Skan public int getJInt (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 104169689Skan public long getJLong (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 105169689Skan public float getJFloat (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 10690075Sobrien public double getJDouble (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 10790075Sobrien public long getCInteger (Address addr, CIntegerType type) 10890075Sobrien throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 10990075Sobrien public Address getAddress (Address addr) throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 11090075Sobrien public OopHandle getOopHandle(Address addr) 11190075Sobrien throws UnmappedAddressException, UnalignedAddressException, WrongTypeException, NotInHeapException; 11290075Sobrien public OopHandle getNarrowOopHandle(Address addr) 11390075Sobrien throws UnmappedAddressException, UnalignedAddressException, WrongTypeException, NotInHeapException; 11490075Sobrien 11590075Sobrien /** <P> These accessors require that the field be static; otherwise, 11690075Sobrien a WrongTypeException will be thrown. Note that type checking is 11790075Sobrien not performed by these accessors in order to allow manual type 11890075Sobrien coercion of field data. For better protection when accessing 119117395Skan primitive fields, use the get(Type)Field accessors in 12090075Sobrien Type.java. </P> 121117395Skan 122117395Skan <P> NOTE that the Address passed in to these routines may, in 123117395Skan fact, be an OopHandle. Specifically, in a reflective system, 12490075Sobrien dereferencing operations applied to the OopHandle must be 125117395Skan performed atomically with respect to GC. </P> 12690075Sobrien 127132718Skan <P> See @see CIntegerType for a description of why all C integer 12890075Sobrien types are bundled into the category "CIntegerType". </P> 129117395Skan */ 130117395Skan public boolean getJBoolean () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 13190075Sobrien public byte getJByte () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 132132718Skan public char getJChar () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 13390075Sobrien public float getJFloat () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 13490075Sobrien public double getJDouble () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 13590075Sobrien public int getJInt () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 13690075Sobrien public long getJLong () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 13790075Sobrien public short getJShort () throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 13890075Sobrien public long getCInteger (CIntegerType type) 139169689Skan throws UnmappedAddressException, UnalignedAddressException, WrongTypeException; 140117395Skan public Address getAddress () throws UnmappedAddressException, UnalignedAddressException; 141117395Skan public OopHandle getOopHandle() 142117395Skan throws UnmappedAddressException, UnalignedAddressException, NotInHeapException; 143117395Skan public OopHandle getNarrowOopHandle() 14490075Sobrien throws UnmappedAddressException, UnalignedAddressException, NotInHeapException; 14590075Sobrien} 14690075Sobrien