JexlSandbox (Apache Commons JEXL 3.7.0 API)
Description: declaration: package: org.apache.commons.jexl3.introspection, class: JexlSandbox

Package org.apache.commons.jexl3.introspection

# Class JexlSandbox

java.lang.Object
org.apache.commons.jexl3.introspection.JexlSandbox

public final class JexlSandbox extends Object
A sandbox describes permissions on a class by explicitly allowing or forbidding access to methods and properties through "allowlists" and "blocklists".

A allowlist explicitly allows methods/properties for a class;

- If a allowlist is empty and thus does not contain any names, all properties/methods are allowed for its class.
- If it is not empty, the only allowed properties/methods are the ones contained.

A blocklist explicitly forbids methods/properties for a class;

- If a blocklist is empty and thus does not contain any names, all properties/methods are forbidden for its class.
- If it is not empty, the only forbidden properties/methods are the ones contained.

Permissions are composed of three lists, read, write, execute, each being "allow" or "block":

- read controls readable properties
- write controls writable properties
- execute controls executable methods and constructor

When specified, permissions - allow or block lists - can be created inheritable on interfaces or classes and thus applicable to their implementations or derived classes; the sandbox must be created with the 'inheritable' flag for this behavior to be triggered. Note that even in this configuration, it is still possible to add non-inheritable permissions. Adding inheritable lists to a non inheritable sandbox has no added effect; permissions only apply to their specified class.

Note that a JexlUberspect always uses a copy of the JexlSandbox used to built it preventing permission changes after its instantiation.

