001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.shiro.authz.permission;
020
021import org.apache.shiro.authz.Permission;
022
023/**
024 * A {@code PermisisonResolver} resolves a String value and converts it into a
025 * {@link org.apache.shiro.authz.Permission Permission} instance.
026 * <p/>
027 * The default {@link WildcardPermissionResolver} should be
028 * suitable for most purposes, which constructs {@link WildcardPermission} objects.
029 * However, any resolver may be configured if an application wishes to use different
030 * {@link org.apache.shiro.authz.Permission} implementations.
031 * <p/>
032 * A {@code PermissionResolver} is used by many Shiro components such as annotations, property file
033 * configuration, URL configuration, etc.  It is useful whenever a String representation of a permission is specified
034 * and that String needs to be converted to a Permission instance before executing a security check.
035 * <p/>
036 * Shiro chooses to support {@link WildcardPermission Wildcardpermission}s by default in almost all components and
037 * we do that in the form of the {@link WildcardPermissionResolver WildcardPermissionResolver}.   One of the nice
038 * things about {@code WildcardPermission}s being supported by default is that it makes it very easy to
039 * store complex permissions in the database - and also makes it very easy to represent permissions in JSP files,
040 * annotations, etc., where a simple string representation is useful.
041 * <p/>
042 * Although this happens to be the Shiro default, you are of course free to provide custom
043 * String-to-Permission conversion by providing Shiro components any instance of this interface.
044 *
045 * @see org.apache.shiro.authz.ModularRealmAuthorizer#setPermissionResolver(PermissionResolver) ModularRealmAuthorizer.setPermissionResolver
046 * @see org.apache.shiro.realm.AuthorizingRealm#setPermissionResolver(PermissionResolver) AuthorizingRealm.setPermissionResolver
047 * @see PermissionResolverAware PermissionResolverAware
048 * @since 0.9
049 */
050public interface PermissionResolver {
051
052    /**
053     * Resolves a Permission based on the given String representation.
054     *
055     * @param permissionString the String representation of a permission.
056     * @return A Permission object that can be used internally to determine a subject's permissions.
057     * @throws InvalidPermissionStringException
058     *          if the permission string is not valid for this resolver.
059     */
060    Permission resolvePermission(String permissionString);
061
062}