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: AMGroupContainer.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 group container.
038 * <code>AMGroupContainer</code> objects can be obtained by using
039 * <code>AMStoreConnection</code>. A handle to this object can be obtained by
040 * using the DN of the object.
041 * 
042 * <PRE>
043 * 
044 * AMStoreConnection amsc = new AMStoreConnection(ssotoken); if
045 * (amsc.doesEntryExist(gcDN)) { AMGroupContainer dg =
046 * amsc.getGroupContainer(gcDN); }
047 * 
048 * </PRE>
049 *
050 * @deprecated  As of Sun Java System Access Manager 7.1.
051 * @supported.all.api
052 */
053public interface AMGroupContainer extends AMObject {
054    /**
055     * Creates sub group containers in this group container.
056     * 
057     * @param groupContainers
058     *            The set of group container names to be created in this group
059     *            container.
060     * @return Set set of group container objects created.
061     * @throws AMException
062     *             if an error is encountered when trying to access/retrieve
063     *             data from the data store.
064     * @throws SSOException
065     *             if the single sign on token is no longer valid.
066     */
067    public Set createSubGroupContainers(Set groupContainers)
068            throws AMException, SSOException;
069
070    /**
071     * Creates sub group containers and initializes their attributes.
072     * 
073     * @param groupContainers
074     *            Map where the key is the name of the group container, and the
075     *            value is a Map to represent Attribute-Value Pairs .
076     * @return Set of group container objects created.
077     * @throws AMException
078     *             if an error is encountered when trying to access/retrieve
079     *             data from the data store.
080     * @throws SSOException
081     *             if the single sign on token is no longer valid.
082     */
083    public Set createSubGroupContainers(Map groupContainers)
084            throws AMException, SSOException;
085
086    /**
087     * Returns the sub containers in this group container. It returns sub
088     * containers either at one level or a whole subtree.
089     * 
090     * @param level
091     *            <code>AMConstants.SCOPE_ONE</code> or
092     *            <code>AMConstants.SCOPE_SUB</code> for returning sub
093     *            containers.
094     * @return The sub container distinguished names in this group container.
095     * @throws AMException
096     *             if an error is encountered when trying to access/retrieve
097     *             data from the data store or if level is invalid.
098     * @throws SSOException
099     *             if the single sign on token is no longer valid.
100     */
101    public Set getSubGroupContainerDNs(int level) throws AMException,
102            SSOException;
103
104    /**
105     * Returns number of sub group containers in the group container.
106     * 
107     * @return Number of sub group containers in the group container.
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 token on is no longer valid.
113     */
114    public long getNumberOfSubGroupContainers() throws AMException,
115            SSOException;
116
117    /**
118     * Deletes sub group containers in this group container.
119     * 
120     * @param groupContainers
121     *            set of container distinguished name to be deleted from the
122     *            group container.
123     * @throws AMException
124     *             if an error is encountered when trying to access/retrieve
125     *             data from the data store.
126     * @throws SSOException
127     *             if the single sign on token is no longer valid.
128     */
129    public void deleteSubGroupContainers(Set groupContainers)
130            throws AMException, SSOException;
131
132    /**
133     * Searches for sub group containers in this group container using wildcards
134     * and attribute values. Wildcards can be specified such as a*, *, *a. To
135     * further refine the search, attribute-value pairs can be specified so that
136     * distinguished name of group containers with matching attribute-value
137     * pairs will be returned.
138     * 
139     * @param wildcard
140     *            wildcard pattern to be used in the search.
141     * @param avPairs
142     *            attribute-value pairs to match when searching group
143     *            Containers.
144     * @param level
145     *            the search level that needs to be used
146     *            <code>AMConstants.SCOPE_ONE</code> or
147     *            <code>AMConstants.SCOPE_SUB</code>.
148     * @return Set distinguished name of group containers matching the search.
149     * @throws AMException
150     *             if an error is encountered when trying to access/retrieve
151     *             data from the data store
152     * @throws SSOException
153     *             if the single sign on token is no longer valid.
154     */
155    public Set searchSubGroupContainers(String wildcard, Map avPairs, int level)
156            throws AMException, SSOException;
157
158    /**
159     * Searches for group containers in this group container using wildcards and
160     * attribute values. Wildcards can be specified such as a*, *, *a. To
161     * further refine the search, attribute-value pairs can be specified so that
162     * distinguished names of group containers with matching attribute-value
163     * pairs will be returned.
164     * 
165     * @param wildcard
166     *            wildcard pattern to be used in the search.
167     * @param avPairs
168     *            attribute-value pairs to match when searching group
169     *            containers.
170     * @param searchControl
171     *            specifies the search scope to be used, VLV ranges etc.,
172     * @return <code>AMSearchResults</code> object which contains the set
173     *         distinguished name of group containers matching the search.
174     * @throws AMException
175     *             if an error is encountered when trying to access/retrieve
176     *             data from the data store.
177     * @throws SSOException
178     *             if the single sign on token is no longer valid.
179     */
180    public AMSearchResults searchSubGroupContainers(String wildcard,
181            Map avPairs, AMSearchControl searchControl) throws AMException,
182            SSOException;
183
184    /**
185     * Creates static groups in this group container.
186     * 
187     * @param groupNames
188     *            The set of static groups' names to be created in this group
189     *            container.
190     * @return set of static group objects created.
191     * @throws AMException
192     *             if an error is encountered when trying to access/retrieve
193     *             data from the data store.
194     * @throws SSOException
195     *             if the single sign on token is no longer valid.
196     * @throws AMException
197     *             if an error is encountered when trying to create entries in
198     *             the data store.
199     */
200    public Set createStaticGroups(Set groupNames) throws AMException,
201            SSOException;
202
203    /**
204     * Creates static groups and initializes their attributes.
205     * 
206     * @param groups
207     *            Map where the key is the name of the static group, and the
208     *            value is a Map to represent attribute-value Pairs.
209     * @return Set of group objects created.
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     * @throws AMException
216     *             if an error is encountered when trying to create entries in
217     *             the data store.
218     */
219    public Set createStaticGroups(Map groups) throws AMException, SSOException;
220
221    /**
222     * Creates static group. Takes <code>serviceNameAndAttr</code> map so that
223     * services can be assigned to the group which is just created.
224     * 
225     * @param name
226     *            of group to be created.
227     * @param attributes
228     *            attributes to be set in group node.
229     * @param serviceNameAndAttrs
230     *            map of service name to attribute map where the map is like
231     *            this:
232     * 
233     * <pre>
234     * &lt;serviceName&gt;&lt;AttrMap&gt;
235     *       (attrMap=&lt;attrName&gt;&lt;Set of attrvalues&gt;)
236     * </pre>
237     * 
238     * @return the newly created group.
239     * @throws AMException
240     *             if an error is encountered when trying to create entries in
241     *             the data store.
242     * @throws SSOException
243     *             if the single sign on token is no longer valid.
244     */
245    public AMGroup createStaticGroup(String name, Map attributes,
246            Map serviceNameAndAttrs) throws AMException, SSOException;
247
248    /**
249     * Creates dynamic groups in this group container.
250     * 
251     * @param groupNames
252     *            The set of dynamic groups' names to be created in this group
253     *            container.
254     * @return Set of dynamic group objects created.
255     * @throws AMException
256     *             if an error is encountered when trying to access/retrieve
257     *             data from the data store.
258     * @throws SSOException
259     *             if the single sign on token is no longer valid.
260     */
261    public Set createDynamicGroups(Set groupNames) throws AMException,
262            SSOException;
263
264    /**
265     * Creates dynamic groups and initializes their attributes.
266     * 
267     * @param groups
268     *            map of dynamic group's name to its attribute-value pairs map.
269     * @return Set of dynamic group objects created.
270     * @throws AMException
271     *             if an error is encountered when trying to access/retrieve
272     *             data from the data store.
273     * @throws SSOException
274     *             if the single sign on token is no longer valid.
275     */
276    public Set createDynamicGroups(Map groups) throws AMException, SSOException;
277
278    /**
279     * Creates dynamic group. Takes <code>serviceNameAndAttr</code> map so
280     * that services can be assigned to the group which is just created.
281     * 
282     * @param name
283     *            of group to be created.
284     * @param attributes
285     *            attributes to be set in group
286     * @param serviceNameAndAttrs
287     *            map of service name and attribute maps where the map is like
288     *            this:
289     * 
290     * <pre>
291     * &lt;serviceName&gt;&lt;AttrMap&gt;
292     *      (attrMap=&lt;attrName&gt;&lt;Set of attrvalues&gt;)
293     * </pre>
294     * 
295     * @return <code>AMGroup</code> object of newly created group.
296     * @throws AMException
297     *             if an error is encountered when trying to create entries in
298     *             the data store.
299     * @throws SSOException
300     *             if the single sign on token is no longer valid.
301     */
302    public AMGroup createDynamicGroup(String name, Map attributes,
303            Map serviceNameAndAttrs) throws AMException, SSOException;
304
305    /**
306     * Creates assignable dynamic groups in this group container.
307     * 
308     * @param groupNames
309     *            The set of assignable dynamic groups' names to be created in
310     *            this group container.
311     * @return Set of assignable dynamic group objects created.
312     * @throws AMException
313     *             if an error is encountered when trying to access/retrieve
314     *             data from the data store.
315     * @throws SSOException
316     *             if the single sign on token is no longer valid.
317     */
318    public Set createAssignableDynamicGroups(Set groupNames)
319            throws AMException, SSOException;
320
321    /**
322     * Creates assignable dynamic groups and initializes their attributes.
323     * 
324     * @param groups
325     *            Map where the key is the name of the assignable dynamic group,
326     *            and the value is a Map to represent attribute-value pairs.
327     * @return Set of assignable dynamic group objects created.
328     * @throws AMException
329     *             if an error is encountered when trying to access/retrieve
330     *             data from the data store.
331     * @throws SSOException
332     *             if the single sign on token is no longer valid.
333     */
334    public Set createAssignableDynamicGroups(Map groups) throws AMException,
335            SSOException;
336
337    /**
338     * Creates assignable dynamic group. Takes <code>serviceNameAndAttr</code>
339     * map so that services can be assigned to the group which is just created.
340     * 
341     * @param name
342     *            of group to be created.
343     * @param attributes
344     *            attribute-value pairs to be set.
345     * @param serviceNameAndAttrs
346     *            map of service name to attribute map where the map is like
347     *            this:
348     * 
349     * <pre>
350     * &lt;serviceName&gt;&lt;AttrMap&gt;
351     *      (attrMap=&lt;attrName&gt;&lt;Set of attrvalues&gt;)
352     * </pre>
353     * 
354     * @return <code>AMGroup</code> object of newly created group.
355     * @throws AMException
356     *             if an error is encountered when trying to create entries in
357     *             the data store.
358     * @throws SSOException
359     *             if the single sign on token is no longer valid.
360     */
361    public AMGroup createAssignableDynamicGroup(String name, Map attributes,
362            Map serviceNameAndAttrs) throws AMException, SSOException;
363
364    /**
365     * Gets the groups in this group container. It returns groups either at one
366     * level or a whole subtree.
367     * 
368     * @param level
369     *            the level (<code>AMConstants.SCOPE_ONE</code> or
370     *            <code>AMConstants.SCOPE_SUB</code>) for returning groups.
371     * @return the group distinguished names in this group container.
372     * @throws AMException
373     *             if an error is encountered when trying to access/retrieve
374     *             data from the data store or if the level is invalid.
375     * @throws SSOException
376     *             if the single sign on token is no longer valid.
377     */
378    public Set getGroupDNs(int level) throws AMException, SSOException;
379
380    /**
381     * Returns number of groups in the group container. It returns number of
382     * groups either at one level or a whole subtree.
383     * 
384     * @param level
385     *            the level (<code>AMConstants.SCOPE_ONE</code> or
386     *            <code>AMConstants.SCOPE_SUB</code>) for returning groups.
387     * @return the number of groups in the group container.
388     * @throws AMException
389     *             if an error is encountered when trying to access/retrieve
390     *             data from the data store.
391     * @throws SSOException
392     *             if the single sign on token is no longer valid.
393     */
394    public long getNumberOfGroups(int level) throws AMException, SSOException;
395
396    /**
397     * Deletes static groups in this group container.
398     * 
399     * @param groupDNs
400     *            The set of static group distinguished name to be deleted from
401     *            this group container.
402     * @throws AMException
403     *             if an error is encountered when trying to access/retrieve
404     *             data from the data store.
405     * @throws SSOException
406     *             if the single sign on token is no longer valid.
407     */
408    public void deleteStaticGroups(Set groupDNs) throws AMException,
409            SSOException;
410
411    /**
412     * Deletes dynamic groups in this group container.
413     * 
414     * @param groupDNs
415     *            The set of dynamic group distinguished names to be deleted
416     *            from this group container.
417     * @throws AMException
418     *             if an error is encountered when trying to access/retrieve
419     *             data from the data store.
420     * @throws SSOException
421     *             if the single sign on token is no longer valid.
422     */
423    public void deleteDynamicGroups(Set groupDNs) throws AMException,
424            SSOException;
425
426    /**
427     * Deletes assignable dynamic groups in this group container.
428     * 
429     * @param groupDNs
430     *            The set of assignable dynamic group distinguished names to be
431     *            deleted from this group container.
432     * @throws AMException
433     *             if an error is encountered when trying to access/retrieve
434     *             data from the data store.
435     * @throws SSOException
436     *             if the single sign on token is no longer valid.
437     */
438    public void deleteAssignableDynamicGroups(Set groupDNs) throws AMException,
439            SSOException;
440
441    /**
442     * Searches for groups in this group container using wildcards and attribute
443     * values. Wildcards can be specified such as a*, *, *a.
444     * 
445     * @param wildcard
446     *            pattern to be used in the search.
447     * @param avPairs
448     *            attribute-value pairs to match when searching groups.
449     * @param level
450     *            the search level that needs to be used
451     *            <code>AMConstants.SCOPE_ON</code> or
452     *            <code>AMConstants.SCOPE_SUB</code>.
453     * @return Set of distinguished name of groups matching the search.
454     * @throws AMException
455     *             if an error is encountered when trying to access/retrieve
456     *             data from the data store.
457     * @throws SSOException
458     *             if the single sign on token is no longer valid.
459     */
460    public Set searchGroups(String wildcard, Map avPairs, int level)
461            throws AMException, SSOException;
462
463    /**
464     * Searches for groups in this group container using wildcards. Wildcards
465     * can be specified such as a*, *, *a. Uses the
466     * <code>groupSearchTemplate</code>, if provided. Otherwise the default
467     * search templates for the types of groups are used.
468     * 
469     * @param wildcard
470     *            pattern to be used in the search.
471     * @param level
472     *            the search level that needs to be used
473     *            <code>AMConstants.SCOPE_ONE</code> or
474     *            <code>AMConstants.SCOPE_SUB</code>.
475     * @param groupSearchTemplate
476     *            name of the search template to be used to perform this search.
477     * @param avPairs
478     *            This option can be used to further qualify the search filter.
479     *            The attribute-value pairs provided by this map are appended to
480     *            the search filter.
481     * @return Set of distinguished name of assignable dynamic groups matching
482     *         the search.
483     * @throws AMException
484     *             if an error is encountered when trying to access/retrieve
485     *             data from the data store.
486     * @throws SSOException
487     *             if the single sign on token is no longer valid.
488     */
489    public Set searchGroups(String wildcard, int level,
490            String groupSearchTemplate, Map avPairs) throws AMException,
491            SSOException;
492
493    /**
494     * Searches for assignable dynamic groups in this group container using
495     * wildcards and attribute values. Wildcards can be specified such as a*, *,
496     * *a. To further refine the search, attribute-value pairs can be specified
497     * so that distinguished name of dynamic groups with matching
498     * attribute-value pairs will be returned.
499     * 
500     * @param wildcard
501     *            pattern to be used in the search.
502     * @param avPairs
503     *            attribute-value pairs to match when searching assignable
504     *            dynamic groups.
505     * @param groupSearchTemplate
506     *            Name of search template to be used to perform the search.
507     * @param searchControl
508     *            specifies the search scope to be used, VLV ranges etc.
509     * @return <code>AMSearchResults</code> which contains a set of
510     *         distinguished name of assignable dynamic groups matching the
511     *         search.
512     * @throws AMException
513     *             if an error is encountered when trying to access/retrieve
514     *             data from the data store.
515     * @throws SSOException
516     *             if the single sign on token is no longer valid.
517     */
518    public AMSearchResults searchGroups(String wildcard, Map avPairs,
519            String groupSearchTemplate, AMSearchControl searchControl)
520            throws AMException, SSOException;
521
522    /**
523     * Searches for groups in this group container using wildcards and attribute
524     * values. Wildcards can be specified such as a*, *, *a.
525     * 
526     * @param wildcard
527     *            pattern to be used in the search.
528     * @param avPairs
529     *            attribute-value pairs to match when searching groups.
530     * @param searchControl
531     *            specifies the search scope to be used.
532     * @return <code>AMSearchResults</code> which contains Set a of
533     *         distinguished name of groups matching the search.
534     * @throws AMException
535     *             if an error is encountered when trying to access/retrieve
536     *             data from the data store.
537     * @throws SSOException
538     *             if the single sign on token is no longer valid.
539     */
540    public AMSearchResults searchGroups(String wildcard, Map avPairs,
541            AMSearchControl searchControl) throws AMException, SSOException;
542
543    /**
544     * Searches for static groups in this group container using wildcards and
545     * attribute values. Wildcards can be specified such as a*, *, *a.
546     * 
547     * @param wildcard
548     *            pattern to be used in the search.
549     * @param avPairs
550     *            attribute-value pairs to match when searching groups.
551     * @param searchControl
552     *            specifies the search scope to be used.
553     * @return <code>AMSearchResults</code> which contains Set a of
554     *         distinguished name of groups matching the search.
555     * @throws AMException
556     *             if an error is encountered when trying to access/retrieve
557     *             data from the data store.
558     * @throws SSOException
559     *             if the single sign on token is no longer valid.
560     */
561    public AMSearchResults searchStaticGroups(String wildcard, Map avPairs,
562            AMSearchControl searchControl) throws AMException, SSOException;
563
564}




























































Copyright © 2010-2017, ForgeRock All Rights Reserved.