Package org.opends.server.api

Class Group<T extends GroupImplementationCfg>

  • Type Parameters:
    T - The type of configuration handled by this group implementation.
    Direct Known Subclasses:
    DynamicGroup, StaticGroup, VirtualStaticGroup
    @PublicAPI(stability=VOLATILE,
           mayInstantiate=false,
           mayExtend=true,
           mayInvoke=true)
public abstract class Group<T extends GroupImplementationCfg>
extends Object
    This class defines the set of methods that must be implemented by a Directory Server group. It is expected that there will be a number of different types of groups (e.g., legacy static and dynamic groups, as well as enhanced groups and virtual static groups). The following operations may be performed on an OpenDS group:
    • Determining whether a given user is a member of this group
    • Determining the set of members for this group, optionally filtered based on some set of criteria.
    • Retrieving or updating the set of nested groups for this group, if the underlying group type supports nesting).
    • Updating the set of members for this group, if the underlying group type provides the ability to explicitly add or remove members.

    • Constructor Summary

      Constructors 
      Constructor Description
      Group()  

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract void addMember​(Entry userEntry)
      Attempts to add the provided user as a member of this group.
      abstract void addNestedGroup​(DN nestedGroupDN)
      Attempts to add the provided group DN as a nested group within this group.
      void finalizeGroupImplementation()
      Performs any necessary finalization that may be needed whenever this group implementation is taken out of service within the Directory Server (e.g., if it is disabled or the server is shutting down).
      abstract SearchFilter getGroupDefinitionFilter()
      Retrieves a search filter that may be used to identify entries containing definitions for groups of this type in the Directory Server.
      abstract DN getGroupDN()
      Retrieves the DN of the entry that contains the definition for this group.
      MemberList getMembers()
      Retrieves an iterator that may be used to cursor through the entries of the members contained in this group.
      abstract MemberList getMembers​(DN baseDN, SearchScope scope, SearchFilter filter)
      Retrieves an iterator that may be used to cursor through the entries of the members contained in this group.
      abstract List<DN> getNestedGroupDNs()
      Retrieves a list of the DNs of any nested groups whose members should be considered members of this group.
      abstract void initializeGroupImplementation​(T configuration)
      Initializes a "shell" instance of this group implementation that may be used to identify and instantiate instances of this type of group in the directory data.
      boolean isConfigurationAcceptable​(GroupImplementationCfg configuration, List<org.forgerock.i18n.LocalizableMessage> unacceptableReasons)
      Indicates whether the provided configuration is acceptable for this group implementation.
      abstract boolean isGroupDefinition​(Entry entry)
      Indicates whether the provided entry contains a valid definition for this type of group.
      boolean isMember​(DN userDN)
      Indicates whether the user with the specified DN is a member of this group.
      abstract boolean isMember​(DN userDN, AtomicReference<Set<DN>> examinedGroups)
      Indicates whether the user with the specified DN is a member of this group.
      boolean isMember​(Entry userEntry)
      Indicates whether the user described by the provided user entry is a member of this group.
      abstract boolean isMember​(Entry userEntry, AtomicReference<Set<DN>> examinedGroups)
      Indicates whether the user described by the provided user entry is a member of this group.
      abstract boolean mayAlterMemberList()
      Indicates whether it is possible to alter the member list for this group (e.g., in order to add members to the group or remove members from it).
      abstract Group<T> newInstance​(ServerContext serverContext, Entry groupEntry)
      Creates a new group of this type based on the definition contained in the provided entry.
      abstract void removeMember​(DN userDN)
      Attempts to remove the specified user as a member of this group.
      abstract void removeNestedGroup​(DN nestedGroupDN)
      Attempts to remove the provided group as a nested group within this group.
      abstract void setGroupDN​(DN groupDN)
      Sets the DN of the entry that contains the definition for this group.
      abstract boolean supportsNestedGroups()
      Indicates whether this group supports nesting other groups, such that the members of the nested groups will also be considered members of this group.
      String toString()
      Retrieves a string representation of this group.
      abstract void toString​(StringBuilder buffer)
      Appends a string representation of this group to the provided buffer.
      abstract void updateMembers​(List<Modification> modifications)
      Attempt to make multiple changes to the group's member list.

    • Constructor Detail

      • Group

        public Group()

    • Method Detail

      • initializeGroupImplementation

        public abstract void initializeGroupImplementation​(T configuration)
                                            throws ConfigException,
                                                   InitializationException
        Initializes a "shell" instance of this group implementation that may be used to identify and instantiate instances of this type of group in the directory data.
        Parameters:
        configuration - The configuration for this group implementation.
        Throws:
        ConfigException - If there is a problem with the provided configuration entry.
        InitializationException - If a problem occurs while attempting to initialize this group implementation that is not related to the server configuration.

      • isConfigurationAcceptable

        public boolean isConfigurationAcceptable​(GroupImplementationCfg configuration,
                                         List<org.forgerock.i18n.LocalizableMessage> unacceptableReasons)
        Indicates whether the provided configuration is acceptable for this group implementation. It should be possible to call this method on an uninitialized group implementation instance in order to determine whether the group implementation would be able to use the provided configuration.

        Note that implementations which use a subclass of the provided configuration class will likely need to cast the configuration to the appropriate subclass type.
        Parameters:
        configuration - The group implementation configuration for which to make the determination.
        unacceptableReasons - A list that may be used to hold the reasons that the provided configuration is not acceptable.
        Returns:
        true if the provided configuration is acceptable for this group implementation, or false if not.

      • finalizeGroupImplementation

        public void finalizeGroupImplementation()
        Performs any necessary finalization that may be needed whenever this group implementation is taken out of service within the Directory Server (e.g., if it is disabled or the server is shutting down).

      • newInstance

        public abstract Group<T> newInstance​(ServerContext serverContext,
                                     Entry groupEntry)
                              throws DirectoryException
        Creates a new group of this type based on the definition contained in the provided entry. This method must be designed so that it may be invoked on the "shell" instance created using the default constructor and initialized with the initializeGroupImplementation method.
        Parameters:
        serverContext - The server context.
        groupEntry - The entry containing the definition for the group to be created.
        Returns:
        The group instance created from the definition in the provided entry.
        Throws:
        DirectoryException - If a problem occurs while trying to create the group instance.

      • getGroupDefinitionFilter

        public abstract SearchFilter getGroupDefinitionFilter()
                                               throws DirectoryException
        Retrieves a search filter that may be used to identify entries containing definitions for groups of this type in the Directory Server. This method must be designed so that it may be invoked on the "shell" instance created using the default constructor and initialized with the initializeGroupImplementation method.
        Returns:
        A search filter that may be used to identify entries containing definitions for groups of this type in the Directory Server.
        Throws:
        DirectoryException - If a problem occurs while trying to locate all of the applicable group definition entries.

      • isGroupDefinition

        public abstract boolean isGroupDefinition​(Entry entry)
        Indicates whether the provided entry contains a valid definition for this type of group.
        Parameters:
        entry - The entry for which to make the determination.
        Returns:
        true if the provided entry does contain a valid definition for this type of group, or false if it does not.

      • getGroupDN

        public abstract DN getGroupDN()
        Retrieves the DN of the entry that contains the definition for this group.
        Returns:
        The DN of the entry that contains the definition for this group.

      • setGroupDN

        public abstract void setGroupDN​(DN groupDN)
        Sets the DN of the entry that contains the definition for this group.
        Parameters:
        groupDN - The DN of the entry that contains the definition for this group.

      • supportsNestedGroups

        public abstract boolean supportsNestedGroups()
        Indicates whether this group supports nesting other groups, such that the members of the nested groups will also be considered members of this group.
        Returns:
        true if this group supports nesting other groups, or false if it does not.

      • getNestedGroupDNs

        public abstract List<DN> getNestedGroupDNs()
        Retrieves a list of the DNs of any nested groups whose members should be considered members of this group.
        Returns:
        A list of the DNs of any nested groups whose members should be considered members of this group.

      • addNestedGroup

        public abstract void addNestedGroup​(DN nestedGroupDN)
                             throws UnsupportedOperationException,
                                    DirectoryException
        Attempts to add the provided group DN as a nested group within this group. The change should be committed to persistent storage through an internal operation.
        Parameters:
        nestedGroupDN - The DN of the group that should be added to the set of nested groups for this group.
        Throws:
        UnsupportedOperationException - If this group does not support nesting.
        DirectoryException - If a problem occurs while attempting to nest the provided group DN.

      • removeNestedGroup

        public abstract void removeNestedGroup​(DN nestedGroupDN)
                                throws UnsupportedOperationException,
                                       DirectoryException
        Attempts to remove the provided group as a nested group within this group. The change should be committed to persistent storage through an internal operation.
        Parameters:
        nestedGroupDN - The DN of the group that should be removed from the set of nested groups for this group.
        Throws:
        UnsupportedOperationException - If this group does not support nesting.
        DirectoryException - If a problem occurs while attempting to nest the provided group DN.

      • isMember

        public boolean isMember​(DN userDN)
                 throws DirectoryException
        Indicates whether the user with the specified DN is a member of this group. Note that this is a point-in-time determination and the caller must not cache the result.
        Parameters:
        userDN - The DN of the user for which to make the determination.
        Returns:
        true if the specified user is currently a member of this group, or false if not.
        Throws:
        DirectoryException - If a problem occurs while attempting to make the determination.

      • isMember

        public abstract boolean isMember​(DN userDN,
                                 AtomicReference<Set<DN>> examinedGroups)
                          throws DirectoryException
        Indicates whether the user with the specified DN is a member of this group. Note that this is a point-in-time determination and the caller must not cache the result. Also note that group implementations that support nesting should use this version of the method rather than the version that does not take a set of DNs when attempting to determine whether a nested group includes the target member.
        Parameters:
        userDN - The DN of the user for which to make the determination.
        examinedGroups - A set of groups that have already been examined in the process of making the determination. This provides a mechanism to prevent infinite recursion due to circular references (e.g., two groups include each other as nested groups). Each time a group instance is checked, its DN should be added to the list, and any DN already contained in the list should be skipped. The use of an atomic reference allow to lazily create the Set to optimize memory when there is no nested groups.
        Returns:
        true if the specified user is currently a member of this group, or false if not.
        Throws:
        DirectoryException - If a problem occurs while attempting to make the determination.

      • isMember

        public boolean isMember​(Entry userEntry)
                 throws DirectoryException
        Indicates whether the user described by the provided user entry is a member of this group. Note that this is a point-in-time determination and the caller must not cache the result.
        Parameters:
        userEntry - The entry for the user for which to make the determination.
        Returns:
        true if the specified user is currently a member of this group, or false if not.
        Throws:
        DirectoryException - If a problem occurs while attempting to make the determination.

      • isMember

        public abstract boolean isMember​(Entry userEntry,
                                 AtomicReference<Set<DN>> examinedGroups)
                          throws DirectoryException
        Indicates whether the user described by the provided user entry is a member of this group. Note that this is a point-in-time determination and the caller must not cache the result. Also note that group implementations that support nesting should use this version of the method rather than the version that does not take a set of DNs when attempting to determine whether a nested group includes the target member.
        Parameters:
        userEntry - The entry for the user for which to make the determination.
        examinedGroups - A set of groups that have already been examined in the process of making the determination. This provides a mechanism to prevent infinite recursion due to circular references (e.g., two groups include each other as nested groups). Each time a group instance is checked, its DN should be added to the list, and any DN already contained in the list should be skipped. The use of an atomic reference allow to lazily create the Set to optimize memory when there is no nested groups.
        Returns:
        true if the specified user is currently a member of this group, or false if not.
        Throws:
        DirectoryException - If a problem occurs while attempting to make the determination.

      • getMembers

        public MemberList getMembers()
                      throws DirectoryException
        Retrieves an iterator that may be used to cursor through the entries of the members contained in this group. Note that this is a point-in-time determination, and the caller must not cache the result. Further, the determination should only include this group and not members from nested groups.
        Returns:
        An iterator that may be used to cursor through the entries of the members contained in this group.
        Throws:
        DirectoryException - If a problem occurs while attempting to retrieve the set of members.

      • getMembers

        public abstract MemberList getMembers​(DN baseDN,
                                      SearchScope scope,
                                      SearchFilter filter)
                               throws DirectoryException
        Retrieves an iterator that may be used to cursor through the entries of the members contained in this group. It may optionally retrieve a subset of the member entries based on a given set of criteria. Note that this is a point-in-time determination, and the caller must not cache the result.
        Parameters:
        baseDN - The base DN that should be used when determining whether a given entry will be returned. If this is null, then all entries will be considered in the scope of the criteria.
        scope - The scope that should be used when determining whether a given entry will be returned. It must not be null if the provided base DN is not null. The scope will be ignored if no base DN is provided.
        filter - The filter that should be used when determining whether a given entry will be returned. If this is null, then any entry in the scope of the criteria will be included in the results.
        Returns:
        An iterator that may be used to cursor through the entries of the members contained in this group.
        Throws:
        DirectoryException - If a problem occurs while attempting to retrieve the set of members.

      • mayAlterMemberList

        public abstract boolean mayAlterMemberList()
        Indicates whether it is possible to alter the member list for this group (e.g., in order to add members to the group or remove members from it).
        Returns:
        true if it is possible to add members to this group, or false if not.

      • addMember

        public abstract void addMember​(Entry userEntry)
                        throws UnsupportedOperationException,
                               DirectoryException
        Attempts to add the provided user as a member of this group. The change should be committed to persistent storage through an internal operation.
        Parameters:
        userEntry - The entry for the user to be added as a member of this group.
        Throws:
        UnsupportedOperationException - If this group does not support altering the member list.
        DirectoryException - If a problem occurs while attempting to add the provided user as a member of this group.

      • removeMember

        public abstract void removeMember​(DN userDN)
                           throws UnsupportedOperationException,
                                  DirectoryException
        Attempts to remove the specified user as a member of this group. The change should be committed to persistent storage through an internal operation.
        Parameters:
        userDN - The DN of the user to remove as a member of this group.
        Throws:
        UnsupportedOperationException - If this group does not support altering the member list.
        DirectoryException - If a problem occurs while attempting to remove the provided user as a member of this group.

      • toString

        public String toString()
        Retrieves a string representation of this group.
        Overrides:
        toString in class Object
        Returns:
        A string representation of this group.

      • toString

        public abstract void toString​(StringBuilder buffer)
        Appends a string representation of this group to the provided buffer.
        Parameters:
        buffer - The buffer to which the string representation should be appended.