Since:
  3.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `JexlSandbox.BlackSet`
  Deprecated.
  since 3.2, use `JexlSandbox.BlockSet`
  `static class`
  `JexlSandbox.Names`
  A base set of names.
  `static final class`
  `JexlSandbox.Permissions`
  Contains the allow or block lists for properties and methods for a given class.
  `static final class`
  `JexlSandbox.WhiteSet`
  Deprecated.
  since 3.2, use `JexlSandbox.AllowSet`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `NULL`
  The marker string for explicitly disallowed null properties.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JexlSandbox()`
  Creates a new default sandbox.
  `JexlSandbox(boolean ab)`
  Creates a new default sandbox.
  `JexlSandbox(boolean ab, boolean inh)`
  Creates a sandbox.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `JexlSandbox.Permissions`
  `allow(String clazz)`
  Creates a new set of permissions based on allow lists for methods and properties for a given class.
  `JexlSandbox.Permissions`
  `black(String clazz)`
  Deprecated.
  3.3
  `JexlSandbox.Permissions`
  `block(String clazz)`
  Creates a new set of permissions based on block lists for methods and properties for a given class.
  `JexlSandbox`
  `copy()`
  Gets a copy of this sandbox
  `String`
  `execute(Class<?> clazz, String name)`
  Gets the execute permission value for a given method of a class.
  `String`
  `execute(String clazz, String name)`
  Deprecated.
  3.3
  `JexlSandbox.Permissions`
  `get(Class<?> clazz)`
  Gets the permissions associated to a class.
  `JexlSandbox.Permissions`
  `get(String clazz)`
  Gets the set of permissions associated to a class.
  `JexlSandbox.Permissions`
  `permissions(String clazz, boolean readFlag, boolean writeFlag, boolean executeFlag)`
  Creates the set of permissions for a given class.
  `JexlSandbox.Permissions`
  `permissions(String clazz, boolean inhf, boolean readf, boolean writef, boolean execf)`
  Creates the set of permissions for a given class.
  `String`
  `read(Class<?> clazz, String name)`
  Gets the read permission value for a given property of a class.
  `String`
  `read(String clazz, String name)`
  Deprecated.
  3.3
  `JexlSandbox.Permissions`
  `white(String clazz)`
  Deprecated.
  3.3
  `String`
  `write(Class<?> clazz, String name)`
  Gets the write permission value for a given property of a class.
  `String`
  `write(String clazz, String name)`
  Deprecated.
  3.3

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

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

- ## Field Details

  - ### NULL

    public static final String NULL
    The marker string for explicitly disallowed null properties.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### JexlSandbox

    public JexlSandbox()
    Creates a new default sandbox.

    In the absence of explicit permissions on a class, the sandbox is an allow-box, allow-listing that class for all permissions (read, write and execute).

  - ### JexlSandbox

    public JexlSandbox(boolean ab)
    Creates a new default sandbox.

    A allow-box considers no permissions as "everything is allowed" when a block-box considers no permissions as "nothing is allowed".

    Parameters:
      `ab` - whether this sandbox is allow (true) or block (false) if no permission is explicitly defined for a class.
    Since:
      3.1

  - ### JexlSandbox

    public JexlSandbox(boolean ab, boolean inh)
    Creates a sandbox.
    Parameters:
      `ab` - whether this sandbox is allow (true) or block (false)
      `inh` - whether permissions on interfaces and classes are inherited (true) or not (false)
    Since:
      3.2

- ## Method Details

  - ### allow

    public JexlSandbox.Permissions allow(String clazz)
    Creates a new set of permissions based on allow lists for methods and properties for a given class.

    The sandbox inheritance property will apply to the permissions created by this method

    Parameters:
      `clazz` - the allowed class name
    Returns:
      the permissions instance

  - ### block

    public JexlSandbox.Permissions block(String clazz)
    Creates a new set of permissions based on block lists for methods and properties for a given class.

    The sandbox inheritance property will apply to the permissions created by this method

    Parameters:
      `clazz` - the blocked class name
    Returns:
      the permissions instance

  - ### copy

    public JexlSandbox copy()
    Gets a copy of this sandbox
    Returns:
      a copy of this sandbox

  - ### execute

    public String execute(Class<?> clazz, String name)
    Gets the execute permission value for a given method of a class.
    Parameters:
      `clazz` - the class
      `name` - the method name
    Returns:
      null if not allowed, the name of the method to use otherwise

  - ### execute

    @Deprecated public String execute(String clazz, String name)
    Deprecated.
    3.3
    Gets the execute permission value for a given method of a class.
    Parameters:
      `clazz` - the class name
      `name` - the method name
    Returns:
      null if not allowed, the name of the method to use otherwise

  - ### get

    public JexlSandbox.Permissions get(String clazz)
    Gets the set of permissions associated to a class.
    Parameters:
      `clazz` - the class name
    Returns:
      the defined permissions or an all-allow permission instance if none were defined

  - ### get

    public JexlSandbox.Permissions get(Class<?> clazz)
    Gets the permissions associated to a class.
    Parameters:
      `clazz` - the class
    Returns:
      the permissions

  - ### permissions

    public JexlSandbox.Permissions permissions(String clazz, boolean readFlag, boolean writeFlag, boolean executeFlag)
    Creates the set of permissions for a given class.

    The sandbox inheritance property will apply to the permissions created by this method

    Parameters:
      `clazz` - the class for which these permissions apply
      `readFlag` - whether the readable property list is allow - true - or block - false -
      `writeFlag` - whether the writable property list is allow - true - or block - false -
      `executeFlag` - whether the executable method list is allow - true - or block - false -
    Returns:
      the set of permissions

  - ### permissions

    public JexlSandbox.Permissions permissions(String clazz, boolean inhf, boolean readf, boolean writef, boolean execf)
    Creates the set of permissions for a given class.
    Parameters:
      `clazz` - the class for which these permissions apply
      `inhf` - whether these permissions are inheritable
      `readf` - whether the readable property list is allow - true - or block - false -
      `writef` - whether the writable property list is allow - true - or block - false -
      `execf` - whether the executable method list is allow - true - or block - false -
    Returns:
      the set of permissions

  - ### read

    public String read(Class<?> clazz, String name)
    Gets the read permission value for a given property of a class.
    Parameters:
      `clazz` - the class
      `name` - the property name
    Returns:
      null (or NULL if name is null) if not allowed, the name of the property to use otherwise

  - ### write

    public String write(Class<?> clazz, String name)
    Gets the write permission value for a given property of a class.
    Parameters:
      `clazz` - the class
      `name` - the property name
    Returns:
      null (or NULL if name is null) if not allowed, the name of the property to use otherwise

  - ### write

    @Deprecated public String write(String clazz, String name)
    Deprecated.
    3.3
    Gets the write permission value for a given property of a class.
    Parameters:
      `clazz` - the class name
      `name` - the property name
    Returns:
      null if not allowed, the name of the property to use otherwise

  - ### black

    @Deprecated public JexlSandbox.Permissions black(String clazz)
    Deprecated.
    3.3
    Use block() instead.
    Parameters:
      `clazz` - the blocked class name
    Returns:
      the permissions instance

  - ### read

    @Deprecated public String read(String clazz, String name)
    Deprecated.
    3.3
    Gets the read permission value for a given property of a class.
    Parameters:
      `clazz` - the class name
      `name` - the property name
    Returns:
      null if not allowed, the name of the property to use otherwise

  - ### white

    @Deprecated public JexlSandbox.Permissions white(String clazz)
    Deprecated.
    3.3
    Use allow() instead.
    Parameters:
      `clazz` - the allowed class name
    Returns:
      the permissions instance