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 * @author Les Hazlewood 49 * @since 1.2 50 */ 51 public interface PrincipalMap extends PrincipalCollection, Map<String,Object> { 52 53 Map<String,Object> getRealmPrincipals(String realmName); 54 55 Map<String,Object> setRealmPrincipals(String realmName, Map<String,Object> principals); 56 57 Object setRealmPrincipal(String realmName, String principalName, Object principal); 58 59 Object getRealmPrincipal(String realmName, String realmPrincipal); 60 61 Object removeRealmPrincipal(String realmName, String principalName); 62 63 }