Source for java.lang.instrument.Instrumentation

   1: /* Instrumentation.java -- Implementation of this interface is used to
   2:    instrument Java bytecode.
   3:    Copyright (C) 2005  Free Software Foundation, Inc.
   4: 
   5: This file is part of GNU Classpath.
   6: 
   7: GNU Classpath is free software; you can redistribute it and/or modify
   8: it under the terms of the GNU General Public License as published by
   9: the Free Software Foundation; either version 2, or (at your option)
  10: any later version.
  11: 
  12: GNU Classpath is distributed in the hope that it will be useful, but
  13: WITHOUT ANY WARRANTY; without even the implied warranty of
  14: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15: General Public License for more details.
  16: 
  17: You should have received a copy of the GNU General Public License
  18: along with GNU Classpath; see the file COPYING.  If not, write to the
  19: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20: 02110-1301 USA.
  21: 
  22: Linking this library statically or dynamically with other modules is
  23: making a combined work based on this library.  Thus, the terms and
  24: conditions of the GNU General Public License cover the whole
  25: combination.
  26: 
  27: As a special exception, the copyright holders of this library give you
  28: permission to link this library with independent modules to produce an
  29: executable, regardless of the license terms of these independent
  30: modules, and to copy and distribute the resulting executable under
  31: terms of your choice, provided that you also meet, for each linked
  32: independent module, the terms and conditions of the license of that
  33: module.  An independent module is a module which is not derived from
  34: or based on this library.  If you modify this library, you may extend
  35: this exception to your version of the library, but you are not
  36: obligated to do so.  If you do not wish to do so, delete this
  37: exception statement from your version. */
  38: 
  39: 
  40: package java.lang.instrument;
  41: 
  42: /**
  43:  * An Instrumentation object has transformers that will
  44:  * be called each time a class is defined or redefined.
  45:  * The object is given to a <code>premain</code> function
  46:  * that is called before the <code>main</code> function.
  47:  *
  48:  * @author Nicolas Geoffray (nicolas.geoffray@menlina.com)
  49:  * @since 1.5
  50:  */
  51: public interface Instrumentation
  52: {
  53:   
  54:   /**
  55:    * Adds a <code>ClassFileTransformer</class> object
  56:    * to the instrumentation. Each time a class is defined
  57:    * or redefined, the <code>transform</code> method of the
  58:    * <code>transformer</code> object is called.
  59:    * 
  60:    * @param transformer the transformer to add
  61:    * @throws NullPointerException if transformer is null
  62:    */
  63:   void addTransformer(ClassFileTransformer transformer);
  64:   
  65:   /**
  66:    * Removes the given transformer from the set of transformers
  67:    * this Instrumentation object has.
  68:    * 
  69:    * @param transformer the transformer to remove
  70:    * @return true if the transformer was found and removed, false if
  71:    * the transformer was not found
  72:    * @throws NullPointerException if transformer is null
  73:    */
  74:   boolean removeTransformer(ClassFileTransformer transformer);
  75: 
  76:   /**
  77:    * Returns if the current JVM supports class redefinition
  78:    * 
  79:    * @return true if the current JVM supports class redefinition
  80:    */
  81:   boolean isRedefineClassesSupported();
  82: 
  83:   /**
  84:    * Redefine classes present in the definitions array, with
  85:    * the corresponding class files.
  86:    *
  87:    * @param definitions an array of classes to redefine
  88:    * 
  89:    * @throws ClassNotFoundException if a class cannot be found 
  90:    * @throws UnmodifiableClassException if a class cannot be modified 
  91:    * @throws UnsupportedOperationException if the JVM does not support
  92:    * redefinition or the redefinition made unsupported changes
  93:    * @throws ClassFormatError if a class file is not valid
  94:    * @throws NoClassDefFoundError if a class name is not equal to the name
  95:    * in the class file specified
  96:    * @throws UnsupportedClassVersionError if the class file version numbers
  97:    * are unsupported
  98:    * @throws ClassCircularityError if circularity occured with the new
  99:    * 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: }