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

Field Summary

protected static boolean	DEFAULT_CASE_SENSITIVE
protected static String	PART_DIVIDER_TOKEN
protected static String	SUBPART_DIVIDER_TOKEN
protected static String	WILDCARD_TOKEN

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)

Method Summary

boolean	equals(Object o)
protected List<Set<String>>	getParts()
int	hashCode()
boolean	implies(Permission p) Returns true if this current instance implies all the functionality and/or resource access described by the specified Permission argument, false otherwise.
protected void	setParts(String wildcardString)
protected void	setParts(String wildcardString, boolean caseSensitive)
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

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

Constructor Detail

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)

Method Detail

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