/**
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at
 * https://opensso.dev.java.net/public/CDDLv1.0.html or
 * opensso/legal/CDDLv1.0.txt
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file
 * at opensso/legal/CDDLv1.0.txt.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 * $Id: AMGroup.java,v 1.4 2008/06/25 05:41:20 qcheng Exp $
 *
 */

package com.iplanet.am.sdk;

import java.util.Map;
import java.util.Set;

import com.iplanet.sso.SSOException;

/**
 * The <code>AMGroup</code> interface provides methods to manage group
 *
 * @deprecated  As of Sun Java System Access Manager 7.1.
 * @supported.all.api
 */
abstract public interface AMGroup extends AMObject {
    /**
     * Returns number of users in the group.
     * 
     * @return Number of users in the group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token no longer valid.
     */
    public long getNumberOfUsers() throws AMException, SSOException;

    /**
     * Returns the distinguished name of users in the group.
     * 
     * @return a set of user distinguished names in the group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set getUserDNs() throws AMException, SSOException;

    /**
     * Returns the distinguished name of users and nested groups in the group.
     * 
     * @return The distinguished name of users and nested groups in the group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set getUserAndGroupDNs() throws AMException, SSOException;

    /**
     * Nests the given group distinguished names in this the group. This will
     * effectively make the groups <code>members</code> of this group. And any
     * ACIs set for this group will be inherited by the nested groups and their
     * members.
     * 
     * @param groups
     *            The set of group distinguished names to be nested in this
     *            group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public void addNestedGroups(Set groups) throws AMException, SSOException;

    /**
     * Searches for users in this group using wildcards and attribute values.
     * Wildcards can be specified such as a*, *, *a.
     * 
     * @param wildcard
     *            wildcard pattern to be used in the search
     * @return Set of distinguished name of users matching the search
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store
     * @throws SSOException
     *             if the single sign on token is no longer valid
     */
    public Set searchUsers(String wildcard) throws AMException, SSOException;

    /**
     * Searches for users in this group using wildcards. Wildcards can be
     * specified such as a*, *, *a.
     * 
     * @param wildcard
     *            wildcard pattern to be used in the search
     * @param avPairs
     *            attribute-value pairs to match when searching users
     * @param searchControl
     *            specifies the size limit and time limit
     * @return <code>AMSearchResults</code> which contains a set of
     *         distinguished name of Users matching the search.
     * @throws AMException
     *             if there is an internal error in the access management store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public AMSearchResults searchUsers(String wildcard, Map avPairs,
            AMSearchControl searchControl) throws AMException, SSOException;

    /**
     * Searches for users in this group using attribute values. Wildcards such
     * as a*, *, *a can be specified for the attribute values. The distinguished
     * names of users with matching attribute-value pairs will be returned.
     * 
     * @param searchControl
     *            specifies the search scope to be used, VLV ranges etc.,
     * @param avfilter
     *            this attribute-value pairs filter will be logical AND with
     *            user search filter.
     * @return <code>AMSearchResults</code> which contains a set of
     *         distinguished names of Users matching the search.
     * @throws AMException
     *             if there is an internal error in the access management Store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public AMSearchResults searchUsers(AMSearchControl searchControl,
            String avfilter) throws AMException, SSOException;

    /**
     * Creates static groups in this group.
     * 
     * @param groupNames
     *            The set of static groups' names to be created in this group.
     * @return set of static group objects created.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set createStaticGroups(Set groupNames) throws AMException,
            SSOException;

    /**
     * Creates static groups and initializes their attributes.
     * 
     * @param groups
     *            Map where the key is the name of the static group, and the
     *            value is a Map to represent Attribute-Value Pairs
     * @return Set of group objects created.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set createStaticGroups(Map groups) throws AMException, SSOException;

    /**
     * Creates dynamic groups in this group.
     * 
     * @param groupNames
     *            The set of dynamic groups' names to be created in this group.
     * @return Set of dynamic group objects created
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set createDynamicGroups(Set groupNames) throws AMException,
            SSOException;

    /**
     * Creates dynamic groups and initializes their attributes.
     * 
     * @param groups
     *            Map of name of the dynamic group to attribute-value pairs map.
     * @return Set of dynamic group objects created.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set createDynamicGroups(Map groups) throws AMException, SSOException;

    /**
     * Creates assignable dynamic groups in this group.
     * 
     * @param groupNames
     *            The set of assignable dynamic groups' names to be created in
     *            this group.
     * @return Set of assignable dynamic group objects created.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set createAssignableDynamicGroups(Set groupNames)
            throws AMException, SSOException;

    /**
     * Creates assignable dynamic groups and initializes their attributes.
     * 
     * @param groups
     *            Map of name of the assignable dynamic group to attribute-value
     *            pairs map;
     * @return Set of assignable dynamic group objects created.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set createAssignableDynamicGroups(Map groups) throws AMException,
            SSOException;

    /**
     * Gets the groups in this group. It returns groups either at one level or a
     * whole subtree.
     * 
     * @param level
     *            the level (<code>AMConstants.SCOPE_ONE</code> or
     *            <code>AMConstants.SCOPE_SUB</code>) for returning groups.
     * @return The group distinguished names in this group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store or if the level is invalid.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set getGroupDNs(int level) throws AMException, SSOException;

    /**
     * Returns the groups nested in this group.
     * 
     * @return The group distinguished names nested in this group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set getNestedGroupDNs() throws AMException, SSOException;

    /**
     * Removes groups which are nested in this group.
     * 
     * @param groups
     *            The set of user DN's to be removed from the static group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store
     * @throws SSOException
     *             if the single sign on token is no longer valid
     */
    public void removeNestedGroups(Set groups) throws AMException, SSOException;

