001 /* Instrumentation.java -- Implementation of this interface is used to 002 instrument Java bytecode. 003 Copyright (C) 2005 Free Software Foundation, Inc. 004 005 This file is part of GNU Classpath. 006 007 GNU Classpath is free software; you can redistribute it and/or modify 008 it under the terms of the GNU General Public License as published by 009 the Free Software Foundation; either version 2, or (at your option) 010 any later version. 011 012 GNU Classpath is distributed in the hope that it will be useful, but 013 WITHOUT ANY WARRANTY; without even the implied warranty of 014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 015 General Public License for more details. 016 017 You should have received a copy of the GNU General Public License 018 along with GNU Classpath; see the file COPYING. If not, write to the 019 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 020 02110-1301 USA. 021 022 Linking this library statically or dynamically with other modules is 023 making a combined work based on this library. Thus, the terms and 024 conditions of the GNU General Public License cover the whole 025 combination. 026 027 As a special exception, the copyright holders of this library give you 028 permission to link this library with independent modules to produce an 029 executable, regardless of the license terms of these independent 030 modules, and to copy and distribute the resulting executable under 031 terms of your choice, provided that you also meet, for each linked 032 independent module, the terms and conditions of the license of that 033 module. An independent module is a module which is not derived from 034 or based on this library. If you modify this library, you may extend 035 this exception to your version of the library, but you are not 036 obligated to do so. If you do not wish to do so, delete this 037 exception statement from your version. */ 038 039 040 package java.lang.instrument; 041 042 /** 043 * An Instrumentation object has transformers that will 044 * be called each time a class is defined or redefined. 045 * The object is given to a <code>premain</code> function 046 * that is called before the <code>main</code> function. 047 * 048 * @author Nicolas Geoffray (nicolas.geoffray@menlina.com) 049 * @since 1.5 050 */ 051 public interface Instrumentation 052 { 053 054 /** 055 * Adds a <code>ClassFileTransformer</class> object 056 * to the instrumentation. Each time a class is defined 057 * or redefined, the <code>transform</code> method of the 058 * <code>transformer</code> object is called. 059 * 060 * @param transformer the transformer to add 061 * @throws NullPointerException if transformer is null 062 */ 063 void addTransformer(ClassFileTransformer transformer); 064 065 /** 066 * Removes the given transformer from the set of transformers 067 * this Instrumentation object has. 068 * 069 * @param transformer the transformer to remove 070 * @return true if the transformer was found and removed, false if 071 * the transformer was not found 072 * @throws NullPointerException if transformer is null 073 */ 074 boolean removeTransformer(ClassFileTransformer transformer); 075 076 /** 077 * Returns if the current JVM supports class redefinition 078 * 079 * @return true if the current JVM supports class redefinition 080 */ 081 boolean isRedefineClassesSupported(); 082 083 /** 084 * Redefine classes present in the definitions array, with 085 * the corresponding class files. 086 * 087 * @param definitions an array of classes to redefine 088 * 089 * @throws ClassNotFoundException if a class cannot be found 090 * @throws UnmodifiableClassException if a class cannot be modified 091 * @throws UnsupportedOperationException if the JVM does not support 092 * redefinition or the redefinition made unsupported changes 093 * @throws ClassFormatError if a class file is not valid 094 * @throws NoClassDefFoundError if a class name is not equal to the name 095 * in the class file specified 096 * @throws UnsupportedClassVersionError if the class file version numbers 097 * are unsupported 098 * @throws ClassCircularityError if circularity occured with the new 099 * classes 100 * @throws LinkageError if a linkage error occurs 101 * @throws NullPointerException if the definitions array is null, or any 102 * of its element 103 * 104 * @see #isRedefineClassesSupported() 105 * @see #addTransformer(java.lang.instrument.ClassFileTransformer) 106 * @see ClassFileTransformer 107 */ 108 void redefineClasses(ClassDefinition[] definitions) 109 throws ClassNotFoundException, 110 UnmodifiableClassException; 111 112 113 /** 114 * Get all the classes loaded by the JVM. 115 * 116 * @return an array containing all the classes loaded by the JVM. The array 117 * is empty if no class is loaded. 118 */ 119 Class[] getAllLoadedClasses(); 120 121 /** 122 * Get all the classes loaded by a given class loader 123 * 124 * @param loader the loader 125 * 126 * @return an array containing all the classes loaded by the given loader. 127 * The array is empty if no class was loaded by the loader. 128 */ 129 Class[] getInitiatedClasses(ClassLoader loader); 130 131 /** 132 * Get the size of an object. It contains the size of all fields. 133 * 134 * @param objectToSize the object 135 * @return the size of the object 136 * @throws NullPointerException if objectToSize is null. 137 */ 138 long getObjectSize(Object objectToSize); 139 }