org.apache.shiro.authz.permission
Class WildcardPermission
java.lang.Object
org.apache.shiro.authz.permission.WildcardPermission
- All Implemented Interfaces:
- Serializable, Permission
- Direct Known Subclasses:
- DomainPermission
public class WildcardPermission
- extends Object
- implements Permission, Serializable
A WildcardPermission
is a very flexible permission construct supporting multiple levels of
permission matching. However, most people will probably follow some standard conventions as explained below.
Simple Usage
In the simplest form, WildcardPermission
can be used as a simple permission string. You could grant a
user an "editNewsletter" permission and then check to see if the user has the editNewsletter
permission by calling
subject.isPermitted("editNewsletter")
This is (mostly) equivalent to
subject.isPermitted( new WildcardPermission("editNewsletter") )
but more on that later.
The simple permission string may work for simple applications, but it requires you to have permissions like
"viewNewsletter"
, "deleteNewsletter"
,
"createNewsletter"
, etc. You can also grant a user "*"
permissions
using the wildcard character (giving this class its name), which means they have all permissions. But
using this approach there's no way to just say a user has "all newsletter permissions".
For this reason, WildcardPermission
supports multiple levels of permissioning.
Multiple Levels
WildcardPermission also supports the concept of multiple levels. For example, you could
restructure the previous simple example by granting a user the permission "newsletter:edit"
.
The colon in this example is a special character used by the WildcardPermission
that delimits the
next token in the permission.
In this example, the first token is the domain that is being operated on
and the second token is the action being performed. Each level can contain multiple values. So you
could simply grant a user the permission "newsletter:view,edit,create"
which gives them
access to perform view
, edit
, and create
actions in the newsletter
domain. Then you could check to see if the user has the "newsletter:create"
permission by calling
subject.isPermitted("newsletter:create")
(which would return true).
In addition to granting multiple permissions via a single string, you can grant all permission for a particular
level. So if you wanted to grant a user all actions in the newsletter
domain, you could simply give
them "newsletter:*"
. Now, any permission check for "newsletter:XXX"
will return true
. It is also possible to use the wildcard token at the domain level (or both): so you
could grant a user the "view"
action across all domains "*:view"
.
Instance-level Access Control
Another common usage of the WildcardPermission
is to model instance-level Access Control Lists.
In this scenario you use three tokens - the first is the domain, the second is the action, and
the third is the instance you are acting on.
So for example you could grant a user "newsletter:edit:12,13,18"
. In this example, assume
that the third token is the system's ID of the newsletter. That would allow the user to edit newsletters
12
, 13
, and 18
. This is an extremely powerful way to express permissions,
since you can now say things like "newsletter:*:13"
(grant a user all actions for newsletter
13
), "newsletter:view,create,edit:*"
(allow the user to
view
, create
, or edit
any newsletter), or
"newsletter:*:*
(allow the user to perform any action on any newsletter).
To perform checks against these instance-level permissions, the application should include the instance ID in the
permission check like so:
subject.isPermitted( "newsletter:edit:13" )
There is no limit to the number of tokens that can be used, so it is up to your imagination in terms of ways that
this could be used in your application. However, the Shiro team likes to standardize some common usages shown
above to help people get started and provide consistency in the Shiro community.
- Since:
- 0.9
- See Also:
- Serialized Form
Constructor Summary |
protected |
WildcardPermission()
Default no-arg constructor for subclasses only - end-user developers instantiating Permission instances must
provide a wildcard string at a minimum, since Permission instances are immutable once instantiated. |
|
WildcardPermission(String wildcardString)
|
|
WildcardPermission(String wildcardString,
boolean caseSensitive)
|
WILDCARD_TOKEN
protected static final String WILDCARD_TOKEN
- See Also:
- Constant Field Values
PART_DIVIDER_TOKEN
protected static final String PART_DIVIDER_TOKEN
- See Also:
- Constant Field Values
SUBPART_DIVIDER_TOKEN
protected static final String SUBPART_DIVIDER_TOKEN
- See Also:
- Constant Field Values
DEFAULT_CASE_SENSITIVE
protected static final boolean DEFAULT_CASE_SENSITIVE
- See Also:
- Constant Field Values
WildcardPermission
protected WildcardPermission()
- Default no-arg constructor for subclasses only - end-user developers instantiating Permission instances must
provide a wildcard string at a minimum, since Permission instances are immutable once instantiated.
Note that the WildcardPermission class is very robust and typically subclasses are not necessary unless you
wish to create type-safe Permission objects that would be used in your application, such as perhaps a
UserPermission
, SystemPermission
, PrinterPermission
, etc. If you want such type-safe
permission usage, consider subclassing the DomainPermission
class for your needs.
WildcardPermission
public WildcardPermission(String wildcardString)
WildcardPermission
public WildcardPermission(String wildcardString,
boolean caseSensitive)
setParts
protected void setParts(String wildcardString)
setParts
protected void setParts(String wildcardString,
boolean caseSensitive)
getParts
protected List<Set<String>> getParts()
implies
public boolean implies(Permission p)
- Description copied from interface:
Permission
- Returns
true
if this current instance implies all the functionality and/or resource access
described by the specified Permission
argument, false
otherwise.
That is, this current instance must be exactly equal to or a superset of the functionalty
and/or resource access described by the given Permission
argument. Yet another way of saying this
would be:
If "permission1 implies permission2", i.e. permission1.implies(permission2)
,
then any Subject granted permission1
would have ability greater than or equal to that defined by
permission2
.
- Specified by:
implies
in interface Permission
- Parameters:
p
- the permission to check for behavior/functionality comparison.
- Returns:
true
if this current instance implies all the functionality and/or resource access
described by the specified Permission
argument, false
otherwise.
toString
public String toString()
- Overrides:
toString
in class Object
equals
public boolean equals(Object o)
- Overrides:
equals
in class Object
hashCode
public int hashCode()
- Overrides:
hashCode
in class Object
Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.