    /**
     * Returns number of groups in the group. It returns number of groups either
     * at one level or a whole subtree.
     * 
     * @param level
     *            the level (<code>AMConstants.SCOPE_ONE</code> or
     *            <code>AMConstants.SCOPE_SUB</code>) for returning groups.
     * @return Number of groups in the group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public long getNumberOfGroups(int level) throws AMException, SSOException;

    /**
     * Deletes static groups in this group.
     * 
     * @param groupDNs
     *            The set of static group distinguished names to be deleted from
     *            this group.
     * 
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public void deleteStaticGroups(Set groupDNs) throws AMException,
            SSOException;

    /**
     * Deletes dynamic groups in this group.
     * 
     * @param groupDNs
     *            The set of dynamic group distinguished names to be deleted
     *            from this group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store
     * @throws SSOException
     *             if the single sign on token is no longer valid
     */
    public void deleteDynamicGroups(Set groupDNs) throws AMException,
            SSOException;

    /**
     * Deletes assignable dynamic groups in this group.
     * 
     * @param groupDNs
     *            The set of assignable dynamic group distinguished names to be
     *            deleted from this group.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public void deleteAssignableDynamicGroups(Set groupDNs) throws AMException,
            SSOException;

    /**
     * Searches for groups in this group using wildcards. Wildcards can be
     * specified such as a*, *, *a.
     * 
     * @param wildcard
     *            wildcard pattern to be used in the search
     * @param level
     *            the search level that needs to be used (
     *            <code>AMConstants.SCOPE_ONE</code>
     *            or <code>AMConstants.SCOPE_TREE</code>).
     * @return Set of distinguished name of sub groups matching the search
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set searchGroups(String wildcard, int level) throws AMException,
            SSOException;

    /**
     * Searches for groups in this group using wildcards and attribute values.
     * Wildcards can be specified such as a*, *, *a.
     * 
     * @param wildcard
     *            wildcard pattern to be used in the search
     * @param avPairs
     *            attribute-value pairs to match when searching groups
     * @param level
     *            the search level that needs to be used (
     *            <code>AMConstants.SCOPE_ONE</code>
     *            or <code>AMConstants.SCOPE_TREE</code>)
     * @return Set of distinguished name of groups matching the search
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public Set searchGroups(String wildcard, Map avPairs, int level)
            throws AMException, SSOException;

    /**
     * Searches for groups in this group using wildcards and attribute values.
     * Wildcards can be specified such as a*, *, *a.
     * 
     * @param wildcard
     *            wildcard pattern to be used in the search
     * @param avPairs
     *            attribute-value pairs to match when searching groups
     * @param searchControl
     *            specifies the search scope to be used
     * @return <code>AMSearchResults</code> which contains a set of
     *         distinguished name of groups matching the search.
     * @throws AMException
     *             if an error is encountered when trying to access/retrieve
     *             data from the data store.
     * @throws SSOException
     *             if the single sign on token is no longer valid.
     */
    public AMSearchResults searchGroups(String wildcard, Map avPairs,
            AMSearchControl searchControl) throws AMException, SSOException;
}