001/** 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 003 * 004 * Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved 005 * 006 * The contents of this file are subject to the terms 007 * of the Common Development and Distribution License 008 * (the License). You may not use this file except in 009 * compliance with the License. 010 * 011 * You can obtain a copy of the License at 012 * https://opensso.dev.java.net/public/CDDLv1.0.html or 013 * opensso/legal/CDDLv1.0.txt 014 * See the License for the specific language governing 015 * permission and limitations under the License. 016 * 017 * When distributing Covered Code, include this CDDL 018 * Header Notice in each file and include the License file 019 * at opensso/legal/CDDLv1.0.txt. 020 * If applicable, add the following below the CDDL Header, 021 * with the fields enclosed by brackets [] replaced by 022 * your own identifying information: 023 * "Portions Copyrighted [year] [name of copyright owner]" 024 * 025 * $Id: AMRole.java,v 1.4 2008/06/25 05:41:22 qcheng Exp $ 026 * 027 */ 028 029package com.iplanet.am.sdk; 030 031import java.util.Map; 032import java.util.Set; 033 034import com.iplanet.sso.SSOException; 035 036/** 037 * <p> 038 * The <code>Role</code> interface provides methods to manage role 039 * <code>AMRole</code> objects can be obtained by using 040 * <code>AMStoreConnection</code>. A handle to this object can be obtained by 041 * using the DN of the object. 042 * 043 * <PRE> 044 * 045 * AMStoreConnection amsc = new AMStoreConnection(ssotoken); if 046 * (amsc.doesEntryExist(rDN)) { AMRole role = amsc.getRole(rDN); } 047 * 048 * </PRE> 049 * 050 * @deprecated As of Sun Java System Access Manager 7.1. 051 * @supported.all.api 052 */ 053public interface AMRole extends AMObject { 054 055 // Admin Role Types 056 /** 057 * Represents a Top Level Administrative Role 058 */ 059 public static final int TOP_LEVEL_ADMIN_ROLE = 1; 060 061 /** 062 * Represents a General Administrative Role 063 */ 064 public static final int GENERAL_ADMIN_ROLE = 2; 065 066 /** 067 * Represents a User Role 068 */ 069 public static final int USER_ROLE = 3; 070 071 /** 072 * Gets the type of the role. 073 * 074 * @return One of the possible values: 075 * <ul> 076 * <li><code>USER_ROLE</code> 077 * <li><code>GENERAL_ADMIN_ROLE</code> 078 * <li><code>TOP_LEVEL_ADMIN_ROLE</code> 079 * </ul> 080 * @throws AMException 081 * if an error is encountered when trying to access/retrieve 082 * data from the data store 083 * @throws SSOException 084 * if the single sign on token is no longer valid 085 */ 086 public int getRoleType() throws AMException, SSOException; 087 088 /** 089 * Sets the type of the role. 090 * 091 * @param roleType 092 * The type of the role. 093 * 094 * @throws AMException 095 * if an error is encountered when trying to access/retrieve 096 * data from the data store 097 * @throws SSOException 098 * if the single sign on token is no longer valid 099 */ 100 public void setRoleType(int roleType) throws AMException, SSOException; 101 102 /** 103 * Adds users to the role. 104 * 105 * @param users 106 * The set of user DN's to be added to the role. 107 * 108 * @throws AMException 109 * if an error is encountered when trying to access/retrieve 110 * data from the data store 111 * @throws SSOException 112 * if the single sign on token is no longer valid 113 */ 114 public void addUsers(Set users) throws AMException, SSOException; 115 116 /** 117 * Removes users from the role. 118 * 119 * @param users 120 * The set of user DN's to be removed from the role. 121 * 122 * @throws AMException 123 * if an error is encountered when trying to access/retrieve 124 * data from the data store 125 * @throws SSOException 126 * if the single sign on token is no longer valid 127 */ 128 public void removeUsers(Set users) throws AMException, SSOException; 129 130 /** 131 * Gets number of users in the role. 132 * 133 * @return Number of users in the role. 134 * 135 * @throws AMException 136 * if an error is encountered when trying to access/retrieve 137 * data from the data store 138 * @throws SSOException 139 * if the single sign on token is no longer valid 140 */ 141 public long getNumberOfUsers() throws AMException, SSOException; 142 143 /** 144 * Gets the DNs of users in the role. 145 * 146 * @return The DNs of users in the role. 147 * 148 * @throws AMException 149 * if an error is encountered when trying to access/retrieve 150 * data from the data store 151 * @throws SSOException 152 * if the single sign on token is no longer valid 153 */ 154 public Set getUserDNs() throws AMException, SSOException; 155 156 /** 157 * Searches for users in this role using wildcards and attribute values. 158 * Wildcards can be specified such as a*, *, *a. 159 * 160 * @param wildcard 161 * wildcard pattern to be used in the search 162 * @param level 163 * the search level that needs to be used ( 164 * <code>AMConstants.SCOPE_ONE</code> 165 * or <code>AMConstants.SCOPE_SUB</code>) 166 * @return Set DNs of Users matching the search 167 * @throws AMException 168 * if an error is encountered when trying to access/retrieve 169 * data from the data store 170 * @throws SSOException 171 * if the single sign on token is no longer valid 172 */ 173 public Set searchUsers(String wildcard, int level) throws AMException, 174 SSOException; 175 176 /** 177 * Searches for users in this people container using wildcards and attribute 178 * values. Wildcards can be specified such as a*, *, *a. 179 * 180 * @param wildcard 181 * wildcard pattern to be used in the search 182 * @param searchControl 183 * specifies the search scope to be used, VLV ranges etc., 184 * @return <code>AMSearchResults</code> which contains a Set DNs of Users 185 * matching the search. 186 * @throws AMException 187 * if an error is encountered when trying to access/retrieve 188 * data from the data store 189 * @throws SSOException 190 * if the single sign on token is no longer valid 191 */ 192 public AMSearchResults searchUsers(String wildcard, 193 AMSearchControl searchControl) throws AMException, SSOException; 194 195 /** 196 * Searches for users in this role using wildcards and attribute values. 197 * Wildcards can be specified such as a*, *, *a. To further refine the 198 * search, attribute-value pairs can be specified so that DNs of users with 199 * matching attribute-value pairs will be returned. 200 * 201 * @param wildcard 202 * wildcard pattern to be used in the search 203 * @param avPairs 204 * attribute-value pairs to match when searching users 205 * @param level 206 * the search level that needs to be used ( 207 * <code>AMConstants.SCOPE_ONE</code> 208 * or <code>AMConstants.SCOPE_SUB</code>) 209 * @return Set DNs of Users matching the search 210 * @throws AMException 211 * if an error is encountered when trying to access/retrieve 212 * data from the data store 213 * @throws SSOException 214 * if the single sign on token is no longer valid 215 */ 216 public Set searchUsers(String wildcard, Map avPairs, int level) 217 throws AMException, SSOException; 218 219 /** 220 * Searches for users in this group using wildcards and attribute values. 221 * Wildcards can be specified such as a*, *, *a. To further refine the 222 * search, attribute-value pairs can be specified so that DNs of users with 223 * matching attribute-value pairs will be returned. 224 * 225 * @param wildcard 226 * wildcard pattern to be used in the search 227 * @param avPairs 228 * attribute-value pairs to match when searching users 229 * @param searchControl 230 * specifies the search scope to be used, VLV ranges etc. 231 * @return <code>AMSearchResults</code> which contains a DNs of Users 232 * matching the search. 233 * @throws AMException 234 * if an error is encountered when trying to access/retrieve 235 * data from the data store 236 * @throws SSOException 237 * if the single sign on token is no longer valid 238 */ 239 public AMSearchResults searchUsers(String wildcard, Map avPairs, 240 AMSearchControl searchControl) throws AMException, SSOException; 241 242 /** 243 * Searches for users in this role using attribute values. Wildcards such as 244 * a*, *, *a can be specified for the attribute values. The DNs of users 245 * with matching attribute-value pairs will be returned. 246 * 247 * @param searchControl 248 * specifies the search scope to be used, VLV ranges etc. 249 * @param avfilter 250 * this attribute-value pairs filter will be logical AND with 251 * user search filter. 252 * @return <code>AMSearchResults</code> which contains a Set DNs of Users 253 * matching the search. 254 * @throws AMException 255 * if there is an internal error in the AM Store. 256 * @throws SSOException 257 * if the single sign on token is no longer valid. 258 */ 259 public AMSearchResults searchUsers(AMSearchControl searchControl, 260 String avfilter) throws AMException, SSOException; 261 262 /** 263 * Get requested templates defined for this role. 264 * 265 * @param templateReqs 266 * a Map of services names and template types. The key in the Map 267 * entry is the service name as a String, and the value of the 268 * Map entry is a <code>java.lang.Integer</code> whose integer 269 * value is one of <code>AMTemplate.DYNAMIC_TEMPLATE</code> 270 * <code>AMTemplate.POLICY_TEMPLATE</code> 271 * <code>AMTemplate.ORGANIZATION_TEMPLATE</code> 272 * <code>AMTemplate.ALL_TEMPLATES</code> 273 * @return a Set of <code>AMTemplate</code> objects representing the 274 * templates requested. If the <code>templateReqs</code> argument 275 * is null or empty, the returned set will contain the 276 * <code>AMTemplates</code> for each registered service which has 277 * a template defined. If there is no template defined for any 278 * registered services for this role, an empty Set will be returned. 279 * @throws AMException 280 * if an error is encountered when trying to access/retrieve 281 * data from the data store 282 * @throws SSOException 283 * if the single sign on token is no longer valid. 284 */ 285 public Set getTemplates(Map templateReqs) throws AMException, SSOException; 286 287 /** 288 * Get requested policy templates defined for this role. 289 * 290 * @param serviceNames 291 * a Set of services names, each specified as a 292 * <code>java.lang.String</code>. 293 * @return set of <code>AMTemplate</code> objects representing the policy 294 * templates requested. If the <code>serviceNames</code> argument 295 * is null or empty, the returned set will contain the 296 * <code>AMTemplates</code> for each registered service which has 297 * a policy template defined. If there is no policy template defined 298 * for any registered services for this role, an empty Set will be 299 * returned. 300 * @throws AMException 301 * if an error is encountered when trying to access/retrieve 302 * data from the data store. 303 * @throws SSOException 304 * if the single sign on token is no longer valid. 305 */ 306 public Set getPolicyTemplates(Set serviceNames) throws AMException, 307 SSOException; 308 309 /** 310 * Gets all the assigned policies created for this role 311 * 312 * @return Set a set of assigned policy DNs 313 * @throws AMException 314 * if an error is encountered when trying to access/retrieve 315 * data from the data store 316 * @throws SSOException 317 * if the single sign on token is no longer valid. 318 */ 319 public Set getAssignedPolicyDNs() throws AMException, SSOException; 320 321}