001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.shiro.subject;
020    
021    import java.io.Serializable;
022    import java.util.Collection;
023    import java.util.List;
024    import java.util.Set;
025    
026    /**
027     * A collection of all principals associated with a corresponding {@link Subject Subject}.  A <em>principal</em> is
028     * just a security term for an identifying attribute, such as a username or user id or social security number or
029     * anything else that can be considered an 'identifying' attribute for a {@code Subject}.
030     * <p/>
031     * A PrincipalCollection organizes its internal principals based on the {@code Realm} where they came from when the
032     * Subject was first created.  To obtain the principal(s) for a specific Realm, see the {@link #fromRealm} method.  You
033     * can also see which realms contributed to this collection via the {@link #getRealmNames() getRealmNames()} method.
034     *
035     * @see #getPrimaryPrincipal()
036     * @see #fromRealm(String realmName)
037     * @see #getRealmNames()
038     * @since 0.9
039     */
040    public interface PrincipalCollection extends Iterable, Serializable {
041    
042        /**
043         * Returns the primary principal used application-wide to uniquely identify the owning account/Subject.
044         * <p/>
045         * The value is usually always a uniquely identifying attribute specific to the data source that retrieved the
046         * account data.  Some examples:
047         * <ul>
048         * <li>a {@link java.util.UUID UUID}</li>
049         * <li>a {@code long} value such as a surrogate primary key in a relational database</li>
050         * <li>an LDAP UUID or static DN</li>
051         * <li>a String username unique across all user accounts</li>
052         * </ul>
053         * <h3>Multi-Realm Applications</h3>
054         * In a single-{@code Realm} application, typically there is only ever one unique principal to retain and that
055         * is the value returned from this method.  However, in a multi-{@code Realm} application, where the
056         * {@code PrincipalCollection} might retain principals across more than one realm, the value returned from this
057         * method should be the single principal that uniquely identifies the subject for the entire application.
058         * <p/>
059         * That value is of course application specific, but most applications will typically choose one of the primary
060         * principals from one of the {@code Realm}s.
061         * <p/>
062         * Shiro's default implementations of this interface make this
063         * assumption by usually simply returning {@link #iterator()}.{@link java.util.Iterator#next() next()}, which just
064         * returns the first returned principal obtained from the first consulted/configured {@code Realm} during the
065         * authentication attempt.  This means in a multi-{@code Realm} application, {@code Realm} configuraiton order
066         * matters if you want to retain this default heuristic.
067         * <p/>
068         * If this heuristic is not sufficient, most Shiro end-users will need to implement a custom
069         * {@link org.apache.shiro.authc.pam.AuthenticationStrategy}.  An {@code AuthenticationStrategy} has exact control
070         * over the {@link PrincipalCollection} returned at the end of an authentication attempt via the
071         * <code>AuthenticationStrategy#{@link org.apache.shiro.authc.pam.AuthenticationStrategy#afterAllAttempts(org.apache.shiro.authc.AuthenticationToken, org.apache.shiro.authc.AuthenticationInfo) afterAllAttempts}</code>
072         * implementation.
073         *
074         * @return the primary principal used to uniquely identify the owning account/Subject
075         * @since 1.0
076         */
077        Object getPrimaryPrincipal();
078    
079        /**
080         * Returns the first discovered principal assignable from the specified type, or {@code null} if there are none
081         * of the specified type.
082         * <p/>
083         * Note that this will return {@code null} if the 'owning' subject has not yet logged in.
084         *
085         * @param type the type of the principal that should be returned.
086         * @return a principal of the specified type or {@code null} if there isn't one of the specified type.
087         */
088        <T> T oneByType(Class<T> type);
089    
090        /**
091         * Returns all principals assignable from the specified type, or an empty Collection if no principals of that
092         * type are contained.
093         * <p/>
094         * Note that this will return an empty Collection if the 'owning' subject has not yet logged in.
095         *
096         * @param type the type of the principals that should be returned.
097         * @return a Collection of principals that are assignable from the specified type, or
098         *         an empty Collection if no principals of this type are associated.
099         */
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    }