Aussom is designed to be embedded inside larger Java applications. There are two supported ways to do that, and the right one depends on how much control you need over the runtime.
This page is a one-screen overview to help you pick. Once you've chosen, follow the linked deep-dive guide for the full how-to.
javax.script)Aussom ships with a JSR 223 ScriptEngine implementation. You go
through the standard Java scripting interfaces:
ScriptEngineManager, ScriptEngine, Bindings, Compilable,
Invocable. The engine is auto-discovered from the classpath; no
configuration code is needed.
Use this when:
eval,
put, get, compile, invokeFunction.ScriptContext writers cover what you need.Read the full guide: Embedding Aussom via JSR 223
Engine API (standard embedding)The lower-level path. You construct com.aussom.Engine yourself,
hand it a SecurityManagerInt, parse sources, and either call
run() or dispatch into Aussom code by name. This is what the
JSR 223 layer is built on top of, and what the Aussom CLI uses.
Use this when:
SecurityManagerImpl, gate operations behind your own property
names, flip permissions on or off at runtime.c, sys, math, etc.).aussom-base.Read the full guide: Embedding Aussom Directly
| Concern | JSR 223 | Direct Engine API |
|---|---|---|
| Setup | Auto-discovered via SPI | new Engine(SecurityManagerInt) |
| Run a snippet | engine.eval("...") |
parseString(...) + run() |
| Pass values in | engine.put(k, v) -> this.bindings["k"] |
Bindings on the synthetic class, or args |
| Get values out | Return from eval |
AussomType returned from method calls |
| Pre-compile | Compilable.compile(...) |
parseString once, instantiate / call later |
| Call by name | Invocable.invokeFunction(...) |
astClass.call(env, false, name, args) |
| Custom security policy | Subclass the factory | First-class -- always pick a SecurityManagerInt |
| Wrap Java classes for scripts | Limited (opaque object passthrough) | Full -- the stdlib pattern |
| Control over parse lifecycle | Hidden behind eval / compile |
Full control: multiple parses, includes, etc. |
| Output routing | Per-call ScriptContext writer |
Per-thread console.get().register(LoggingInt) |
| Threading model | MULTITHREADED advertised; engine handles serialization |
You manage Environment / CallStack per call |
| Migration cost | Small -- standard interfaces | Larger -- bespoke API |
"I just want to run user scripts and pass a few values." -> JSR 223.
"I want to expose my host's services to scripts." -> Direct Engine API. You'll be writing extern classes.
"I need a lockdown sandbox for untrusted code."
-> Direct Engine API. Build a custom SecurityManagerInt.
"My host already runs JavaScript / Groovy via JSR 223 and I want Aussom too." -> JSR 223. Drop the Aussom jar on the classpath; nothing else changes in your scripting framework.
"I'm building the next Aussom-aware tool (CLI, IDE plugin,
REPL, browser runtime)."
-> Direct Engine API. Look at Main.java and the
aussom-script / aussom repos as references.
You can also use both. The JSR 223 layer is layered on top of the
same Engine class, and a host that mostly uses JSR 223 can still
reach the underlying engine via ((AussomScriptEngine) engine) .getAussomEngine() for the rare advanced case.
javax.script integration, end-to-end.Engine API, security manager customization, extern
class authoring, threading model.