View Javadoc
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 }