hunt.shiro.authz.AuthorizationInfo source code

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 module hunt.shiro.authz.AuthorizationInfo;
20 
21 import hunt.shiro.authz.permission.Permission;
22 
23 import hunt.util.Common;
24 import hunt.collection;
25 
26 /**
27  * <code>AuthorizationInfo</code> represents a single Subject's stored authorization data (roles, permissions, etc)
28  * used during authorization (access control) checks only.
29  * <p/>
30  * Roles are represented as a <code>Collection</code> of Strings
31  * ({@link java.util.Collection Collection}<{@link string string}>), typically each element being the Role name.
32  * <p/>
33  * {@link Permission Permission}s are provided in two ways:
34  * <ul>
35  * <li>A <code>Collection</code> of Strings, where each string can usually be converted into <code>Permission</code>
36  * objects by a <code>Realm</code>'s
37  * {@link hunt.shiro.authz.permission.PermissionResolver PermissionResolver}</li>
38  * <li>A <code>Collection</code> of {@link Permission Permission} objects</li>
39  * </ul>
40  * Both permission collections together represent the total aggregate collection of permissions.  You may use one
41  * or both depending on your preference and needs.
42  * <p/>
43  * Because the act of authorization (access control) is orthogonal to authentication (log-in), this interface is
44  * intended to represent only the account data needed by Shiro during an access control check
45  * (role, permission, etc).  Shiro also has a parallel
46  * {@link hunt.shiro.authc.AuthenticationInfo AuthenticationInfo} interface for use during the authentication
47  * process that represents identity data such as principals and credentials.
48  * <p/>
49  * Because many if not most {@link hunt.shiro.realm.Realm Realm}s store both sets of data for a Subject, it might be
50  * convenient for a <code>Realm</code> implementation to utilize an implementation of the
51  * {@link hunt.shiro.authc.Account Account} interface instead, which is a convenience interface that combines both
52  * <code>AuthenticationInfo</code> and <code>AuthorizationInfo</code>.  Whether you choose to implement these two
53  * interfaces separately or implement the one <code>Account</code> interface for a given <code>Realm</code> is
54  * entirely based on your application's needs or your preferences.
55  *
56  * @see hunt.shiro.authc.AuthenticationInfo AuthenticationInfo
57  * @see hunt.shiro.authc.Account
58  */
59 interface AuthorizationInfo {
60 
61     /**
62      * Returns the names of all roles assigned to a corresponding Subject.
63      *
64      * @return the names of all roles assigned to a corresponding Subject.
65      */
66     Collection!(string) getRoles();
67 
68     /**
69      * Returns all string-based permissions assigned to the corresponding Subject.  The permissions here plus those
70      * returned from {@link #getObjectPermissions() getObjectPermissions()} represent the total set of permissions
71      * assigned.  The aggregate set is used to perform a permission authorization check.
72      * <p/>
73      * This method is a convenience mechanism that allows Realms to represent permissions as Strings if they choose.
74      * When performing a security check, a <code>Realm</code> usually converts these strings to object
75      * {@link Permission Permission}s via an internal
76      * {@link hunt.shiro.authz.permission.PermissionResolver PermissionResolver}
77      * in order to perform the actual permission check.  This is not a requirement of course, since <code>Realm</code>s
78      * can perform security checks in whatever manner deemed necessary, but this explains the conversion mechanism that
79      * most Shiro Realms execute for string-based permission checks.
80      *
81      * @return all string-based permissions assigned to the corresponding Subject.
82      */
83     Collection!(string) getStringPermissions();
84 
85     /**
86      * Returns all type-safe {@link Permission Permission}s assigned to the corresponding Subject.  The permissions
87      * returned from this method plus any returned from {@link #getStringPermissions() getStringPermissions()}
88      * represent the total set of permissions.  The aggregate set is used to perform a permission authorization check.
89      *
90      * @return all type-safe {@link Permission Permission}s assigned to the corresponding Subject.
91      */
92     Collection!(Permission) getObjectPermissions();
93 }