com.google.gerrit.server.group.db

Class GroupConfig

java.lang.Object

com.google.gerrit.server.git.meta.VersionedMetaData

com.google.gerrit.server.group.db.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.

Nested Class Summary

Nested classes/interfaces inherited from class com.google.gerrit.server.git.meta.VersionedMetaData

VersionedMetaData.BatchMetaDataUpdate, VersionedMetaData.PathInfo

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	GROUP_CONFIG_FILE

Fields inherited from class com.google.gerrit.server.git.meta.VersionedMetaData

inserter, newTree, projectName, reader, revision, rw

Method Summary

Modifier and Type	Method and Description
org.eclipse.jgit.revwalk.RevCommit	commit(MetaDataUpdate update) Update this metadata branch, recording a new commit on its reference.
static GroupConfig	createForNewGroup(Project.NameKey projectName, org.eclipse.jgit.lib.Repository repository, InternalGroupCreation groupCreation) Creates a GroupConfig for a new group from the InternalGroupCreation blueprint.
java.util.Optional<InternalGroup>	getLoadedGroup() Returns the group loaded from NoteDb.
java.lang.String	getRefName()
static GroupConfig	loadForGroup(Project.NameKey projectName, org.eclipse.jgit.lib.Repository repository, AccountGroup.UUID groupUuid) Creates a GroupConfig for an existing group.
static GroupConfig	loadForGroupSnapshot(Project.NameKey projectName, org.eclipse.jgit.lib.Repository repository, AccountGroup.UUID groupUuid, org.eclipse.jgit.lib.ObjectId commitId) Creates a GroupConfig for an existing group at a specific revision of the repository.
protected void	onLoad() Set up the metadata, parsing any state from the loaded revision.
protected boolean	onSave(org.eclipse.jgit.lib.CommitBuilder commit) Save any changes to the metadata in a commit.
void	setAllowSaveEmptyName() Allows the new name of a group to be empty during creation or update.
void	setGroupUpdate(InternalGroupUpdate groupUpdate, AuditLogFormatter auditLogFormatter) Specifies how the current group should be updated.

Methods inherited from class com.google.gerrit.server.git.meta.VersionedMetaData

commit, commitToNewRef, getObjectId, getPathInfos, getRevision, load, load, load, load, load, openUpdate, openUpdate, readConfig, readFile, readTree, readUTF8, saveConfig, saveFile, saveUTF8, set, set, set

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GROUP_CONFIG_FILE

public static final java.lang.String GROUP_CONFIG_FILE

See Also:

Constant Field Values

Method Detail

createForNewGroup

public static GroupConfig createForNewGroup(Project.NameKey projectName,
                                            org.eclipse.jgit.lib.Repository repository,
                                            InternalGroupCreation groupCreation)
                                     throws java.io.IOException,
                                            org.eclipse.jgit.errors.ConfigInvalidException,
                                            com.google.gwtorm.server.OrmDuplicateKeyException

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:

java.io.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.gwtorm.server.OrmDuplicateKeyException - 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 java.io.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:

java.io.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 java.io.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:

java.io.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 java.util.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.

getRefName

public java.lang.String getRefName()

Specified by:

getRefName in class VersionedMetaData

Returns:

name of the reference storing this configuration.

onLoad

protected void onLoad()
               throws java.io.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:

java.io.IOException

org.eclipse.jgit.errors.ConfigInvalidException

commit

public org.eclipse.jgit.revwalk.RevCommit commit(MetaDataUpdate update)
                                          throws java.io.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:

java.io.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 java.io.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:

java.io.IOException

org.eclipse.jgit.errors.ConfigInvalidException