Package org.apache.groovy.util

# Class JavaShell

java.lang.Object
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
  Description
  `JavaShell()`
  Initializes a newly created `JavaShell` object
  `JavaShell(ClassLoader parentClassLoader)`
  Initializes a newly created `JavaShell` object

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Class<?>`
  `compile(String className, Iterable<String> options, String src)`
  Compile and return the main class
  `Class<?>`
  `compile(String className, String src)`
  Compile and return the main class
  `Map<String,Class<?>>`
  `compileAll(String className, Iterable<String> options, String src)`
  Compile and return all classes
  `Map<String,Class<?>>`
  `compileAll(String className, String src)`
  Compile and return all classes
  `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.
  `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.
  `org.apache.groovy.util.JavaShell.JavaShellClassLoader`
  `getClassLoader()`
  When and only when `compile(String, String)` or `compileAll(String, String)` is invoked, returned class loader will reference the compiled classes.
  `void`
  `run(String className, Iterable<String> options, String src, String... args)`
  Run main method
  `void`
  `run(String className, String src, String... args)`
  Run main method

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

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

- ## Constructor Details

  - ### JavaShell

    public JavaShell()
    Initializes a newly created `JavaShell` object

  - ### JavaShell

    public JavaShell(ClassLoader parentClassLoader)
    Initializes a newly created `JavaShell` object
    Parameters:
      `parentClassLoader` - the parent class loader for delegation

- ## Method Details

  - ### run

    public void run(String className, Iterable<String> options, String src, String... args) throws Throwable
    Run main method
    Parameters:
      `className` - the main class name
      `options` - compiler options
      `src` - the source code
      `args` - arguments for main method
    Throws:
      `Throwable`

  - ### run

    public void run(String className, String src, String... args) throws Throwable
    Run main method
    Parameters:
      `className` - the main class name
      `src` - the source code
      `args` - arguments for main method
    Throws:
      `Throwable`

  - ### compile

    public Class<?> compile(String className, Iterable<String> options, String src) throws IOException, ClassNotFoundException
    Compile and return the main class
    Parameters:
      `className` - the main class name
      `options` - compiler options
      `src` - the source code
    Returns:
      the main class
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### compile

    public Class<?> compile(String className, String src) throws IOException, ClassNotFoundException
    Compile and return the main class
    Parameters:
      `className` - the main class name
      `src` - the source code
    Returns:
      the main class
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### compileAll

    public Map<String,Class<?>> compileAll(String className, Iterable<String> options, String src) throws IOException, ClassNotFoundException
    Compile and return all classes
    Parameters:
      `className` - the main class name
      `options` - compiler options
      `src` - the source code
    Returns:
      all classes
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### compileAll

    public Map<String,Class<?>> compileAll(String className, String src) throws IOException, ClassNotFoundException
    Compile and return all classes
    Parameters:
      `className` - the main class name
      `src` - the source code
    Returns:
      all classes
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### compileAllTo

    @Incubating public Map<String,Path> compileAllTo(String className, Iterable<String> options, String src, Path outputDir) throws IOException
    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()`.
    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)
    Throws:
      `IOException` - if writing a class file fails
      `JavaShellCompilationException` - if the source fails to compile
    Since:
      6.0.0

  - ### compileAllTo

    @Incubating public Map<String,Path> compileAllTo(String className, String src, Path outputDir) throws IOException
    Convenience overload of `compileAllTo(String, Iterable, String, Path)` that compiles with no extra compiler options.
    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
    Throws:
      `IOException` - if writing a class file fails
      `JavaShellCompilationException` - if the source fails to compile
    Since:
      6.0.0

  - ### getClassLoader

    public org.apache.groovy.util.JavaShell.JavaShellClassLoader getClassLoader()
    When and only when `compile(String, String)` or `compileAll(String, String)` is invoked, returned class loader will reference the compiled classes.