org.apache.shiro.authz.Authorizer Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.shiro.authz;
import org.apache.shiro.subject.PrincipalCollection;
import java.util.Collection;
import java.util.List;
/**
* An Authorizer performs authorization (access control) operations for any given Subject
* (aka 'application user').
*
* Each method requires a subject principal to perform the action for the corresponding Subject/user.
*
*
This principal argument is usually an object representing a user database primary key or a String username or
* something similar that uniquely identifies an application user. The runtime value of the this principal
* is application-specific and provided by the application's configured Realms.
*
*
Note that there are many *Permission methods in this interface overloaded to accept String arguments instead of
* {@link Permission Permission} instances. They are a convenience allowing the caller to use a String representation of
* a {@link Permission Permission} if desired. Most implementations of this interface will simply convert these
* String values to {@link Permission Permission} instances and then just call the corresponding type-safe method.
* (Shiro's default implementations do String-to-Permission conversion for these methods using
* {@link org.apache.shiro.authz.permission.PermissionResolver PermissionResolver}s.)
*
*
These overloaded *Permission methods do forego type-saftey for the benefit of convenience and simplicity,
* so you should choose which ones to use based on your preferences and needs.
*
* @since 0.1
*/
public interface Authorizer {
/**
* Returns true if the corresponding subject/user is permitted to perform an action or access a resource
* summarized by the specified permission string.
*
*
This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
* Please see the class-level JavaDoc for more information on these String-based permission methods.
*
* @param principals the application-specific subject/user identifier.
* @param permission the String representation of a Permission that is being checked.
* @return true if the corresponding Subject/user is permitted, false otherwise.
* @see #isPermitted(PrincipalCollection principals,Permission permission)
* @since 0.9
*/
boolean isPermitted(PrincipalCollection principals, String permission);
/**
* Returns true if the corresponding subject/user is permitted to perform an action or access a resource
* summarized by the specified permission.
*
*
More specifically, this method determines if any Permissions associated
* with the subject {@link Permission#implies(Permission) imply} the specified permission.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param permission the permission that is being checked.
* @return true if the corresponding Subject/user is permitted, false otherwise.
*/
boolean isPermitted(PrincipalCollection subjectPrincipal, Permission permission);
/**
* Checks if the corresponding Subject implies the given permission strings and returns a boolean array
* indicating which permissions are implied.
*
*
This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
* Please see the class-level JavaDoc for more information on these String-based permission methods.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param permissions the String representations of the Permissions that are being checked.
* @return an array of booleans whose indices correspond to the index of the
* permissions in the given list. A true value at an index indicates the user is permitted for
* for the associated Permission string in the list. A false value at an index
* indicates otherwise.
* @since 0.9
*/
boolean[] isPermitted(PrincipalCollection subjectPrincipal, String... permissions);
/**
* Checks if the corresponding Subject/user implies the given Permissions and returns a boolean array indicating
* which permissions are implied.
*
*
More specifically, this method should determine if each Permission in
* the array is {@link Permission#implies(Permission) implied} by permissions
* already associated with the subject.
*
*
This is primarily a performance-enhancing method to help reduce the number of
* {@link #isPermitted} invocations over the wire in client/server systems.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param permissions the permissions that are being checked.
* @return an array of booleans whose indices correspond to the index of the
* permissions in the given list. A true value at an index indicates the user is permitted for
* for the associated Permission object in the list. A false value at an index
* indicates otherwise.
*/
boolean[] isPermitted(PrincipalCollection subjectPrincipal, List permissions);
/**
* Returns true if the corresponding Subject/user implies all of the specified permission strings,
* false otherwise.
*
* This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
* Please see the class-level JavaDoc for more information on these String-based permission methods.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param permissions the String representations of the Permissions that are being checked.
* @return true if the user has all of the specified permissions, false otherwise.
* @see #isPermittedAll(PrincipalCollection,Collection)
* @since 0.9
*/
boolean isPermittedAll(PrincipalCollection subjectPrincipal, String... permissions);
/**
* Returns true if the corresponding Subject/user implies all of the specified permissions, false
* otherwise.
*
*
More specifically, this method determines if all of the given Permissions are
* {@link Permission#implies(Permission) implied by} permissions already associated with the subject.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param permissions the permissions to check.
* @return true if the user has all of the specified permissions, false otherwise.
*/
boolean isPermittedAll(PrincipalCollection subjectPrincipal, Collection permissions);
/**
* Ensures the corresponding Subject/user implies the specified permission String.
*
* If the subject's existing associated permissions do not {@link Permission#implies(Permission)} imply}
* the given permission, an {@link AuthorizationException} will be thrown.
*
*
This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
* Please see the class-level JavaDoc for more information on these String-based permission methods.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param permission the String representation of the Permission to check.
* @throws AuthorizationException
* if the user does not have the permission.
* @since 0.9
*/
void checkPermission(PrincipalCollection subjectPrincipal, String permission) throws AuthorizationException;
/**
* Ensures a subject/user {@link Permission#implies(Permission)} implies} the specified Permission.
* If the subject's exisiting associated permissions do not {@link Permission#implies(Permission)} imply}
* the given permission, an {@link AuthorizationException} will be thrown.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param permission the Permission to check.
* @throws AuthorizationException
* if the user does not have the permission.
*/
void checkPermission(PrincipalCollection subjectPrincipal, Permission permission) throws AuthorizationException;
/**
* Ensures the corresponding Subject/user
* {@link Permission#implies(Permission) implies} all of the
* specified permission strings.
*
* If the subject's exisiting associated permissions do not
* {@link Permission#implies(Permission) imply} all of the given permissions,
* an {@link AuthorizationException} will be thrown.
*
*
This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
* Please see the class-level JavaDoc for more information on these String-based permission methods.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param permissions the string representations of Permissions to check.
* @throws AuthorizationException if the user does not have all of the given permissions.
* @since 0.9
*/
void checkPermissions(PrincipalCollection subjectPrincipal, String... permissions) throws AuthorizationException;
/**
* Ensures the corresponding Subject/user
* {@link Permission#implies(Permission) implies} all of the
* specified permission strings.
*
* If the subject's exisiting associated permissions do not
* {@link Permission#implies(Permission) imply} all of the given permissions,
* an {@link AuthorizationException} will be thrown.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param permissions the Permissions to check.
* @throws AuthorizationException if the user does not have all of the given permissions.
*/
void checkPermissions(PrincipalCollection subjectPrincipal, Collection permissions) throws AuthorizationException;
/**
* Returns true if the corresponding Subject/user has the specified role, false otherwise.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param roleIdentifier the application-specific role identifier (usually a role id or role name).
* @return true if the corresponding subject has the specified role, false otherwise.
*/
boolean hasRole(PrincipalCollection subjectPrincipal, String roleIdentifier);
/**
* Checks if the corresponding Subject/user has the specified roles, returning a boolean array indicating
* which roles are associated with the given subject.
*
* This is primarily a performance-enhancing method to help reduce the number of
* {@link #hasRole} invocations over the wire in client/server systems.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
* @return an array of booleans whose indices correspond to the index of the
* roles in the given identifiers. A true value indicates the user has the
* role at that index. False indicates the user does not have the role at that index.
*/
boolean[] hasRoles(PrincipalCollection subjectPrincipal, List roleIdentifiers);
/**
* Returns true if the corresponding Subject/user has all of the specified roles, false otherwise.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
* @return true if the user has all the roles, false otherwise.
*/
boolean hasAllRoles(PrincipalCollection subjectPrincipal, Collection roleIdentifiers);
/**
* Asserts the corresponding Subject/user has the specified role by returning quietly if they do or throwing an
* {@link AuthorizationException} if they do not.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param roleIdentifier the application-specific role identifier (usually a role id or role name ).
* @throws AuthorizationException
* if the user does not have the role.
*/
void checkRole(PrincipalCollection subjectPrincipal, String roleIdentifier) throws AuthorizationException;
/**
* Asserts the corresponding Subject/user has all of the specified roles by returning quietly if they do or
* throwing an {@link AuthorizationException} if they do not.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
* @throws AuthorizationException
* if the user does not have all of the specified roles.
*/
void checkRoles(PrincipalCollection subjectPrincipal, Collection roleIdentifiers) throws AuthorizationException;
/**
* Same as {@link #checkRoles(org.apache.shiro.subject.PrincipalCollection, java.util.Collection)
* checkRoles(PrincipalCollection subjectPrincipal, Collection<String> roleIdentifiers)} but doesn't require a collection
* as an argument.
* Asserts the corresponding Subject/user has all of the specified roles by returning quietly if they do or
* throwing an {@link AuthorizationException} if they do not.
*
* @param subjectPrincipal the application-specific subject/user identifier.
* @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
* @throws AuthorizationException
* if the user does not have all of the specified roles.
*
* @since 1.1.0
*/
void checkRoles(PrincipalCollection subjectPrincipal, String... roleIdentifiers) throws AuthorizationException;
}