View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.shiro.authz.permission;
20  
21  import org.apache.shiro.authz.Permission;
22  
23  /**
24   * A {@code PermisisonResolver} resolves a String value and converts it into a
25   * {@link org.apache.shiro.authz.Permission Permission} instance.
26   * <p/>
27   * The default {@link WildcardPermissionResolver} should be
28   * suitable for most purposes, which constructs {@link WildcardPermission} objects.
29   * However, any resolver may be configured if an application wishes to use different
30   * {@link org.apache.shiro.authz.Permission} implementations.
31   * <p/>
32   * A {@code PermissionResolver} is used by many Shiro components such as annotations, property file
33   * configuration, URL configuration, etc.  It is useful whenever a String representation of a permission is specified
34   * and that String needs to be converted to a Permission instance before executing a security check.
35   * <p/>
36   * Shiro chooses to support {@link WildcardPermission Wildcardpermission}s by default in almost all components and
37   * we do that in the form of the {@link WildcardPermissionResolver WildcardPermissionResolver}.   One of the nice
38   * things about {@code WildcardPermission}s being supported by default is that it makes it very easy to
39   * store complex permissions in the database - and also makes it very easy to represent permissions in JSP files,
40   * annotations, etc., where a simple string representation is useful.
41   * <p/>
42   * Although this happens to be the Shiro default, you are of course free to provide custom
43   * String-to-Permission conversion by providing Shiro components any instance of this interface.
44   *
45   * @see org.apache.shiro.authz.ModularRealmAuthorizer#setPermissionResolver(PermissionResolver) ModularRealmAuthorizer.setPermissionResolver
46   * @see org.apache.shiro.realm.AuthorizingRealm#setPermissionResolver(PermissionResolver) AuthorizingRealm.setPermissionResolver
47   * @see PermissionResolverAware PermissionResolverAware
48   * @since 0.9
49   */
50  public interface PermissionResolver {
51  
52      /**
53       * Resolves a Permission based on the given String representation.
54       *
55       * @param permissionString the String representation of a permission.
56       * @return A Permission object that can be used internally to determine a subject's permissions.
57       * @throws InvalidPermissionStringException
58       *          if the permission string is not valid for this resolver.
59       */
60      Permission resolvePermission(String permissionString);
61  
62  }