Package org.apache.commons.jexl3.introspection

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

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

      • JexlSandbox

        private 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

    • 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

      • 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()
        Gets a copy of this sandbox
        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.
        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​(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

      • get

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

      • compute

        private JexlSandbox.Permissions compute​(java.lang.Class<?> clazz,
                                        boolean store)
        Computes and optionally stores the permissions associated to a class.
        Parameters:
        clazz - the class
        store - whether the computed permissions should be stored in the sandbox
        Returns:
        the permissions

      • 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

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

      • read

        @Deprecated
public java.lang.String read​(java.lang.String clazz,
                             java.lang.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​(java.lang.String clazz)
        Deprecated.
        3.3
        Use allow() instead.
        Parameters:
        clazz - the allowed class name
        Returns:
        the permissions instance