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: AMEntity.java,v 1.4 2008/06/25 05:41:20 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 * This interface provides methods to manage entities. The entities that can be 038 * managed by these interfaces are configured in the <code> DAI </code> service 039 * of Access Manager. This service will group the name of the entity and the 040 * creation templates, search template, primary LDAP <code>objectclass</code> 041 * and the status attribute (if any). This grouping is used to determine what 042 * object is being managed. <code>AMEntity</code> objects can be obtained by 043 * using <code>AMStoreConnection</code>. A handle to this object can be 044 * obtained by using the DN of the object. 045 * 046 * <PRE> 047 * 048 * AMStoreConnection amsc = new AMStoreConnection(ssotoken); if 049 * (amsc.doesEntryExist(uDN)) { AMEntity entity = amsc.getEntity(uDN); } 050 * 051 * </PRE> 052 * 053 * @deprecated As of Sun Java System Access Manager 7.1. 054 * @supported.all.api 055 */ 056public interface AMEntity { 057 058 /** 059 * Returns the distinguished name of the entry. 060 * 061 * @return distinguished name. 062 */ 063 public String getDN(); 064 065 /** 066 * Returns the parent distinguished name of the entry. 067 * 068 * @return distinguished name. 069 */ 070 public String getParentDN(); 071 072 /** 073 * Returns true if the entry exists in the directory or not. First a syntax 074 * check is done on the distinguished name string corresponding to the 075 * entry. If the distinguished name syntax is valid, a directory call will 076 * be made to check for the existence of the entry. 077 * <p> 078 * 079 * <B>NOTE:</B> This method internally invokes a call to the directory to 080 * verify the existence of the entry. There could be a performance overhead. 081 * Hence, please use your discretion while using this method. 082 * 083 * @return false if the entry does not have a valid DN syntax or if the 084 * entry does not exists in the Directory. 085 * @throws SSOException 086 * if the single sign on token is no longer valid. 087 */ 088 public boolean isExists() throws SSOException; 089 090 /** 091 * Returns Map of all attributes. Map key is the attribute name and value is 092 * the attribute value. 093 * 094 * @return Map of all attributes. 095 * @throws AMException 096 * if an error is encountered when trying to read attributes 097 * from the data store. 098 * @throws SSOException 099 * if the single sign on token is no longer valid. 100 */ 101 public Map getAttributes() throws AMException, SSOException; 102 103 /** 104 * Returns Map of specified attributes. Map key is the attribute name and 105 * value is the attribute value. 106 * 107 * @param attributeNames 108 * The Set of attribute names. 109 * @return Map of specified attributes. 110 * @throws AMException 111 * if an error is encountered when trying to access/retrieve 112 * data from the data store 113 * @throws SSOException 114 * if the single sign on token is no longer valid. 115 */ 116 public Map getAttributes(Set attributeNames) throws AMException, 117 SSOException; 118 119 /** 120 * Sets attribute values in this <code>AMObject</code>. Note that this 121 * method sets or replaces the attribute value with the new value supplied. 122 * Also, the attributes changed by this method are not committed to the LDAP 123 * data store unless the method {@link AMObject#store store()} is called 124 * explicitly. 125 * 126 * @param attributes 127 * map of attribute name to a set of attribute values. Each of 128 * the attribute value must be a string value. 129 * @throws AMException 130 * if an error is encountered when trying to set/replace 131 * attributes from the data store. 132 * @throws SSOException 133 * if the single sign on token is no longer valid. 134 */ 135 public void setAttributes(Map attributes) throws AMException, SSOException; 136 137 /** 138 * Removes attributes in this <code>AMObject</code>. The attributes are 139 * removed from the LDAP data store. 140 * 141 * @param attributes 142 * The Set of attribute names. 143 * @throws AMException 144 * if an error is encountered when trying to remove attributes 145 * from the data store. 146 * @throws SSOException 147 * if the single sign on token is no longer valid. 148 */ 149 public void removeAttributes(Set attributes) throws AMException, 150 SSOException; 151 152 /** 153 * Activates the entity (if a status attribute is defined for this entity). 154 * If a status attribute is not defined then this method returns without 155 * doing anything. 156 * 157 * @throws AMException 158 * if an error is encountered when trying to activate the 159 * managed object. 160 * @throws SSOException 161 * if the single sign on token is no longer valid. 162 */ 163 public void activate() throws AMException, SSOException; 164 165 /** 166 * Deactivates the entity (if a status attribute is defined for this 167 * entity). If a status attribute is not defined then this method returns 168 * without doing anything. 169 * 170 * @throws AMException 171 * if an error is encountered when trying to deactivate the 172 * managed object. 173 * @throws SSOException 174 * if the single sign on token is no longer valid. 175 */ 176 public void deactivate() throws AMException, SSOException; 177 178 /** 179 * Returns true if the entity is activated. If the entity does not have a 180 * status attribute, then this method returns true, rather that throw an 181 * exception. 182 * 183 * @return true if the entity is activated. 184 * @throws AMException 185 * if an error is encountered when trying to get the status 186 * attribute from the data store. 187 * @throws SSOException 188 * if the single sign on token is no longer valid. 189 */ 190 public boolean isActivated() throws AMException, SSOException; 191 192 /** 193 * Deletes the object. 194 * 195 * @see #delete(boolean) 196 * @see #purge(boolean, int) 197 * @throws AMException 198 * if an error is encountered when trying to delete entry from 199 * the data store. 200 * @throws SSOException 201 * if the single sign on token is no longer valid. 202 */ 203 public void delete() throws AMException, SSOException; 204 205 /** 206 * Deletes object(s). This method takes a boolean parameter, if its value is 207 * true, will remove the object and any objects under it, otherwise, will 208 * try to remove the object only. Two notes on recursive delete. First, be 209 * aware of the PERFORMANCE hit when large amount of child objects present. 210 * In the soft-delete mode, this method will mark the following objects for 211 * deletion: <code>Organization, Group, User</code> 212 * <code>purge()</code> 213 * should be used to physically delete this object. 214 * 215 * @see #purge(boolean, int) 216 * 217 * @param recursive 218 * if true delete the object and any objects under it, otherwise, 219 * delete the object only. 220 * @throws AMException 221 * if an error is encountered when trying to delete entry from 222 * the data store. 223 * @throws SSOException 224 * if the single sign on token is no longer valid. 225 */ 226 public void delete(boolean recursive) throws AMException, SSOException; 227 228 /** 229 * Gets the object's organization distinguished name. NOTE: Obtaining an 230 * organization distinguished name involves considerable overhead. Hence 231 * after obtaining the organization distinguished name, each object saves 232 * this information. Consecutives method calls on this object fetch the 233 * value stored in the object. Creating a new <code>AMEntity</code> 234 * instance every time to obtain the organization distinguished name is not 235 * recommended. 236 * 237 * @return The object's organization DN. 238 * @throws AMException 239 * if an error is encountered when trying to access/retrieve 240 * data from the data store or the object does not have 241 * organization distinguished name. 242 * @throws SSOException 243 * if the single sign on token is no longer valid. 244 */ 245 public String getOrganizationDN() throws AMException, SSOException; 246 247 /** 248 * Stores the change to directory server. This method should be called after 249 * doing <code>setAttributes</code> so that the changes that are made can 250 * be permanently committed to the LDAP data store. 251 * 252 * @throws AMException 253 * if an error is encountered when trying to save the attributes 254 * to the data store. 255 * @throws SSOException 256 * if the single sign on token is no longer valid. 257 */ 258 public void store() throws AMException, SSOException; 259 260 /** 261 * Purges entry from data store. It will physically delete the entry from 262 * the data store. This method will override the soft-delete option, which 263 * the method <code>delete()</code> will not. There is a big PERFORMANCE 264 * hit if this method is used to delete a large organization in the 265 * recursive mode. 266 * 267 * @see #delete() 268 * @param recursive 269 * true to recursively delete the whole subtree. 270 * @param graceperiod 271 * If set to an integer greater than -1, it will verify if the 272 * object was last modified at least that many days ago before 273 * physically deleting it. Pre/Post Callback plugins as 274 * registered in the Administration Service, will be called upon 275 * object deletion. If any of the pre-callback classes throw an 276 * exception, then the operation is aborted. 277 * @throws AMException 278 * if there is an internal error in the data store. 279 * @throws SSOException 280 * if the single sign on token is no longer valid. 281 */ 282 public void purge(boolean recursive, int graceperiod) throws AMException, 283 SSOException; 284 285}