Class Guard

java.lang.Object

org.codehaus.commons.compiler.sandbox.Guard

public final class Guard
extends Object

Enforces the SandboxLimits of an execution by a SandboxExecutor.

When a SandboxPolicy is set, JANINO inserts calls to tick() at the beginning of every loop body and of every method and constructor body, wraps the dimension of one-dimensional array creations in calls to arrayLength(int, int), and replaces multi-dimensional array creations with calls to newArray(Class, int[]). Sandboxed code may also call these methods itself; that is harmless.

Outside of a SandboxExecutor, these methods do nothing. If the policy requires an executor, then JANINO inserts calls to the "strict" variants tickStrict(), arrayLengthStrict(int, int) and newArrayStrict(Class, int[]) instead, which throw an IllegalStateException outside of a SandboxExecutor.

Once a limit is exceeded, the guard stays tripped: Every subsequent call throws a SandboxLimitExceededError again, so that code cannot continue by catching the error.

Method Summary

Modifier and Type	Method	Description
static int	arrayLength(int length, int elementSize)	Checks whether an array of the given size fits into the remaining memory budget of the current execution.
static int	arrayLengthStrict(int length, int elementSize)	Same as arrayLength(int, int), but throws an IllegalStateException outside of a SandboxExecutor.
static Object	newArray(Class<?> componentType, int[] dimensions)	Creates a multi-dimensional array, like Array.newInstance(Class, int...), after checking whether all the arrays that are created fit into the remaining memory budget of the current execution.
static Object	newArrayStrict(Class<?> componentType, int[] dimensions)	Same as newArray(Class, int[]), but throws an IllegalStateException outside of a SandboxExecutor.
static void	tick()	Counts one tick and, every now and then, checks the limits of the current execution.
static void	tickStrict()	Same as tick(), but throws an IllegalStateException outside of a SandboxExecutor.

Methods inherited from class Object

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

Method Details

tick

public static void tick()

Counts one tick and, every now and then, checks the limits of the current execution.

Throws:

SandboxLimitExceededError - A limit is exceeded

tickStrict

public static void tickStrict()

Same as tick(), but throws an IllegalStateException outside of a SandboxExecutor.

Throws:

SandboxLimitExceededError - A limit is exceeded

arrayLength

public static int arrayLength(int length,
 int elementSize)

Checks whether an array of the given size fits into the remaining memory budget of the current execution.

Parameters:

elementSize - The size of one array element in bytes

Returns:

The length

Throws:

SandboxLimitExceededError - The array would exceed the memory limit, or another limit is exceeded

arrayLengthStrict

public static int arrayLengthStrict(int length,
 int elementSize)

Same as arrayLength(int, int), but throws an IllegalStateException outside of a SandboxExecutor.

Throws:

SandboxLimitExceededError - The array would exceed the memory limit, or another limit is exceeded

newArray

public static Object newArray(Class<?> componentType,
 int[] dimensions)

Creates a multi-dimensional array, like Array.newInstance(Class, int...), after checking whether all the arrays that are created fit into the remaining memory budget of the current execution.

Parameters:

componentType - The type of the elements of the innermost arrays that are created

Throws:

SandboxLimitExceededError - The arrays would exceed the memory limit, or another limit is exceeded

newArrayStrict

public static Object newArrayStrict(Class<?> componentType,
 int[] dimensions)

Same as newArray(Class, int[]), but throws an IllegalStateException outside of a SandboxExecutor.

Throws:

SandboxLimitExceededError - The arrays would exceed the memory limit, or another limit is exceeded