/** * 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: AMGroupContainer.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; /** * This interface provides methods to manage group container. * AMGroupContainer objects can be obtained by using * AMStoreConnection. A handle to this object can be obtained by * using the DN of the object. * * 
 * 
 * AMStoreConnection amsc = new AMStoreConnection(ssotoken); if
 * (amsc.doesEntryExist(gcDN)) { AMGroupContainer dg =
 * amsc.getGroupContainer(gcDN); }
 * 
 *
* * @deprecated As of Sun Java System Access Manager 7.1. * @supported.all.api */ public interface AMGroupContainer extends AMObject { /** * Creates sub group containers in this group container. * * @param groupContainers * The set of group container names to be created in this group * container. * @return Set set of group container 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 createSubGroupContainers(Set groupContainers) throws AMException, SSOException; /** * Creates sub group containers and initializes their attributes. * * @param groupContainers * Map where the key is the name of the group container, and the * value is a Map to represent Attribute-Value Pairs . * @return Set of group container 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 createSubGroupContainers(Map groupContainers) throws AMException, SSOException; /** * Returns the sub containers in this group container. It returns sub * containers either at one level or a whole subtree. * * @param level * AMConstants.SCOPE_ONE or * AMConstants.SCOPE_SUB for returning sub * containers. * @return The sub container distinguished names in this group container. * @throws AMException * if an error is encountered when trying to access/retrieve * data from the data store or if level is invalid. * @throws SSOException * if the single sign on token is no longer valid. */ public Set getSubGroupContainerDNs(int level) throws AMException, SSOException; /** * Returns number of sub group containers in the group container. * * @return Number of sub group containers in the group container. * @throws AMException * if an error is encountered when trying to access/retrieve * data from the data store. * @throws SSOException * if the single sign token on is no longer valid. */ public long getNumberOfSubGroupContainers() throws AMException, SSOException; /** * Deletes sub group containers in this group container. * * @param groupContainers * set of container distinguished name to be deleted from the * group container. * @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 deleteSubGroupContainers(Set groupContainers) throws AMException, SSOException; /** * Searches for sub group containers in this group container using wildcards * and attribute values. Wildcards can be specified such as a*, *, *a. To * further refine the search, attribute-value pairs can be specified so that * distinguished name of group containers with matching attribute-value * pairs will be returned. * * @param wildcard * wildcard pattern to be used in the search. * @param avPairs * attribute-value pairs to match when searching group * Containers. * @param level * the search level that needs to be used * AMConstants.SCOPE_ONE or * AMConstants.SCOPE_SUB. * @return Set distinguished name of group containers 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 searchSubGroupContainers(String wildcard, Map avPairs, int level) throws AMException, SSOException; /** * Searches for group containers in this group container using wildcards and * attribute values. Wildcards can be specified such as a*, *, *a. To * further refine the search, attribute-value pairs can be specified so that * distinguished names of group containers with matching attribute-value * pairs will be returned. * * @param wildcard * wildcard pattern to be used in the search. * @param avPairs * attribute-value pairs to match when searching group * containers. * @param searchControl * specifies the search scope to be used, VLV ranges etc., * @return AMSearchResults object which contains the set * distinguished name of group containers 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 searchSubGroupContainers(String wildcard, Map avPairs, AMSearchControl searchControl) throws AMException, SSOException; /** * Creates static groups in this group container. * * @param groupNames * The set of static groups' names to be created in this group * container. * @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. * @throws AMException * if an error is encountered when trying to create entries in * the data store. */ 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. * @throws AMException * if an error is encountered when trying to create entries in * the data store. */ public Set createStaticGroups(Map groups) throws AMException, SSOException; /** * Creates static group. Takes serviceNameAndAttr map so that * services can be assigned to the group which is just created. * * @param name * of group to be created. * @param attributes * attributes to be set in group node. * @param serviceNameAndAttrs * map of service name to attribute map where the map is like * this: * * 
     * <serviceName><AttrMap>
     *       (attrMap=<attrName><Set of attrvalues>)
     *
* * @return the newly created group. * @throws AMException * if an error is encountered when trying to create entries in * the data store. * @throws SSOException * if the single sign on token is no longer valid. */ public AMGroup createStaticGroup(String name, Map attributes, Map serviceNameAndAttrs) throws AMException, SSOException; /** * Creates dynamic groups in this group container. * * @param groupNames * The set of dynamic groups' names to be created in this group * container. * @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 dynamic group's name to its 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 dynamic group. Takes serviceNameAndAttr map so * that services can be assigned to the group which is just created. * * @param name * of group to be created. * @param attributes * attributes to be set in group * @param serviceNameAndAttrs * map of service name and attribute maps where the map is like * this: * * 
     * <serviceName><AttrMap>
     *      (attrMap=<attrName><Set of attrvalues>)
     *
* * @return AMGroup object of newly created group. * @throws AMException * if an error is encountered when trying to create entries in * the data store. * @throws SSOException * if the single sign on token is no longer valid. */ public AMGroup createDynamicGroup(String name, Map attributes, Map serviceNameAndAttrs) throws AMException, SSOException; /** * Creates assignable dynamic groups in this group container. * * @param groupNames * The set of assignable dynamic groups' names to be created in * this group container. * @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 where the key is the name of the assignable dynamic group, * and the value is a Map to represent attribute-value pairs. * @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; /** * Creates assignable dynamic group. Takes serviceNameAndAttr * map so that services can be assigned to the group which is just created. * * @param name * of group to be created. * @param attributes * attribute-value pairs to be set. * @param serviceNameAndAttrs * map of service name to attribute map where the map is like * this: * * 
     * <serviceName><AttrMap>
     *      (attrMap=<attrName><Set of attrvalues>)
     *
* * @return AMGroup object of newly created group. * @throws AMException * if an error is encountered when trying to create entries in * the data store. * @throws SSOException * if the single sign on token is no longer valid. */ public AMGroup createAssignableDynamicGroup(String name, Map attributes, Map serviceNameAndAttrs) throws AMException, SSOException; /** * Gets the groups in this group container. It returns groups either at one * level or a whole subtree. * * @param level * the level (AMConstants.SCOPE_ONE or * AMConstants.SCOPE_SUB) for returning groups. * @return the group distinguished names in this group container. * @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 number of groups in the group container. It returns number of * groups either at one level or a whole subtree. * * @param level * the level (AMConstants.SCOPE_ONE or * AMConstants.SCOPE_SUB) for returning groups. * @return the number of groups in the group container. * @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 container. * * @param groupDNs * The set of static group distinguished name to be deleted from * this group container. * @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 container. * * @param groupDNs * The set of dynamic group distinguished names to be deleted * from this group container. * @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 container. * * @param groupDNs * The set of assignable dynamic group distinguished names to be * deleted from this group container. * @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 container using wildcards and attribute * values. Wildcards can be specified such as a*, *, *a. * * @param 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 * AMConstants.SCOPE_ON or * AMConstants.SCOPE_SUB. * @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 container using wildcards. Wildcards * can be specified such as a*, *, *a. Uses the * groupSearchTemplate, if provided. Otherwise the default * search templates for the types of groups are used. * * @param wildcard * pattern to be used in the search. * @param level * the search level that needs to be used * AMConstants.SCOPE_ONE or * AMConstants.SCOPE_SUB. * @param groupSearchTemplate * name of the search template to be used to perform this search. * @param avPairs * This option can be used to further qualify the search filter. * The attribute-value pairs provided by this map are appended to * the search filter. * @return Set of distinguished name of assignable dynamic 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, String groupSearchTemplate, Map avPairs) throws AMException, SSOException; /** * Searches for assignable dynamic groups in this group container using * wildcards and attribute values. Wildcards can be specified such as a*, *, * *a. To further refine the search, attribute-value pairs can be specified * so that distinguished name of dynamic groups with matching * attribute-value pairs will be returned. * * @param wildcard * pattern to be used in the search. * @param avPairs * attribute-value pairs to match when searching assignable * dynamic groups. * @param groupSearchTemplate * Name of search template to be used to perform the search. * @param searchControl * specifies the search scope to be used, VLV ranges etc. * @return AMSearchResults which contains a set of * distinguished name of assignable dynamic 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, String groupSearchTemplate, AMSearchControl searchControl) throws AMException, SSOException; /** * Searches for groups in this group container using wildcards and attribute * values. Wildcards can be specified such as a*, *, *a. * * @param 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 AMSearchResults which contains Set a 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; /** * Searches for static groups in this group container using wildcards and * attribute values. Wildcards can be specified such as a*, *, *a. * * @param 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 AMSearchResults which contains Set a 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 searchStaticGroups(String wildcard, Map avPairs, AMSearchControl searchControl) throws AMException, SSOException; }