org.quilt.cl
Class QuiltClassLoader

java.lang.Object
  |
  +--java.lang.ClassLoader
        |
        +--java.security.SecureClassLoader
              |
              +--java.net.URLClassLoader
                    |
                    +--org.quilt.cl.QuiltClassLoader

public class QuiltClassLoader

extends java.net.URLClassLoader

Quilt's transforming class loader. Can be directed to instrument a set of classes, matching class names against a list of prefixes and another list excluding classes from instrumentation, the exclusion list taking priority. Will delegate loading to a parent class loader where explicitly directed to; otherwise will be the defining loader. By default the loading of classes whose names begin with java., javax., junit., org.apache.bcel., org.apache.tools.ant. and org.quilt. is delegated.

Classes whose names begin with a reserved prefix, currently test.data.Test, are synthesized instead of being loaded. This must be specifically enabled.

Author:

Jim Dixon

See Also:

ClassFactory

Field Summary

static char	CLASSPATH_DELIM_CHAR
static java.lang.String	CLASSPATH_DELIM_STR
static java.lang.String[]	DELEGATED Names of classes which must be loaded by the parent.
static char	FILE_PATH_DELIM_CHAR Operating system specific
static java.lang.String	FILE_PATH_DELIM_STR
java.util.Map	regMap Map of registries by String name.
static java.lang.String	SYNTH_PREFIX Prefix indicating that the class should be synthesized.
static java.lang.String	THIS_DIR Convert domain name in classpath to file name, allowing for initial dots.
static int	THIS_DIR_LEN
static java.lang.String	UP_DIR
static int	UP_DIR_LEN
ClassTransformer	xformer Responsible for instrumenting classes.

Constructor Summary

QuiltClassLoader(java.net.URL[] cp, java.lang.ClassLoader parent, java.lang.String[] del, java.lang.String[] inc, java.lang.String[] exc)
Constructor with full argument list.

QuiltClassLoader(java.net.URL[] cp, java.lang.String[] inc)
Constructor with abbreviated argument list.

Method Summary

void	addClassXformer(ClassXformer xf) Add a class transformer.
void	addDelegated(java.lang.String prefix) Add a class name prefix to the list of those to be delegated to the parent.
void	addExcluded(java.lang.String prefix) Add a class name prefix to the list of those to be excluded from instrumentation.
void	addGraphXformer(GraphXformer xf) Add a graph transformer.
void	addIncluded(java.lang.String prefix) Add a class name prefix to the list of those to be instrumented.
void	addMethodXformer(MethodXformer xf) Add a method transformer.
void	addPath(java.net.URL url) Add a path to the class loader's classpath.
QuiltRegistry	addQuiltRegistry(java.lang.String regName) Add a new QuiltRegistry to the list.
static java.lang.String	classFileName(java.lang.String className) Convert a class name into a file name by replacing dots with forward slashes and appending ".class".
static java.net.URL[]	cpToURLs(java.lang.String cp) Convert classpath in normal form to URL[]
static java.lang.String	domainToFileName(java.lang.String name) Convert a dotted domain name to its path form, allowing for leading ./ and ../ and terminating .jar
protected java.lang.Class	findClass(java.lang.String name) Locate the class whose name is passed and define it.
protected byte[]	getClassData(java.lang.String className) Find a class along the class path and load it as a byte array.
java.net.URL[]	getClassPath()
java.lang.String[]	getDelegated()
java.lang.String[]	getExcluded()
java.lang.String[]	getIncluded()
QuiltRegistry	getRegistry(java.lang.String regName) Get a reference to a Quilt registry.
java.lang.String	getReport() Get reports from any or all registries.
boolean	getSynthEnabled() Get synthesizing-enabled flag.
java.lang.String	getSynthPrefix()
java.lang.Class	loadClass(java.lang.String name) Class loader.
void	setClassPath(java.lang.String cp) Convert classpath in normal form to URL[] and sets loader classpath to the corresponding value.
void	setExcluded(java.lang.String s) Sets the list of classes to be excluded from instrumentation.
void	setIncluded(java.lang.String s) Sets the list of classes to be instrumented.
void	setSynthEnabled(boolean b) Enable class synthesizing.
java.lang.String	urlsToString()

Methods inherited from class java.net.URLClassLoader

addURL, definePackage, findResource, findResources, getPermissions, getURLs, newInstance, newInstance

Methods inherited from class java.security.SecureClassLoader

defineClass

Methods inherited from class java.lang.ClassLoader

clearAssertionStatus, defineClass, defineClass, defineClass, definePackage, findLibrary, findLoadedClass, findSystemClass, getPackage, getPackages, getParent, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FILE_PATH_DELIM_CHAR

public static final char FILE_PATH_DELIM_CHAR

Operating system specific

FILE_PATH_DELIM_STR

public static final java.lang.String FILE_PATH_DELIM_STR

CLASSPATH_DELIM_CHAR

public static final char CLASSPATH_DELIM_CHAR

CLASSPATH_DELIM_STR

public static final java.lang.String CLASSPATH_DELIM_STR

DELEGATED

public static final java.lang.String[] DELEGATED

Names of classes which must be loaded by the parent. There is one exception to this list: org.quilt.QIC, which is not delegated and not instrumented.

SYNTH_PREFIX

public static final java.lang.String SYNTH_PREFIX

Prefix indicating that the class should be synthesized.

See Also:

Constant Field Values

xformer

public ClassTransformer xformer

