Package com.google.gerrit.server.group.db

Class GroupConfig

  • public class GroupConfig
extends VersionedMetaData
    A representation of a group in NoteDb.

    Groups in NoteDb can be created by following the descriptions of createForNewGroup(Project.NameKey, Repository, InternalGroupCreation). For reading groups from NoteDb or updating them, refer to loadForGroup(Project.NameKey, Repository, AccountGroup.UUID) or loadForGroupSnapshot(Project.NameKey, Repository, AccountGroup.UUID, ObjectId).

    Note: Any modification (group creation or update) only becomes permanent (and hence written to NoteDb) if commit(MetaDataUpdate) is called.

    Warning: This class is a low-level API for groups in NoteDb. Most code which deals with internal Gerrit groups should use Groups or GroupsUpdate instead.

    Internal details

    Each group is represented by a commit on a branch as defined by RefNames.refsGroups(AccountGroup.UUID). Previous versions of the group exist as older commits on the same branch and can be reached by following along the parent references. New commits for updates are only created if a real modification occurs.

    The commit messages of all commits on that branch form the audit log for the group. The messages mention any important modifications which happened for the group to avoid costly computations.

    Within each commit, the properties of a group are spread across three files:

    • group.config, which holds all basic properties of a group (further specified by GroupConfigEntry), formatted as a JGit Config file
    • members, which lists all members (accounts) of a group, formatted as one numeric ID per line
    • subgroups, which lists all subgroups of a group, formatted as one UUID per line

    The files members and subgroups need not exist, which means that the group doesn't have any members or subgroups.

    • Method Detail

      • createForNewGroup

        public static GroupConfig createForNewGroup​(Project.NameKey projectName,
                                            org.eclipse.jgit.lib.Repository repository,
                                            InternalGroupCreation groupCreation)
                                     throws IOException,
                                            org.eclipse.jgit.errors.ConfigInvalidException,
                                            com.google.gerrit.exceptions.DuplicateKeyException
        Creates a GroupConfig for a new group from the InternalGroupCreation blueprint. Further, optional properties can be specified by setting an InternalGroupUpdate via setGroupUpdate(InternalGroupUpdate, AuditLogFormatter) on the returned GroupConfig.

        Note: The returned GroupConfig has to be committed via commit(MetaDataUpdate) in order to create the group for real.

        Parameters:
        projectName - the name of the project which holds the NoteDb commits for groups
        repository - the repository which holds the NoteDb commits for groups
        groupCreation - an InternalGroupCreation specifying all properties which are required for a new group
        Returns:
        a GroupConfig for a group creation
        Throws:
        IOException - if the repository can't be accessed for some reason
        org.eclipse.jgit.errors.ConfigInvalidException - if a group with the same UUID already exists but can't be read due to an invalid format
        com.google.gerrit.exceptions.DuplicateKeyException - if a group with the same UUID already exists

      • loadForGroup

        public static GroupConfig loadForGroup​(Project.NameKey projectName,
                                       org.eclipse.jgit.lib.Repository repository,
                                       AccountGroup.UUID groupUuid)
                                throws IOException,
                                       org.eclipse.jgit.errors.ConfigInvalidException
        Creates a GroupConfig for an existing group.

        The group is automatically loaded within this method and can be accessed via getLoadedGroup().

        It's safe to call this method for non-existing groups. In that case, getLoadedGroup() won't return any group. Thus, the existence of a group can be easily tested.

        The group represented by the returned GroupConfig can be updated by setting an InternalGroupUpdate via setGroupUpdate(InternalGroupUpdate, AuditLogFormatter) and committing the GroupConfig via commit(MetaDataUpdate).

        Parameters:
        projectName - the name of the project which holds the NoteDb commits for groups
        repository - the repository which holds the NoteDb commits for groups
        groupUuid - the UUID of the group
        Returns:
        a GroupConfig for the group with the specified UUID
        Throws:
        IOException - if the repository can't be accessed for some reason
        org.eclipse.jgit.errors.ConfigInvalidException - if the group exists but can't be read due to an invalid format

      • loadForGroupSnapshot

        public static GroupConfig loadForGroupSnapshot​(Project.NameKey projectName,
                                               org.eclipse.jgit.lib.Repository repository,
                                               AccountGroup.UUID groupUuid,
                                               org.eclipse.jgit.lib.ObjectId commitId)
                                        throws IOException,
                                               org.eclipse.jgit.errors.ConfigInvalidException
        Creates a GroupConfig for an existing group at a specific revision of the repository.

        This method behaves nearly the same as loadForGroup(Project.NameKey, Repository, AccountGroup.UUID). The only difference is that loadForGroup(Project.NameKey, Repository, AccountGroup.UUID) loads the group from the current state of the repository whereas this method loads the group at a specific (maybe past) revision.

        Parameters:
        projectName - the name of the project which holds the NoteDb commits for groups
        repository - the repository which holds the NoteDb commits for groups
        groupUuid - the UUID of the group
        commitId - the revision of the repository at which the group should be loaded
        Returns:
        a GroupConfig for the group with the specified UUID
        Throws:
        IOException - if the repository can't be accessed for some reason
        org.eclipse.jgit.errors.ConfigInvalidException - if the group exists but can't be read due to an invalid format

      • getLoadedGroup

        public Optional<InternalGroup> getLoadedGroup()
        Returns the group loaded from NoteDb.

        If not any NoteDb commits exist for the group represented by this GroupConfig, no group is returned.

        After commit(MetaDataUpdate) was called on this GroupConfig, this method returns a group which is in line with the latest NoteDb commit for this group. So, after creating a GroupConfig for a new group and committing it, this method can be used to retrieve a representation of the created group. The same holds for the representation of an updated group.

        Returns:
        the loaded group, or an empty Optional if the group doesn't exist

      • setGroupUpdate

        public void setGroupUpdate​(InternalGroupUpdate groupUpdate,
                           AuditLogFormatter auditLogFormatter)
        Specifies how the current group should be updated.

        If the group is newly created, the InternalGroupUpdate can be used to specify optional properties.

        Note: This method doesn't perform the update. It only contains the instructions for the update. To apply the update for real and write the result back to NoteDb, call commit(MetaDataUpdate) on this GroupConfig.

        Parameters:
        groupUpdate - an InternalGroupUpdate outlining the modifications which should be applied
        auditLogFormatter - an AuditLogFormatter for formatting the commit message in a parsable way

      • setAllowSaveEmptyName

        public void setAllowSaveEmptyName()
        Allows the new name of a group to be empty during creation or update.

        Note: This method exists only to support the migration of legacy groups which don't always necessarily have a name. Nowadays, we enforce that groups always have names. When we remove the migration code, we can probably remove this method as well.

      • onLoad

        protected void onLoad()
               throws IOException,
                      org.eclipse.jgit.errors.ConfigInvalidException
        Description copied from class: VersionedMetaData
        Set up the metadata, parsing any state from the loaded revision.
        Specified by:
        onLoad in class VersionedMetaData
        Throws:
        IOException
        org.eclipse.jgit.errors.ConfigInvalidException

      • commit

        public org.eclipse.jgit.revwalk.RevCommit commit​(MetaDataUpdate update)
                                          throws IOException
        Description copied from class: VersionedMetaData
        Update this metadata branch, recording a new commit on its reference. This method mutates its receiver.
        Overrides:
        commit in class VersionedMetaData
        Parameters:
        update - helper information to define the update that will occur.
        Returns:
        the commit that was created
        Throws:
        IOException - if there is a storage problem and the update cannot be executed as requested or if it failed because of a concurrent update to the same reference

      • onSave

        protected boolean onSave​(org.eclipse.jgit.lib.CommitBuilder commit)
                  throws IOException,
                         org.eclipse.jgit.errors.ConfigInvalidException
        Description copied from class: VersionedMetaData
        Save any changes to the metadata in a commit.
        Specified by:
        onSave in class VersionedMetaData
        Returns:
        true if the commit should proceed, false to abort.
        Throws:
        IOException
        org.eclipse.jgit.errors.ConfigInvalidException