001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: * The Original Software is NetBeans. The Initial Developer of the Original
026: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
027: * Microsystems, Inc. All Rights Reserved.
028: *
029: * If you wish your version of this file to be governed by only the CDDL
030: * or only the GPL Version 2, indicate your decision by adding
031: * "[Contributor] elects to include this software in this distribution
032: * under the [CDDL or GPL Version 2] license." If you do not indicate a
033: * single choice of license, a recipient has the option to distribute
034: * your version of this file under either the CDDL, the GPL Version 2 or
035: * to extend the choice of license to its licensees as provided above.
036: * However, if you add GPL Version 2 code and therefore, elected the GPL
037: * Version 2 license, then the option applies only if the new code is
038: * made subject to such option by the copyright holder.
039: */
040:
041: package org.netbeans.lib.profiler.heap;
042:
043: import java.util.List;
044:
045: /**
046: * This object represents one instance of java class.
047: * @author Tomas Hurka
048: */
049: public interface Instance {
050: //~ Methods ------------------------------------------------------------------------------------------------------------------
051:
052: /**
053: * computes the list of instance field values. The order is: fields of this class followed by
054: * super class, etc.
055: * <br>
056: * Speed: normal
057: * @return list of {@link FieldValue} instance field values.
058: */
059: List /*<FieldValue>*/getFieldValues();
060:
061: /**
062: * returns <CODE>true</CODE> if this is instance of GC root.
063: * <br>
064: * Speed: normal for first invocation, fast for subsequent
065: * @return <CODE>true</CODE> if this is instance of GC root, <CODE>false</CODE> otherwise.
066: */
067: boolean isGCRoot();
068:
069: /**
070: * gets unique (in whole heap) ID of this {@link Instance}.
071: * <br>
072: * Speed: fast
073: * @return ID of this {@link Instance}
074: */
075: long getInstanceId();
076:
077: /**
078: * gets unique number of this {@link Instance} amoung all instances of the same Java Class.
079: * Instances are numbered sequentially starting from 1.
080: * <br>
081: * Speed: fast
082: * @return unique number of this {@link Instance}
083: */
084: int getInstanceNumber();
085:
086: /**
087: * returns corresponding {@link JavaClass} for this instance.
088: * <br>
089: * Speed: fast
090: * @return {@link JavaClass} of this instance.
091: */
092: JavaClass getJavaClass();
093:
094: /**
095: * returns next {@link Instance} on the path to the nearest GC root.
096: * <br>
097: * Speed: first invocation is slow, all subsequent invocations are fast
098: * @return next {@link Instance} on the path to the nearest GC root, itself if the instance is GC root,
099: * <CODE>null</CODE> if path to the nearest GC root does not exist
100: */
101: Instance getNearestGCRootPointer();
102:
103: int getReachableSize();
104:
105: /**
106: * returns the list of references to this instance. The references can be of two kinds.
107: * The first one is from {@link ObjectFieldValue} and the second one if from {@link ArrayItemValue}
108: * <br>
109: * Speed: slow
110: * @return list of {@link Value} representing all references to this instance
111: */
112: List /*<Value>*/getReferences();
113:
114: int getRetainedSize();
115:
116: /**
117: * returns the size of the {@link Instance} in bytes. If the instance is not
118: * {@link PrimitiveArrayInstance} or {@link ObjectArrayInstance} this size is
119: * equal to <CODE>getJavaClass().getInstanceSize()</CODE>.
120: * <br>
121: * Speed: fast
122: * @return size of this {@link Instance}
123: */
124: int getSize();
125:
126: /**
127: * returns the list of static field values.
128: * This is delegated to {@link JavaClass#getStaticFieldValues()}
129: * <br>
130: * Speed: normal
131: * @return list of {@link FieldValue} static field values.
132: */
133: List /*<FieldValue>*/getStaticFieldValues();
134:
135: /**
136: * Returns a value object that reflects the specified field of the instance
137: * represented by this {@link Instance} object. Fields are searched from the java.lang.Object.
138: * The first field with the matching name is used.
139: * The name parameter is a String that specifies the simple name of the desired field.
140: * <br>
141: * Speed: normal
142: * @param name the name of the field
143: * @return @return the value for the specified static field in this class.
144: * If a field with the specified name is not found <CODE>null</CODE> is returned.
145: * If the field.getType() is {@link Type} object {@link Instance} is returned as a field value,
146: * for primitive types its corresponding object wapper (Boolean, Integer, Float, etc.) is returned.
147: */
148: Object getValueOfField(String name);
149: }
|