Responsible for instrumenting classes.

THIS_DIR

public static final java.lang.String THIS_DIR

Convert domain name in classpath to file name, allowing for initial dots. Need to cope with ../../target/big.jar and similar constructions.

UP_DIR

public static final java.lang.String UP_DIR

THIS_DIR_LEN

public static final int THIS_DIR_LEN

UP_DIR_LEN

public static final int UP_DIR_LEN

regMap

public java.util.Map regMap

Map of registries by String name.

Constructor Detail

QuiltClassLoader

public QuiltClassLoader(java.net.URL[] cp,
                        java.lang.String[] inc)

Constructor with abbreviated argument list.

QuiltClassLoader

public QuiltClassLoader(java.net.URL[] cp,
                        java.lang.ClassLoader parent,
                        java.lang.String[] del,
                        java.lang.String[] inc,
                        java.lang.String[] exc)

Constructor with full argument list.

Parameters:

cp - Class path, an array of paths

parent - Class loader which we delegate to.

del - String array, names of classes to be delegated

inc - String array, names of classes to be instrumented

exc - String array, names of classes not to be instrumented.

Method Detail

classFileName

public static java.lang.String classFileName(java.lang.String className)

Convert a class name into a file name by replacing dots with forward slashes and appending ".class".

loadClass

public java.lang.Class loadClass(java.lang.String name)
                          throws java.lang.ClassNotFoundException

Class loader. Delegates the loading if specifically instructed to do so. Returns the class if it has already been loaded. Otherwise creates a class transformer if necessary and then passes the name to findClass.

Overrides:

loadClass in class java.lang.ClassLoader

java.lang.ClassNotFoundException

findClass

protected java.lang.Class findClass(java.lang.String name)
                             throws java.lang.ClassNotFoundException

Locate the class whose name is passed and define it. If the class name has the appropriate prefix and synthesizing it is enabled, it synthesizes it. Otherwise it searches for it along the class path. If indicated, it transforms (instruments) the class. Finally, it defines and returns the result.

Overrides:

findClass in class java.net.URLClassLoader

Parameters:

name - Class name in embedded dot (.) form.

java.lang.ClassNotFoundException

urlsToString

public java.lang.String urlsToString()

Returns:

Classpath as a newline-terminated String.

getClassData

protected byte[] getClassData(java.lang.String className)
                       throws java.io.IOException

Find a class along the class path and load it as a byte array.

java.io.IOException

addPath

public void addPath(java.net.URL url)

Add a path to the class loader's classpath.

Parameters:

url - Path to be added.

getClassPath

public java.net.URL[] getClassPath()

Returns:

The classpath used by this QuiltClassLoader.

domainToFileName

public static java.lang.String domainToFileName(java.lang.String name)

Convert a dotted domain name to its path form, allowing for leading ./ and ../ and terminating .jar

cpToURLs

public static java.net.URL[] cpToURLs(java.lang.String cp)

Convert classpath in normal form to URL[]

setClassPath

public void setClassPath(java.lang.String cp)

Convert classpath in normal form to URL[] and sets loader classpath to the corresponding value.

Parameters:

cp - Class path in colon- or semicolon-delimited form.

addDelegated

public void addDelegated(java.lang.String prefix)

Add a class name prefix to the list of those to be delegated to the parent.

Parameters:

prefix - Prefix to be added.

getDelegated

public java.lang.String[] getDelegated()

Returns:

As a String array the list of class name prefixes whose loading is to be delegated to the parent.

addExcluded

public void addExcluded(java.lang.String prefix)

Add a class name prefix to the list of those to be excluded from instrumentation.

Parameters:

prefix - Prefix to be added.

getExcluded

public java.lang.String[] getExcluded()

Returns:

As a String array the list of class name prefixes which are NOT to be instrumented.

setExcluded

public void setExcluded(java.lang.String s)

Sets the list of classes to be excluded from instrumentation.

Parameters:

s - List of classes in comma-separated String form.

addIncluded

public void addIncluded(java.lang.String prefix)

Add a class name prefix to the list of those to be instrumented.

Parameters:

prefix - Prefix to be added.

getIncluded

public java.lang.String[] getIncluded()

Returns:

As a String array the list of class name prefixes which ARE to be instrumented.

setIncluded

public void setIncluded(java.lang.String s)

Sets the list of classes to be instrumented.

Parameters:

s - List of classes in comma-separated String form.

getSynthEnabled

public boolean getSynthEnabled()

Get synthesizing-enabled flag.

setSynthEnabled

public void setSynthEnabled(boolean b)

Enable class synthesizing.

getSynthPrefix

public java.lang.String getSynthPrefix()

Returns:

The prefix signifying that a class is to be synthesized.

addClassXformer

public void addClassXformer(ClassXformer xf)

Add a class transformer.

addMethodXformer

public void addMethodXformer(MethodXformer xf)

Add a method transformer.

addGraphXformer

public void addGraphXformer(GraphXformer xf)

Add a graph transformer.

getRegistry

public QuiltRegistry getRegistry(java.lang.String regName)

Get a reference to a Quilt registry.

addQuiltRegistry

public QuiltRegistry addQuiltRegistry(java.lang.String regName)

Add a new QuiltRegistry to the list. An example of the argument is "org.quilt.cover.stmt.StmtRegistry".

Parameters:

regName - The domain name of the registry in dotted form.

getReport

public java.lang.String getReport()

Get reports from any or all registries. XXX This should not be returning a String -- it might be huge.