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     */
019    package org.apache.shiro.authz;
020    
021    import java.io.Serializable;
022    import java.util.Collection;
023    
024    /**
025     * <code>AuthorizationInfo</code> represents a single Subject's stored authorization data (roles, permissions, etc)
026     * used during authorization (access control) checks only.
027     * <p/>
028     * Roles are represented as a <code>Collection</code> of Strings
029     * ({@link java.util.Collection Collection}<{@link String String}>), typically each element being the Role name.
030     * <p/>
031     * {@link Permission Permission}s are provided in two ways:
032     * <ul>
033     * <li>A <code>Collection</code> of Strings, where each String can usually be converted into <code>Permission</code>
034     * objects by a <code>Realm</code>'s
035     * {@link org.apache.shiro.authz.permission.PermissionResolver PermissionResolver}</li>
036     * <li>A <code>Collection</code> of {@link Permission Permission} objects</li>
037     * </ul>
038     * Both permission collections together represent the total aggregate collection of permissions.  You may use one
039     * or both depending on your preference and needs.
040     * <p/>
041     * Because the act of authorization (access control) is orthoganal to authentication (log-in), this interface is
042     * intended to represent only the account data needed by Shiro during an access control check
043     * (role, permission, etc).  Shiro also has a parallel
044     * {@link org.apache.shiro.authc.AuthenticationInfo AuthenticationInfo} interface for use during the authentication
045     * process that represents identity data such as principals and credentials.
046     * <p/>
047     * Because many if not most {@link org.apache.shiro.realm.Realm Realm}s store both sets of data for a Subject, it might be
048     * convenient for a <code>Realm</code> implementation to utilize an implementation of the
049     * {@link org.apache.shiro.authc.Account Account} interface instead, which is a convenience interface that combines both
050     * <code>AuthenticationInfo</code> and <code>AuthorizationInfo</code>.  Whether you choose to implement these two
051     * interfaces separately or implement the one <code>Account</code> interface for a given <code>Realm</code> is
052     * entirely based on your application's needs or your preferences.
053     *
054     * @see org.apache.shiro.authc.AuthenticationInfo AuthenticationInfo
055     * @see org.apache.shiro.authc.Account
056     * @since 0.9
057     */
058    public interface AuthorizationInfo extends Serializable {
059    
060        /**
061         * Returns the names of all roles assigned to a corresponding Subject.
062         *
063         * @return the names of all roles assigned to a corresponding Subject.
064         */
065        Collection<String> getRoles();
066    
067        /**
068         * Returns all string-based permissions assigned to the corresponding Subject.  The permissions here plus those
069         * returned from {@link #getObjectPermissions() getObjectPermissions()} represent the total set of permissions
070         * assigned.  The aggregate set is used to perform a permission authorization check.
071         * <p/>
072         * This method is a convenience mechanism that allows Realms to represent permissions as Strings if they choose.
073         * When performing a security check, a <code>Realm</code> usually converts these strings to object
074         * {@link Permission Permission}s via an internal
075         * {@link org.apache.shiro.authz.permission.PermissionResolver PermissionResolver}
076         * in order to perform the actual permission check.  This is not a requirement of course, since <code>Realm</code>s
077         * can perform security checks in whatever manner deemed necessary, but this explains the conversion mechanism that
078         * most Shiro Realms execute for string-based permission checks.
079         *
080         * @return all string-based permissions assigned to the corresponding Subject.
081         */
082        Collection<String> getStringPermissions();
083    
084        /**
085         * Returns all type-safe {@link Permission Permission}s assigned to the corresponding Subject.  The permissions
086         * returned from this method plus any returned from {@link #getStringPermissions() getStringPermissions()}
087         * represent the total set of permissions.  The aggregate set is used to perform a permission authorization check.
088         *
089         * @return all type-safe {@link Permission Permission}s assigned to the corresponding Subject.
090         */
091        Collection<Permission> getObjectPermissions();
092    }