Class JexlSandbox


  • public final class JexlSandbox
    extends java.lang.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
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      JexlSandbox.Permissions allow​(java.lang.String clazz)
      Creates a new set of permissions based on allow lists for methods and properties for a given class.
      JexlSandbox.Permissions black​(java.lang.String clazz)
      Deprecated.
      JexlSandbox.Permissions block​(java.lang.String clazz)
      Creates a new set of permissions based on block lists for methods and properties for a given class.
      JexlSandbox copy()  
      java.lang.String execute​(java.lang.Class<?> clazz, java.lang.String name)
      Gets the execute permission value for a given method of a class.
      java.lang.String execute​(java.lang.String clazz, java.lang.String name)
      Deprecated.
      (package private) static java.lang.Class<?> forName​(java.lang.String cname)
      Gets a class by name, crude mechanism for backwards (<3.2 ) compatibility.
      JexlSandbox.Permissions get​(java.lang.Class<?> clazz)
      Gets the permissions associated to a class.
      JexlSandbox.Permissions get​(java.lang.String clazz)
      Gets the set of permissions associated to a class.
      JexlSandbox.Permissions permissions​(java.lang.String clazz, boolean readFlag, boolean writeFlag, boolean executeFlag)
      Creates the set of permissions for a given class.
      JexlSandbox.Permissions permissions​(java.lang.String clazz, boolean inhf, boolean readf, boolean writef, boolean execf)
      Creates the set of permissions for a given class.
      java.lang.String read​(java.lang.Class<?> clazz, java.lang.String name)
      Gets the read permission value for a given property of a class.
      java.lang.String read​(java.lang.String clazz, java.lang.String name)
      Deprecated.
      JexlSandbox.Permissions white​(java.lang.String clazz)
      Deprecated.
      java.lang.String write​(java.lang.Class<?> clazz, java.lang.String name)
      Gets the write permission value for a given property of a class.
      java.lang.String write​(java.lang.String clazz, java.lang.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 java.lang.String NULL
        The marker string for explicitly disallowed null properties.
        See Also:
        Constant Field Values
      • BLOCK_NAMES

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

        private final java.util.Map<java.lang.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 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

        protected JexlSandbox​(boolean ab,
                              boolean inh,
                              java.util.Map<java.lang.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,
                              java.util.Map<java.lang.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​(java.util.Map<java.lang.String,​JexlSandbox.Permissions> map)
        Deprecated.
        Creates a sandbox based on an existing permissions map.
        Parameters:
        map - the permissions map
    • Method Detail

      • forName

        static java.lang.Class<?> forName​(java.lang.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​(java.lang.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​(java.lang.String clazz)
        Deprecated.
        Use block() instead.
        Parameters:
        clazz - the allowed class name
        Returns:
        the permissions instance
      • block

        public JexlSandbox.Permissions block​(java.lang.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 java.lang.String execute​(java.lang.Class<?> clazz,
                                        java.lang.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 java.lang.String execute​(java.lang.String clazz,
                                        java.lang.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​(java.lang.Class<?> clazz)
        Gets the permissions associated to a class.
        Parameters:
        clazz - the class
        Returns:
        the permissions
      • get

        public JexlSandbox.Permissions get​(java.lang.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​(java.lang.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​(java.lang.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 java.lang.String read​(java.lang.Class<?> clazz,
                                     java.lang.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 java.lang.String read​(java.lang.String clazz,
                                     java.lang.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​(java.lang.String clazz)
        Deprecated.
        Use allow() instead.
        Parameters:
        clazz - the allowed class name
        Returns:
        the permissions instance
      • write

        public java.lang.String write​(java.lang.Class<?> clazz,
                                      java.lang.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 java.lang.String write​(java.lang.String clazz,
                                      java.lang.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