hunt.shiro.subject.PrincipalCollection 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.subject.PrincipalCollection;
20 
21 import hunt.util.Common;
22 import hunt.collection;
23 
24 /**
25  * A collection of all principals associated with a corresponding {@link Subject Subject}.  A <em>principal</em> is
26  * just a security term for an identifying attribute, such as a username or user id or social security number or
27  * anything else that can be considered an 'identifying' attribute for a {@code Subject}.
28  * <p/>
29  * A PrincipalCollection organizes its internal principals based on the {@code Realm} where they came from when the
30  * Subject was first created.  To obtain the principal(s) for a specific Realm, see the {@link #fromRealm} method.  You
31  * can also see which realms contributed to this collection via the {@link #getRealmNames() getRealmNames()} method.
32  *
33  * @see #getPrimaryPrincipal()
34  * @see #fromRealm(string realmName)
35  * @see #getRealmNames()
36  */
37 interface PrincipalCollection : Iterable!Object {
38 
39     /**
40      * Returns the primary principal used application-wide to uniquely identify the owning account/Subject.
41      * <p/>
42      * The value is usually always a uniquely identifying attribute specific to the data source that retrieved the
43      * account data.  Some examples:
44      * <ul>
45      * <li>a {@link java.util.UUID UUID}</li>
46      * <li>a {@code long} value such as a surrogate primary key in a relational database</li>
47      * <li>an LDAP UUID or static DN</li>
48      * <li>a string username unique across all user accounts</li>
49      * </ul>
50      * <h3>Multi-Realm Applications</h3>
51      * In a single-{@code Realm} application, typically there is only ever one unique principal to retain and that
52      * is the value returned from this method.  However, in a multi-{@code Realm} application, where the
53      * {@code PrincipalCollection} might retain principals across more than one realm, the value returned from this
54      * method should be the single principal that uniquely identifies the subject for the entire application.
55      * <p/>
56      * That value is of course application specific, but most applications will typically choose one of the primary
57      * principals from one of the {@code Realm}s.
58      * <p/>
59      * Shiro's default implementations of this interface make this
60      * assumption by usually simply returning {@link #iterator()}.{@link java.util.Iterator#next() next()}, which just
61      * returns the first returned principal obtained from the first consulted/configured {@code Realm} during the
62      * authentication attempt.  This means in a multi-{@code Realm} application, {@code Realm} configuration order
63      * matters if you want to retain this default heuristic.
64      * <p/>
65      * If this heuristic is not sufficient, most Shiro end-users will need to implement a custom
66      * {@link hunt.shiro.authc.pam.AuthenticationStrategy}.  An {@code AuthenticationStrategy} has exact control
67      * over the {@link PrincipalCollection} returned at the end of an authentication attempt via the
68      * <code>AuthenticationStrategy#{@link hunt.shiro.authc.pam.AuthenticationStrategy#afterAllAttempts(hunt.shiro.authc.AuthenticationToken, hunt.shiro.authc.AuthenticationInfo) afterAllAttempts}</code>
69      * implementation.
70      *
71      * @return the primary principal used to uniquely identify the owning account/Subject
72      */
73     Object getPrimaryPrincipal();
74 
75     /**
76      * Returns the first discovered principal assignable from the specified type, or {@code null} if there are none
77      * of the specified type.
78      * <p/>
79      * Note that this will return {@code null} if the 'owning' subject has not yet logged in.
80      *
81      * @param type the type of the principal that should be returned.
82      * @return a principal of the specified type or {@code null} if there isn't one of the specified type.
83      */
84     // T oneByType(T)(TypeInfo_Class type);
85 
86     /**
87      * Returns all principals assignable from the specified type, or an empty Collection if no principals of that
88      * type are contained.
89      * <p/>
90      * Note that this will return an empty Collection if the 'owning' subject has not yet logged in.
91      *
92      * @param type the type of the principals that should be returned.
93      * @return a Collection of principals that are assignable from the specified type, or
94      *         an empty Collection if no principals of this type are associated.
95      */
96     // Collection!(T) byType(T)(TypeInfo_Class type);
97 
98     /**
99      * Returns a single Subject's principals retrieved from all configured Realms as a List, or an empty List if
100      * there are not any principals.
101      * <p/>
102      * Note that this will return an empty List if the 'owning' subject has not yet logged in.
103      *
104      * @return a single Subject's principals retrieved from all configured Realms as a List.
105      */
106     List!Object asList();
107 
108     /**
109      * Returns a single Subject's principals retrieved from all configured Realms as a Set, or an empty Set if there
110      * are not any principals.
111      * <p/>
112      * Note that this will return an empty Set if the 'owning' subject has not yet logged in.
113      *
114      * @return a single Subject's principals retrieved from all configured Realms as a Set.
115      */
116     Set!Object asSet();
117 
118     /**
119      * Returns a single Subject's principals retrieved from the specified Realm <em>only</em> as a Collection, or an empty
120      * Collection if there are not any principals from that realm.
121      * <p/>
122      * Note that this will return an empty Collection if the 'owning' subject has not yet logged in.
123      *
124      * @param realmName the name of the Realm from which the principals were retrieved.
125      * @return the Subject's principals from the specified Realm only as a Collection or an empty Collection if there
126      *         are not any principals from that realm.
127      */
128     Object[] fromRealm(string realmName);
129 
130     /**
131      * Returns the realm names that this collection has principals for.
132      *
133      * @return the names of realms that this collection has one or more principals for.
134      */
135     string[] getRealmNames();
136 
137     /**
138      * Returns {@code true} if this collection is empty, {@code false} otherwise.
139      *
140      * @return {@code true} if this collection is empty, {@code false} otherwise.
141      */
142     bool isEmpty();
143 }