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 */ 019package org.apache.shiro.subject; 020 021import 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 */ 051public 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}