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

  • Field Details

    • NULL

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

    • ALLOW_NAMES

      static final JexlSandbox.Names ALLOW_NAMES
      The pass-thru name set.

    • BLOCK_NAMES

      private static final JexlSandbox.Names BLOCK_NAMES
      The block-all name set.

    • ALLOW_ALL

      private static final JexlSandbox.Permissions ALLOW_ALL
      The pass-thru permissions.

    • BLOCK_ALL

      private static final JexlSandbox.Permissions BLOCK_ALL
      The block-all permissions.

    • sandbox

      private final Map<String,JexlSandbox.Permissions> sandbox
      The map from class names to permissions.

    • inherit

      private final boolean inherit
      Whether permissions can be inherited (through implementation or extension).

    • allow

      private final boolean allow
      Default behavior, block or allow.

  • Constructor Details

    • 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

      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

    • 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

      @Deprecated protected JexlSandbox(Map<String,JexlSandbox.Permissions> map)
      Deprecated.
      Creates a sandbox based on an existing permissions map.
      Parameters:
      map - the permissions map

  • Method Details

    • forName

      static Class<?> forName(String cname)
      Gets a class by name, crude mechanism for backwards (<3.2 ) compatibility.
      Parameters:
      cname - the class name
      Returns:
      the class

    • 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

    • black

      @Deprecated public JexlSandbox.Permissions black(String clazz)
      Deprecated.
      Use block() 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

    • copy

      public JexlSandbox copy()
      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.
      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(Class<?> clazz)
      Gets the permissions associated to a class.
      Parameters:
      clazz - the class
      Returns:
      the permissions

    • 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

    • 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

    • 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

    • white

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

    • 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