Interface Control

All Known Implementing Classes:

ClassReferenceControl, ConstantPoolControl, TimeLimitControl

public interface Control

Monitors, modifies, and/or restricts the execution of scripts running in a JavaBox.

Script controls are allowed to modify a script's generated bytecode, for example, to prevent linking to certain classes, weave in periodic checsks, etc.

Control Contexts

Controls are given per-container and per-execution contexts, to which they may create and attach their own private state. The lifecycle methods initialize() and shutdown() are for managing per-container context, and startExecution() and finishExecution() are for per-execution context. An "execution" happens with script snippets that contain statements or expressions; snippets that simply declare classes, etc., do not execute (not immediately, anyway).

If the return value from a script execution is an invokable object, then any subsequent invocations into that object's methods will not have any per-container or per-execution context, because that execution will be happening outside of the container. However, a control could use other tricks to regain context outside of the container, e.g., wrapping return values in a proxy interface, static method invocations that provide a unique symbolic key, etc.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final record	Control.ContainerContext	The per-JavaBox context associated with a Control.
static final record	Control.ExecutionContext	The per-execution context associated with a Control.

Method Summary

Modifier and Type	Method	Description
default void	finishExecution(Control.ExecutionContext context, Object result, Throwable error)	Notification that the execution of a script snippet has finished, either successfully or by throwing an exception.
default Object	initialize(JavaBox box)	Initialize this control for the given JavaBox and return any associated private context.
default byte[]	modifyBytecode(ClassDesc name, byte[] bytecode)	Apply this control to the given class which was generated from a script.
default void	shutdown(Control.ContainerContext context)	Shutdown this control for the given JavaBox.
default Object	startExecution(Control.ContainerContext context)	Notification that the execution of a script snippet has started.

Method Details

initialize

default Object initialize(JavaBox box)

Initialize this control for the given JavaBox and return any associated private context.

Controls may create their own private context on a per-JavaBox basis using this method. If no private context is needed, this method may return null.

This method should also perform any other required per-container initialization, for example, loading custom support classes.

When the given JavaBox is closed, shutdown() will be invoked with a Control.ContainerContext referencing the returned context object.

The default implementation in Control returns null.

Parameters:

box - the JavaBox instance

Returns:

this control's private context for the given JavaBox, or null if none is needed

Throws:

JavaBoxException - if some error occurs

shutdown

default void shutdown(Control.ContainerContext context)

Shutdown this control for the given JavaBox.

The default implementation in Control does nothing.

Parameters:

context - the container context for this control

modifyBytecode

default byte[] modifyBytecode(ClassDesc name,
 byte[] bytecode)

Apply this control to the given class which was generated from a script.

The default implementation in Control just returns bytecode.

Parameters:

name - the name of the class being added

bytecode - the Java bytecode of the class being added

Returns:

replacement java bytecode; must not be null

Throws:

ControlViolationException - if the class contains something rejected by this control

JavaBoxException - if some other error occurs

startExecution

default Object startExecution(Control.ContainerContext context)

Notification that the execution of a script snippet has started.

This method should initialize this control for the new execution and return any associated private context.

This method should also perform any required per-execution initialization, for example, initializing resource counters, etc.

The current thread will be the thread that is actually executing the script snippet. A Control.ExecutionContext will be created using the returned private context and made available in this thread via JavaBox.executionContextFor(), and also provided to finishExecution().

The default implementation in Control returns null.

Parameters:

context - the container context for this control

finishExecution

default void finishExecution(Control.ExecutionContext context,
 Object result,
 Throwable error)

Notification that the execution of a script snippet has finished, either successfully or by throwing an exception.

The current thread will be the thread that actually executed the snippet.

The default implementation in Control does nothing.

Parameters:

context - the execution context for this control

result - the return value from the successful execution of an expression snippet, otherwise null

error - the exception thrown by snippet execution if there was an error, otherwise null