Class JexlSandbox
- java.lang.Object
-
- org.apache.commons.jexl3.introspection.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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
JexlSandbox.AllowSet
A allow set of names.static class
JexlSandbox.BlackSet
Deprecated.since 3.2, useJexlSandbox.BlockSet
(package private) static class
JexlSandbox.BlockSet
A block set of names.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, useJexlSandbox.AllowSet
-
Field Summary
Fields Modifier and Type Field Description private boolean
allow
Default behavior, block or allow.private static JexlSandbox.Permissions
ALLOW_ALL
The pass-thru permissions.(package private) static JexlSandbox.Names
ALLOW_NAMES
The pass-thru name set.private static JexlSandbox.Permissions
BLOCK_ALL
The block-all permissions.private static JexlSandbox.Names
BLOCK_NAMES
The block-all name set.private boolean
inherit
Whether permissions can be inherited (through implementation or extension).static java.lang.String
NULL
The marker string for explicitly disallowed null properties.private java.util.Map<java.lang.String,JexlSandbox.Permissions>
sandbox
The map from class names to permissions.
-
Constructor Summary
Constructors Modifier Constructor 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, java.util.Map<java.lang.String,JexlSandbox.Permissions> map)
Creates a sandbox based on an existing permissions map.protected
JexlSandbox(boolean ab, java.util.Map<java.lang.String,JexlSandbox.Permissions> map)
Deprecated.protected
JexlSandbox(java.util.Map<java.lang.String,JexlSandbox.Permissions> map)
Deprecated.
-
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.
-
-
-
Field Detail
-
NULL
public static final java.lang.String NULL
The marker string for explicitly disallowed null properties.- See Also:
- Constant Field Values
-
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 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 falsemap
- 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 classname
- 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 namename
- 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 applyreadFlag
- 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 applyinhf
- whether these permissions are inheritablereadf
- 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 classname
- 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 namename
- 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 classname
- 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 namename
- the property name- Returns:
- null if not allowed, the name of the property to use otherwise
-
-