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}