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