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