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: AMPeopleContainer.java,v 1.4 2008/06/25 05:41:21 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 people container.
038 * <code>AMPeopleContainer</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(pcDN)) { AMPeopleContainer pc =
046 * amsc.getPeopleContainer(oDN); }
047 * 
048 * </PRE>
049 *
050 * @deprecated  As of Sun Java System Access Manager 7.1.
051 * @supported.all.api
052 */
053public interface AMPeopleContainer extends AMObject {
054
055    /**
056     * Creates users in this people container. For each user the, object classes
057     * specified by organization type attribute
058     * <code>iplanet-am-required-services</code> of the service
059     * <code>iPlanetAMAdminConsoleService</code> template are added. If a
060     * corresponding template does not exist, the default values are picked up
061     * from schema.
062     * 
063     * @param users
064     *            The set of user names to be created in this people container.
065     * @return Set Set of User objects created
066     * @throws AMException
067     *             if an error is encountered when trying to access/retrieve
068     *             data from the data store
069     * @throws SSOException
070     *             if the single sign on token is no longer valid
071     */
072    public Set createUsers(Set users) throws AMException, SSOException;
073
074    /**
075     * Creates users and initializes their attributes. For each user the, object
076     * classes specified by organization type attribute
077     * <code>iplanet-am-required-services</code> of the service
078     * <code>iPlanetAMAdminConsoleService</code> template are added. If a
079     * corresponding template does not exist, the default values are picked up
080     * from schema.
081     * 
082     * @param users
083     *            Map where the key is the name of the user, and the value is a
084     *            Map to represent Attribute-Value Pairs
085     * @return Set Set of User objects created
086     * @throws AMException
087     *             if an error is encountered when trying to access/retrieve
088     *             data from the data store
089     * @throws SSOException
090     *             if the single sign on token is no longer valid
091     */
092    public Set createUsers(Map users) throws AMException, SSOException;
093
094    /**
095     * Creates users and initializes their attributes.
096     * 
097     * @param users
098     *            Map where the key is the name of the user, and the value is a
099     *            Map to represent Attribute-Value Pairs
100     * @param serviceNames
101     *            Set of service names assigned to the users where the key is
102     *            the name of the user, and the value is a Map to represent
103     *            Attribute-Value Pairs
104     * @return Set Set of User objects created
105     * @throws AMException
106     *             if an error is encountered when trying to access/retrieve
107     *             data from the data store
108     * @throws SSOException
109     *             if the single sign on token is no longer valid
110     */
111    public Set createUsers(Map users, Set serviceNames) throws AMException,
112            SSOException;
113
114    /**
115     * Create user and initializes the attributes. For each user the, object
116     * classes specified by organization type attribute
117     * <code>iplanet-am-required-services</code> of the service
118     * <code>iPlanetAMAdminConsoleService</code> template are added. If a
119     * corresponding template does not exist, the default values are picked up
120     * from schema. Also services as defined in the arguments, are assigned to
121     * the user, with default values being picked up from the service schema if
122     * none are provided for required attributes of the service.
123     * 
124     * @param uid
125     *            value of naming attribute for user.
126     * @param attrMap
127     *            attribute-values to be set in the user entry.
128     * @param serviceNameAndAttrs
129     *            service names and attributes to be assigned to the user.
130     * @return AMUser object of newly created user.
131     * @throws AMException
132     *             if an error is encountered when trying to access/retrieve
133     *             data from the data store.
134     * @throws SSOException
135     *             if the single sign on token is no longer valid.
136     */
137    public AMUser createUser(String uid, Map attrMap, Map serviceNameAndAttrs)
138            throws AMException, SSOException;
139
140    /**
141     * Deletes users from this people container.
142     * 
143     * @param users
144     *            The set of user DN's to be deleted from the people container.
145     * 
146     * @throws AMException
147     *             if an error is encountered when trying to access/retrieve
148     *             data from the data store
149     * @throws SSOException
150     *             if the single sign on token is no longer valid
151     */
152    public void deleteUsers(Set users) throws AMException, SSOException;
153
154    /**
155     * Gets number of users in the people container.
156     * 
157     * @return Number of users in the people container.
158     * 
159     * @throws AMException
160     *             if an error is encountered when trying to access/retrieve
161     *             data from the data store
162     * @throws SSOException
163     *             if the single sign on token is no longer valid
164     */
165    public long getNumberOfUsers() throws AMException, SSOException;
166
167    /**
168     * Gets the names (DNs) of users in the people container.
169     * 
170     * @return Set The names(DNs) of users in the people container.
171     * 
172     * @throws AMException
173     *             if an error is encountered when trying to access/retrieve
174     *             data from the data store
175     * @throws SSOException
176     *             if the single sign on token is no longer valid
177     */
178    public Set getUserDNs() throws AMException, SSOException;
179
180    /**
181     * Creates sub people containers in this people container.
182     * 
183     * @param peopleContainersNames
184     *            The set of people container names to be created in this people
185     *            container.
186     * @return set of <code>PeopleContainer</code> 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 createSubPeopleContainers(Set peopleContainersNames)
194            throws AMException, SSOException;
195
196    /**
197     * Creates sub people containers and initializes their attributes.
198     * 
199     * @param peopleContainers
200     *            Map where the key is the name of the people container, and the
201     *            value is a Map to represent Attribute-Value Pairs.
202     * @return set of <code>PeopleContainer</code> objects created.
203     * @throws AMException
204     *             if an error is encountered when trying to access/retrieve
205     *             data from the data store.
206     * @throws SSOException
207     *             if the single sign on token is no longer valid.
208     */
209    public Set createSubPeopleContainers(Map peopleContainers)
210            throws AMException, SSOException;
211
212    /**
213     * Gets the sub containers in this people container. It returns sub
214     * containers either at one level or a whole subtree.
215     * 
216     * @param level
217     *            the level (<code>SCOPE_ONE</code> or
218     *            <code>SCOPE_TREE</code>) for returning sub containers
219     * @return The sub container DNs in this people container.
220     * @throws AMException
221     *             if an error is encountered when trying to access/retrieve
222     *             data from the data store and if the level is invalid.
223     * @throws SSOException
224     *             if the single sign on token is no longer valid.
225     */
226    public Set getSubPeopleContainerDNs(int level) throws AMException,
227            SSOException;
228
229    /**
230     * Gets number of sub people containers in the people container.
231     * 
232     * @return Number of sub people containers in the people container.
233     * 
234     * @throws AMException
235     *             if an error is encountered when trying to access/retrieve
236     *             data from the data store
237     * @throws SSOException
238     *             if the single sign on token is no longer valid
239     */
240    public long getNumberOfSubPeopleContainers() throws AMException,
241            SSOException;
242
243    /**
244     * Deletes sub people containers in this people container.
245     * 
246     * @param peopleContainers
247     *            The set of container DN's to be deleted from the people
248     *            container.
249     * 
250     * @throws AMException
251     *             if an error is encountered when trying to access/retrieve
252     *             data from the data store
253     * @throws SSOException
254     *             if the single sign on token is no longer valid
255     */
256    public void deleteSubPeopleContainers(Set peopleContainers)
257            throws AMException, SSOException;
258
259    /**
260     * Searches for users in this people container using wildcards and attribute
261     * values. Wildcards can be specified such as a*, *, *a.
262     * 
263     * @param wildcard
264     *            wildcard pattern to be used in the search
265     * @param level
266     *            the search level that needs to be used (
267     *            <code>AMConstants.SCOPE_ONE</code>
268     *            or <code>AMConstants.SCOPE_TREE</code>)
269     * @return Set DNs of Users matching the search
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 searchUsers(String wildcard, int level) throws AMException,
277            SSOException;
278
279    /**
280     * Searches for users in this organization using wildcards and attribute
281     * values. Wildcards can be specified such as a*, *, *a. SDK users the
282     * <code>userSearchTemplate</code>, if provided. Otherwise, it uses the
283     * <code>BasicUserSearchTemplate</code>. Any <code>%U</code> in the
284     * search template are replaced with the wildcard.
285     * 
286     * @param wildcard
287     *            wildcard pattern to be used in the search
288     * @param level
289     *            the search level that needs to be used (
290     *            <code>AMConstants.SCOPE_ONE</code>
291     *            or <code>AMConstants.SCOPE_TREE</code>)
292     * @param userSearchTemplate
293     *            Name of search template to use. If null is passed then the
294     *            default search template <code>BasicUserSearch</code> is
295     *            used.
296     * @param avPairs
297     *            This option can be used to further qualify the search filter.
298     *            The attribute-value pairs provided by this map are appended to
299     *            the search filter.
300     * 
301     * @return Set DNs of Users matching the search
302     * 
303     * @throws AMException
304     *             if an error is encountered when trying to access/retrieve
305     *             data from the data store
306     * @throws SSOException
307     *             if the single sign on token is no longer valid
308     */
309
310    public Set searchUsers(String wildcard, int level,
311            String userSearchTemplate, Map avPairs) throws AMException,
312            SSOException;
313
314    /**
315     * Searches for users in this people container using wildcards and attribute
316     * values. Wildcards can be specified such as a*, *, *a.
317     * 
318     * @param wildcard
319     *            wildcard pattern to be used in the search
320     * @param searchControl
321     *            specifies the search scope to be used, VLV ranges etc.,
322     * 
323     * @return <code>AMSearchResults</code> which contains a Set DNs of Users
324     *         matching the search.
325     * @throws AMException
326     *             if an error is encountered when trying to access/retrieve
327     *             data from the data store
328     * @throws SSOException
329     *             if the single sign on token is no longer valid
330     */
331    public AMSearchResults searchUsers(String wildcard,
332            AMSearchControl searchControl) throws AMException, SSOException;
333
334    /**
335     * Searches for users in this group using wildcards and attribute values.
336     * Wildcards can be specified such as a*, *, *a. To further refine the
337     * search, attribute-value pairs can be specified so that DNs of users with
338     * matching attribute-value pairs will be returned.
339     * 
340     * @param wildcard
341     *            wildcard pattern to be used in the search
342     * @param avPairs
343     *            attribute-value pairs to match when searching users
344     * @param level
345     *            the search level that needs to be used (
346     *            <code>AMConstants.SCOPE_ONE</code>
347     *            or <code>AMConstants.SCOPE_TREE</code>)
348     * @return Set DNs of Users matching the search
349     * @throws AMException
350     *             if an error is encountered when trying to access/retrieve
351     *             data from the data store
352     * @throws SSOException
353     *             if the single sign on token is no longer valid
354     */
355    public Set searchUsers(String wildcard, Map avPairs, int level)
356            throws AMException, SSOException;
357
358    /**
359     * Searches for users in this group using wildcards and attribute values.
360     * Wildcards can be specified such as a*, *, *a. To further refine the
361     * search, attribute-value pairs can be specified so that DNs of users with
362     * matching attribute-value pairs will be returned.
363     * 
364     * @param wildcard
365     *            wildcard pattern to be used in the search
366     * @param avPairs
367     *            attribute-value pairs to match when searching users
368     * @param searchControl
369     *            specifies the search scope to be used, VLV ranges etc.,
370     * 
371     * @return <code>AMSearchResults</code> which contains a Set DNs of Users
372     *         matching the search.
373     * 
374     * @throws AMException
375     *             if an error is encountered when trying to access/retrieve
376     *             data from the data store
377     * @throws SSOException
378     *             if the single sign on token is no longer valid
379     */
380    public AMSearchResults searchUsers(String wildcard, Map avPairs,
381            AMSearchControl searchControl) throws AMException, SSOException;
382
383    /**
384     * Searches for users in this people container using wildcards and attribute
385     * values. Wildcards can be specified such as a*, *, *a. To further refine
386     * the search, attribute-value pairs can be specified so that DNs of users
387     * with matching attribute-value pairs will be returned.
388     * 
389     * @param wildcard
390     *            wildcard pattern to be used in the search
391     * @param searchControl
392     *            specifies the search scope to be used, VLV ranges etc.,
393     * @param avfilter
394     *            this attribute-value pairs filter will be logical AND with
395     *            user search filter.
396     * @return <code>AMSearchResults</code> which contains a Set DNs of Users
397     *         matching the search.
398     * @throws AMException
399     *             if an error is encountered when trying to access/retrieve
400     *             data from the data store.
401     * @throws SSOException
402     *             if the single sign on token is no longer valid.
403     */
404    public AMSearchResults searchUsers(String wildcard,
405            AMSearchControl searchControl, String avfilter) throws AMException,
406            SSOException;
407
408    /**
409     * Searches for users in this people container using attribute values.
410     * Wildcards such as a*, *, *a can be specified for the attribute values.
411     * The DNs of users with matching attribute-value pairs will be returned.
412     * 
413     * @param searchControl
414     *            specifies the search scope to be used, VLV ranges etc.
415     * @param avfilter
416     *            this attribute-value pairs filter will be logical AND with
417     *            user search filter.
418     * @return <code>AMSearchResults</code> which contains a Set DNs of Users
419     *         matching the search.
420     * @throws AMException
421     *             if there is an internal error in the AM Store
422     * @throws SSOException
423     *             if the single sign on token is no longer valid
424     */
425    public AMSearchResults searchUsers(AMSearchControl searchControl,
426            String avfilter) throws AMException, SSOException;
427
428    /**
429     * Searches for users in this people container using wildcards and attribute
430     * values. Wildcards can be specified such as a*, *, *a. To further refine
431     * the search, attribute-value pairs can be specified so that DNs of users
432     * with matching attribute-value pairs will be returned.
433     * 
434     * @param wildcard
435     *            wildcard pattern to be used in the search
436     * @param avPairs
437     *            attribute-value pairs to match when searching users
438     * @param userSearchTemplate
439     *            Name of user search template to be used.
440     * @param searchControl
441     *            specifies the search scope to be used, VLV ranges etc.,
442     * @return <code>AMSearchResults</code> which contains a Set DNs of Users
443     *         matching the search.
444     * @throws AMException
445     *             if an error is encountered when trying to access/retrieve
446     *             data from the data store.
447     * @throws SSOException
448     *             if the single sign on token is no longer valid
449     */
450    public AMSearchResults searchUsers(String wildcard, Map avPairs,
451            String userSearchTemplate, AMSearchControl searchControl)
452            throws AMException, SSOException;
453
454    /**
455     * Create resources in this organization. Resource is a specialized entity,
456     * which is created in the people container and is a leaf node.
457     * 
458     * @param resourceNames
459     *            Names of the resources to be created.
460     * @return Set of <code>AMResource</code> objects
461     * @throws AMException
462     *             If there is an error when trying to save to the data store
463     * @throws SSOException
464     *             If the SSO Token is invalid.
465     */
466    public Set createResources(Set resourceNames) throws AMException,
467            SSOException;
468
469    /**
470     * Create resources in this organization. Resource is a specialized entity,
471     * which is created in the people container and is a leaf node.
472     * 
473     * @param resourceMap
474     *            Map of resource names to be created and attributes to be set
475     *            in the newly creates resource.
476     * @return Set of <code>AMResource</code> objects.
477     * @throws AMException
478     *             If there is an error when trying to save to the data store
479     * @throws SSOException
480     *             If the SSO Token is invalid.
481     */
482    public Set createResources(Map resourceMap) throws AMException,
483            SSOException;
484
485    /**
486     * Create managed entities in this container. Supported entities, as defined
487     * in the configuration service <code>DAI</code>, can be created using
488     * this method.
489     * 
490     * @param type
491     *            Type of entity to be create (For example "user" or "agent")
492     * @param entities
493     *            Set of names for the entities to be created
494     * @return Set of <code>AMEntity</code> objects
495     * @throws AMException
496     *             If there is an error when trying to save to the data store
497     * @throws SSOException
498     *             If the SSO Token is invalid.
499     */
500    public Set createEntities(String type, Set entities) throws AMException,
501            SSOException;
502
503    /**
504     * Creates entities and initializes their attributes. Supported entities, as
505     * defined in the configuration service <code>DAI</code>, can be created
506     * using this method.
507     * 
508     * @param stype
509     *            Type of entity to be create (For example "user" or "agent")
510     * @param entities
511     *            Map where the key is the name of the entity, and the value is
512     *            a Map to represent Attribute-Value Pairs
513     * @return Set Set of <code>AMEntity</code> objects created
514     * @throws AMException
515     *             if an error is encountered when trying to create entity in
516     *             the data store.
517     * @throws SSOException
518     *             if the single sign on token is no longer valid
519     */
520    public Set createEntities(String stype, Map entities) throws AMException,
521            SSOException;
522
523    /**
524     * Searches for resources in this organization using wildcards and attribute
525     * values. Wildcards can be specified such as a*, *, *a. SDK uses the
526     * <code>resourceSearchTemplate</code>, if provided. Otherwise, it uses
527     * the <code>BasicResourceSearchTemplate</code>.
528     * 
529     * @param wildcard
530     *            wildcard pattern to be used in the search
531     * @param level
532     *            the search level that needs to be used (
533     *            <code>AMConstants.SCOPE_ONE</code>
534     *            or <code>AMConstants.SCOPE_TREE</code>)
535     * @param resourceSearchTemplate
536     *            Name of resource search template to be used.
537     * @param avPairs
538     *            This option can be used to further qualify the search filter.
539     *            The attribute-value pairs provided by this map are appended to
540     *            the search filter.
541     * @return Set DNs of resources matching the search
542     * @throws AMException
543     *             if an error is encountered when trying to access/retrieve
544     *             data from the data store.
545     * @throws SSOException
546     *             if the single sign on token is no longer valid.
547     */
548    public Set searchResources(String wildcard, int level,
549            String resourceSearchTemplate, Map avPairs) throws AMException,
550            SSOException;
551
552    /**
553     * Searches for resources in this people container using wildcards and
554     * attribute values. Wildcards can be specified such as a*, *, *a. To
555     * further refine the search, attribute-value pairs can be specified so that
556     * DNs of users with matching attribute-value pairs will be returned.
557     * 
558     * @param wildcard
559     *            wildcard pattern to be used in the search
560     * @param avPairs
561     *            attribute-value pairs to match when searching users
562     * @param rSearchTemplate
563     *            Name of resource search template to be used.
564     * @param searchControl
565     *            specifies the search scope to be used, VLV ranges etc.,
566     * @return <code>AMSearchResults</code> which contains a Set DNs of
567     *         resources matching the search.
568     * @throws AMException
569     *             if an error is encountered when trying to access/retrieve
570     *             data from the data store
571     * @throws SSOException
572     *             if the single sign on token is no longer valid
573     */
574    public AMSearchResults searchResources(String wildcard, Map avPairs,
575            String rSearchTemplate, AMSearchControl searchControl)
576            throws AMException, SSOException;
577
578    /**
579     * Searches for resources in this organization using wildcards and attribute
580     * values. Wildcards can be specified such as a*, *, *a. SDK uses the
581     * <code>eSearchTemplate</code>, if provided. Otherwise, it uses the
582     * <code>BasicEntitySearch</code> template.
583     * 
584     * @param wildcard
585     *            wildcard pattern to be used in the search
586     * @param level
587     *            the search level that needs to be used (
588     *            <code>AMConstants.SCOPE_ONE</code>
589     *            or <code>AMConstants.SCOPE_SUB</code>)
590     * @param eSearchTemplate
591     *            Name of search template to be used.
592     * @param avPairs
593     *            This option can be used to further qualify the search filter.
594     *            The attribute-value pairs provided by this map are appended to
595     *            the search filter.
596     * @return Set DNs of resources matching the search
597     * 
598     * @throws AMException
599     *             if an error is encountered when trying to access/retrieve
600     *             data from the data store.
601     * @throws SSOException
602     *             if the single sign on token is no longer valid.
603     */
604    public Set searchEntities(String wildcard, int level,
605            String eSearchTemplate, Map avPairs) throws AMException,
606            SSOException;
607
608    /**
609     * Searches for entities in this people container using wildcards and
610     * attribute values. Wildcards can be specified such as a*, *, *a. To
611     * further refine the search, attribute-value pairs can be specified so that
612     * DNs of users with matching attribute-value pairs will be returned.
613     * 
614     * @param wildcard
615     *            wildcard pattern to be used in the search
616     * @param avPairs
617     *            attribute-value pairs to match when searching users
618     * @param eSearchTemplate
619     *            Name of search template to be used.
620     * @param searchControl
621     *            specifies the search scope to be used, VLV ranges etc.,
622     * @return <code>AMSearchResults</code> which contains a Set DNs of
623     *         resources matching the search.
624     * @throws AMException
625     *             if an error is encountered when trying to access/retrieve
626     *             data from the data store
627     * @throws SSOException
628     *             if the single sign on token is no longer valid
629     */
630    public AMSearchResults searchEntities(String wildcard, Map avPairs,
631            String eSearchTemplate, AMSearchControl searchControl)
632            throws AMException, SSOException;
633
634    /**
635     * Searches for entities in this people container using wildcards and a
636     * filter. Wildcards can be specified such as a*, *, *a. To further refine
637     * the search, a filter can be passed, which is used to further qualify the
638     * basic entity search filter.
639     * 
640     * @param wildcard
641     *            wildcard pattern to be used in the search
642     * @param searchControl
643     *            specifies the search scope to be used, VLV ranges etc.
644     * @param avfilter
645     *            this attribute-value pairs filter will be logical AND with
646     *            user search filter.
647     * @param eSearchTemplate
648     *            Name of search template to be used. If a null is passed then
649     *            the default search template for entities
650     *            <code>BasicEntitySearch</code> is used.
651     * @return <code>AMSearchResults</code> which contains a Set DNs of Users
652     *         matching the search.
653     * @throws AMException
654     *             if an error is encountered when trying to access/retrieve
655     *             data from the data store.
656     * @throws SSOException
657     *             if the single sign on token is no longer valid
658     */
659    public AMSearchResults searchEntities(String wildcard,
660            AMSearchControl searchControl, String avfilter,
661            String eSearchTemplate) throws AMException, SSOException;
662
663    /**
664     * Deletes a set of resources in this people container.
665     * 
666     * @param resources
667     *            The set of resource DNs to be removed.
668     * @throws AMException
669     *             if an error is encountered when trying to access/retrieve
670     *             data from the data store.
671     * @throws SSOException
672     *             if the single sign on token is no longer valid
673     */
674    public void deleteResources(Set resources) throws AMException, SSOException;
675
676    /**
677     * Deletes a set of resources in this people container.
678     * 
679     * @param resources
680     *            The set of resource DNs to be removed.
681     * @throws AMException
682     *             if an error is encountered when trying to access/retrieve
683     *             data from the data store.
684     * @throws SSOException
685     *             if the single sign on token is no longer valid
686     */
687    public void deleteEntities(Set resources) throws AMException, SSOException;
688
689    /**
690     * Searches for sub people containers in this people container using
691     * wildcards and attribute values. Wildcards can be specified such as a*, *,
692     * *a.
693     * 
694     * @param wildcard
695     *            wildcard pattern to be used in the search
696     * @param level
697     *            the search level that needs to be used (
698     *            <code>AMConstants.SCOPE_ONE</code>
699     *            or <code>AMConstants.SCOPE_SUB</code>)
700     * @return Set DNs of people containers matching the search
701     * 
702     * @throws AMException
703     *             if an error is encountered when trying to access/retrieve
704     *             data from the data store
705     * @throws SSOException
706     *             if the single sign on token is no longer valid
707     */
708    public Set searchSubPeopleContainers(String wildcard, int level)
709            throws AMException, SSOException;
710
711    /**
712     * Searches for sub people containers in this people container using
713     * wildcards and attribute values. Wildcards can be specified such as a*, *,
714     * *a. To further refine the search, attribute-value pairs can be specified
715     * so that DNs of people containers with matching attribute-value pairs will
716     * be returned.
717     * 
718     * @param wildcard
719     *            wildcard pattern to be used in the search
720     * @param avPairs
721     *            attribute-value pairs to match when searching people
722     *            Containers
723     * @param level
724     *            the search level that needs to be used (
725     *            <code>AMConstants.SCOPE_ONE</code>
726     *            or <code>AMConstants.SCOPE_SUB</code>)
727     * @return Set DNs of people containers matching the search
728     * 
729     * @throws AMException
730     *             if an error is encountered when trying to access/retrieve
731     *             data from the data store
732     * @throws SSOException
733     *             if the single sign on token is no longer valid
734     */
735    public Set searchSubPeopleContainers(
736            String wildcard, Map avPairs, int level)
737            throws AMException, SSOException;
738}