Package ch.grengine.engine

Interface Engine

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
LayeredEngine
public interface Engine extends Closeable
Engine interface.

Provides the base functionality for a Grengine, without all the convenience methods.

Since:
1.0
Author:
Alain Stalder, Made in Switzerland.

  • Method Summary

    Modifier and Type
    Method
    Description
    ClassLoader
    asClassLoader(Loader loader)
    returns a class loader based on this engine and the given loader.
    void
    close()
    release metadata for all classed ever loaded using this engine.
    Loader
    getLoader()
    gets the default attached loader.
    Class<?>
    loadClass(Loader loader, Source source, String name)
    loads a class with the given name and from the given source from the given loader.
    Class<?>
    loadClass(Loader loader, String name)
    loads a class by name from the given loader.
    Class<?>
    loadMainClass(Loader loader, Source source)
    loads the main class of the given source from the given loader.
    Loader
    newAttachedLoader()
    creates and gets a new attached loader, backed by the same bytecode as all other shared loaders created by this engine and automatically updated if code layers are set.
    Loader
    newDetachedLoader()
    creates and gets a new detached loader, backed initially by the same bytecode as all attached loaders created by this engine, but not updated if code layers are set.
    void
    setCodeLayers(List<Code> codeLayers)
    sets (replaces) code layers of the engine, based on already compiled code layers.
    void
    setCodeLayersBySource(List<Sources> sourcesLayers)
    sets (replaces) code layers of the engine, based on sources to compile to code layers.

  • Method Details

    • getLoader

      Loader getLoader()
      gets the default attached loader.
      Returns:
      default attached loader
      Since:
      1.0

    • newAttachedLoader

      Loader newAttachedLoader()
      creates and gets a new attached loader, backed by the same bytecode as all other shared loaders created by this engine and automatically updated if code layers are set.
      Returns:
      new attached loader
      Since:
      1.0

    • newDetachedLoader

      Loader newDetachedLoader()
      creates and gets a new detached loader, backed initially by the same bytecode as all attached loaders created by this engine, but not updated if code layers are set.

      For example, a web application might create a detached loader for each new HTTP session: A new loader in order to separate static variables of scripts between sessions (security feature); a detached loader in order to keep code layers constant during the lifetime of the session (consistent behavior of Groovy script calls).

      Returns:
      new detached loader
      Since:
      1.0

    • loadMainClass

      Class<?> loadMainClass(Loader loader, Source source)
      loads the main class of the given source from the given loader.

      Note that if a class with the main class name is available for loading, but was not compiled as part of a set of Source that included the given source, that class will not count for loading.

      Parameters:
      loader - loader
      source - source
      Returns:
      loaded class
      Throws:
      CompileException - if compilation was necessary to load the class and failed
      LoadException - if loading failed, including if the class was not found
      Since:
      1.0

    • loadClass

      Class<?> loadClass(Loader loader, Source source, String name)
      loads a class with the given name and from the given source from the given loader.

      Note that if a class with the given class name is available for loading, but was not compiled as part of a set of Source that included the given source, that class will not count for loading.

      Parameters:
      loader - loader
      source - source
      name - class name
      Returns:
      loaded class
      Throws:
      CompileException - if compilation was necessary to load the class and failed
      LoadException - if loading failed, including if the class was not found
      Since:
      1.0

    • loadClass

      Class<?> loadClass(Loader loader, String name)
      loads a class by name from the given loader.

      Note that a top code cache is not searched in this case, because each set of source has its own top loader.

      Parameters:
      loader - loader
      name - class name
      Returns:
      loaded class
      Throws:
      LoadException - if loading failed, including if the class was not found
      Since:
      1.0

    • setCodeLayers

      void setCodeLayers(List<Code> codeLayers)
      sets (replaces) code layers of the engine, based on already compiled code layers.

      Note that normally it is supported to do this "live", while the engine is used.

      Parameters:
      codeLayers - code layers
      Throws:
      ClassNameConflictException - optionally if the same class name occurs in different code layers or would already be available from a parent class loader
      NullPointerException - if code layers are null
      Since:
      1.0

    • setCodeLayersBySource

      void setCodeLayersBySource(List<Sources> sourcesLayers)
      sets (replaces) code layers of the engine, based on sources to compile to code layers.

      Note that normally it is supported to do this "live", while the engine is used.

      Parameters:
      sourcesLayers - sources layers
      Throws:
      CompileException - if compilation failed
      ClassNameConflictException - optionally if the same class name resulted from compiling different sources layers or would already be available from a parent class loader
      NullPointerException - if sources layers are null
      Since:
      1.0

    • close

      void close()
      release metadata for all classed ever loaded using this engine.

      Allows to remove metadata associated by Groovy (or Java) with a class, which is often necessary to get on-the-fly garbage collection.

      Generally call only when really done using this engine and all loaded classes; subsequently trying to use this engine or its classes results generally in undefined behavior.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Since:
      1.1

    • asClassLoader

      ClassLoader asClassLoader(Loader loader)
      returns a class loader based on this engine and the given loader.

      Note that the returned class loader typically does not load classes itself; it just wraps the engine and its loader.

      Parameters:
      loader - loader
      Returns:
      class loader
      Throws:
      NullPointerException - if the loader is null
      IllegalArgumentException - if the loader does not match the engine
      Since:
      1.3