Package org.apache.tools.ant

Class AntClassLoader

java.lang.Object
java.lang.ClassLoader
org.apache.tools.ant.AntClassLoader
All Implemented Interfaces:
java.io.Closeable, java.lang.AutoCloseable, java.util.EventListener, BuildListener, SubBuildListener
Direct Known Subclasses:
AntClassLoader2, AntClassLoader5, SplitClassLoader
public class AntClassLoader
extends java.lang.ClassLoader
implements SubBuildListener, java.io.Closeable
Used to load classes within ant with a different classpath from that used to start ant. Note that it is possible to force a class into this loader even when that class is on the system classpath by using the forceLoadClass method. Any subsequent classes loaded by that class will then use this loader rather than the system class loader.

Note that this classloader has a feature to allow loading in reverse order and for "isolation". Due to the fact that a number of methods in java.lang.ClassLoader are final (at least in java 1.4 getResources) this means that the class has to fake the given parent.

  • Constructor Summary

    Constructors 
    Constructor Description
    AntClassLoader()
    Create an Ant Class Loader
    AntClassLoader​(java.lang.ClassLoader parent, boolean parentFirst)
    Creates an empty class loader.
    AntClassLoader​(java.lang.ClassLoader parent, Project project, Path classpath)
    Create an Ant ClassLoader for a given project, with a parent classloader and an initial classpath.
    AntClassLoader​(java.lang.ClassLoader parent, Project project, Path classpath, boolean parentFirst)
    Creates a classloader for the given project using the classpath given.
    AntClassLoader​(Project project, Path classpath)
    Creates a classloader for the given project using the classpath given.
    AntClassLoader​(Project project, Path classpath, boolean parentFirst)
    Creates a classloader for the given project using the classpath given.

  • Method Summary

    Modifier and Type Method Description
    void addJavaLibraries()
    add any libraries that come with different java versions here
    void addLoaderPackageRoot​(java.lang.String packageRoot)
    Adds a package root to the list of packages which must be loaded using this loader.
    void addPathComponent​(java.io.File file)
    Add a path component.
    void addPathElement​(java.lang.String pathElement)
    Adds an element to the classpath to be searched.
    protected void addPathFile​(java.io.File pathComponent)
    Add a file to the path.
    void addSystemPackageRoot​(java.lang.String packageRoot)
    Adds a package root to the list of packages which must be loaded on the parent loader.
    void buildFinished​(BuildEvent event)
    Cleans up any resources held by this classloader at the end of a build.
    void buildStarted​(BuildEvent event)
    Empty implementation to satisfy the BuildListener interface.
    void cleanup()
    Cleans up any resources held by this classloader.
    void close()
    protected java.lang.Class<?> defineClassFromData​(java.io.File container, byte[] classData, java.lang.String classname)
    Define a class given its bytes
    protected void definePackage​(java.io.File container, java.lang.String className)
    Define the package information associated with a class.
    protected void definePackage​(java.io.File container, java.lang.String packageName, java.util.jar.Manifest manifest)
    Define the package information when the class comes from a jar with a manifest
    java.lang.Class<?> findClass​(java.lang.String name)
    Searches for and load a class on the classpath of this class loader.
    protected java.util.Enumeration<java.net.URL> findResources​(java.lang.String name)
    Returns an enumeration of URLs representing all the resources with the given name by searching the class loader's classpath.
    protected java.util.Enumeration<java.net.URL> findResources​(java.lang.String name, boolean parentHasBeenSearched)
    Returns an enumeration of URLs representing all the resources with the given name by searching the class loader's classpath.
    java.lang.Class<?> forceLoadClass​(java.lang.String classname)
    Loads a class through this class loader even if that class is available on the parent classpath.
    java.lang.Class<?> forceLoadSystemClass​(java.lang.String classname)
    Loads a class through this class loader but defer to the parent class loader.
    java.lang.String getClasspath()
    Returns the classpath this classloader will consult.
    java.lang.ClassLoader getConfiguredParent()
    Gets the parent as has been specified in the constructor or via setParent.
    java.util.Enumeration<java.net.URL> getNamedResources​(java.lang.String name)
    Finds all the resources with the given name.
    java.net.URL getResource​(java.lang.String name)
    Finds the resource with the given name.
    java.io.InputStream getResourceAsStream​(java.lang.String name)
    Returns a stream to read the requested resource name.
    java.util.Enumeration<java.net.URL> getResources​(java.lang.String name)
    protected java.net.URL getResourceURL​(java.io.File file, java.lang.String resourceName)
    Returns the URL of a given resource in the given file which may either be a directory or a zip file.
    static void initializeClass​(java.lang.Class<?> theClass)
    Deprecated.
    since 1.6.x.
    protected boolean isInPath​(java.io.File component)
    Indicate if the given file is in this loader's path
    protected java.lang.Class<?> loadClass​(java.lang.String classname, boolean resolve)
    Loads a class with this class loader.
    protected void log​(java.lang.String message, int priority)
    Logs a message through the project object if one has been provided.
    void messageLogged​(BuildEvent event)
    Empty implementation to satisfy the BuildListener interface.
    static AntClassLoader newAntClassLoader​(java.lang.ClassLoader parent, Project project, Path path, boolean parentFirst)
    Factory method
    void resetThreadContextLoader()
    Resets the current thread's context loader to its original value.
    void setClassPath​(Path classpath)
    Set the classpath to search for classes to load.
    void setIsolated​(boolean isolated)
    Sets whether this classloader should run in isolated mode.
    void setParent​(java.lang.ClassLoader parent)
    Set the parent for this class loader.
    void setParentFirst​(boolean parentFirst)
    Control whether class lookup is delegated to the parent loader first or after this loader.
    void setProject​(Project project)
    Set the project associated with this class loader
    void setThreadContextLoader()
    Sets the current thread's context loader to this classloader, storing the current loader value for later resetting.
    void subBuildFinished​(BuildEvent event)
    Cleans up any resources held by this classloader at the end of a subbuild if it has been created for the subbuild's project instance.
    void subBuildStarted​(BuildEvent event)
    Empty implementation to satisfy the BuildListener interface.
    void targetFinished​(BuildEvent event)
    Empty implementation to satisfy the BuildListener interface.
    void targetStarted​(BuildEvent event)
    Empty implementation to satisfy the BuildListener interface.
    void taskFinished​(BuildEvent event)
    Empty implementation to satisfy the BuildListener interface.
    void taskStarted​(BuildEvent event)
    Empty implementation to satisfy the BuildListener interface.
    java.lang.String toString()
    Returns a String representing this loader.

    Methods inherited from class java.lang.ClassLoader

    clearAssertionStatus, defineClass, defineClass, defineClass, defineClass, definePackage, findClass, findLibrary, findLoadedClass, findResource, findResource, findSystemClass, getClassLoadingLock, getDefinedPackage, getDefinedPackages, getName, getPackage, getPackages, getParent, getPlatformClassLoader, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, getUnnamedModule, isRegisteredAsParallelCapable, loadClass, registerAsParallelCapable, resolveClass, resources, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • AntClassLoader

      public AntClassLoader​(java.lang.ClassLoader parent, Project project, Path classpath)
      Create an Ant ClassLoader for a given project, with a parent classloader and an initial classpath.
      Parameters:
      parent - the parent for this classloader.
      project - The project to which this classloader is to belong.
      classpath - The classpath to use to load classes.
      Since:
      Ant 1.7.

    • AntClassLoader

      public AntClassLoader()
      Create an Ant Class Loader

    • AntClassLoader

      public AntClassLoader​(Project project, Path classpath)
      Creates a classloader for the given project using the classpath given.
      Parameters:
      project - The project to which this classloader is to belong. Must not be null.
      classpath - The classpath to use to load the classes. This is combined with the system classpath in a manner determined by the value of ${build.sysclasspath}. May be null, in which case no path elements are set up to start with.

    • AntClassLoader

      public AntClassLoader​(java.lang.ClassLoader parent, Project project, Path classpath, boolean parentFirst)
      Creates a classloader for the given project using the classpath given.
      Parameters:
      parent - The parent classloader to which unsatisfied loading attempts are delegated. May be null, in which case the classloader which loaded this class is used as the parent.
      project - The project to which this classloader is to belong. Must not be null.
      classpath - the classpath to use to load the classes. May be null, in which case no path elements are set up to start with.
      parentFirst - If true, indicates that the parent classloader should be consulted before trying to load the a class through this loader.

    • AntClassLoader

      public AntClassLoader​(Project project, Path classpath, boolean parentFirst)
      Creates a classloader for the given project using the classpath given.
      Parameters:
      project - The project to which this classloader is to belong. Must not be null.
      classpath - The classpath to use to load the classes. May be null, in which case no path elements are set up to start with.
      parentFirst - If true, indicates that the parent classloader should be consulted before trying to load the a class through this loader.

    • AntClassLoader

      public AntClassLoader​(java.lang.ClassLoader parent, boolean parentFirst)
      Creates an empty class loader. The classloader should be configured with path elements to specify where the loader is to look for classes.
      Parameters:
      parent - The parent classloader to which unsatisfied loading attempts are delegated. May be null, in which case the classloader which loaded this class is used as the parent.
      parentFirst - If true, indicates that the parent classloader should be consulted before trying to load the a class through this loader.

  • Method Details

    • setProject

      public void setProject​(Project project)
      Set the project associated with this class loader
      Parameters:
      project - the project instance

    • setClassPath

      public void setClassPath​(Path classpath)
      Set the classpath to search for classes to load. This should not be changed once the classloader starts to server classes
      Parameters:
      classpath - the search classpath consisting of directories and jar/zip files.

    • setParent

      public void setParent​(java.lang.ClassLoader parent)
      Set the parent for this class loader. This is the class loader to which this class loader will delegate to load classes
      Parameters:
      parent - the parent class loader.

    • setParentFirst

      public void setParentFirst​(boolean parentFirst)
      Control whether class lookup is delegated to the parent loader first or after this loader. Use with extreme caution. Setting this to false violates the class loader hierarchy and can lead to Linkage errors
      Parameters:
      parentFirst - if true, delegate initial class search to the parent classloader.

    • log

      protected void log​(java.lang.String message, int priority)
      Logs a message through the project object if one has been provided.
      Parameters:
      message - The message to log. Should not be null.
      priority - The logging priority of the message.

    • setThreadContextLoader

      public void setThreadContextLoader()
      Sets the current thread's context loader to this classloader, storing the current loader value for later resetting.

    • resetThreadContextLoader

      public void resetThreadContextLoader()
      Resets the current thread's context loader to its original value.

    • addPathElement

      public void addPathElement​(java.lang.String pathElement) throws BuildException
      Adds an element to the classpath to be searched.
      Parameters:
      pathElement - The path element to add. Must not be null.
      Throws:
      BuildException - if the given path element cannot be resolved against the project.

    • addPathComponent

      public void addPathComponent​(java.io.File file)
      Add a path component. This simply adds the file, unlike addPathElement it does not open jar files and load files from their CLASSPATH entry in the manifest file.
      Parameters:
      file - the jar file or directory to add.

    • addPathFile

      protected void addPathFile​(java.io.File pathComponent) throws java.io.IOException
      Add a file to the path. Reads the manifest, if available, and adds any additional class path jars specified in the manifest.
      Parameters:
      pathComponent - the file which is to be added to the path for this class loader
      Throws:
      java.io.IOException - if data needed from the file cannot be read.

    • getClasspath

      public java.lang.String getClasspath()
      Returns the classpath this classloader will consult.
      Returns:
      the classpath used for this classloader, with elements separated by the path separator for the system.

    • setIsolated

      public void setIsolated​(boolean isolated)
      Sets whether this classloader should run in isolated mode. In isolated mode, classes not found on the given classpath will not be referred to the parent class loader but will cause a ClassNotFoundException.
      Parameters:
      isolated - Whether or not this classloader should run in isolated mode.

    • initializeClass

      @Deprecated public static void initializeClass​(java.lang.Class<?> theClass)
      Deprecated.
      since 1.6.x. Use Class.forName with initialize=true instead.
      Forces initialization of a class in a JDK 1.1 compatible, albeit hacky way.
      Parameters:
      theClass - The class to initialize. Must not be null.

    • addSystemPackageRoot

      public void addSystemPackageRoot​(java.lang.String packageRoot)
      Adds a package root to the list of packages which must be loaded on the parent loader. All subpackages are also included.
      Parameters:
      packageRoot - The root of all packages to be included. Should not be null.

    • addLoaderPackageRoot

      public void addLoaderPackageRoot​(java.lang.String packageRoot)
      Adds a package root to the list of packages which must be loaded using this loader. All subpackages are also included.
      Parameters:
      packageRoot - The root of all packages to be included. Should not be null.

    • forceLoadClass

      public java.lang.Class<?> forceLoadClass​(java.lang.String classname) throws java.lang.ClassNotFoundException
      Loads a class through this class loader even if that class is available on the parent classpath. This ensures that any classes which are loaded by the returned class will use this classloader.
      Parameters:
      classname - The name of the class to be loaded. Must not be null.
      Returns:
      the required Class object
      Throws:
      java.lang.ClassNotFoundException - if the requested class does not exist on this loader's classpath.

    • forceLoadSystemClass

      public java.lang.Class<?> forceLoadSystemClass​(java.lang.String classname) throws java.lang.ClassNotFoundException
      Loads a class through this class loader but defer to the parent class loader. This ensures that instances of the returned class will be compatible with instances which have already been loaded on the parent loader.
      Parameters:
      classname - The name of the class to be loaded. Must not be null.
      Returns:
      the required Class object
      Throws:
      java.lang.ClassNotFoundException - if the requested class does not exist on this loader's classpath.

    • getResourceAsStream

      public java.io.InputStream getResourceAsStream​(java.lang.String name)
      Returns a stream to read the requested resource name.
      Overrides:
      getResourceAsStream in class java.lang.ClassLoader
      Parameters:
      name - The name of the resource for which a stream is required. Must not be null.
      Returns:
      a stream to the required resource or null if the resource cannot be found on the loader's classpath.

    • getResource

      public java.net.URL getResource​(java.lang.String name)
      Finds the resource with the given name. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code.
      Overrides:
      getResource in class java.lang.ClassLoader
      Parameters:
      name - The name of the resource for which a stream is required. Must not be null.
      Returns:
      a URL for reading the resource, or null if the resource could not be found or the caller doesn't have adequate privileges to get the resource.

    • getNamedResources

      public java.util.Enumeration<java.net.URL> getNamedResources​(java.lang.String name) throws java.io.IOException
      Finds all the resources with the given name. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code.

      Would override getResources if that wasn't final in Java 1.4.

      Parameters:
      name - name of the resource
      Returns:
      possible URLs as enumeration
      Throws:
      java.io.IOException - if something goes wrong
      Since:
      Ant 1.8.0
      See Also:
      findResources(String, boolean)

    • findResources

      protected java.util.Enumeration<java.net.URL> findResources​(java.lang.String name) throws java.io.IOException
      Returns an enumeration of URLs representing all the resources with the given name by searching the class loader's classpath.
      Overrides:
      findResources in class java.lang.ClassLoader
      Parameters:
      name - The resource name to search for. Must not be null.
      Returns:
      an enumeration of URLs for the resources
      Throws:
      java.io.IOException - if I/O errors occurs (can't happen)

    • findResources

      protected java.util.Enumeration<java.net.URL> findResources​(java.lang.String name, boolean parentHasBeenSearched) throws java.io.IOException
      Returns an enumeration of URLs representing all the resources with the given name by searching the class loader's classpath.
      Parameters:
      name - The resource name to search for. Must not be null.
      parentHasBeenSearched - whether ClassLoader.this.parent has been searched - will be true if the method is (indirectly) called from ClassLoader.getResources
      Returns:
      an enumeration of URLs for the resources
      Throws:
      java.io.IOException - if I/O errors occurs (can't happen)

    • getResourceURL

      protected java.net.URL getResourceURL​(java.io.File file, java.lang.String resourceName)
      Returns the URL of a given resource in the given file which may either be a directory or a zip file.
      Parameters:
      file - The file (directory or jar) in which to search for the resource. Must not be null.
      resourceName - The name of the resource for which a stream is required. Must not be null.
      Returns:
      a stream to the required resource or null if the resource cannot be found in the given file object.

    • loadClass

      protected java.lang.Class<?> loadClass​(java.lang.String classname, boolean resolve) throws java.lang.ClassNotFoundException
      Loads a class with this class loader. This class attempts to load the class in an order determined by whether or not the class matches the system/loader package lists, with the loader package list taking priority. If the classloader is in isolated mode, failure to load the class in this loader will result in a ClassNotFoundException.
      Overrides:
      loadClass in class java.lang.ClassLoader
      Parameters:
      classname - The name of the class to be loaded. Must not be null.
      resolve - true if all classes upon which this class depends are to be loaded.
      Returns:
      the required Class object
      Throws:
      java.lang.ClassNotFoundException - if the requested class does not exist on the system classpath (when not in isolated mode) or this loader's classpath.

    • defineClassFromData

      protected java.lang.Class<?> defineClassFromData​(java.io.File container, byte[] classData, java.lang.String classname) throws java.io.IOException
      Define a class given its bytes
      Parameters:
      container - the container from which the class data has been read may be a directory or a jar/zip file.
      classData - the bytecode data for the class
      classname - the name of the class
      Returns:
      the Class instance created from the given data
      Throws:
      java.io.IOException - if the class data cannot be read.

    • definePackage

      protected void definePackage​(java.io.File container, java.lang.String className) throws java.io.IOException
      Define the package information associated with a class.
      Parameters:
      container - the file containing the class definition.
      className - the class name of for which the package information is to be determined.
      Throws:
      java.io.IOException - if the package information cannot be read from the container.

    • definePackage

      protected void definePackage​(java.io.File container, java.lang.String packageName, java.util.jar.Manifest manifest)
      Define the package information when the class comes from a jar with a manifest
      Parameters:
      container - the jar file containing the manifest
      packageName - the name of the package being defined.
      manifest - the jar's manifest

    • findClass

      public java.lang.Class<?> findClass​(java.lang.String name) throws java.lang.ClassNotFoundException
      Searches for and load a class on the classpath of this class loader.
      Overrides:
      findClass in class java.lang.ClassLoader
      Parameters:
      name - The name of the class to be loaded. Must not be null.
      Returns:
      the required Class object
      Throws:
      java.lang.ClassNotFoundException - if the requested class does not exist on this loader's classpath.

    • isInPath

      protected boolean isInPath​(java.io.File component)
      Indicate if the given file is in this loader's path
      Parameters:
      component - the file which is to be checked
      Returns:
      true if the file is in the class path

    • cleanup

      public void cleanup()
      Cleans up any resources held by this classloader. Any open archive files are closed.

    • getConfiguredParent

      public java.lang.ClassLoader getConfiguredParent()
      Gets the parent as has been specified in the constructor or via setParent.
      Returns:
      classloader
      Since:
      Ant 1.8.0

    • buildStarted

      public void buildStarted​(BuildEvent event)
      Empty implementation to satisfy the BuildListener interface.
      Specified by:
      buildStarted in interface BuildListener
      Parameters:
      event - the buildStarted event

    • buildFinished

      public void buildFinished​(BuildEvent event)
      Cleans up any resources held by this classloader at the end of a build.
      Specified by:
      buildFinished in interface BuildListener
      Parameters:
      event - the buildFinished event
      See Also:
      BuildEvent.getException()

    • subBuildFinished

      public void subBuildFinished​(BuildEvent event)
      Cleans up any resources held by this classloader at the end of a subbuild if it has been created for the subbuild's project instance.
      Specified by:
      subBuildFinished in interface SubBuildListener
      Parameters:
      event - the buildFinished event
      Since:
      Ant 1.6.2
      See Also:
      BuildEvent.getException()

    • subBuildStarted

      public void subBuildStarted​(BuildEvent event)
      Empty implementation to satisfy the BuildListener interface.
      Specified by:
      subBuildStarted in interface SubBuildListener
      Parameters:
      event - the buildStarted event
      Since:
      Ant 1.6.2

    • targetStarted

      public void targetStarted​(BuildEvent event)
      Empty implementation to satisfy the BuildListener interface.
      Specified by:
      targetStarted in interface BuildListener
      Parameters:
      event - the targetStarted event
      See Also:
      BuildEvent.getTarget()

    • targetFinished

      public void targetFinished​(BuildEvent event)
      Empty implementation to satisfy the BuildListener interface.
      Specified by:
      targetFinished in interface BuildListener
      Parameters:
      event - the targetFinished event
      See Also:
      BuildEvent.getException()

    • taskStarted

      public void taskStarted​(BuildEvent event)
      Empty implementation to satisfy the BuildListener interface.
      Specified by:
      taskStarted in interface BuildListener
      Parameters:
      event - the taskStarted event
      See Also:
      BuildEvent.getTask()

    • taskFinished

      public void taskFinished​(BuildEvent event)
      Empty implementation to satisfy the BuildListener interface.
      Specified by:
      taskFinished in interface BuildListener
      Parameters:
      event - the taskFinished event
      See Also:
      BuildEvent.getException()

    • messageLogged

      public void messageLogged​(BuildEvent event)
      Empty implementation to satisfy the BuildListener interface.
      Specified by:
      messageLogged in interface BuildListener
      Parameters:
      event - the messageLogged event
      See Also:
      BuildEvent.getMessage(), BuildEvent.getException(), BuildEvent.getPriority()

    • addJavaLibraries

      public void addJavaLibraries()
      add any libraries that come with different java versions here

    • toString

      public java.lang.String toString()
      Returns a String representing this loader.
      Overrides:
      toString in class java.lang.Object
      Returns:
      the path that this classloader has.

    • getResources

      public java.util.Enumeration<java.net.URL> getResources​(java.lang.String name) throws java.io.IOException
      Overrides:
      getResources in class java.lang.ClassLoader
      Throws:
      java.io.IOException

    • close

      public void close()
      Specified by:
      close in interface java.lang.AutoCloseable
      Specified by:
      close in interface java.io.Closeable

    • newAntClassLoader

      public static AntClassLoader newAntClassLoader​(java.lang.ClassLoader parent, Project project, Path path, boolean parentFirst)
      Factory method
      Parameters:
      parent - ClassLoader
      project - Project
      path - Path
      parentFirst - boolean
      Returns:
      AntClassLoader