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.util.Map;
022    
023    /**
024     * EXPERIMENTAL - DO NOT USE YET
025     * <p/>
026     * A {@code PrincipalMap} is map of all of a subject's principals - its identifying attributes like username, userId,
027     * etc.
028     * <p/>
029     * The {@link Map} methods allow you to interact with a unified representation of
030     * all of the Subject's principals, even if they came from different realms.  You can think of the {@code Map} methods
031     * as the general purpose API for a Subject's principals.  That is, you can access a principal generally:
032     * <pre>
033     * Object principal = subject.getPrincipals().get(principalName);
034     * </pre>
035     * For example, to get the Subject's username (if the
036     * username principal indeed exists and was populated by a Realm), you can do the following:
037     * <pre>
038     * String username = (String)subject.getPrincipals().get("username");
039     * </pre>
040     * <h3>Multi-Realm Environments</h3>
041     * If your application uses multiple realms, the {@code Map} methods reflect
042     * the the aggregate principals from <em>all</em> realms that authenticated the owning {@code Subject}.
043     * <p/>
044     * But in these multi-realm environments, it is often convenient or necessary to acquire only the principals contributed
045     * by a specific realm (often in a realm implementation itself).  This {@code PrincipalMap} interface satisfies
046     * those needs by providing additional realm-specific accessor/mutator methods.
047     *
048     * @author Les Hazlewood
049     * @since 1.2
050     */
051    public interface PrincipalMap extends PrincipalCollection, Map<String,Object> {
052    
053        Map<String,Object> getRealmPrincipals(String realmName);
054    
055        Map<String,Object> setRealmPrincipals(String realmName, Map<String,Object> principals);
056    
057        Object setRealmPrincipal(String realmName, String principalName, Object principal);
058    
059        Object getRealmPrincipal(String realmName, String realmPrincipal);
060    
061        Object removeRealmPrincipal(String realmName, String principalName);
062    
063    }