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 and Description
    --- | ---
    `static class` | `JexlSandbox.BlackSet` Deprecated. since 3.2, use `BlockSet`
    `static class` | `JexlSandbox.Names` A base set of names.
    `static class` | `JexlSandbox.Permissions` Contains the allow or block lists for properties and methods for a given class.
    `static class` | `JexlSandbox.WhiteSet` Deprecated. since 3.2, use `AllowSet`

  - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `JexlSandbox()` Creates a new default sandbox.
    `` | `JexlSandbox(boolean ab)` Creates a new default sandbox.
    `` | `JexlSandbox(boolean ab, boolean inh)` Creates a sandbox.
    `protected` | `JexlSandbox(boolean ab, boolean inh, Map<String,JexlSandbox.Permissions> map)` Creates a sandbox based on an existing permissions map.
    `protected` | `JexlSandbox(boolean ab, Map<String,JexlSandbox.Permissions> map)` Deprecated.
    `protected` | `JexlSandbox(Map<String,JexlSandbox.Permissions> map)` Deprecated.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and 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.
    `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()`
    `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.
    `JexlSandbox.Permissions` | `get(Class<?> clazz)` Get 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.
    `JexlSandbox.Permissions` | `white(String clazz)` Deprecated.
    `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.

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

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

- - ### Field Detail

    - #### NULL

          public static final String NULL

      The marker string for explicitly disallowed null properties.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### JexlSandbox

          public JexlSandbox()

      Creates a new default sandbox.

      In the absence of explicit permissions on a class, the sandbox is a 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

    - #### JexlSandbox

          @Deprecated
          protected JexlSandbox(Map<String,JexlSandbox.Permissions> map)

      Deprecated.
      Creates a sandbox based on an existing permissions map.
      Parameters:
        `map` - the permissions map

    - #### JexlSandbox

          @Deprecated
          protected JexlSandbox(boolean ab,
                                            Map<String,JexlSandbox.Permissions> map)

      Deprecated.
      Creates a sandbox based on an existing permissions map.
      Parameters:
        `ab` - whether this sandbox is allow (true) or block (false)
        `map` - the permissions map
      Since:
        3.1

    - #### JexlSandbox

          protected JexlSandbox(boolean ab,
                                boolean inh,
                                Map<String,JexlSandbox.Permissions> map)

      Creates a sandbox based on an existing permissions map.
      Parameters:
        `ab` - whether this sandbox is allow (true) or block (false)
        `inh` - whether permissions are inherited, default false
        `map` - the permissions map
      Since:
        3.2

  - ### Method Detail

    - #### copy

          public JexlSandbox copy()

      Returns:
        a copy of this sandbox

    - #### 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

    - #### read

          @Deprecated
          public String read(String clazz,
                                         String name)

      Deprecated.
      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

    - #### 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.
      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

    - #### 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.
      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

    - #### 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

    - #### 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

    - #### white

          @Deprecated
          public JexlSandbox.Permissions white(String clazz)

      Deprecated.
      Use allow() instead.
      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

    - #### black

          @Deprecated
          public JexlSandbox.Permissions black(String clazz)

      Deprecated.
      Use block() instead.
      Parameters:
        `clazz` - the allowed class name
      Returns:
        the permissions instance

    - #### 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)

      Get the permissions associated to a class.
      Parameters:
        `clazz` - the class
      Returns:
        the permissions

Copyright © 2001–2022 The Apache Software Foundation. All rights reserved.