Package 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`, `GroovyEngine.EngineClassLoader`

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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `GroovyClassLoader.ClassCollector`
  Collects classes defined during a compilation unit callback.
  `static class`
  `GroovyClassLoader.InnerLoader`
  Loader used while defining classes during a compilation round.

- ## Field Summary

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GroovyClassLoader()`
  Creates a GroovyClassLoader using the current Thread's context ClassLoader as parent.
  `GroovyClassLoader(GroovyClassLoader parent)`
  Creates a GroovyClassLoader using the given GroovyClassLoader as parent.
  `GroovyClassLoader(ClassLoader parent)`
  Creates a GroovyClassLoader using the given ClassLoader as parent.
  `GroovyClassLoader(ClassLoader parent, CompilerConfiguration config)`
  Creates a GroovyClassLoader using the given ClassLoader as parent.
  `GroovyClassLoader(ClassLoader parent, CompilerConfiguration config, boolean useConfigurationClasspath)`
  Creates a GroovyClassLoader with the default sourceCache.
  `GroovyClassLoader(ClassLoader parent, CompilerConfiguration config, boolean useConfigurationClasspath, FlexibleCache<String,Class> sourceCache)`
  Creates a GroovyClassLoader with a custom sourceCache.

- ## Method Summary

  Modifier and Type
  Method
  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.
  `void`
  `close()`
  Closes this GroovyClassLoader and clears any caches it maintains.
  `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(String name, byte[] bytes)`
  Converts an array of bytes into an instance of `Class`.
  `Class`
  `defineClass(ClassNode classNode, String file, String newCodeBase)`
  Compiles the given `ClassNode` returning the resulting `Class`.
  `String`
  `genEncodingString(CharSequence chars)`
  Generates an encoded string based on the specified characters and the defined encoding algorithm.
  `String`
  `generateScriptName()`
  Generates a unique script name for unnamed parsed sources.
  `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()`
  Returns the resource loader used to resolve Groovy source by script name.
  `protected long`
  `getTimeStamp(Class cls)`
  Gets the time stamp of a given class.
  `boolean`
  `hasCompatibleConfiguration(CompilerConfiguration config)`
  Checks if this class loader has compatible `CompilerConfiguration` with the provided one.
  `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 loader.
  `Class`
  `loadClass(String name, boolean lookupScriptFiles, boolean preferClassOverScript, boolean resolve)`
  Loads a class from a file or a parent loader.
  `Class`
  `parseClass(GroovyCodeSource codeSource)`
  Parses Groovy source described by a `GroovyCodeSource`.
  `Class`
  `parseClass(GroovyCodeSource codeSource, boolean shouldCacheSource)`
  Parses the given code source into a Java class.
  `Class`
  `parseClass(File file)`
  Parses the given file into a Java class capable of being run
  `Class`
  `parseClass(Reader reader, String fileName)`
  Parses Groovy source read from a `Reader`.
  `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)`
  Sets the resource loader used to resolve Groovy source by script name.
  `void`
  `setShouldRecompile(Boolean mode)`
  sets if the recompilation should be enabled.

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

  `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, findClass, findLibrary, findLoadedClass, findResource, findSystemClass, getClassLoadingLock, getDefinedPackage, getDefinedPackages, getName, getPackage, getPackages, getParent, getPlatformClassLoader, getResource, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, getUnnamedModule, isRegisteredAsParallelCapable, registerAsParallelCapable, resolveClass, resources, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners`

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### classCache

    protected final EvictableCache<String,Class> classCache
    This cache contains the loaded classes or PARSING, if the class is currently parsed.

  - ### sourceCache

    protected final FlexibleCache<String,Class> sourceCache
    This cache contains mappings of file name to class. It is used to bypass compilation.

- ## Constructor Details

  - ### GroovyClassLoader

    public GroovyClassLoader()
    Creates a GroovyClassLoader using the current Thread's context ClassLoader as parent.

  - ### GroovyClassLoader

    public GroovyClassLoader(ClassLoader parent)
    Creates a GroovyClassLoader using the given ClassLoader as parent.

  - ### GroovyClassLoader

    public GroovyClassLoader(GroovyClassLoader parent)
    Creates a GroovyClassLoader using the given GroovyClassLoader as parent. The new loader will get the parent's CompilerConfiguration.

  - ### GroovyClassLoader

    public GroovyClassLoader(ClassLoader parent, CompilerConfiguration config)
    Creates a GroovyClassLoader using the given ClassLoader as parent.

  - ### GroovyClassLoader

    public GroovyClassLoader(ClassLoader parent, CompilerConfiguration config, boolean useConfigurationClasspath)
    Creates a GroovyClassLoader with the default sourceCache.
    Parameters:
      `parent` - the parent class loader
      `config` - the compiler configuration
      `useConfigurationClasspath` - determines if the configurations classpath should be added

  - ### GroovyClassLoader

    public GroovyClassLoader(ClassLoader parent, CompilerConfiguration config, boolean useConfigurationClasspath, FlexibleCache<String,Class> sourceCache)
    Creates a GroovyClassLoader with a custom sourceCache.
    Parameters:
      `parent` - the parent class loader
      `config` - the compiler configuration
      `useConfigurationClasspath` - determines if the configurations classpath should be added
      `sourceCache` - the source cache to use

- ## Method Details

  - ### setResourceLoader

    public void setResourceLoader(GroovyResourceLoader resourceLoader)
    Sets the resource loader used to resolve Groovy source by script name.
    Parameters:
      `resourceLoader` - the resource loader to use

  - ### getResourceLoader

    public GroovyResourceLoader getResourceLoader()
    Returns the resource loader used to resolve Groovy source by script name.
    Returns:
      the current resource loader

  - ### defineClass

    public Class defineClass(String name, byte[] bytes) throws ClassFormatError
    Converts an array of bytes into an instance of `Class`. Before the class can be used it must be resolved.
    Throws:
      `ClassFormatError`

  - ### defineClass

    public Class defineClass(ClassNode classNode, String file, String newCodeBase)
    Compiles the given `ClassNode` returning the resulting `Class`.

    WARNING: compilation is not synchronized

  - ### hasCompatibleConfiguration

    public boolean hasCompatibleConfiguration(CompilerConfiguration config)
    Checks if this class loader has compatible `CompilerConfiguration` with the provided one.
    Parameters:
      `config` - the compiler configuration to test for compatibility
    Returns:
      `true` if the provided config is exactly the same instance of `CompilerConfiguration` as this loader has

  - ### 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`

  - ### parseClass

    public Class parseClass(Reader reader, String fileName) throws CompilationFailedException
    Parses Groovy source read from a `Reader`.
    Parameters:
      `reader` - the reader supplying source text
      `fileName` - the logical script name
    Returns:
      the main class defined by the source
    Throws:
      `CompilationFailedException` - if compilation fails

  - ### parseClass

    public Class parseClass(GroovyCodeSource codeSource) throws CompilationFailedException
    Parses Groovy source described by a `GroovyCodeSource`.
    Parameters:
      `codeSource` - the code source to compile
    Returns:
      the main class defined by the source
    Throws:
      `CompilationFailedException` - if compilation fails

  - ### 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`

  - ### generateScriptName

    public String generateScriptName()
    Generates a unique script name for unnamed parsed sources.
    Returns:
      a unique script name ending in `.groovy`

  - ### 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

  - ### 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 enabled. There are 3 possible values for this. Any value different from 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) throws ClassNotFoundException
    Overrides:
      `loadClass` in class `ClassLoader`
    Throws:
      `ClassNotFoundException`
    See Also:
      - `ClassLoader.loadClass(java.lang.String,boolean)`

  - ### loadClass

    protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException, CompilationFailedException
    Implemented here to check package access prior to returning an already-loaded class.
    Overrides:
      `loadClass` in class `ClassLoader`
    Throws:
      `ClassNotFoundException` - if class could not be found
      `CompilationFailedException` - if compilation of script failed

  - ### loadClass

    public Class loadClass(String name, boolean lookupScriptFiles, boolean preferClassOverScript) throws ClassNotFoundException, CompilationFailedException
    Loads a class from a file or a parent loader. This method delegates to:

         loadClass(name, lookupScriptFiles, preferClassOverScript, false);

    Throws:
      `ClassNotFoundException` - if class could not be found
      `CompilationFailedException` - if compilation of script failed

  - ### loadClass

    public Class loadClass(String name, boolean lookupScriptFiles, boolean preferClassOverScript, boolean resolve) throws ClassNotFoundException, CompilationFailedException
    Loads a class from a file or a parent loader.
    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 class could not be found
      `CompilationFailedException` - if compilation of script failed

  - ### 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)`

  - ### 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. Last-modified is read via `URLStreams.getLastModified(URL)`. A class is considered current until the source is newer by more than `CompilerConfiguration.getMinimumRecompilationInterval()`.
    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 a 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.

    In addition to internal caches this method also clears any previously set MetaClass information for the given set of classes being removed.

    See Also:
      - `getClassCacheEntry(String)`
      - `setClassCacheEntry(Class)`
      - `removeClassCacheEntry(String)`

  - ### close

    public void close() throws IOException
    Closes this GroovyClassLoader and clears any caches it maintains.

    No use should be made of this instance after this method is invoked. Any classes that are already loaded are still accessible.

    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Overrides:
      `close` in class `URLClassLoader`
    Throws:
      `IOException`
    Since:
      2.5.0
    See Also:
      - `URLClassLoader.close()`
      - `clearCache()`

  - ### genEncodingString

    public String genEncodingString(CharSequence chars)
    Generates an encoded string based on the specified characters and the defined encoding algorithm. Supported algorithms currently are "md5" and sha256". An exception is throw for an unknown algorithm or if the JVM doesn't support the algorithm.
    Parameters:
      `chars` - The characters to encode.
    Returns:
      The encoded string.