groovy.lang

## Class GroovyClassLoader

- java.lang.Object
- - java.lang.ClassLoader
  - - java.security.SecureClassLoader
    - - java.net.URLClassLoader
      - - groovy.lang.GroovyClassLoader

- All Implemented Interfaces:
    Closeable, AutoCloseable
  Direct Known Subclasses:
    GroovyClassLoader.InnerLoader

      public class GroovyClassLoader
      extends URLClassLoader

  A ClassLoader which can load Groovy classes. The loaded classes are cached, classes from other classloaders should not be cached. To be able to load a script that was asked for earlier but was created later it is essential not to keep anything like a "class not found" information for that class name. This includes possible parent loaders. Classes that are not cached are always reloaded.
  Version:
    $Revision$
  Author:
    James Strachan, Guillaume Laforge, Steve Goetze, Bing Ran, Scott Stirling, Jochen Theodorou

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `GroovyClassLoader.ClassCollector`
    `static class` | `GroovyClassLoader.InnerLoader`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Map<String,Class>` | `classCache` this cache contains the loaded classes or PARSING, if the class is currently parsed
    `protected Map<String,Class>` | `sourceCache` This cache contains mappings of file name to class.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GroovyClassLoader()` creates a GroovyClassLoader using the current Thread's context Class loader as parent.
    `GroovyClassLoader(ClassLoader loader)` creates a GroovyClassLoader using the given ClassLoader as parent
    `GroovyClassLoader(ClassLoader loader, CompilerConfiguration config)` creates a GroovyClassLoader using the given ClassLoader as parent.
    `GroovyClassLoader(ClassLoader parent, CompilerConfiguration config, boolean useConfigurationClasspath)` creates a GroovyClassLoader.
    `GroovyClassLoader(GroovyClassLoader parent)` creates a GroovyClassLoader using the given GroovyClassLoader as parent.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addClasspath(String path)` adds a classpath to this classloader.
    `void` | `addURL(URL url)` adds a URL to the classloader.
    `void` | `clearCache()` Removes all classes from the class cache.
    `protected GroovyClassLoader.ClassCollector` | `createCollector(CompilationUnit unit, SourceUnit su)` creates a ClassCollector for a new compilation.
    `protected CompilationUnit` | `createCompilationUnit(CompilerConfiguration config, CodeSource source)` creates a new CompilationUnit.
    `Class` | `defineClass(ClassNode classNode, String file, String newCodeBase)` Loads the given class node returning the implementation Class.
    `Class` | `defineClass(String name, byte[] b)` open up the super class define that takes raw bytes
    `String` | `generateScriptName()`
    `protected Class` | `getClassCacheEntry(String name)` gets a class from the class cache.
    `protected String[]` | `getClassPath()` gets the currently used classpath.
    `Class[]` | `getLoadedClasses()` Returns all Groovy classes loaded by this class loader.
    `protected PermissionCollection` | `getPermissions(CodeSource codeSource)`
    `GroovyResourceLoader` | `getResourceLoader()`
    `protected long` | `getTimeStamp(Class cls)` gets the time stamp of a given class.
    `protected boolean` | `isRecompilable(Class cls)` Indicates if a class is recompilable.
    `Boolean` | `isShouldRecompile()` gets the currently set recompilation mode.
    `protected boolean` | `isSourceNewer(URL source, Class cls)` Decides if the given source is newer than a class.
    `Class<?>` | `loadClass(String name)`
    `protected Class` | `loadClass(String name, boolean resolve)` Implemented here to check package access prior to returning an already loaded class.
    `Class` | `loadClass(String name, boolean lookupScriptFiles, boolean preferClassOverScript)` loads a class from a file or a parent classloader.
    `Class` | `loadClass(String name, boolean lookupScriptFiles, boolean preferClassOverScript, boolean resolve)` loads a class from a file or a parent classloader.
    `Class` | `parseClass(File file)` Parses the given file into a Java class capable of being run
    `Class` | `parseClass(GroovyCodeSource codeSource)`
    `Class` | `parseClass(GroovyCodeSource codeSource, boolean shouldCacheSource)` Parses the given code source into a Java class.
    `Class` | `parseClass(InputStream in, String fileName)` Deprecated. Prefer using methods taking a Reader rather than an InputStream to avoid wrong encoding issues.
    `Class` | `parseClass(String text)` Parses the given text into a Java class capable of being run
    `Class` | `parseClass(String text, String fileName)` Parses the given text into a Java class capable of being run
    `protected Class` | `recompile(URL source, String className, Class oldClass)` (Re)Compiles the given source.
    `protected void` | `removeClassCacheEntry(String name)` removes a class from the class cache.
    `protected void` | `setClassCacheEntry(Class cls)` sets an entry in the class cache.
    `void` | `setResourceLoader(GroovyResourceLoader resourceLoader)`
    `void` | `setShouldRecompile(Boolean mode)` sets if the recompilation should be enable.

    - ### Methods inherited from class java.net.URLClassLoader

      `close, definePackage, findClass, findResource, findResources, getResourceAsStream, getURLs, newInstance, newInstance`

    - ### Methods inherited from class java.security.SecureClassLoader

      `defineClass, defineClass`

    - ### Methods inherited from class java.lang.ClassLoader

      `clearAssertionStatus, defineClass, defineClass, defineClass, defineClass, definePackage, findLibrary, findLoadedClass, findSystemClass, getClassLoadingLock, getPackage, getPackages, getParent, getResource, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, registerAsParallelCapable, 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

    - #### classCache

          protected final Map<String,Class> classCache

      this cache contains the loaded classes or PARSING, if the class is currently parsed

    - #### sourceCache

          protected final Map<String,Class> sourceCache

      This cache contains mappings of file name to class. It is used to bypass compilation.

  - ### Constructor Detail

    - #### GroovyClassLoader

          public GroovyClassLoader()

      creates a GroovyClassLoader using the current Thread's context Class loader as parent.

    - #### GroovyClassLoader

          public GroovyClassLoader(ClassLoader loader)

      creates a GroovyClassLoader using the given ClassLoader as parent

    - #### GroovyClassLoader

          public GroovyClassLoader(GroovyClassLoader parent)

      creates a GroovyClassLoader using the given GroovyClassLoader as parent. This loader will get the parent's CompilerConfiguration

    - #### GroovyClassLoader

          public GroovyClassLoader(ClassLoader parent,
                           CompilerConfiguration config,
                           boolean useConfigurationClasspath)

      creates a GroovyClassLoader.
      Parameters:
        `parent` - the parent class loader
        `config` - the compiler configuration
        `useConfigurationClasspath` - determines if the configurations classpath should be added

    - #### GroovyClassLoader

          public GroovyClassLoader(ClassLoader loader,
                           CompilerConfiguration config)

      creates a GroovyClassLoader using the given ClassLoader as parent.

  - ### Method Detail

    - #### setResourceLoader

          public void setResourceLoader(GroovyResourceLoader resourceLoader)

    - #### getResourceLoader

          public GroovyResourceLoader getResourceLoader()

    - #### defineClass

          public Class defineClass(ClassNode classNode,
                          String file,
                          String newCodeBase)

      Loads the given class node returning the implementation Class.

      WARNING: this compilation is not synchronized

      Parameters:
        `classNode` -
      Returns:
        a class

    - #### parseClass

          public Class parseClass(File file)
                           throws CompilationFailedException,
                                  IOException

      Parses the given file into a Java class capable of being run
      Parameters:
        `file` - the file name to parse
      Returns:
        the main class defined in the given script
      Throws:
        `CompilationFailedException`
        `IOException`

    - #### parseClass

          public Class parseClass(String text,
                         String fileName)
                           throws CompilationFailedException

      Parses the given text into a Java class capable of being run
      Parameters:
        `text` - the text of the script/class to parse
        `fileName` - the file name to use as the name of the class
      Returns:
        the main class defined in the given script
      Throws:
        `CompilationFailedException`

    - #### parseClass

          public Class parseClass(String text)
                           throws CompilationFailedException

      Parses the given text into a Java class capable of being run
      Parameters:
        `text` - the text of the script/class to parse
      Returns:
        the main class defined in the given script
      Throws:
        `CompilationFailedException`

    - #### generateScriptName

          public String generateScriptName()

    - #### parseClass

          public Class parseClass(InputStream in,
                         String fileName)
                           throws CompilationFailedException

      Deprecated. Prefer using methods taking a Reader rather than an InputStream to avoid wrong encoding issues.
      Throws:
        `CompilationFailedException`

    - #### parseClass

          public Class parseClass(GroovyCodeSource codeSource)
                           throws CompilationFailedException

      Throws:
        `CompilationFailedException`

    - #### parseClass

          public Class parseClass(GroovyCodeSource codeSource,
                         boolean shouldCacheSource)
                           throws CompilationFailedException

      Parses the given code source into a Java class. If there is a class file for the given code source, then no parsing is done, instead the cached class is returned.
      Parameters:
        `shouldCacheSource` - if true then the generated class will be stored in the source cache
      Returns:
        the main class defined in the given script
      Throws:
        `CompilationFailedException`

    - #### getClassPath

          protected String[] getClassPath()

      gets the currently used classpath.
      Returns:
        a String[] containing the file information of the urls
      See Also:
        `URLClassLoader.getURLs()`

    - #### getPermissions

          protected PermissionCollection getPermissions(CodeSource codeSource)

      Overrides:
        `getPermissions` in class `URLClassLoader`

    - #### createCompilationUnit

          protected CompilationUnit createCompilationUnit(CompilerConfiguration config,
                                              CodeSource source)

      creates a new CompilationUnit. If you want to add additional phase operations to the CompilationUnit (for example to inject additional methods, variables, fields), then you should overwrite this method.
      Parameters:
        `config` - the compiler configuration, usually the same as for this class loader
        `source` - the source containing the initial file to compile, more files may follow during compilation
      Returns:
        the CompilationUnit

    - #### createCollector

          protected GroovyClassLoader.ClassCollector createCollector(CompilationUnit unit,
                                                         SourceUnit su)

      creates a ClassCollector for a new compilation.
      Parameters:
        `unit` - the compilationUnit
        `su` - the SourceUnit
      Returns:
        the ClassCollector

    - #### defineClass

          public Class defineClass(String name,
                          byte[] b)

      open up the super class define that takes raw bytes

    - #### loadClass

          public Class loadClass(String name,
                        boolean lookupScriptFiles,
                        boolean preferClassOverScript)
                          throws ClassNotFoundException,
                                 CompilationFailedException

      loads a class from a file or a parent classloader. This method does call loadClass(String, boolean, boolean, boolean) with the last parameter set to false.
      Throws:
        `CompilationFailedException` - if compilation was not successful
        `ClassNotFoundException`

    - #### getClassCacheEntry

          protected Class getClassCacheEntry(String name)

      gets a class from the class cache. This cache contains only classes loaded through this class loader or an InnerLoader instance. If no class is stored for a specific name, then the method should return null.
      Parameters:
        `name` - of the class
      Returns:
        the class stored for the given name
      See Also:
        `removeClassCacheEntry(String)`, `setClassCacheEntry(Class)`, `clearCache()`

    - #### setClassCacheEntry

          protected void setClassCacheEntry(Class cls)

      sets an entry in the class cache.
      Parameters:
        `cls` - the class
      See Also:
        `removeClassCacheEntry(String)`, `getClassCacheEntry(String)`, `clearCache()`

    - #### removeClassCacheEntry

          protected void removeClassCacheEntry(String name)

      removes a class from the class cache.
      Parameters:
        `name` - of the class
      See Also:
        `getClassCacheEntry(String)`, `setClassCacheEntry(Class)`, `clearCache()`

    - #### addURL

          public void addURL(URL url)

      adds a URL to the classloader.
      Overrides:
        `addURL` in class `URLClassLoader`
      Parameters:
        `url` - the new classpath element

    - #### isRecompilable

          protected boolean isRecompilable(Class cls)

      Indicates if a class is recompilable. Recompilable means, that the classloader will try to locate a groovy source file for this class and then compile it again, adding the resulting class as entry to the cache. Giving null as class is like a recompilation, so the method should always return true here. Only classes that are implementing GroovyObject are compilable and only if the timestamp in the class is lower than Long.MAX_VALUE.

      NOTE: First the parent loaders will be asked and only if they don't return a class the recompilation will happen. Recompilation also only happen if the source file is newer.

      Parameters:
        `cls` - the class to be tested. If null the method should return true
      Returns:
        true if the class should be compiled again
      See Also:
        `isSourceNewer(URL, Class)`

    - #### setShouldRecompile

          public void setShouldRecompile(Boolean mode)

      sets if the recompilation should be enable. There are 3 possible values for this. Any value different than null overrides the value from the compiler configuration. true means to recompile if needed false means to never recompile.
      Parameters:
        `mode` - the recompilation mode
      See Also:
        `CompilerConfiguration`

    - #### isShouldRecompile

          public Boolean isShouldRecompile()

      gets the currently set recompilation mode. null means, the compiler configuration is used. False means no recompilation and true means that recompilation will be done if needed.
      Returns:
        the recompilation mode

    - #### loadClass

          public Class loadClass(String name,
                        boolean lookupScriptFiles,
                        boolean preferClassOverScript,
                        boolean resolve)
                          throws ClassNotFoundException,
                                 CompilationFailedException

      loads a class from a file or a parent classloader.
      Parameters:
        `name` - of the class to be loaded
        `lookupScriptFiles` - if false no lookup at files is done at all
        `preferClassOverScript` - if true the file lookup is only done if there is no class
        `resolve` - see `ClassLoader.loadClass(java.lang.String, boolean)`
      Returns:
        the class found or the class created from a file lookup
      Throws:
        `ClassNotFoundException` - if the class could not be found
        `CompilationFailedException` - if the source file could not be compiled

    - #### recompile

          protected Class recompile(URL source,
                        String className,
                        Class oldClass)
                             throws CompilationFailedException,
                                    IOException

      (Re)Compiles the given source. This method starts the compilation of a given source, if the source has changed since the class was created. For this isSourceNewer is called.
      Parameters:
        `source` - the source pointer for the compilation
        `className` - the name of the class to be generated
        `oldClass` - a possible former class
      Returns:
        the old class if the source wasn't new enough, the new class else
      Throws:
        `CompilationFailedException` - if the compilation failed
        `IOException` - if the source is not readable
      See Also:
        `isSourceNewer(URL, Class)`

    - #### loadClass

          public Class<?> loadClass(String name)
                             throws ClassNotFoundException

      Overrides:
        `loadClass` in class `ClassLoader`
      Throws:
        `ClassNotFoundException`

    - #### loadClass

          protected Class loadClass(String name,
                        boolean resolve)
                             throws ClassNotFoundException

      Implemented here to check package access prior to returning an already loaded class.
      Overrides:
        `loadClass` in class `ClassLoader`
      Throws:
        `CompilationFailedException` - if the compilation failed
        `ClassNotFoundException` - if the class was not found
      See Also:
        `ClassLoader.loadClass(java.lang.String, boolean)`

    - #### getTimeStamp

          protected long getTimeStamp(Class cls)

      gets the time stamp of a given class. For groovy generated classes this usually means to return the value of the static field __timeStamp. If the parameter doesn't have such a field, then Long.MAX_VALUE is returned
      Parameters:
        `cls` - the class
      Returns:
        the time stamp

    - #### isSourceNewer

          protected boolean isSourceNewer(URL source,
                              Class cls)
                                   throws IOException

      Decides if the given source is newer than a class.
      Parameters:
        `source` - the source we may want to compile
        `cls` - the former class
      Returns:
        true if the source is newer, false else
      Throws:
        `IOException` - if it is not possible to open an connection for the given source
      See Also:
        `getTimeStamp(Class)`

    - #### addClasspath

          public void addClasspath(String path)

      adds a classpath to this classloader.
      Parameters:
        `path` - is a jar file or a directory.
      See Also:
        `addURL(URL)`

    - #### getLoadedClasses

          public Class[] getLoadedClasses()

      Returns all Groovy classes loaded by this class loader.

      Returns:
        all classes loaded by this class loader

    - #### clearCache

          public void clearCache()

      Removes all classes from the class cache.
      See Also:
        `getClassCacheEntry(String)`, `setClassCacheEntry(Class)`, `removeClassCacheEntry(String)`