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: AMOrganization.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 organization.
038 * <code>AMOrganization</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); 
045 * if (amsc.doesEntryExist(oDN)) { 
046 *     AMOrganization org = amsc.getOrganization(oDN); 
047 * }
048 * 
049 * </PRE>
050 *
051 * @deprecated  As of Sun Java System Access Manager 7.1.
052 * @supported.all.api
053 */
054
055public interface AMOrganization extends AMObject {
056    /**
057     * Creates sub-organizations.
058     * 
059     * @param subOrganizations
060     *            The set of sub-organizations names to be created.
061     * @return Set set of sub Organization objects created.
062     * 
063     * @throws AMException
064     *             if an error is encountered when trying to access/retrieve
065     *             data from the data store
066     * @throws SSOException
067     *             if the single sign on token is no longer valid
068     */
069    public Set createSubOrganizations(Set subOrganizations) throws AMException,
070            SSOException;
071
072    /**
073     * Creates sub-organizations and initializes their attributes.
074     * 
075     * @param subOrganizations
076     *            Map where the key is the name of the sub organization, and the
077     *            value is a Map to represent Attribute-Value Pairs
078     * @return Set set of sub Organization objects created.
079     * @throws AMException
080     *             if an error is encountered when trying to access/retrieve
081     *             data from the data store.
082     * @throws SSOException
083     *             if the single sign on token is no longer valid.
084     */
085    public Set createSubOrganizations(Map subOrganizations) throws AMException,
086            SSOException;
087
088    /**
089     * Creates sub-organizations and initializes their attributes. Initializes
090     * service <code>objectclasses</code> and attributes as provided in the
091     * <code>serviceNameAndAttrs</code> map.
092     * 
093     * @param orgName
094     *            name of organization to be created under this organization.
095     * @param domainName
096     *            name of the domain (
097     *            example <code>sun.com, iplanet.com</code>).
098     * @param attrMap
099     *            Map of attribute-value pairs to be set on the entry.
100     * @param serviceNamesAndAttrs
101     *            Map of service names and attribute-values for that service to
102     *            be set in the organization entry.
103     *            <code>serviceNameAndAttrs</code> has service names keys and
104     *            map of attribute-values (values are in a Set).
105     * @return DN of organization created.
106     * @throws AMException
107     *             if an error is encountered when trying to access/retrieve
108     *             data from the data store.
109     * @throws SSOException
110     *             if the single sign on token is no longer valid.
111     */
112    public String createOrganization(String orgName, String domainName,
113            Map attrMap, Map serviceNamesAndAttrs) throws AMException,
114            SSOException;
115
116    /**
117     * Deletes sub organizations.
118     * 
119     * @param subOrganizations
120     *            The set of sub organization DNs to be deleted.
121     * @throws AMException
122     *             if an error is encountered when trying to access/retrieve
123     *             data from the data store
124     * @throws SSOException
125     *             if the single sign on token is no longer valid
126     */
127    public void deleteSubOrganizations(Set subOrganizations)
128            throws AMException, SSOException;
129
130    /**
131     * Returns the sub-organization by DN
132     * 
133     * @param dn
134     *            distinguished name.
135     * @return The sub Organization object
136     * @throws AMException
137     *             if an error is encountered when trying to access/retrieve
138     *             data from the data store
139     * @throws SSOException
140     *             if the single sign on token is no longer valid
141     */
142    public AMOrganization getSubOrganization(String dn) throws AMException,
143            SSOException;
144
145    /**
146     * Gets the sub organizations within the specified level.
147     * 
148     * @param level
149     *            The search level starting from the organization.
150     * @return Set of sub organizations DNs within the specified level.
151     * @throws AMException
152     *             if an error is encountered when trying to access/retrieve
153     *             data from the data store
154     * @throws SSOException
155     *             if the single sign on token is no longer valid
156     */
157    public Set getSubOrganizations(int level) throws AMException, SSOException;
158
159    /**
160     * Gets number of sub organizations within the specified level.
161     * 
162     * @param level
163     *            The search level starting from the organization.
164     * @return Number of sub organizations within the specified level.
165     * @throws AMException
166     *             if an error is encountered when trying to access/retrieve
167     *             data from the data store
168     * @throws SSOException
169     *             if the single sign on token is no longer valid
170     */
171    public long getNumberOfSubOrganizations(int level) throws AMException,
172            SSOException;
173
174    /**
175     * Searches for sub organizations in this organization using wildcards.
176     * Wildcards can be specified such as a*, *, *a.
177     * 
178     * @param wildcard
179     *            wildcard pattern to be used in the search
180     * @param level
181     *            the search level that needs to be used (
182     *            <code>AMConstants.SCOPE_ONE</code>
183     *            or <code>AMConstants.SCOPE_SUB</code>)
184     * @return Set Set of DNs of Sub Organizations matching the search
185     * 
186     * @throws AMException
187     *             if an error is encountered when trying to access/retrieve
188     *             data from the data store
189     * @throws SSOException
190     *             if the single sign on token is no longer valid
191     */
192    public Set searchSubOrganizations(String wildcard, int level)
193            throws AMException, SSOException;
194
195    /**
196     * Searches for sub organizations in this organization using wildcards.
197     * Wildcards can be specified such as a*, *, *a.
198     * 
199     * @param wildcard
200     *            wildcard pattern to be used in the search
201     * @param searchControl
202     *            specifies the search scope to be used, VLV ranges etc.
203     * @return <code>AMSearchResults</code> which contains a set of DNs of sub
204     *         Organizations matching the search
205     * @throws AMException
206     *             if an error is encountered when trying to access/retrieve
207     *             data from the data store.
208     * @throws SSOException
209     *             if the single sign on token is no longer valid.
210     */
211    public AMSearchResults searchSubOrganizations(String wildcard,
212            AMSearchControl searchControl) throws AMException, SSOException;
213
214    /**
215     * Searches for sub organizations in this organization using wildcards and
216     * attribute values. Wildcards can be specified such as a*, *, *a. To
217     * further refine the search, attribute-value pairs can be specified so that
218     * DNs of sub organizations with matching attribute-value pairs will be
219     * returned.
220     * 
221     * @param wildcard
222     *            wildcard pattern to be used in the search
223     * @param avPairs
224     *            attribute-value pairs to match when searching sub
225     *            organizations
226     * @param level
227     *            the search level that needs to be used (
228     *            <code>AMConstants.SCOPE_ONE</code>
229     *            or <code>AMConstants.SCOPE_SUB</code>)
230     * @return Set Set of DNs of sub organizations matching the search
231     * 
232     * @throws AMException
233     *             if an error is encountered when trying to access/retrieve
234     *             data from the data store
235     * @throws SSOException
236     *             if the single sign on token is no longer valid
237     */
238    public Set searchSubOrganizations(String wildcard, Map avPairs, int level)
239            throws AMException, SSOException;
240
241    /**
242     * Searches for sub organizations in this organization using wildcards and
243     * attribute values. Wildcards can be specified such as a*, *, *a. To
244     * further refine the search, attribute-value pairs can be specified so that
245     * DNs of sub organizations with matching attribute-value pairs will be
246     * returned.
247     * 
248     * @param wildcard
249     *            wildcard pattern to be used in the search.
250     * @param avPairs
251     *            attribute-value pairs to match when searching sub
252     *            organizations.
253     * @param searchControl
254     *            specifies the search scope to be used, VLV ranges etc.
255     * @return <code>AMSearchResults</code> which contains a Set of DNs of sub
256     *         organizations matching the search.
257     * @throws AMException
258     *             if an error is encountered when trying to access/retrieve
259     *             data from the data store.
260     * @throws SSOException
261     *             if the single sign on token is no longer valid.
262     */
263    public AMSearchResults searchSubOrganizations(String wildcard, Map avPairs,
264            AMSearchControl searchControl) throws AMException, SSOException;
265
266    /**
267     * Creates organizational units.
268     * 
269     * @param organizationalUnits
270     *            The set of organizational units names to be created.
271     * @return set of sub <code>OrganizationalUnit</code> objects created.
272     * @throws AMException
273     *             if an error is encountered when trying to access/retrieve
274     *             data from the data store.
275     * @throws SSOException
276     *             if the single sign on token is no longer valid.
277     */
278    public Set createOrganizationalUnits(Set organizationalUnits)
279            throws AMException, SSOException;
280
281    /**
282     * Creates organizational units and initializes their attributes.
283     * 
284     * @param organizationalUnits
285     *            Map where the key is the name of the organizational unit, and
286     *            the value is a Map to represent Attribute-Value Pairs
287     * @return Set set of <code>OrganizationalUnit</code> objects created.
288     * @throws AMException
289     *             if an error is encountered when trying to access/retrieve
290     *             data from the data store
291     * @throws SSOException
292     *             if the single sign on token is no longer valid
293     */
294    public Set createOrganizationalUnits(Map organizationalUnits)
295            throws AMException, SSOException;
296
297    /**
298     * Deletes organizational units
299     * 
300     * @param organizationalUnits
301     *            The set of organizational units DNs to be deleted.
302     * @throws AMException
303     *             if an error is encountered when trying to access/retrieve
304     *             data from the data store.
305     * @throws SSOException
306     *             if the single sign on token is no longer valid.
307     */
308    public void deleteOrganizationalUnits(Set organizationalUnits)
309            throws AMException, SSOException;
310
311    /**
312     * Gets the organizational unit by DN.
313     * 
314     * @param dn
315     *            distinguished name.
316     * @return The <code>OrganizationalUnit</code> object
317     * @throws AMException
318     *             if an error is encountered when trying to access/retrieve
319     *             data from the data store
320     * @throws SSOException
321     *             if the single sign on token is no longer valid
322     */
323    public AMOrganizationalUnit getOrganizationalUnit(String dn)
324            throws AMException, SSOException;
325
326    /**
327     * Gets the organizational units within the specified level.
328     * 
329     * @param level
330     *            The search level starting from the organization.
331     * @return The Set of organizational units DNs within the specified level.
332     * @throws AMException
333     *             if an error is encountered when trying to access/retrieve
334     *             data from the data store
335     * @throws SSOException
336     *             if the single sign on token is no longer valid
337     */
338    public Set getOrganizationalUnits(int level) throws AMException,
339            SSOException;
340
341    /**
342     * Gets number of organizational units within the specified level.
343     * 
344     * @param level
345     *            The search level starting from the organization.
346     * @return Number of organizational units within the specified level.
347     * @throws AMException
348     *             if an error is encountered when trying to access/retrieve
349     *             data from the data store
350     * @throws SSOException
351     *             if the single sign on token is no longer valid
352     */
353    public long getNumberOfOrganizationalUnits(int level) throws AMException,
354            SSOException;
355
356    /**
357     * Searches for organizational units in this organization using wildcards.
358     * Wildcards can be specified such as a*, *, *a.
359     * 
360     * @param wildcard
361     *            wildcard pattern to be used in the search
362     * @param level
363     *            the search level that needs to be used (
364     *            <code>AMConstants.SCOPE_ONE</code>
365     *            or <code>AMConstants.SCOPE_SUB</code>)
366     * @return Set Set of DNs of organizational units matching the search
367     * @throws AMException
368     *             if an error is encountered when trying to access/retrieve
369     *             data from the data store
370     * @throws SSOException
371     *             if the single sign on token is no longer valid
372     */
373    public Set searchOrganizationalUnits(String wildcard, int level)
374            throws AMException, SSOException;
375
376    /**
377     * Searches for organizational units in this organization using wildcards.
378     * Wildcards can be specified such as a*, *, *a.
379     * 
380     * @param wildcard
381     *            wildcard pattern to be used in the search
382     * @param searchControl
383     *            specifies the search scope to be used, VLV ranges etc.,
384     * @return <code>AMSearchResults</code> which contains a set of DNs of
385     *         organizational units matching the search.
386     * @throws AMException
387     *             if an error is encountered when trying to access/retrieve
388     *             data from the data store
389     * @throws SSOException
390     *             if the single sign on token is no longer valid
391     */
392    public AMSearchResults searchOrganizationalUnits(String wildcard,
393            AMSearchControl searchControl) throws AMException, SSOException;
394
395    /**
396     * Searches for organizational units in this organization using wildcards
397     * and attribute values. Wildcards can be specified such as a*, *, *a. To
398     * further refine the search, attribute-value pairs can be specified so that
399     * DNs of organizational units with matching attribute-value pairs will be
400     * returned.
401     * 
402     * @param wildcard
403     *            wildcard pattern to be used in the search
404     * @param avPairs
405     *            attribute-value pairs to match when searching organizational
406     *            units
407     * @param level
408     *            the search level that needs to be used (
409     *            <code>AMConstants.SCOPE_ONE</code>
410     *            or <code>AMConstants.SCOPE_SUB</code>)
411     * @return Set Set of DNs of organizational units matching the search
412     * @throws AMException
413     *             if an error is encountered when trying to access/retrieve
414     *             data from the data store
415     * @throws SSOException
416     *             if the single sign on token is no longer valid
417     */
418    public Set searchOrganizationalUnits(
419            String wildcard, Map avPairs, int level)
420            throws AMException, SSOException;
421
422    /**
423     * Searches for organizational units in this organization using wildcards
424     * and attribute values. Wildcards can be specified such as a*, *, *a. To
425     * further refine the search, attribute-value pairs can be specified so that
426     * DNs of organizational units with matching attribute-value pairs will be
427     * returned.
428     * 
429     * @param wildcard
430     *            wildcard pattern to be used in the search
431     * @param avPairs
432     *            attribute-value pairs to match when searching organizational
433     *            units
434     * @param searchControl
435     *            specifies the search scope to be used, VLV ranges etc.,
436     * 
437     * @return <code>AMSearchResults</code> which contains a Set of DNs of
438     *         organizational units matching the search.
439     * 
440     * @throws AMException
441     *             if an error is encountered when trying to access/retrieve
442     *             data from the data store
443     * @throws SSOException
444     *             if the single sign on token is no longer valid
445     */
446    public AMSearchResults searchOrganizationalUnits(String wildcard,
447            Map avPairs, AMSearchControl searchControl) throws AMException,
448            SSOException;
449
450    /**
451     * Creates roles.
452     * 
453     * @param roles
454     *            The set of Roles' names to be created.
455     * @return Set set of Role objects created.
456     * @throws AMException
457     *             if an error is encountered when trying to access/retrieve
458     *             data from the data store
459     * @throws SSOException
460     *             if the single sign on token is no longer valid
461     */
462    public Set createRoles(Set roles) throws AMException, SSOException;
463
464    /**
465     * Creates roles.
466     * 
467     * @param roles
468     *            Map where the key is the name of the role, and the value is a
469     *            Map to represent Attribute-Value Pairs
470     * @return Set set of Role objects created.
471     * @throws AMException
472     *             if an error is encountered when trying to access/retrieve
473     *             data from the data store
474     * @throws SSOException
475     *             if the single sign on token is no longer valid
476     */
477    public Set createRoles(Map roles) throws AMException, SSOException;
478
479    /**
480     * Deletes roles.
481     * 
482     * @param roles
483     *            The set of roles' DNs to be deleted.
484     * @throws AMException
485     *             if an error is encountered when trying to access/retrieve
486     *             data from the data store
487     * @throws SSOException
488     *             if the single sign on token is no longer valid
489     */
490    public void deleteRoles(Set roles) throws AMException, SSOException;
491
492    /**
493     * Gets the roles within the specified level.
494     * 
495     * @param level
496     *            The search level starting from the organization.
497     * @return The Set of Roles' DNs within the specified level.
498     * @throws AMException
499     *             if an error is encountered when trying to access/retrieve
500     *             data from the data store
501     * @throws SSOException
502     *             if the single sign on token is no longer valid
503     */
504    public Set getRoles(int level) throws AMException, SSOException;
505
506    /**
507     * Gets number of roles within the specified level.
508     * 
509     * @param level
510     *            The search level starting from the organization.
511     * @return Number of roles within the specified level.
512     * @throws AMException
513     *             if an error is encountered when trying to access/retrieve
514     *             data from the data store
515     * @throws AMException
516     *             if an error is encountered when trying to access/retrieve
517     *             data from the data store
518     * @throws SSOException
519     *             if the single sign on token is no longer valid
520     */
521    public long getNumberOfRoles(int level) throws AMException, SSOException;
522
523    /**
524     * Searches for roles in this organization using wildcards. Wildcards can be
525     * specified such as a*, *, *a.
526     * 
527     * @param wildcard
528     *            wildcard pattern to be used in the search
529     * @param level
530     *            the search level that needs to be used (
531     *            <code>AMConstants.SCOPE_ONE</code>
532     *            or <code>AMConstants.SCOPE_SUB</code>)
533     * @return Set Set of DNs of roles 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 Set searchRoles(String wildcard, int level) throws AMException,
541            SSOException;
542
543    /**
544     * Searches for roles in this organization using wildcards. Wildcards can be
545     * specified such as a*, *, *a.
546     * 
547     * @param wildcard
548     *            wildcard pattern to be used in the search.
549     * @param searchControl
550     *            specifies the search scope to be used, VLV ranges etc.
551     * @return <code>AMSearchResults</code> which contains a set of DNs of
552     *         roles matching the search.
553     * @throws AMException
554     *             if an error is encountered when trying to access/retrieve
555     *             data from the data store
556     * @throws SSOException
557     *             if the single sign on token is no longer valid
558     */
559    public AMSearchResults searchRoles(String wildcard,
560            AMSearchControl searchControl) throws AMException, SSOException;
561
562    /**
563     * Searches for roles in this organization using wildcards and attribute
564     * values. Wildcards can be specified such as a*, *, *a. To further refine
565     * the search, attribute-value pairs can be specified so that DNs of roles
566     * with matching attribute-value pairs will be returned.
567     * 
568     * @param wildcard
569     *            wildcard pattern to be used in the search
570     * @param avPairs
571     *            attribute-value pairs to match when searching roles
572     * @param level
573     *            the search level that needs to be used (
574     *            <code>AMConstants.SCOPE_ONE</code>
575     *            or <code>AMConstants.SCOPE_SUB</code>)
576     * 
577     * @return Set Set of DNs of roles matching the search
578     * 
579     * @throws AMException
580     *             if an error is encountered when trying to access/retrieve
581     *             data from the data store
582     * @throws SSOException
583     *             if the single sign on token is no longer valid
584     */
585    public Set searchRoles(String wildcard, Map avPairs, int level)
586            throws AMException, SSOException;
587
588    /**
589     * Searches for roles in this organization using wildcards and attribute
590     * values. Wildcards can be specified such as a*, *, *a. To further refine
591     * the search, attribute-value pairs can be specified so that DNs of roles
592     * with matching attribute-value pairs will be returned.
593     * 
594     * @param wildcard
595     *            wildcard pattern to be used in the search
596     * @param avPairs
597     *            attribute-value pairs to match when searching roles
598     * @param searchControl
599     *            specifies the search scope to be used, VLV ranges etc.,
600     * 
601     * @return <code>AMSearchResults</code> which contains a set of DNs of
602     *         roles matching the search.
603     * 
604     * @throws AMException
605     *             if an error is encountered when trying to access/retrieve
606     *             data from the data store
607     * @throws SSOException
608     *             if the single sign on token is no longer valid
609     */
610    public AMSearchResults searchRoles(String wildcard, Map avPairs,
611            AMSearchControl searchControl) throws AMException, SSOException;
612
613    /**
614     * Creates filtered roles.
615     * 
616     * @param roles
617     *            The set of filtered roles' names to be created.
618     * @return Set set of <code>FilteredRole</code> objects created.
619     * @throws AMException
620     *             if an error is encountered when trying to access/retrieve
621     *             data from the data store.
622     * @throws SSOException
623     *             if the single sign on token is no longer valid.
624     */
625    public Set createFilteredRoles(Set roles) throws AMException, SSOException;
626
627    /**
628     * Creates filtered roles.
629     * 
630     * @param roles
631     *            Map where the key is the name of the filtered role, and the
632     *            value is a Map to represent Attribute-Value Pairs
633     * @return set of <code>FilteredRole</code> objects created.
634     * @throws AMException
635     *             if an error is encountered when trying to access/retrieve
636     *             data from the data store.
637     * @throws SSOException
638     *             if the single sign on token is no longer valid.
639     */
640    public Set createFilteredRoles(Map roles) throws AMException, SSOException;
641
642    /**
643     * Deletes filtered roles.
644     * 
645     * @param roles
646     *            The set of filtered roles' DNs to be deleted.
647     * @throws AMException
648     *             if an error is encountered when trying to access/retrieve
649     *             data from the data store
650     * @throws SSOException
651     *             if the single sign on token is no longer valid
652     */
653    public void deleteFilteredRoles(Set roles) throws AMException, SSOException;
654
655    /**
656     * Gets the filtered roles within the specified level.
657     * 
658     * @param level
659     *            The search level starting from the organization.
660     * @return The Set of filtered roles' DNs within the specified level.
661     * @throws AMException
662     *             if an error is encountered when trying to access/retrieve
663     *             data from the data store
664     * @throws SSOException
665     *             if the single sign on token is no longer valid
666     */
667    public Set getFilteredRoles(int level) throws AMException, SSOException;
668
669    /**
670     * Gets number of filtered roles within the specified level.
671     * 
672     * @param level
673     *            The search level starting from the organization.
674     * @return Number of filtered roles within the specified level.
675     * @throws AMException
676     *             if an error is encountered when trying to access/retrieve
677     *             data from the data store
678     * @throws SSOException
679     *             if the single sign on token is no longer valid
680     */
681    public long getNumberOfFilteredRoles(int level) throws AMException,
682            SSOException;
683
684    /**
685     * Searches for filtered roles in this organization using wildcards.
686     * Wildcards can be specified such as a*, *, *a.
687     * 
688     * @param wildcard
689     *            wildcard pattern to be used in the search
690     * @param level
691     *            the search level that needs to be used (
692     *            <code>AMConstants.SCOPE_ONE</code>
693     *            or <code>AMConstants.SCOPE_SUB</code>)
694     * 
695     * @return Set Set of DNs of filtered roles matching the search
696     * 
697     * @throws AMException
698     *             if an error is encountered when trying to access/retrieve
699     *             data from the data store
700     * @throws SSOException
701     *             if the single sign on token is no longer valid
702     */
703    public Set searchFilteredRoles(String wildcard, int level)
704            throws AMException, SSOException;
705
706    /**
707     * Searches for filtered roles in this organization using wildcards.
708     * Wildcards can be specified such as a*, *, *a.
709     * 
710     * @param wildcard
711     *            wildcard pattern to be used in the search
712     * @param searchControl
713     *            specifies the search scope to be used, VLV ranges etc.
714     * @return <code>AMSearchResults</code> which contains a set of DNs of
715     *         filtered roles matching the search.
716     * @throws AMException
717     *             if an error is encountered when trying to access/retrieve
718     *             data from the data store.
719     * @throws SSOException
720     *             if the single sign on token is no longer valid.
721     */
722    public AMSearchResults searchFilteredRoles(String wildcard,
723            AMSearchControl searchControl) throws AMException, SSOException;
724
725    /**
726     * Searches for filtered roles in this organization using wildcards and
727     * attribute values. Wildcards can be specified such as a*, *, *a. To
728     * further refine the search, attribute-value pairs can be specified so that
729     * DNs of filtered roles with matching attribute-value pairs will be
730     * returned.
731     * 
732     * @param wildcard
733     *            wildcard pattern to be used in the search
734     * @param avPairs
735     *            attribute-value pairs to match when searching filtered roles
736     * @param level
737     *            the search level that needs to be used (
738     *            <code>AMConstants.SCOPE_ONE</code>
739     *            or <code>AMConstants.SCOPE_SUB</code>)
740     * 
741     * @return Set Set of DNs of filtered roles matching the search
742     * 
743     * @throws AMException
744     *             if an error is encountered when trying to access/retrieve
745     *             data from the data store
746     * @throws SSOException
747     *             if the single sign on token is no longer valid
748     */
749    public Set searchFilteredRoles(String wildcard, Map avPairs, int level)
750            throws AMException, SSOException;
751
752    /**
753     * Searches for filtered roles in this organization using wildcards and
754     * attribute values. Wildcards can be specified such as a*, *, *a. To
755     * further refine the search, attribute-value pairs can be specified so that
756     * DNs of filtered roles with matching attribute-value pairs will be
757     * returned.
758     * 
759     * @param wildcard
760     *            pattern to be used in the search.
761     * @param avPairs
762     *            attribute-value pairs to match when searching filtered roles.
763     * @param searchControl
764     *            specifies the search scope to be used, VLV ranges etc.
765     * @return <code>AMSearchResults</code> which contains a set of DNs of
766     *         filtered roles matching the search.
767     * @throws AMException
768     *             if an error is encountered when trying to access/retrieve
769     *             data from the data store.
770     * @throws SSOException
771     *             if the single sign on token is no longer valid.
772     */
773    public AMSearchResults searchFilteredRoles(String wildcard, Map avPairs,
774            AMSearchControl searchControl) throws AMException, SSOException;
775
776    /**
777     * Searches for all roles in this organization using wildcards. Wildcards
778     * can be specified such as a*, *, *a.
779     * 
780     * @param wildcard
781     *            wildcard pattern to be used in the search
782     * @param level
783     *            the search level that needs to be used (
784     *            <code>AMConstants.SCOPE_ONE</code>
785     *            or <code>AMConstants.SCOPE_SUB</code>)
786     * 
787     * @return Set of DNs of all roles matching the search
788     * 
789     * @throws AMException
790     *             if an error is encountered when trying to access/retrieve
791     *             data from the data store
792     * @throws SSOException
793     *             if the single sign on token is no longer valid
794     */
795    public Set searchAllRoles(String wildcard, int level) throws AMException,
796            SSOException;
797
798    /**
799     * Searches for all roles in this organization using wildcards. Wildcards
800     * can be specified such as a*, *, *a.
801     * 
802     * @param wildcard
803     *            wildcard pattern to be used in the search
804     * @param searchControl
805     *            specifies the search scope to be used, VLV ranges etc.
806     * @return <code>AMSearchResults</code> which contains a Set of DNs of all
807     *         roles matching the search.
808     * @throws AMException
809     *             if an error is encountered when trying to access/retrieve
810     *             data from the data store.
811     * @throws SSOException
812     *             if the single sign on token is no longer valid.
813     */
814    public AMSearchResults searchAllRoles(String wildcard,
815            AMSearchControl searchControl) throws AMException, SSOException;
816
817    /**
818     * Searches for all roles in this organization using wildcards and attribute
819     * values. Wildcards can be specified such as a*, *, *a. To further refine
820     * the search, attribute-value pairs can be specified so that DNs of all
821     * roles with matching attribute-value pairs will be returned.
822     * 
823     * @param wildcard
824     *            wildcard pattern to be used in the search
825     * @param avPairs
826     *            attribute-value pairs to match when searching all roles
827     * @param level
828     *            the search level that needs to be used (
829     *            <code>AMConstants.SCOPE_ONE</code>
830     *            or <code>AMConstants.SCOPE_SUB</code>)
831     * 
832     * @return Set of DNs of all roles matching the search
833     * 
834     * @throws AMException
835     *             if an error is encountered when trying to access/retrieve
836     *             data from the data store
837     * @throws SSOException
838     *             if the single sign on token is no longer valid
839     */
840    public Set searchAllRoles(String wildcard, Map avPairs, int level)
841            throws AMException, SSOException;
842
843    /**
844     * Searches for all roles in this organization using wildcards and attribute
845     * values. Wildcards can be specified such as a*, *, *a. To further refine
846     * the search, attribute-value pairs can be specified so that DNs of all
847     * roles with matching attribute-value pairs will be returned.
848     * 
849     * @param wildcard
850     *            wildcard pattern to be used in the search
851     * @param avPairs
852     *            attribute-value pairs to match when searching all roles
853     * @param searchControl
854     *            specifies the search scope to be used, VLV ranges etc.
855     * @return <code>AMSearchResults</code> which contains a set of DNs of all
856     *         roles matching the search.
857     * @throws AMException
858     *             if an error is encountered when trying to access/retrieve
859     *             data from the data store.
860     * @throws SSOException
861     *             if the single sign on token is no longer valid.
862     */
863    public AMSearchResults searchAllRoles(String wildcard, Map avPairs,
864            AMSearchControl searchControl) throws AMException, SSOException;
865
866    /**
867     * Creates assignable dynamic groups.
868     * 
869     * @param assignableDynamicGroups
870     *            The set of assignable dynamic groups's names to be created.
871     * @return set of <code>AssignableDynamicGroup</code> objects created.
872     * @throws AMException
873     *             if an error is encountered when trying to access/retrieve
874     *             data from the data store.
875     * @throws SSOException
876     *             if the single sign on token is no longer valid.
877     */
878    public Set createAssignableDynamicGroups(Set assignableDynamicGroups)
879            throws AMException, SSOException;
880
881    /**
882     * Creates assignable dynamic group. Takes <code>serviceNameAndAttr</code>
883     * map so that services can be assigned to the group which is just created.
884     * 
885     * @param name
886     *            of group to be created
887     * @param attributes
888     *            attribute-value pairs to be set
889     * @param serviceNameAndAttrs
890     *            service name and attribute map where the map is like this:
891     *            <code>&lt;serviceName>&lt;AttrMap>
892     *      (attrMap=&lt;attrName>&lt;Set of attrvalues>)</code>
893     * @return <code>AMGroup</code> object of newly created group.
894     * @throws AMException
895     *             if an error is encountered when trying to access/retrieve
896     *             data from the data store.
897     * @throws SSOException
898     *             if the single sign on token is no longer valid
899     */
900    public AMGroup createAssignableDynamicGroup(String name, Map attributes,
901            Map serviceNameAndAttrs) throws AMException, SSOException;
902
903    /**
904     * Deletes assignable dynamic groups.
905     * 
906     * @param assignableDynamicGroups
907     *            The set of assignable dynamic groups's DNs to be deleted.
908     * 
909     * @throws AMException
910     *             if an error is encountered when trying to access/retrieve
911     *             data from the data store
912     * @throws SSOException
913     *             if the single sign on token is no longer valid
914     */
915    public void deleteAssignableDynamicGroups(Set assignableDynamicGroups)
916            throws AMException, SSOException;
917
918    /**
919     * Returns the assignable dynamic groups within the specified level.
920     * 
921     * @param level
922     *            The search level starting from the organization.
923     * @return Set of DNs of <code>AssignableDynamicGroups</code> within the
924     *         specified level.
925     * @throws AMException
926     *             if an error is encountered when trying to access/retrieve
927     *             data from the data store
928     * @throws SSOException
929     *             if the single sign on token is no longer valid
930     */
931    public Set getAssignableDynamicGroups(int level) throws AMException,
932            SSOException;
933
934    /**
935     * Gets number of assignable dynamic groups within the specified level.
936     * 
937     * @param level
938     *            The search level starting from the organization.
939     * @return Number of assignable dynamic groups within the specified level.
940     * @throws AMException
941     *             if an error is encountered when trying to access/retrieve
942     *             data from the data store
943     * @throws SSOException
944     *             if the single sign on token is no longer valid
945     */
946    public long getNumberOfAssignableDynamicGroups(int level)
947            throws AMException, SSOException;
948
949    /**
950     * Searches for assignable dynamic groups in this organization using
951     * wildcards. Wildcards can be specified such as a*, *, *a.
952     * 
953     * @param wildcard
954     *            wildcard pattern to be used in the search
955     * @param level
956     *            the search level that needs to be used (
957     *            <code>AMConstants.SCOPE_ONE</code>
958     *            or <code>AMConstants.SCOPE_SUB</code>)
959     * 
960     * @return Set Set of DNs of assignable dynamic groups matching the search
961     * 
962     * @throws AMException
963     *             if an error is encountered when trying to access/retrieve
964     *             data from the data store
965     * @throws SSOException
966     *             if the single sign on token is no longer valid
967     */
968    public Set searchAssignableDynamicGroups(String wildcard, int level)
969            throws AMException, SSOException;
970
971    /**
972     * Searches for assignable dynamic groups in this organization using
973     * wildcards. Wildcards can be specified such as a*, *, *a. Uses the
974     * <code>groupSearchTemplate</code>, if provided. Otherwise the default
975     * search template is used.
976     * 
977     * @param wildcard
978     *            pattern to be used in the search.
979     * @param level
980     *            the search level that needs to be used (
981     *            <code>AMConstants.SCOPE_ONE</code>
982     *            or <code>AMConstants.SCOPE_SUB</code>).
983     * @param groupSearchTemplate
984     *            name of the search template to be used to perform this search.
985     * @param avPairs
986     *            This option can be used to further qualify the search filter.
987     *            The attribute-value pairs provided by this map are appended to
988     *            the search filter.
989     * @return Set of DNs of assignable dynamic groups matching the search.
990     * @throws AMException
991     *             if an error is encountered when trying to access/retrieve
992     *             data from the data store.
993     * @throws SSOException
994     *             if the single sign on token is no longer valid.
995     */
996    public Set searchAssignableDynamicGroups(String wildcard, int level,
997            String groupSearchTemplate, Map avPairs) throws AMException,
998            SSOException;
999
1000    /**
1001     * Searches for assignable dynamic groups in this organization using
1002     * wildcards. Wildcards can be specified such as a*, *, *a.
1003     * 
1004     * @param wildcard
1005     *            wildcard pattern to be used in the search
1006     * @param searchControl
1007     *            specifies the search scope to be used, VLV ranges etc.
1008     * @return <code>AMSearchResults</code> which contains a set of DNs of
1009     *         assignable dynamic groups matching the search.
1010     * @throws AMException
1011     *             if an error is encountered when trying to access/retrieve
1012     *             data from the data store.
1013     * @throws SSOException
1014     *             if the single sign on token is no longer valid.
1015     */
1016    public AMSearchResults searchAssignableDynamicGroups(String wildcard,
1017            AMSearchControl searchControl) throws AMException, SSOException;
1018
1019    /**
1020     * Searches for assignable dynamic groups in this organization using
1021     * wildcards and attribute values. Wildcards can be specified such as a*, *,
1022     * *a. To further refine the search, attribute-value pairs can be specified
1023     * so that DNs of dynamic groups with matching attribute-value pairs will be
1024     * returned.
1025     * 
1026     * @param wildcard
1027     *            wildcard pattern to be used in the search
1028     * @param avPairs
1029     *            attribute-value pairs to match when searching assignable
1030     *            dynamic groups
1031     * @param level
1032     *            the search level that needs to be used (
1033     *            <code>AMConstants.SCOPE_ONE</code>
1034     *            or <code>AMConstants.SCOPE_SUB</code>)
1035     * 
1036     * @return Set Set of DNs of assignable dynamic groups matching the search
1037     * 
1038     * @throws AMException
1039     *             if an error is encountered when trying to access/retrieve
1040     *             data from the data store
1041     * @throws SSOException
1042     *             if the single sign on token is no longer valid
1043     */
1044    public Set searchAssignableDynamicGroups(String wildcard, Map avPairs,
1045            int level) throws AMException, SSOException;
1046
1047    /**
1048     * Searches for assignable dynamic groups in this organization using
1049     * wildcards and attribute values. Wildcards can be specified such as a*, *,
1050     * *a. To further refine the search, attribute-value pairs can be specified
1051     * so that DNs of dynamic groups with matching attribute-value pairs will be
1052     * returned.
1053     * 
1054     * @param wildcard
1055     *            wildcard pattern to be used in the search
1056     * @param avPairs
1057     *            attribute-value pairs to match when searching assignable
1058     *            dynamic groups.
1059     * @param searchControl
1060     *            specifies the search scope to be used, VLV ranges etc.
1061     * @return <code>AMSearchResults</code> which contains a set of DNs of
1062     *         assignable dynamic groups matching the search.
1063     * @throws AMException
1064     *             if an error is encountered when trying to access/retrieve
1065     *             data from the data store.
1066     * @throws SSOException
1067     *             if the single sign on token is no longer valid.
1068     */
1069    public AMSearchResults searchAssignableDynamicGroups(String wildcard,
1070            Map avPairs, AMSearchControl searchControl) throws AMException,
1071            SSOException;
1072
1073    /**
1074     * Searches for assignable dynamic groups in this organization using
1075     * wildcards and attribute values. Wildcards can be specified such as a*, *,
1076     * *a. To further refine the search, attribute-value pairs can be specified
1077     * so that DNs of dynamic groups with matching attribute-value pairs will be
1078     * returned.
1079     * 
1080     * @param wildcard
1081     *            wildcard pattern to be used in the search
1082     * @param avPairs
1083     *            attribute-value pairs to match when searching assignable
1084     *            dynamic groups
1085     * @param groupSearchTemplate
1086     *            Name of search template to be used to perform
1087     * @param searchControl
1088     *            specifies the search scope to be used, VLV ranges etc., the
1089     *            search.
1090     * @return <code>AMSearchResults</code> which contains a set of DNs of
1091     *         assignable dynamic groups matching the search.
1092     * @throws AMException
1093     *             if an error is encountered when trying to access/retrieve
1094     *             data from the data store.
1095     * @throws SSOException
1096     *             if the single sign on token is no longer valid.
1097     */
1098    public AMSearchResults searchAssignableDynamicGroups(String wildcard,
1099            Map avPairs, String groupSearchTemplate,
1100            AMSearchControl searchControl) throws AMException, SSOException;
1101
1102    /**
1103     * Creates dynamic groups and initializes their attributes.
1104     * 
1105     * @param dynamicGroups
1106     *            Map where the key is the name of the dynamic group, and the
1107     *            value is a Map to represent Attribute-Value Pairs.
1108     * @return Set of <code>AMDynamicGroup</code> objects created
1109     * @throws AMException
1110     *             if an error is encountered when trying to access/retrieve
1111     *             data from the data store.
1112     * @throws SSOException
1113     *             if the single sign on token is no longer valid.
1114     */
1115    public Set createDynamicGroups(Map dynamicGroups) throws AMException,
1116            SSOException;
1117
1118    /**
1119     * Creates dynamic group. Takes <code>serviceNameAndAttr<code> map
1120     * so that services can be assigned to the group which is just created.
1121     *
1122     * @param name of group to be created
1123     * @param attributes to be set in group 
1124     * @param serviceNameAndAttrs service name and attribute map where the map
1125     *        is like this:
1126     * <code>&lt;serviceName>&lt;AttrMap>
1127     *       (attrMap=&lt;attrName>&lt;Set of attrvalues>)</code>
1128     * @return <code>AMGroup</code> object of newly created group.
1129     * @throws AMException if an error is encountered when trying to
1130     *         access/retrieve data from the data store.
1131     * @throws SSOException if the single sign on token is no longer valid.
1132     */
1133    public AMGroup createDynamicGroup(String name, Map attributes,
1134            Map serviceNameAndAttrs) throws AMException, SSOException;
1135
1136    /**
1137     * Deletes dynamic groups.
1138     * 
1139     * @param dynamicGroups
1140     *            The set of dynamic groups's DNs to be deleted.
1141     * 
1142     * @throws AMException
1143     *             if an error is encountered when trying to access/retrieve
1144     *             data from the data store
1145     * @throws SSOException
1146     *             if the single sign on token is no longer valid
1147     */
1148    public void deleteDynamicGroups(Set dynamicGroups) throws AMException,
1149            SSOException;
1150
1151    /**
1152     * Gets the dynamic groups within the specified level.
1153     * 
1154     * @param level
1155     *            The search level starting from the organization.
1156     * @return The Set of DNs of <code>DynamicGroups</code> within the
1157     *         specified level.
1158     * @throws AMException
1159     *             if an error is encountered when trying to access/retrieve
1160     *             data from the data store
1161     * @throws SSOException
1162     *             if the single sign on token is no longer valid
1163     */
1164    public Set getDynamicGroups(int level) throws AMException, SSOException;
1165
1166    /**
1167     * Gets number of dynamic groups within the specified level.
1168     * 
1169     * @param level
1170     *            The search level starting from the organization.
1171     * @return Number of dynamic groups within the specified level.
1172     * @throws AMException
1173     *             if an error is encountered when trying to access/retrieve
1174     *             data from the data store
1175     * @throws SSOException
1176     *             if the single sign on token is no longer valid
1177     */
1178    public long getNumberOfDynamicGroups(int level) throws AMException,
1179            SSOException;
1180
1181    /**
1182     * Searches for dynamic groups in this organization using wildcards.
1183     * Wildcards can be specified such as a*, *, *a.
1184     * 
1185     * @param wildcard
1186     *            wildcard pattern to be used in the search
1187     * @param level
1188     *            the search level that needs to be used (
1189     *            <code>AMConstants.SCOPE_ONE</code>
1190     *            or <code>AMConstants.SCOPE_SUB</code>)
1191     * 
1192     * @return Set Set of DNs of dynamic groups matching the search
1193     * 
1194     * @throws AMException
1195     *             if an error is encountered when trying to access/retrieve
1196     *             data from the data store
1197     * @throws SSOException
1198     *             if the single sign on token is no longer valid
1199     */
1200    public Set searchDynamicGroups(String wildcard, int level)
1201            throws AMException, SSOException;
1202
1203    /**
1204     * Searches for dynamic groups in this organization using wildcards.
1205     * Wildcards can be specified such as a*, *, *a. Uses the
1206     * <code>groupSearchTemplate</code>, if provided. Otherwise uses the the
1207     * default <code>GroupSearch</code> template.
1208     * 
1209     * @param wildcard
1210     *            pattern to be used in the search.
1211     * @param level
1212     *            the search level that needs to be used.
1213     * @param groupSearchTemplate
1214     *            name of the search template to be used to perform this search.
1215     * @param avPairs
1216     *            This option can be used to further qualify the search filter.
1217     *            The attribute-value pairs provided by this map are appended to
1218     *            the search filter. (<code>AMConstants.SCOPE_ONE</code> or
1219     *            <code>AMConstants.SCOPE_SUB</code>)
1220     * @return set of DNs of dynamic groups matching the search.
1221     * @throws AMException
1222     *             if an error is encountered when trying to access/retrieve
1223     *             data from the data store.
1224     * @throws SSOException
1225     *             if the single sign on token is no longer valid.
1226     */
1227    public Set searchDynamicGroups(String wildcard, int level,
1228            String groupSearchTemplate, Map avPairs) throws AMException,
1229            SSOException;
1230
1231    /**
1232     * Searches for dynamic groups in this organization using wildcards.
1233     * Wildcards can be specified such as a*, *, *a.
1234     * 
1235     * @param wildcard
1236     *            wildcard pattern to be used in the search
1237     * @param searchControl
1238     *            specifies the search scope to be used, VLV ranges etc.,
1239     * 
1240     * @return <code>AMSearchResults</code> which contains a set of DNs of
1241     *         dynamic groups matching the search.
1242     * @throws AMException
1243     *             if an error is encountered when trying to access/retrieve
1244     *             data from the data store.
1245     * @throws SSOException
1246     *             if the single sign on token is no longer valid.
1247     */
1248    public AMSearchResults searchDynamicGroups(String wildcard,
1249            AMSearchControl searchControl) throws AMException, SSOException;
1250
1251    /**
1252     * Searches for dynamic groups in this organization using wildcards and
1253     * attribute values. Wildcards can be specified such as a*, *, *a. To
1254     * further refine the search, attribute-value pairs can be specified so that
1255     * DNs of dynamic groups with matching attribute-value pairs will be
1256     * returned.
1257     * 
1258     * @param wildcard
1259     *            wildcard pattern to be used in the search
1260     * @param avPairs
1261     *            attribute-value pairs to match when searching dynamic groups
1262     * @param level
1263     *            the search level that needs to be used (
1264     *            <code>AMConstants.SCOPE_ONE</code>
1265     *            or <code>AMConstants.SCOPE_SUB</code>)
1266     * 
1267     * @return Set Set of DNs of dynamic groups matching the search
1268     * 
1269     * @throws AMException
1270     *             if an error is encountered when trying to access/retrieve
1271     *             data from the data store
1272     * @throws SSOException
1273     *             if the single sign on token is no longer valid
1274     */
1275    public Set searchDynamicGroups(String wildcard, Map avPairs, int level)
1276            throws AMException, SSOException;
1277
1278    /**
1279     * Searches for dynamic groups in this organization using wildcards and
1280     * attribute values. Wildcards can be specified such as a*, *, *a. To
1281     * further refine the search, attribute-value pairs can be specified so that
1282     * DNs of dynamic groups with matching attribute-value pairs will be
1283     * returned.
1284     * 
1285     * @param wildcard
1286     *            wildcard pattern to be used in the search
1287     * @param avPairs
1288     *            attribute-value pairs to match when searching dynamic groups
1289     * @param searchControl
1290     *            specifies the search scope to be used, VLV ranges etc.,
1291     * 
1292     * @return <code>AMSearchResults</code> which contains set a of DNs of
1293     *         dynamic groups matching the search.
1294     * @throws AMException
1295     *             if an error is encountered when trying to access/retrieve
1296     *             data from the data store.
1297     * @throws SSOException
1298     *             if the single sign on token is no longer valid.
1299     */
1300    public AMSearchResults searchDynamicGroups(String wildcard, Map avPairs,
1301            AMSearchControl searchControl) throws AMException, SSOException;
1302
1303    /**
1304     * Searches for dynamic groups in this organization using wildcards and
1305     * attribute values. Wildcards can be specified such as a*, *, *a. To
1306     * further refine the search, attribute-value pairs can be specified so that
1307     * DNs of dynamic groups with matching attribute-value pairs will be
1308     * returned.
1309     * 
1310     * @param wildcard
1311     *            wildcard pattern to be used in the search
1312     * @param avPairs
1313     *            attribute-value pairs to match when searching dynamic groups
1314     * @param groupSearchTemplate
1315     *            Name of search template to be used to perform the search.
1316     * @param searchControl
1317     *            specifies the search scope to be used
1318     * @return <code>AMSearchResults</code> which contains a Set of DNs of
1319     *         dynamic groups matching the search
1320     * @throws AMException
1321     *             if an error is encountered when trying to access/retrieve
1322     *             data from the data store.
1323     * @throws SSOException
1324     *             if the single sign on token is no longer valid.
1325     */
1326    public AMSearchResults searchDynamicGroups(String wildcard, Map avPairs,
1327            String groupSearchTemplate, AMSearchControl searchControl)
1328            throws AMException, SSOException;
1329
1330    /**
1331     * Creates static groups.
1332     * 
1333     * @param groups
1334     *            The set of static groups's names to be created.
1335     * @return set of <code>AMStaticGroup</code> objects created.
1336     * @throws AMException
1337     *             if an error is encountered when trying to access/retrieve
1338     *             data from the data store.
1339     * @throws SSOException
1340     *             if the single sign on token is no longer valid.
1341     */
1342    public Set createStaticGroups(Set groups) throws AMException, SSOException;
1343
1344    /**
1345     * Creates static group. Takes <code>serviceNameAndAttr</code> map so that
1346     * services can be assigned to the group which is just created.
1347     * 
1348     * @param name
1349     *            of group to be created.
1350     * @param attributes
1351     *            to be set in group node.
1352     * @param serviceNameAndAttrs
1353     *            service name and attribute map where the map is like this:
1354     *            <code>&lt;serviceName>&lt;AttrMap>
1355     *              (attrMap=&lt;attrName>&lt;Set of attrvalues>)</code>.
1356     * @return <code>AMGroup</code> object of newly created group.
1357     * @throws AMException
1358     *             if an error is encountered when trying to access/retrieve
1359     *             data from the data store.
1360     * @throws SSOException
1361     *             if the single sign on token is no longer valid.
1362     */
1363    public AMGroup createStaticGroup(String name, Map attributes,
1364            Map serviceNameAndAttrs) throws AMException, SSOException;
1365
1366    /**
1367     * Deletes static groups.
1368     * 
1369     * @param groups
1370     *            The set of static groups's DNs to be deleted.
1371     * @throws AMException
1372     *             if an error is encountered when trying to access/retrieve
1373     *             data from the data store
1374     * @throws SSOException
1375     *             if the single sign on token is no longer valid
1376     * @throws AMException
1377     *             if an error is encountered when trying to access/retrieve
1378     *             data from the data store.
1379     */
1380    public void deleteStaticGroups(Set groups) throws AMException, SSOException;
1381
1382    /**
1383     * Gets the static groups within the specified level.
1384     * 
1385     * @param level
1386     *            The search level starting from the organization.
1387     * @return The Set of DNs of Groups within the specified level.
1388     * @throws AMException
1389     *             if an error is encountered when trying to access/retrieve
1390     *             data from the data store
1391     * @throws SSOException
1392     *             if the single sign on token is no longer valid
1393     * @throws AMException
1394     *             if an error is encountered when trying to access/retrieve
1395     *             data from the data store.
1396     */
1397    public Set getStaticGroups(int level) throws AMException, SSOException;
1398
1399    /**
1400     * Gets number of static groups within the specified level.
1401     * 
1402     * @param level
1403     *            The search level starting from the organization.
1404     * @return Number of static groups within the specified level.
1405     * @throws AMException
1406     *             if an error is encountered when trying to access/retrieve
1407     *             data from the data store.
1408     * @throws SSOException
1409     *             if the single sign on token is no longer valid.
1410     * @throws AMException
1411     *             if an error is encountered when trying to access/retrieve
1412     *             data from the data store.
1413     */
1414    public long getNumberOfStaticGroups(int level) throws AMException,
1415            SSOException;
1416
1417    /**
1418     * Searches for static groups in this organization using wildcards.
1419     * Wildcards can be specified such as a*, *, *a.
1420     * 
1421     * @param wildcard
1422     *            wildcard pattern to be used in the search
1423     * @param level
1424     *            the search level that needs to be used (
1425     *            <code>AMConstants.SCOPE_ONE</code>
1426     *            or <code>AMConstants.SCOPE_SUB</code>)
1427     * 
1428     * @return Set Set of DNs of static groups matching the search
1429     * 
1430     * @throws AMException
1431     *             if an error is encountered when trying to access/retrieve
1432     *             data from the data store
1433     * @throws SSOException
1434     *             if the single sign on token is no longer valid
1435     */
1436    public Set searchStaticGroups(String wildcard, int level)
1437            throws AMException, SSOException;
1438
1439    /**
1440     * Searches for static groups in this organization using wildcards.
1441     * Wildcards can be specified such as a*, *, *a. Uses the
1442     * <code>groupSearchTemplate</code>, if provided. If it is null, default
1443     * search templates are used.
1444     * 
1445     * @param wildcard
1446     *            wildcard pattern to be used in the search
1447     * @param level
1448     *            the search level that needs to be used (
1449     *            <code>AMConstants.SCOPE_ONE</code>
1450     *            or <code>AMConstants.SCOPE_SUB</code>)
1451     * @param groupSearchTemplate
1452     *            name of the search template to be used to perform this search.
1453     * @param avPairs
1454     *            This option can be used to further qualify the search filter.
1455     *            The attribute-value pairs provided by this map are appended to
1456     *            the search filter.
1457     * 
1458     * @return Set Set of DNs of static groups matching the search
1459     * 
1460     * @throws AMException
1461     *             if an error is encountered when trying to access/retrieve
1462     *             data from the data store
1463     * @throws SSOException
1464     *             if the single sign on token is no longer valid
1465     */
1466    public Set searchStaticGroups(String wildcard, int level,
1467            String groupSearchTemplate, Map avPairs) throws AMException,
1468            SSOException;
1469
1470    /**
1471     * Searches for static groups in this organization using wildcards.
1472     * Wildcards can be specified such as a*, *, *a.
1473     * 
1474     * @param wildcard
1475     *            wildcard pattern to be used in the search
1476     * @param searchControl
1477     *            specifies the search scope to be used, VLV ranges etc.
1478     * @return <code>AMSearchResults</code> which contains a set of DNs of
1479     *         static groups matching the search.
1480     * @throws AMException
1481     *             if an error is encountered when trying to access/retrieve
1482     *             data from the data store.
1483     * @throws SSOException
1484     *             if the single sign on token is no longer valid.
1485     */
1486    public AMSearchResults searchStaticGroups(String wildcard,
1487            AMSearchControl searchControl) throws AMException, SSOException;
1488
1489    /**
1490     * Searches for static groups in this organization using wildcards and
1491     * attribute values. Wildcards can be specified such as a*, *, *a. To
1492     * further refine the search, attribute-value pairs can be specified so that
1493     * DNs of static groups with matching attribute-value pairs will be
1494     * returned.
1495     * 
1496     * @param wildcard
1497     *            wildcard pattern to be used in the search
1498     * @param avPairs
1499     *            attribute-value pairs to match when searching groups
1500     * @param level
1501     *            the search level that needs to be used (
1502     *            <code>AMConstants.SCOPE_ONE</code>
1503     *            or <code>AMConstants.SCOPE_SUB</code>)
1504     * @return Set Set of DNs of static groups matching the search
1505     * @throws AMException
1506     *             if an error is encountered when trying to access/retrieve
1507     *             data from the data store
1508     * @throws SSOException
1509     *             if the single sign on token is no longer valid
1510     */
1511    public Set searchStaticGroups(String wildcard, Map avPairs, int level)
1512            throws AMException, SSOException;
1513
1514    /**
1515     * Searches for static groups in this organization using wildcards and
1516     * attribute values. Wildcards can be specified such as a*, *, *a. To
1517     * further refine the search, attribute-value pairs can be specified so that
1518     * DNs of static groups with matching attribute-value pairs will be
1519     * returned.
1520     * 
1521     * @param wildcard
1522     *            wildcard pattern to be used in the search
1523     * @param avPairs
1524     *            attribute-value pairs to match when searching groups
1525     * @param searchControl
1526     *            specifies the search scope to be used, VLV ranges etc.
1527     * @return <code>AMSearchResults</code> which contains a set of DNs of
1528     *         static groups matching the search.
1529     * @throws AMException
1530     *             if an error is encountered when trying to access/retrieve
1531     *             data from the data store.
1532     * @throws SSOException
1533     *             if the single sign on token is no longer valid.
1534     */
1535    public AMSearchResults searchStaticGroups(String wildcard, Map avPairs,
1536            AMSearchControl searchControl) throws AMException, SSOException;
1537
1538    /**
1539     * Searches for static groups in this organization using wildcards and
1540     * attribute values. Wildcards can be specified such as a*, *, *a. To
1541     * further refine the search, attribute-value pairs can be specified so that
1542     * DNs of static groups with matching attribute-value pairs will be
1543     * returned.
1544     * 
1545     * @param wildcard
1546     *            wildcard pattern to be used in the search.
1547     * @param avPairs
1548     *            attribute-value pairs to match when searching static groups.
1549     * @param groupSearchTemplate
1550     *            Name of search template to be used to perform the search.
1551     * @param searchControl
1552     *            specifies the search scope to be used.
1553     * @return <code>AMSearchResults</code> which contains a Set of DNs of
1554     *         static groups matching the search.
1555     * @throws AMException
1556     *             if an error is encountered when trying to access/retrieve
1557     *             data from the data store.
1558     * @throws SSOException
1559     *             if the single sign on token is no longer valid.
1560     */
1561    public AMSearchResults searchStaticGroups(String wildcard, Map avPairs,
1562            String groupSearchTemplate, AMSearchControl searchControl)
1563            throws AMException, SSOException;
1564
1565    /**
1566     * Searches for groups in this organization using wildcards and attribute
1567     * values. Wildcards can be specified such as a*, *, *a.
1568     * 
1569     * @param wildcard
1570     *            wildcard pattern to be used in the search
1571     * @param avPairs
1572     *            attribute-value pairs to match when searching groups
1573     * @param level
1574     *            the search level that needs to be used (
1575     *            <code>AMConstants.SCOPE_ONE</code>
1576     *            or <code>AMConstants.SCOPE_SUB</code>)
1577     * 
1578     * @return Set DNs of groups matching the search
1579     * 
1580     * @throws AMException
1581     *             if an error is encountered when trying to access/retrieve
1582     *             data from the data store
1583     * @throws SSOException
1584     *             if the single sign on token is no longer valid
1585     */
1586    public Set searchGroups(String wildcard, Map avPairs, int level)
1587            throws AMException, SSOException;
1588
1589    /**
1590     * Searches for groups in this organization using wildcards and attribute
1591     * values. Wildcards can be specified such as a*, *, *a.
1592     * 
1593     * @param wildcard
1594     *            wildcard pattern to be used in the search.
1595     * @param avPairs
1596     *            attribute-value pairs to match when searching groups.
1597     * @param searchControl
1598     *            specifies the search scope to be used.
1599     * @return <code>AMSearchResults</code> which contains set a of DNs of
1600     *         groups matching the search.
1601     * @throws AMException
1602     *             if an error is encountered when trying to access/retrieve
1603     *             data from the data store.
1604     * @throws SSOException
1605     *             if the single sign on token is no longer valid.
1606     */
1607    public AMSearchResults searchGroups(String wildcard, Map avPairs,
1608            AMSearchControl searchControl) throws AMException, SSOException;
1609
1610    /**
1611     * Creates people containers.
1612     * 
1613     * @param peopleContainers
1614     *            The set of people containers' names to be created
1615     * @return set of <code>PeopleContainer</code> objects created.
1616     * @throws AMException
1617     *             if an error is encountered when trying to access/retrieve
1618     *             data from the data store.
1619     * @throws SSOException
1620     *             if the single sign on token is no longer valid.
1621     */
1622    public Set createPeopleContainers(Set peopleContainers) throws AMException,
1623            SSOException;
1624
1625    /**
1626     * Creates people containers and initializes their attributes.
1627     * 
1628     * @param peopleContainers
1629     *            Map where the key is the name of the people container, and the
1630     *            value is a Map to represent attribute-value pairs.
1631     * @return set of <code>PeopleContainer</code> objects created.
1632     * @throws AMException
1633     *             if an error is encountered when trying to access/retrieve
1634     *             data from the data store.
1635     * @throws SSOException
1636     *             if the single sign on token is no longer valid.
1637     */
1638    public Set createPeopleContainers(Map peopleContainers) throws AMException,
1639            SSOException;
1640
1641    /**
1642     * Deletes people containers.
1643     * 
1644     * @param peopleContainers
1645     *            The set of people containers' DN to be deleted.
1646     * 
1647     * @throws AMException
1648     *             if an error is encountered when trying to access/retrieve
1649     *             data from the data store
1650     * @throws SSOException
1651     *             if the single sign on token is no longer valid
1652     */
1653    public void deletePeopleContainers(Set peopleContainers)
1654            throws AMException, SSOException;
1655
1656    /**
1657     * Gets the people containers within the specified level.
1658     * 
1659     * @param level
1660     *            The search level starting from the organization.
1661     * @return Set of people containers within the specified level.
1662     * @throws AMException
1663     *             if an error is encountered when trying to access/retrieve
1664     *             data from the data store
1665     * @throws SSOException
1666     *             if the single sign on token is no longer valid
1667     */
1668    public Set getPeopleContainers(int level) throws AMException, SSOException;
1669
1670    /**
1671     * Gets number of people containers within the specified level.
1672     * 
1673     * @param level
1674     *            The search level starting from the organization.
1675     * @return long Number of people containers within the specified level.
1676     * @throws AMException
1677     *             if an error is encountered when trying to access/retrieve
1678     *             data from the data store
1679     * @throws SSOException
1680     *             if the single sign on token is no longer valid
1681     */
1682    public long getNumberOfPeopleContainers(int level) throws AMException,
1683            SSOException;
1684
1685    /**
1686     * Searches for people containers in this organization using wildcards and
1687     * attribute values. Wildcards can be specified such as a*, *, *a.
1688     * 
1689     * @param wildcard
1690     *            wildcard pattern to be used in the search
1691     * @param level
1692     *            the search level that needs to be used (
1693     *            <code>AMConstants.SCOPE_ONE</code>
1694     *            or <code>AMConstants.SCOPE_SUB</code>)
1695     * 
1696     * @return Set DNs of people containers matching the search
1697     * 
1698     * @throws AMException
1699     *             if an error is encountered when trying to access/retrieve
1700     *             data from the data store
1701     * @throws SSOException
1702     *             if the single sign on token is no longer valid
1703     */
1704    public Set searchPeopleContainers(String wildcard, int level)
1705            throws AMException, SSOException;
1706
1707    /**
1708     * Searches for people containers in this organization using wildcards and
1709     * attribute values. Wildcards can be specified such as a*, *, *a.
1710     * 
1711     * @param wildcard
1712     *            wildcard pattern to be used in the search.
1713     * @param searchControl
1714     *            specifies the search scope to be used, VLV ranges etc.
1715     * @return <code>AMSearchResults</code> which contains a set DNs of people
1716     *         containers matching the search.
1717     * @throws AMException
1718     *             if an error is encountered when trying to access/retrieve
1719     *             data from the data store.
1720     * @throws SSOException
1721     *             if the single sign on token is no longer valid.
1722     */
1723    public AMSearchResults searchPeopleContainers(String wildcard,
1724            AMSearchControl searchControl) throws AMException, SSOException;
1725
1726    /**
1727     * Searches for people containers in this organization using wildcards and
1728     * attribute values. Wildcards can be specified such as a*, *, *a. To
1729     * further refine the search, attribute-value pairs can be specified so that
1730     * DNs of people containers with matching attribute-value pairs will be
1731     * returned.
1732     * 
1733     * @param wildcard
1734     *            wildcard pattern to be used in the search
1735     * @param avPairs
1736     *            attribute-value pairs to match when searching people
1737     *            containers
1738     * @param level
1739     *            the search level that needs to be used (
1740     *            <code>AMConstants.SCOPE_ONE</code>
1741     *            or <code>AMConstants.SCOPE_SUB</code>)
1742     * 
1743     * @return Set DNs of people containers matching the search
1744     * 
1745     * @throws AMException
1746     *             if an error is encountered when trying to access/retrieve
1747     *             data from the data store
1748     * @throws SSOException
1749     *             if the single sign on token is no longer valid
1750     */
1751    public Set searchPeopleContainers(String wildcard, Map avPairs, int level)
1752            throws AMException, SSOException;
1753
1754    /**
1755     * Searches for people containers in this organization using wildcards and
1756     * attribute values. Wildcards can be specified such as a*, *, *a. To
1757     * further refine the search, attribute-value pairs can be specified so that
1758     * DNs of people containers with matching attribute-value pairs will be
1759     * returned.
1760     * 
1761     * @param wildcard
1762     *            wildcard pattern to be used in the search.
1763     * @param avPairs
1764     *            attribute-value pairs to match when searching people
1765     *            containers.
1766     * @param searchControl
1767     *            specifies the search scope to be used, VLV ranges etc.
1768     * @return <code>AMSearchResults</code> which contains a set DNs of people
1769     *         containers matching the search.
1770     * @throws AMException
1771     *             if an error is encountered when trying to access/retrieve
1772     *             data from the data store.
1773     * @throws SSOException
1774     *             if the single sign on token is no longer valid.
1775     */
1776    public AMSearchResults searchPeopleContainers(String wildcard, Map avPairs,
1777            AMSearchControl searchControl) throws AMException, SSOException;
1778
1779    /**
1780     * Creates group containers.
1781     * 
1782     * @param groupContainers
1783     *            The set of group containers' names to be created.
1784     * @return set of group container objects created.
1785     * @throws AMException
1786     *             if an error is encountered when trying to access/retrieve
1787     *             data from the data store.
1788     * @throws SSOException
1789     *             if the single sign on token is no longer valid.
1790     */
1791    public Set createGroupContainers(Set groupContainers) throws AMException,
1792            SSOException;
1793
1794    /**
1795     * Creates group containers and initializes their attributes.
1796     * 
1797     * @param groupContainers
1798     *            Map where the key is the name of the group container, and the
1799     *            value is a Map to represent attribute-value pairs.
1800     * @return set of group container objects created.
1801     * @throws AMException
1802     *             if an error is encountered when trying to access/retrieve
1803     *             data from the data store.
1804     * @throws SSOException
1805     *             if the single sign on token is no longer valid.
1806     */
1807    public Set createGroupContainers(Map groupContainers) throws AMException,
1808            SSOException;
1809
1810    /**
1811     * Deletes group containers.
1812     * 
1813     * @param groupContainers
1814     *            The set of group containers' DN to be deleted.
1815     * 
1816     * @throws AMException
1817     *             if an error is encountered when trying to access/retrieve
1818     *             data from the data store
1819     * @throws SSOException
1820     *             if the single sign on token is no longer valid
1821     */
1822    public void deleteGroupContainers(Set groupContainers) throws AMException,
1823            SSOException;
1824
1825    /**
1826     * Gets the group containers within the specified level.
1827     * 
1828     * @param level
1829     *            The search level starting from the organization.
1830     * @return set of group containers within the specified level.
1831     * @throws AMException
1832     *             if an error is encountered when trying to access/retrieve
1833     *             data from the data store
1834     * @throws SSOException
1835     *             if the single sign on token is no longer valid
1836     */
1837    public Set getGroupContainers(int level) throws AMException, SSOException;
1838
1839    /**
1840     * Gets number of group containers within the specified level.
1841     * 
1842     * @param level
1843     *            The search level starting from the organization.
1844     * @return long Number of group containers within the specified level.
1845     * @throws AMException
1846     *             if an error is encountered when trying to access/retrieve
1847     *             data from the data store
1848     * @throws SSOException
1849     *             if the single sign on token is no longer valid
1850     */
1851    public long getNumberOfGroupContainers(int level) throws AMException,
1852            SSOException;
1853
1854    /**
1855     * Searches for group containers in this organization using wildcards and
1856     * attribute values. Wildcards can be specified such as a*, *, *a. To
1857     * further refine the search, attribute-value pairs can be specified so that
1858     * DNs of group containers with matching attribute-value pairs will be
1859     * returned.
1860     * 
1861     * @param wildcard
1862     *            wildcard pattern to be used in the search
1863     * @param avPairs
1864     *            attribute-value pairs to match when searching group containers
1865     * @param level
1866     *            the search level that needs to be used (
1867     *            <code>AMConstants.SCOPE_ONE</code>
1868     *            or <code>AMConstants.SCOPE_SUB</code>)
1869     * 
1870     * @return Set DNs of group containers matching the search
1871     * 
1872     * @throws AMException
1873     *             if an error is encountered when trying to access/retrieve
1874     *             data from the data store
1875     * @throws SSOException
1876     *             if the single sign on token is no longer valid
1877     */
1878    public Set searchGroupContainers(String wildcard, Map avPairs, int level)
1879            throws AMException, SSOException;
1880
1881    /**
1882     * Searches for group containers in this organization using wildcards and
1883     * attribute values. Wildcards can be specified such as a*, *, *a. To
1884     * further refine the search, attribute-value pairs can be specified so that
1885     * DNs of group containers with matching attribute-value pairs will be
1886     * returned.
1887     * 
1888     * @param wildcard
1889     *            wildcard pattern to be used in the search.
1890     * @param avPairs
1891     *            attribute-value pairs to match when searching group
1892     *            containers.
1893     * @param searchControl
1894     *            specifies the search scope to be used, VLV ranges etc.
1895     * @return <code>AMSearchResults</code> which contains a set DNs of group
1896     *         containers matching the search.
1897     * @throws AMException
1898     *             if an error is encountered when trying to access/retrieve
1899     *             data from the data store.
1900     * @throws SSOException
1901     *             if the single sign on token is no longer valid.
1902     */
1903    public AMSearchResults searchGroupContainers(String wildcard, Map avPairs,
1904            AMSearchControl searchControl) throws AMException, SSOException;
1905
1906    /**
1907     * Creates users in this organization. For each user the, object classes
1908     * specified by organization type attribute
1909     * <code>iplanet-am-required-services</code> of the service
1910     * <code>iPlanetAMAdminConsoleService</code> template are added. If a
1911     * corresponding template does not exist, the default values are picked up
1912     * from schema.
1913     * 
1914     * @param users
1915     *            The set of user names to be created in this organization.
1916     * @return Set Set of User objects created
1917     * @throws AMException
1918     *             if an error is encountered when trying to access/retrieve
1919     *             data from the data store
1920     * @throws SSOException
1921     *             if the single sign on token is no longer valid
1922     */
1923    public Set createUsers(Set users) throws AMException, SSOException;
1924
1925    /**
1926     * Creates users and initializes their attributes. For each user the, object
1927     * classes specified by organization type attribute
1928     * <code>iplanet-am-required-services</code> of the service
1929     * <code>iPlanetAMAdminConsoleService</code> template are added. If a
1930     * corresponding template does not exist, the default values are picked up
1931     * from schema.
1932     * 
1933     * @param users
1934     *            Map where the key is the name of the user, and the value is a
1935     *            Map to represent Attribute-Value Pairs
1936     * @return Set Set of User objects created
1937     * @throws AMException
1938     *             if an error is encountered when trying to access/retrieve
1939     *             data from the data store
1940     * @throws SSOException
1941     *             if the single sign on token is no longer valid
1942     */
1943    public Set createUsers(Map users) throws AMException, SSOException;
1944
1945    /**
1946     * Create user and initializes the attributes. For each user the, object
1947     * classes specified by organization type attribute
1948     * <code>iplanet-am-required-services</code> of the service
1949     * <code>iPlanetAMAdminConsoleService</code> template are added. If a
1950     * corresponding template does not exist, the default values are picked up
1951     * from schema. Also services as defined in the arguments, are assigned to
1952     * the user, with default values being picked up from the service schema if
1953     * none are provided for required attributes of the service.
1954     * 
1955     * @param uid
1956     *            value of naming attribute for user.
1957     * @param attrMap
1958     *            attribute-values to be set in the user entry.
1959     * @param serviceNameAndAttrs
1960     *            service names and attributes to be assigned to the user.
1961     * @return AMUser object of newly created user.
1962     * @throws AMException
1963     *             if an error is encountered when trying to access/retrieve
1964     *             data from the data store
1965     * @throws SSOException
1966     *             if the single sign on token is no longer valid
1967     */
1968    public AMUser createUser(String uid, Map attrMap, Map serviceNameAndAttrs)
1969            throws AMException, SSOException;
1970
1971    /**
1972     * Deletes users from this organization.
1973     * 
1974     * @param users
1975     *            The set of user DN's to be deleted from the organization.
1976     * @throws AMException
1977     *             if an error is encountered when trying to access/retrieve
1978     *             data from the data store.
1979     * @throws SSOException
1980     *             if the single sign on token is no longer valid.
1981     */
1982    public void deleteUsers(Set users) throws AMException, SSOException;
1983
1984    /**
1985     * Returns the names (DNs) of users in the organization.
1986     * 
1987     * @return Set The names(DNs) of users in the organization.
1988     * @throws AMException
1989     *             if an error is encountered when trying to access/retrieve
1990     *             data from the data store
1991     * @throws SSOException
1992     *             if the single sign on token is no longer valid
1993     */
1994    public Set getUserDNs() throws AMException, SSOException;
1995
1996    /**
1997     * Returns <code>AMUser</code> object of user in this organization (or in
1998     * sub organizations), whose naming attribute exactly matches with
1999     * <code>uid</code>. If <code>userSearchTemplate</code> is not null,
2000     * then this search template is used otherwise the
2001     * <code>BasicUserSearchTemplate</code> is used. Any <code>%U</code> in
2002     * the search filter are replaced with <code>uid</code>. If the search
2003     * returns more than one user, an exception is thrown because this is a
2004     * violation of the name space constraint.
2005     * 
2006     * @param uid
2007     *            naming attribute value for user.
2008     * @param userSearchTemplate
2009     *            search template.
2010     * @return <code>AMUser</code> object of user found.
2011     * @throws AMException
2012     * @throws SSOException
2013     */
2014    AMUser getUser(String uid, String userSearchTemplate) throws AMException,
2015            SSOException;
2016
2017    /**
2018     * Gets number of users within the specified level.
2019     * 
2020     * @param level
2021     *            The search level starting from the organization.
2022     * @return Number of users within the specified level.
2023     * @throws AMException
2024     *             if an error is encountered when trying to access/retrieve
2025     *             data from the data store
2026     * @throws SSOException
2027     *             if the single sign on token is no longer valid
2028     */
2029    public long getNumberOfUsers(int level) throws AMException, SSOException;
2030
2031    /**
2032     * Searches for users in this organization using wildcards and attribute
2033     * values. Wildcards can be specified such as a*, *, *a.
2034     * 
2035     * @param wildcard
2036     *            wildcard pattern to be used in the search
2037     * @param level
2038     *            the search level that needs to be used (
2039     *            <code>AMConstants.SCOPE_ONE</code>
2040     *            or <code>AMConstants.SCOPE_SUB</code>)
2041     * 
2042     * @return Set DNs of Users matching the search
2043     * 
2044     * @throws AMException
2045     *             if an error is encountered when trying to access/retrieve
2046     *             data from the data store
2047     * @throws SSOException
2048     *             if the single sign on token is no longer valid
2049     */
2050    public Set searchUsers(String wildcard, int level) throws AMException,
2051            SSOException;
2052
2053    /**
2054     * Searches for users in this organization using wildcards and attribute
2055     * values. Wildcards can be specified such as a*, *, *a. SDK users the
2056     * <code>userSearchTemplate</code>, if provided. Otherwise, it uses the
2057     * <code>BasicUserSearchTemplate</code>. Any <code>%U</code> in the
2058     * search template are replaced with the wildcard.
2059     * 
2060     * @param wildcard
2061     *            wildcard pattern to be used in the search
2062     * @param level
2063     *            the search level that needs to be used (
2064     *            <code>AMConstants.SCOPE_ONE</code>
2065     *            or <code>AMConstants.SCOPE_SUB</code>)
2066     * @param userSearchTemplate
2067     *            Name of search template to be used. If null is passed then the
2068     *            default search template <code>BasicUserSearch</code> will be
2069     *            used.
2070     * @param avPairs
2071     *            This option can be used to further qualify the search filter.
2072     *            The attribute-value pairs provided by this map are appended to
2073     *            the search filter.
2074     * @return Set DNs of Users matching the search
2075     * @throws AMException
2076     *             if an error is encountered when trying to access/retrieve
2077     *             data from the data store.
2078     * @throws SSOException
2079     *             if the single sign on token is no longer valid.
2080     */
2081    public Set searchUsers(String wildcard, int level,
2082            String userSearchTemplate, Map avPairs) throws AMException,
2083            SSOException;
2084
2085    /**
2086     * Searches for users in this organization using wildcards and attribute
2087     * values. Wildcards can be specified such as a*, *, *a.
2088     * 
2089     * @param wildcard
2090     *            wildcard pattern to be used in the search.
2091     * @param searchControl
2092     *            specifies the search scope to be used, VLV ranges etc.
2093     * @return <code>AMSearchResults</code> which contains a set DNs of users
2094     *         matching the search.
2095     * @throws AMException
2096     *             if an error is encountered when trying to access/retrieve
2097     *             data from the data store.
2098     * @throws SSOException
2099     *             if the single sign on token is no longer valid.
2100     */
2101    public AMSearchResults searchUsers(String wildcard,
2102            AMSearchControl searchControl) throws AMException, SSOException;
2103
2104    /**
2105     * Searches for users in this organization using wildcards and attribute
2106     * values. Wildcards can be specified such as a*, *, *a. To further refine
2107     * the search, attribute-value pairs can be specified so that DNs of users
2108     * with matching attribute-value pairs will be returned.
2109     * 
2110     * @param wildcard
2111     *            wildcard pattern to be used in the search
2112     * @param avPairs
2113     *            attribute-value pairs to match when searching users
2114     * @param level
2115     *            the search level that needs to be used (
2116     *            <code>AMConstants.SCOPE_ONE</code>
2117     *            or <code>AMConstants.SCOPE_SUB</code>)
2118     * 
2119     * @return Set DNs of Users matching the search
2120     * 
2121     * @throws AMException
2122     *             if an error is encountered when trying to access/retrieve
2123     *             data from the data store
2124     * @throws SSOException
2125     *             if the single sign on token is no longer valid
2126     */
2127    public Set searchUsers(String wildcard, Map avPairs, int level)
2128            throws AMException, SSOException;
2129
2130    /**
2131     * Searches for users in this organization using wildcards and attribute
2132     * values. Wildcards can be specified such as a*, *, *a. To further refine
2133     * the search, attribute-value pairs can be specified so that DNs of users
2134     * with matching attribute-value pairs will be returned.
2135     * 
2136     * @param wildcard
2137     *            wildcard pattern to be used in the search.
2138     * @param avPairs
2139     *            attribute-value pairs to match when searching users.
2140     * @param searchControl
2141     *            specifies the search scope to be used, VLV ranges etc.,
2142     * @return <code>AMSearchResults</code> which contains a set DNs of users
2143     *         matching the search.
2144     * @throws AMException
2145     *             if an error is encountered when trying to access/retrieve
2146     *             data from the data store.
2147     * @throws SSOException
2148     *             if the single sign on token is no longer valid.
2149     */
2150    public AMSearchResults searchUsers(String wildcard, Map avPairs,
2151            AMSearchControl searchControl) throws AMException, SSOException;
2152
2153    /**
2154     * Searches for users in this organization using wildcards and attribute
2155     * values. Wildcards can be specified such as a*, *, *a. To further refine
2156     * the search, attribute-value pairs can be specified so that DNs of users
2157     * with matching attribute-value pairs will be returned.
2158     * 
2159     * @param wildcard
2160     *            wildcard pattern to be used in the search
2161     * @param avPairs
2162     *            attribute-value pairs to match when searching users
2163     * @param userSearchTemplate
2164     *            Name of user search template to be used.
2165     * @param searchControl
2166     *            specifies the search scope to be used, VLV ranges etc.
2167     * @return <code>AMSearchResults</code> which contains a set DNs of users
2168     *         matching the search.
2169     * @throws AMException
2170     *             if an error is encountered when trying to access/retrieve
2171     *             data from the data store.
2172     * @throws SSOException
2173     *             if the single sign on token is no longer valid.
2174     */
2175    public AMSearchResults searchUsers(String wildcard, Map avPairs,
2176            String userSearchTemplate, AMSearchControl searchControl)
2177            throws AMException, SSOException;
2178
2179    /**
2180     * Searches for users in this organization using wildcards and attribute
2181     * values. Wildcards can be specified such as a*, *, *a. To further refine
2182     * the search, attribute-value pairs can be specified so that DNs of users
2183     * with matching attribute-value pairs will be returned.
2184     * 
2185     * @param wildcard
2186     *            wildcard pattern to be used in the search.
2187     * @param searchControl
2188     *            specifies the search scope to be used, VLV ranges etc.
2189     * @param avfilter
2190     *            this attribute-value pairs filter will be logical AND with
2191     *            user search filter.
2192     * @return <code>AMSearchResults</code> which contains a Set DNs of users
2193     *         matching the search.
2194     * @throws AMException
2195     *             if an error is encountered when trying to access/retrieve
2196     *             data from the data store.
2197     * @throws SSOException
2198     *             if the single sign on token is no longer valid.
2199     */
2200    public AMSearchResults searchUsers(String wildcard,
2201            AMSearchControl searchControl, String avfilter) throws AMException,
2202            SSOException;
2203
2204    /**
2205     * Searches for users in this organization using attribute values. Wildcards
2206     * such as can be specified for the attribute values. The DNs of users with
2207     * matching attribute-value pairs will be returned.
2208     * 
2209     * @param searchControl
2210     *            specifies the search scope to be used, VLV ranges etc.
2211     * @param avfilter
2212     *            this attribute-value pairs filter will be logical AND with
2213     *            user search filter.
2214     * @return <code>AMSearchResults</code> which contains a set of DNs of
2215     *         users matching the search.
2216     * @throws AMException
2217     *             if there is an internal error in the access management data
2218     *             store
2219     * @throws SSOException
2220     *             if the single sign on token is no longer valid
2221     */
2222    public AMSearchResults searchUsers(AMSearchControl searchControl,
2223            String avfilter) throws AMException, SSOException;
2224
2225    /**
2226     * Returns the number of services.
2227     * 
2228     * @return number of services.
2229     * @throws AMException
2230     *             if there is an internal error in the access management data
2231     *             store
2232     * @throws SSOException
2233     *             if the single sign on token is no longer valid
2234     */
2235    public long getNumberOfServices() throws AMException, SSOException;
2236
2237    /**
2238     * Gets the names of registered services.
2239     * 
2240     * @return The Set of the names of registered services.
2241     * @throws AMException
2242     *             if there is an internal error in the access management data
2243     *             store
2244     * @throws SSOException
2245     *             if the single sign on token is no longer valid
2246     */
2247    public Set getRegisteredServiceNames() throws AMException, SSOException;
2248
2249    /**
2250     * Register a service for this organization.
2251     * 
2252     * @param serviceName
2253     *            The name of service to be registered
2254     * @param createTemplate
2255     *            true if to create default template
2256     * @param activate
2257     *            true if to activate the service
2258     * @throws AMException
2259     *             if the service does not exist or could not be registered.
2260     * @throws SSOException
2261     *             if the single sign on token is no longer valid.
2262     */
2263    public void registerService(String serviceName, boolean createTemplate,
2264            boolean activate) throws AMException, SSOException;
2265
2266    /**
2267     * Unregisters a service for this organization.
2268     * 
2269     * @param serviceName
2270     *            service name to be unregistered.
2271     * @throws AMException
2272     *             if the service does not exist or could not be unregistered.
2273     * @throws SSOException
2274     *             if the single sign on token is no longer valid.
2275     */
2276    public void unregisterService(String serviceName) throws AMException,
2277            SSOException;
2278
2279    /**
2280     * Unassigns the given policies from this organization and its roles.
2281     * 
2282     * @param serviceName
2283     *            service name.
2284     * @param policyDNs
2285     *            Set of policy DN string.
2286     * @throws AMException
2287     *             if there is an internal problem with access management data
2288     *             store.
2289     * @throws SSOException
2290     *             if the single sign on token is no longer valid.
2291     */
2292    public void unassignAllPolicies(String serviceName, Set policyDNs)
2293            throws AMException, SSOException;
2294
2295    /**
2296     * Modifies all the templates under this organization that contain any
2297     * <code>policyDN</code> in given <code>policyDNs</code>.
2298     * 
2299     * @param serviceName
2300     *            service name.
2301     * @param policyDNs
2302     *            Set of policy DN string
2303     * 
2304     * @throws AMException
2305     *             if there is an internal problem with access management data
2306     *             store.
2307     * @throws SSOException
2308     *             if the single sign on token is no longer valid.
2309     */
2310    public void modifyAllPolicyTemplates(String serviceName, Set policyDNs)
2311            throws AMException, SSOException;
2312
2313    /**
2314     * Deletes all the named policy templates for this Organization
2315     * corresponding to the given policy. This includes organizational based and
2316     * role based policy templates. This is a convenience method.
2317     * 
2318     * @param policyDN
2319     *            a policy DN string
2320     * @throws AMException
2321     *             if there is an internal problem with access management data
2322     *             store.
2323     * @throws SSOException
2324     *             if the single sign on token is no longer valid.
2325     * @return true if policy templates were found and deleted.
2326     */
2327    public boolean deleteAllNamedPolicyTemplates(String policyDN)
2328            throws AMException, SSOException;
2329
2330    /**
2331     * Gets all the assigned policies for this Organization
2332     * 
2333     * @return Set a set of assigned policy DNs
2334     * @throws AMException
2335     *             if there is an internal problem with access management data
2336     *             store.
2337     * @throws SSOException
2338     *             if the single sign on token is no longer valid.
2339     */
2340    public Set getAssignedPolicyDNs() throws AMException, SSOException;
2341
2342    /**
2343     * Returns true if a <code>policyDN</code> is assigned to an organization
2344     * or a role.
2345     * 
2346     * @param policyDN
2347     *            a policy DN string
2348     * @param serviceName
2349     *            service name
2350     * @return true if policy is assigned to an organization or role.
2351     * @throws AMException
2352     *             if there is an internal error in the access management data
2353     *             store
2354     * @throws SSOException
2355     *             if the single sign on token is no longer valid
2356     */
2357    public boolean isPolicyAssigned(String policyDN, String serviceName)
2358            throws AMException, SSOException;
2359
2360    /**
2361     * Returns true if an organizational template exists for the service.
2362     * 
2363     * @param serviceName
2364     *            service name
2365     * @return true if the organizational template exists.
2366     * @throws AMException
2367     *             if there is an internal error in the access management data
2368     *             store
2369     * @throws SSOException
2370     *             if the single sign on token is no longer valid
2371     */
2372    public boolean orgTemplateExists(String serviceName) throws AMException,
2373            SSOException;
2374
2375    /**
2376     * Unassigns services from the organization. Also removes service specific
2377     * attributes, if defined in the user entry.
2378     * 
2379     * @param serviceNames
2380     *            Set of service names
2381     * @throws AMException
2382     *             if an error is encountered when trying to access/retrieve
2383     *             data from the data store
2384     * @throws SSOException
2385     *             if the single sign on token is no longer valid
2386     */
2387    public void unassignServices(Set serviceNames) throws AMException,
2388            SSOException;
2389
2390    /**
2391     * This method creates the entities of the given type. The entity is created
2392     * under a default container, if specified in the <code>DAI</code>
2393     * service. If the specified default container does not exist, then it is
2394     * created under the current organization and then the entities are created
2395     * under it. If no specified container is specified, then the entities are
2396     * created directly under the organization.
2397     * 
2398     * @param type
2399     *            Type of entity being created. The types supported by SDK are
2400     *            configured in the list of Managed Objects in the
2401     *            <code>DAI</code> service.
2402     * @param entityNames
2403     *            Set of names of entities to be created
2404     * @return Set of <code>AMEntity</code> objects.
2405     * @throws AMException
2406     *             if an error encountered when trying to set/access the data
2407     *             store.
2408     * @throws SSOException
2409     *             if the single sign on token of user is no longer valid.
2410     */
2411    public Set createEntities(int type, Set entityNames) throws AMException,
2412            SSOException;
2413
2414    /**
2415     * Creates the entities of the given type. The entity is created under a
2416     * default container, if specified in the <code>DAI</code> service. If the
2417     * specified default container does not exist, then it is created under the
2418     * current organization and then the entities are created under it. If no
2419     * specified container is specified, then the entities are created directly
2420     * under the organization.
2421     * 
2422     * @param type
2423     *            Type of entity being created. The types supported by SDK are
2424     *            configured in the list of Managed Objects in the
2425     *            <code>DAI</code> service.
2426     * @param entityNamesAndAttrs
2427     *            Map of entity name to a map of attribute name to a set of
2428     *            values.
2429     * @return Set of <code>AMEntity</code> objects.
2430     * @throws AMException
2431     *             if an error encountered when trying to set/access the data
2432     *             store.
2433     * @throws SSOException
2434     *             if the single sign on token of user is no longer valid.
2435     */
2436    public Set createEntities(int type, Map entityNamesAndAttrs)
2437            throws AMException, SSOException;
2438
2439    /**
2440     * Searches for entities of the given type. The basic search filter is used
2441     * from the search template as defined in the <code>DAI</code> service.
2442     * The map of attribute-value pairs is <code>or-ed</code> to the basic
2443     * search filter along with the wildcard, which is used to specify the
2444     * naming attribute in the final search filter. The search is conducted
2445     * under the specified container, if it exists. It the specified container
2446     * does not exist, then an exception is thrown. If there is no specified
2447     * container, then the search is performed directly under the organization.
2448     * 
2449     * @param type
2450     *            Type of entity being created. The types supported by SDK are
2451     *            configured in the list of Managed Objects in the
2452     *            <code>DAI</code> service.
2453     * @param wildcard
2454     *            Pattern for naming attribute when performing the search.
2455     * @param scope
2456     *            Search level that needs to be used (
2457     *            <code>AMConstants.SCOPE_ONE</code>
2458     *            or <code>AMConstants.SCOPE_SUB</code>).
2459     * @param avPairs
2460     *            Map of attribute-value pairs.
2461     * @return Set of matching entity distinguished names.
2462     * @throws AMException
2463     *             If there is an error trying to access the data store.
2464     * @throws SSOException
2465     *             If the user's single sign on token is invalid.
2466     */
2467    public Set searchEntities(int type, String wildcard, int scope, Map avPairs)
2468            throws AMException, SSOException;
2469
2470    /**
2471     * Searches for entities of the given type. The basic search filter is used
2472     * from the search template as defined in the <code>DAI</code> service.
2473     * The map of attribute-value pairs is <code>or-ed</code> to the basic
2474     * search filter along with the wildcard, which is used to specify the
2475     * naming attribute in the final search filter. The search is conducted
2476     * under the specified container, if it exists. It the specified container
2477     * does not exist, then an exception is thrown. If there is no specified
2478     * container, then the search is performed directly under the organization.
2479     * 
2480     * @param type
2481     *            The type of entity to be searched. The types are defined in
2482     *            the list of managed objects in the <code>DAI</code> service.
2483     * @param wildcard
2484     *            Pattern for naming attribute when performing the search.
2485     * @param avPairs
2486     *            Map of attribute-value pairs.
2487     * @param ctrls
2488     *            Search control object specifying various search parameter.
2489     * @return com.iplanet.am.sdk.AMSearchResults
2490     * @throws AMException
2491     *             If there is an error trying to access the data store.
2492     * @throws SSOException
2493     *             If the user's single sign on token is invalid.
2494     */
2495    public AMSearchResults searchEntities(int type, String wildcard,
2496            Map avPairs, AMSearchControl ctrls) throws AMException,
2497            SSOException;
2498
2499    /**
2500     * 
2501     * Searches for entities of the given type. The basic search filter is used
2502     * from the search template as defined in the <code>DAI</code> service.
2503     * The map of attribute-value pairs is <code>or-ed</code> to the basic
2504     * search filter along with the wildcard, which is used to specify the
2505     * naming attribute in the final search filter. The search is conducted
2506     * under the specified container, if it exists. It the specified container
2507     * does not exist, then an exception is thrown. If there is no specified
2508     * container, then the search is performed directly under the organization.
2509     * 
2510     * @param type
2511     *            The type of entity to be searched. The types are defined in
2512     *            the list of managed objects in the <code>DAI</code> service.
2513     * @param wildcard
2514     *            Pattern for naming attribute when performing the search.
2515     * @param avfilter
2516     *            Search filter to add to the basic search filter.
2517     * @param ctrl
2518     *            Search control object specifying various search parameter.
2519     * @return <code>com.iplanet.am.sdk.AMSearchResults</code>
2520     * @throws AMException
2521     *             If there is an error trying to access the data store.
2522     * @throws SSOException
2523     *             If the user's single sign on token is invalid.
2524     */
2525    public AMSearchResults searchEntities(int type, String wildcard,
2526            String avfilter, AMSearchControl ctrl) throws AMException,
2527            SSOException;
2528
2529    /**
2530     * Deletes the entities whose fully-qualified distinguished names are
2531     * provided in the set below.
2532     * 
2533     * @param type
2534     *            Type of entity being deleted.
2535     * @param entityDNs
2536     *            Set of the <code> FQDNs </code> of entities to be deleted.
2537     * @throws AMException
2538     *             If there is an error in trying to access the data store.
2539     * @throws SSOException
2540     *             If the user's single sign on token is invalid.
2541     */
2542    public void deleteEntities(int type, Set entityDNs) throws AMException,
2543            SSOException;
2544
2545    /**
2546     * Returns true if the organization is activated.
2547     * 
2548     * @return true if the organization is activated.
2549     * @throws AMException
2550     *             if an error is encountered when trying to access/retrieve
2551     *             data from the data store
2552     * @throws SSOException
2553     *             if the single sign on token is no longer valid.
2554     */
2555    public boolean isActivated() throws AMException, SSOException;
2556
2557}