Package: org.apache.groovy.util

## [Java] Class JavaShell

- org.apache.groovy.util.JavaShell

-     public class JavaShell
      extends Object

  A shell for compiling or running pure Java code in-memory using the platform's JavaCompiler. Compiled bytes are kept in a backing class loader (see getClassLoader()) and can optionally be written to disk via compileAllTo(String, Iterable, String, Path).

  The `className` argument supplied to `run`, `compile`, `compileAll` and `compileAllTo` must be the fully-qualified binary name and match any `package` declaration in `src`: if the source begins with `package com.example;` and declares class `Foo`, pass `"com.example.Foo"`, not `"Foo"`. A mismatch produces a standard `javac` diagnostic ("class X is public, should be declared in a file named X.java"). Source with no `package` declaration takes a simple name (e.g. `"Foo"`); `compileAllTo` writes such a class directly under `outputDir` as `Foo.class`, while packaged classes land under the matching subdirectory (e.g. `<outputDir>/com/example/Foo.class`).

  The `Iterable<String>` compiler-options parameter accepted by `run`, `compile`, `compileAll` and `compileAllTo` uses the same flags as the `javac` command line, with one token per element (so `"-source"` and `"17"` are two entries, not a single `"-source 17"` string). Examples:

  - `List.of("--release", "17")` — target a specific Java release
  - `List.of("-source", "17", "-target", "17")` — separate source/target levels
  - `List.of("-parameters")` — retain formal parameter names
  - `List.of("-g")` — emit debug information
  - `List.of("-Xlint:all", "-Werror")` — enable all warnings and treat them as errors
  - `List.of("-proc:none")` — disable annotation processing
  - `List.of("-classpath", extraJars)` — extend the compile-time class path
  The `-d` flag has no effect: in-memory output is always captured (and is additionally written to disk by `compileAllTo`). See the `javac` documentation for the complete list of supported flags.

- - ### Constructor Summary

    Constructors
    Constructor and description
    `JavaShell()` Initializes a newly created `JavaShell` object
    `JavaShell(ClassLoader parentClassLoader)` Initializes a newly created `JavaShell` object

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public Class<?>` | `compile(String className, Iterable<String> options, String src)` Compile and return the main class
    `` | `public Class<?>` | `compile(String className, String src)` Compile and return the main class
    `` | `public Map<String, Class<?>>` | `compileAll(String className, Iterable<String> options, String src)` Compile and return all classes
    `` | `public Map<String, Class<?>>` | `compileAll(String className, String src)` Compile and return all classes
    `` | `public Map<String, Path>` | `compileAllTo(String className, Iterable<String> options, String src, Path outputDir)` Compile `src` and write each resulting class file beneath `outputDir` as a standard package directory tree (e.g.
    `` | `public Map<String, Path>` | `compileAllTo(String className, String src, Path outputDir)` Convenience overload of compileAllTo(String, Iterable, String, Path) that compiles with no extra compiler options.
    `` | `public JavaShell.JavaShellClassLoader` | `getClassLoader()` When and only when compile(String, String) or compileAll(String, String) is invoked, returned class loader will reference the compiled classes.
    `` | `public void` | `run(String className, Iterable<String> options, String src, String args)` Run main method
    `` | `public void` | `run(String className, String src, String args)` Run main method

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### public JavaShell()

      Initializes a newly created `JavaShell` object

    - #### public JavaShell(ClassLoader parentClassLoader)

      Initializes a newly created `JavaShell` object

      Parameters:
        `parentClassLoader` - the parent class loader for delegation

  - ### Method Detail

    - #### public Class<?> compile(String className, Iterable<String> options, String src)

      Compile and return the main class

      Parameters:
        `className` - the main class name
        `options` - compiler options
        `src` - the source code
      Returns:
        the main class

    - #### public Class<?> compile(String className, String src)

      Compile and return the main class

      Parameters:
        `className` - the main class name
        `src` - the source code
      Returns:
        the main class

    - #### public Map<String, Class<?>> compileAll(String className, Iterable<String> options, String src)

      Compile and return all classes

      Parameters:
        `className` - the main class name
        `options` - compiler options
        `src` - the source code
      Returns:
        all classes

    - #### public Map<String, Class<?>> compileAll(String className, String src)

      Compile and return all classes

      Parameters:
        `className` - the main class name
        `src` - the source code
      Returns:
        all classes

    - #### @Incubating
      public Map<String, Path> compileAllTo(String className, Iterable<String> options, String src, Path outputDir)

      Compile `src` and write each resulting class file beneath `outputDir` as a standard package directory tree (e.g. `com.example.Foo$Bar` becomes `<outputDir>/com/example/Foo$Bar.class`). Intermediate directories are created as needed; existing class files at those locations are overwritten. The compiled classes also remain available through getClassLoader().

      throws:
        IOException if writing a class file fails
      throws:
        JavaShellCompilationException if the source fails to compile
      Parameters:
        `className` - the main class name (binary name, e.g. `com.example.Foo`)
        `options` - compiler options; see the class-level documentation for the expected format
        `src` - the source code
        `outputDir` - root directory under which class files are written; created if absent
      Returns:
        a map from binary class name to the Path of the written `.class` file, iterating in the order the compiler emitted them (stable across invocations for the same source, but JDK-dependent — inner and auxiliary classes commonly appear before the enclosing class)
      Since:
        6.0.0

    - #### @Incubating
      public Map<String, Path> compileAllTo(String className, String src, Path outputDir)

      Convenience overload of compileAllTo(String, Iterable, String, Path) that compiles with no extra compiler options.

      throws:
        IOException if writing a class file fails
      throws:
        JavaShellCompilationException if the source fails to compile
      Parameters:
        `className` - the main class name (binary name)
        `src` - the source code
        `outputDir` - root directory under which class files are written; created if absent
      Returns:
        a map from binary class name to the Path of the written `.class` file
      Since:
        6.0.0

    - #### public JavaShell.JavaShellClassLoader getClassLoader()

      When and only when compile(String, String) or compileAll(String, String) is invoked, returned class loader will reference the compiled classes.

    - #### public void run(String className, Iterable<String> options, String src, String args)

      Run main method

      Parameters:
        `className` - the main class name
        `options` - compiler options
        `src` - the source code
        `args` - arguments for main method

    - #### public void run(String className, String src, String args)

      Run main method

      Parameters:
        `className` - the main class name
        `src` - the source code
        `args` - arguments for main method