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: AMGroup.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 * The <code>AMGroup</code> interface provides methods to manage group
038 *
039 * @deprecated  As of Sun Java System Access Manager 7.1.
040 * @supported.all.api
041 */
042abstract public interface AMGroup extends AMObject {
043    /**
044     * Returns number of users in the group.
045     * 
046     * @return Number of users in the group.
047     * @throws AMException
048     *             if an error is encountered when trying to access/retrieve
049     *             data from the data store.
050     * @throws SSOException
051     *             if the single sign on token no longer valid.
052     */
053    public long getNumberOfUsers() throws AMException, SSOException;
054
055    /**
056     * Returns the distinguished name of users in the group.
057     * 
058     * @return a set of user distinguished names in the group.
059     * @throws AMException
060     *             if an error is encountered when trying to access/retrieve
061     *             data from the data store.
062     * @throws SSOException
063     *             if the single sign on token is no longer valid.
064     */
065    public Set getUserDNs() throws AMException, SSOException;
066
067    /**
068     * Returns the distinguished name of users and nested groups in the group.
069     * 
070     * @return The distinguished name of users and nested groups in the group.
071     * @throws AMException
072     *             if an error is encountered when trying to access/retrieve
073     *             data from the data store.
074     * @throws SSOException
075     *             if the single sign on token is no longer valid.
076     */
077    public Set getUserAndGroupDNs() throws AMException, SSOException;
078
079    /**
080     * Nests the given group distinguished names in this the group. This will
081     * effectively make the groups <code>members</code> of this group. And any
082     * ACIs set for this group will be inherited by the nested groups and their
083     * members.
084     * 
085     * @param groups
086     *            The set of group distinguished names to be nested in this
087     *            group.
088     * @throws AMException
089     *             if an error is encountered when trying to access/retrieve
090     *             data from the data store.
091     * @throws SSOException
092     *             if the single sign on token is no longer valid.
093     */
094    public void addNestedGroups(Set groups) throws AMException, SSOException;
095
096    /**
097     * Searches for users in this group using wildcards and attribute values.
098     * Wildcards can be specified such as a*, *, *a.
099     * 
100     * @param wildcard
101     *            wildcard pattern to be used in the search
102     * @return Set of distinguished name of users matching the search
103     * @throws AMException
104     *             if an error is encountered when trying to access/retrieve
105     *             data from the data store
106     * @throws SSOException
107     *             if the single sign on token is no longer valid
108     */
109    public Set searchUsers(String wildcard) throws AMException, SSOException;
110
111    /**
112     * Searches for users in this group using wildcards. Wildcards can be
113     * specified such as a*, *, *a.
114     * 
115     * @param wildcard
116     *            wildcard pattern to be used in the search
117     * @param avPairs
118     *            attribute-value pairs to match when searching users
119     * @param searchControl
120     *            specifies the size limit and time limit
121     * @return <code>AMSearchResults</code> which contains a set of
122     *         distinguished name of Users matching the search.
123     * @throws AMException
124     *             if there is an internal error in the access management store.
125     * @throws SSOException
126     *             if the single sign on token is no longer valid.
127     */
128    public AMSearchResults searchUsers(String wildcard, Map avPairs,
129            AMSearchControl searchControl) throws AMException, SSOException;
130
131    /**
132     * Searches for users in this group using attribute values. Wildcards such
133     * as a*, *, *a can be specified for the attribute values. The distinguished
134     * names of users with matching attribute-value pairs will be returned.
135     * 
136     * @param searchControl
137     *            specifies the search scope to be used, VLV ranges etc.,
138     * @param avfilter
139     *            this attribute-value pairs filter will be logical AND with
140     *            user search filter.
141     * @return <code>AMSearchResults</code> which contains a set of
142     *         distinguished names of Users matching the search.
143     * @throws AMException
144     *             if there is an internal error in the access management Store.
145     * @throws SSOException
146     *             if the single sign on token is no longer valid.
147     */
148    public AMSearchResults searchUsers(AMSearchControl searchControl,
149            String avfilter) throws AMException, SSOException;
150
151    /**
152     * Creates static groups in this group.
153     * 
154     * @param groupNames
155     *            The set of static groups' names to be created in this group.
156     * @return set of static group objects created.
157     * @throws AMException
158     *             if an error is encountered when trying to access/retrieve
159     *             data from the data store.
160     * @throws SSOException
161     *             if the single sign on token is no longer valid.
162     */
163    public Set createStaticGroups(Set groupNames) throws AMException,
164            SSOException;
165
166    /**
167     * Creates static groups and initializes their attributes.
168     * 
169     * @param groups
170     *            Map where the key is the name of the static group, and the
171     *            value is a Map to represent Attribute-Value Pairs
172     * @return Set of group objects created.
173     * @throws AMException
174     *             if an error is encountered when trying to access/retrieve
175     *             data from the data store.
176     * @throws SSOException
177     *             if the single sign on token is no longer valid.
178     */
179    public Set createStaticGroups(Map groups) throws AMException, SSOException;
180
181    /**
182     * Creates dynamic groups in this group.
183     * 
184     * @param groupNames
185     *            The set of dynamic groups' names to be created in this group.
186     * @return Set of dynamic group objects created
187     * @throws AMException
188     *             if an error is encountered when trying to access/retrieve
189     *             data from the data store.
190     * @throws SSOException
191     *             if the single sign on token is no longer valid.
192     */
193    public Set createDynamicGroups(Set groupNames) throws AMException,
194            SSOException;
195
196    /**
197     * Creates dynamic groups and initializes their attributes.
198     * 
199     * @param groups
200     *            Map of name of the dynamic group to attribute-value pairs map.
201     * @return Set of dynamic group objects created.
202     * @throws AMException
203     *             if an error is encountered when trying to access/retrieve
204     *             data from the data store.
205     * @throws SSOException
206     *             if the single sign on token is no longer valid.
207     */
208    public Set createDynamicGroups(Map groups) throws AMException, SSOException;
209
210    /**
211     * Creates assignable dynamic groups in this group.
212     * 
213     * @param groupNames
214     *            The set of assignable dynamic groups' names to be created in
215     *            this group.
216     * @return Set of assignable dynamic group objects created.
217     * @throws AMException
218     *             if an error is encountered when trying to access/retrieve
219     *             data from the data store.
220     * @throws SSOException
221     *             if the single sign on token is no longer valid.
222     */
223    public Set createAssignableDynamicGroups(Set groupNames)
224            throws AMException, SSOException;
225
226    /**
227     * Creates assignable dynamic groups and initializes their attributes.
228     * 
229     * @param groups
230     *            Map of name of the assignable dynamic group to attribute-value
231     *            pairs map;
232     * @return Set of assignable dynamic group objects created.
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 Set createAssignableDynamicGroups(Map groups) throws AMException,
240            SSOException;
241
242    /**
243     * Gets the groups in this group. It returns groups either at one level or a
244     * whole subtree.
245     * 
246     * @param level
247     *            the level (<code>AMConstants.SCOPE_ONE</code> or
248     *            <code>AMConstants.SCOPE_SUB</code>) for returning groups.
249     * @return The group distinguished names in this group.
250     * @throws AMException
251     *             if an error is encountered when trying to access/retrieve
252     *             data from the data store or if the level is invalid.
253     * @throws SSOException
254     *             if the single sign on token is no longer valid.
255     */
256    public Set getGroupDNs(int level) throws AMException, SSOException;
257
258    /**
259     * Returns the groups nested in this group.
260     * 
261     * @return The group distinguished names nested in this group.
262     * @throws AMException
263     *             if an error is encountered when trying to access/retrieve
264     *             data from the data store.
265     * @throws SSOException
266     *             if the single sign on token is no longer valid.
267     */
268    public Set getNestedGroupDNs() throws AMException, SSOException;
269
270    /**
271     * Removes groups which are nested in this group.
272     * 
273     * @param groups
274     *            The set of user DN's to be removed from the static group.
275     * @throws AMException
276     *             if an error is encountered when trying to access/retrieve
277     *             data from the data store
278     * @throws SSOException
279     *             if the single sign on token is no longer valid
280     */
281    public void removeNestedGroups(Set groups) throws AMException, SSOException;
282
283    /**
284     * Returns number of groups in the group. It returns number of groups either
285     * at one level or a whole subtree.
286     * 
287     * @param level
288     *            the level (<code>AMConstants.SCOPE_ONE</code> or
289     *            <code>AMConstants.SCOPE_SUB</code>) for returning groups.
290     * @return Number of groups in the group.
291     * @throws AMException
292     *             if an error is encountered when trying to access/retrieve
293     *             data from the data store.
294     * @throws SSOException
295     *             if the single sign on token is no longer valid.
296     */
297    public long getNumberOfGroups(int level) throws AMException, SSOException;
298
299    /**
300     * Deletes static groups in this group.
301     * 
302     * @param groupDNs
303     *            The set of static group distinguished names to be deleted from
304     *            this group.
305     * 
306     * @throws AMException
307     *             if an error is encountered when trying to access/retrieve
308     *             data from the data store.
309     * @throws SSOException
310     *             if the single sign on token is no longer valid.
311     */
312    public void deleteStaticGroups(Set groupDNs) throws AMException,
313            SSOException;
314
315    /**
316     * Deletes dynamic groups in this group.
317     * 
318     * @param groupDNs
319     *            The set of dynamic group distinguished names to be deleted
320     *            from this group.
321     * @throws AMException
322     *             if an error is encountered when trying to access/retrieve
323     *             data from the data store
324     * @throws SSOException
325     *             if the single sign on token is no longer valid
326     */
327    public void deleteDynamicGroups(Set groupDNs) throws AMException,
328            SSOException;
329
330    /**
331     * Deletes assignable dynamic groups in this group.
332     * 
333     * @param groupDNs
334     *            The set of assignable dynamic group distinguished names to be
335     *            deleted from this group.
336     * @throws AMException
337     *             if an error is encountered when trying to access/retrieve
338     *             data from the data store.
339     * @throws SSOException
340     *             if the single sign on token is no longer valid.
341     */
342    public void deleteAssignableDynamicGroups(Set groupDNs) throws AMException,
343            SSOException;
344
345    /**
346     * Searches for groups in this group using wildcards. Wildcards can be
347     * specified such as a*, *, *a.
348     * 
349     * @param wildcard
350     *            wildcard pattern to be used in the search
351     * @param level
352     *            the search level that needs to be used (
353     *            <code>AMConstants.SCOPE_ONE</code>
354     *            or <code>AMConstants.SCOPE_TREE</code>).
355     * @return Set of distinguished name of sub groups matching the search
356     * @throws AMException
357     *             if an error is encountered when trying to access/retrieve
358     *             data from the data store.
359     * @throws SSOException
360     *             if the single sign on token is no longer valid.
361     */
362    public Set searchGroups(String wildcard, int level) throws AMException,
363            SSOException;
364
365    /**
366     * Searches for groups in this group using wildcards and attribute values.
367     * Wildcards can be specified such as a*, *, *a.
368     * 
369     * @param wildcard
370     *            wildcard pattern to be used in the search
371     * @param avPairs
372     *            attribute-value pairs to match when searching groups
373     * @param level
374     *            the search level that needs to be used (
375     *            <code>AMConstants.SCOPE_ONE</code>
376     *            or <code>AMConstants.SCOPE_TREE</code>)
377     * @return Set of distinguished name of groups matching the search
378     * @throws AMException
379     *             if an error is encountered when trying to access/retrieve
380     *             data from the data store.
381     * @throws SSOException
382     *             if the single sign on token is no longer valid.
383     */
384    public Set searchGroups(String wildcard, Map avPairs, int level)
385            throws AMException, SSOException;
386
387    /**
388     * Searches for groups in this group using wildcards and attribute values.
389     * Wildcards can be specified such as a*, *, *a.
390     * 
391     * @param wildcard
392     *            wildcard pattern to be used in the search
393     * @param avPairs
394     *            attribute-value pairs to match when searching groups
395     * @param searchControl
396     *            specifies the search scope to be used
397     * @return <code>AMSearchResults</code> which contains a set of
398     *         distinguished name of groups matching the search.
399     * @throws AMException
400     *             if an error is encountered when trying to access/retrieve
401     *             data from the data store.
402     * @throws SSOException
403     *             if the single sign on token is no longer valid.
404     */
405    public AMSearchResults searchGroups(String wildcard, Map avPairs,
406            AMSearchControl searchControl) throws AMException, SSOException;
407}