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.Collection;
044: import java.util.List;
045: import java.util.Properties;
046:
047: /**
048: * This is top-level interface representing one instance of heap dump.
049: * @author Tomas Hurka
050: */
051: public interface Heap {
052: //~ Methods ------------------------------------------------------------------------------------------------------------------
053:
054: /**
055: * computes List of all {@link JavaClass} instances in this heap.
056: * The classes are ordered according to the position in the dump file.
057: * <br>
058: * Speed: slow for the first time, subsequent invocations are fast.
059: * @return list of all {@link JavaClass} in the heap.
060: */
061: List /*<JavaClass>*/getAllClasses();
062:
063: /**
064: * returns {@link GCRoot} for {@link Instance}.
065: * <br>
066: * Speed: normal for first invocation, fast for subsequent
067: * @param instance {@link Instance} whose associated {@link GCRoot} is to be returned.
068: * @return {@link GCRoot} for corresponding instance or <CODE>null</CODE> if instance is not GC root.
069: */
070: GCRoot getGCRoot(Instance instance);
071:
072: /**
073: * returns list of all GC roots.
074: * <br>
075: * Speed: normal for first invocation, fast for subsequent
076: * @return list of {@link GCRoot} instances representing all GC roots.
077: */
078: Collection /*<GCRoot>*/getGCRoots();
079:
080: /**
081: * computes {@link Instance} for instanceId.
082: * <br>
083: * Speed: fast
084: * @param instanceId unique ID of {@link Instance}
085: * @return return <CODE>null</CODE> if there no {@link Instance} with instanceId, otherwise
086: * corresponding {@link Instance} is returned so that
087: * <CODE>heap.getInstanceByID(instanceId).getInstanceId() == instanceId</CODE>
088: */
089: Instance getInstanceByID(long instanceId);
090:
091: /**
092: * computes {@link JavaClass} for javaclassId.
093: * <br>
094: * Speed: fast
095: * @param javaclassId unique ID of {@link JavaClass}
096: * @return return <CODE>null</CODE> if there no java class with javaclassId, otherwise corresponding {@link JavaClass}
097: * is returned so that <CODE>heap.getJavaClassByID(javaclassId).getJavaClassId() == javaclassId</CODE>
098: */
099: JavaClass getJavaClassByID(long javaclassId);
100:
101: /**
102: * computes {@link JavaClass} for fully qualified name.
103: * <br>
104: * Speed: slow
105: * @param fqn fully qualified name of the java class.
106: * @return return <CODE>null</CODE> if there no class with fqn name, otherwise corresponding {@link JavaClass}
107: * is returned so that <CODE>heap.getJavaClassByName(fqn).getName().equals(fqn)</CODE>
108: */
109: JavaClass getJavaClassByName(String fqn);
110:
111: /**
112: * returns optional summary information of the heap.
113: * If this information is not available in the dump,
114: * some data (like number of instances) are computed
115: * from the dump itself.
116: * <br>
117: * Speed: fast if the summary is available in dump, slow if
118: * summary needs to be computed from dump.
119: * @return {@link HeapSummary} of the heap
120: */
121: HeapSummary getSummary();
122:
123: /**
124: * Determines the system properties of the {@link Heap}. It returns {@link Properties} with the same
125: * content as if {@link System#getProperties()} was invoked in JVM, where this heap dump was taken.
126: * <br>
127: * Speed: slow
128: * @return the system properties or <CODE>null</CODE> if the system properties cannot be computed from
129: * this {@link Heap}
130: */
131: Properties getSystemProperties();
132: }
|