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.util.Map;
22
23 /**
24 * EXPERIMENTAL - DO NOT USE YET
25 * <p/>
26 * A {@code PrincipalMap} is map of all of a subject's principals - its identifying attributes like username, userId,
27 * etc.
28 * <p/>
29 * The {@link Map} methods allow you to interact with a unified representation of
30 * all of the Subject's principals, even if they came from different realms. You can think of the {@code Map} methods
31 * as the general purpose API for a Subject's principals. That is, you can access a principal generally:
32 * <pre>
33 * Object principal = subject.getPrincipals().get(principalName);
34 * </pre>
35 * For example, to get the Subject's username (if the
36 * username principal indeed exists and was populated by a Realm), you can do the following:
37 * <pre>
38 * String username = (String)subject.getPrincipals().get("username");
39 * </pre>
40 * <h3>Multi-Realm Environments</h3>
41 * If your application uses multiple realms, the {@code Map} methods reflect
42 * the the aggregate principals from <em>all</em> realms that authenticated the owning {@code Subject}.
43 * <p/>
44 * But in these multi-realm environments, it is often convenient or necessary to acquire only the principals contributed
45 * by a specific realm (often in a realm implementation itself). This {@code PrincipalMap} interface satisfies
46 * those needs by providing additional realm-specific accessor/mutator methods.
47 *
48 * @since 1.2
49 */
50 public interface PrincipalMap extends PrincipalCollection, Map<String, Object> {
51
52 Map<String, Object> getRealmPrincipals(String realmName);
53
54 Map<String, Object> setRealmPrincipals(String realmName, Map<String, Object> principals);
55
56 Object setRealmPrincipal(String realmName, String principalName, Object principal);
57
58 Object getRealmPrincipal(String realmName, String realmPrincipal);
59
60 Object removeRealmPrincipal(String realmName, String principalName);
61
62 }