Package com.google.gerrit.server.account.externalids

Class ExternalIdNotes

java.lang.Object

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

com.google.gerrit.server.account.externalids.ExternalIdNotes

public class ExternalIdNotes
extends VersionedMetaData

VersionedMetaData subclass to update external IDs.

This is a low-level API. Read/write of external IDs should be done through AccountsUpdate or AccountConfig.

On load the note map from refs/meta/external-ids is read, but the external IDs are not parsed yet (see onLoad()).

After loading the note map callers can access single or all external IDs. Only now the requested external IDs are parsed.

After loading the note map callers can stage various external ID updates (insert, upsert, delete, replace).

On save the staged external ID updates are performed (see onSave(CommitBuilder)).

After committing the external IDs a cache update can be requested which also reindexes the accounts for which external IDs have been updated (see updateCaches()).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ExternalIdNotes.ExternalIdNotesLoader
static class	ExternalIdNotes.Factory
static class	ExternalIdNotes.FactoryNoReindex

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

VersionedMetaData.BatchMetaDataUpdate, VersionedMetaData.PathInfo

Field Summary

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

inserter, newTree, projectName, reader, revision, rw

Method Summary

Modifier and Type	Method	Description
com.google.common.collect.ImmutableSet<ExternalId>	all()	Parses and returns all external IDs.
static Account.Id	checkSameAccount(Iterable<ExternalId> extIds, Account.Id accountId)	Checks that all specified external IDs belong to specified account.
org.eclipse.jgit.revwalk.RevCommit	commit(MetaDataUpdate update)	Update this metadata branch, recording a new commit on its reference.
void	delete(Account.Id accountId, ExternalId.Key extIdKey)	Delete an external ID by key.
void	delete(Account.Id accountId, Collection<ExternalId.Key> extIdKeys)	Delete external IDs by external ID key.
void	delete(ExternalId extId)	Deletes an external ID.
void	delete(Collection<ExternalId> extIds)	Deletes external IDs.
void	deleteByKeys(Collection<ExternalId.Key> extIdKeys)	Delete external IDs by external ID key.
Optional<ExternalId>	get(ExternalId.Key key)	Parses and returns the specified external ID.
Set<ExternalId>	get(Collection<ExternalId.Key> keys)	Parses and returns the specified external IDs.
protected String	getRefName()
org.eclipse.jgit.lib.Repository	getRepository()
void	insert(ExternalId extId)	Inserts a new external ID.
void	insert(Collection<ExternalId> extIds)	Inserts new external IDs.
static ExternalIdNotes	loadNoCacheUpdate(AllUsersName allUsersName, org.eclipse.jgit.lib.Repository allUsersRepo)	Loads the external ID notes for updates without cache evictions.
static ExternalIdNotes	loadReadOnly(AllUsersName allUsersName, org.eclipse.jgit.lib.Repository allUsersRepo)	Loads the external ID notes for reading only.
static ExternalIdNotes	loadReadOnly(AllUsersName allUsersName, org.eclipse.jgit.lib.Repository allUsersRepo, org.eclipse.jgit.lib.ObjectId rev)	Loads the external ID notes for reading only.
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	replace(Account.Id accountId, Collection<ExternalId.Key> toDelete, Collection<ExternalId> toAdd)	Replaces external IDs for an account by external ID keys.
void	replace(ExternalId toDelete, ExternalId toAdd)	Replaces an external ID.
void	replace(Collection<ExternalId> toDelete, Collection<ExternalId> toAdd)	Replaces external IDs.
void	replaceByKeys(Collection<ExternalId.Key> toDelete, Collection<ExternalId> toAdd)	Replaces external IDs for an account by external ID keys.
ExternalIdNotes	setAfterReadRevision(Runnable afterReadRevision)
void	updateCaches()	Updates the caches (external ID cache, account cache) and reindexes the accounts for which external IDs were modified.
void	updateCaches(Collection<Account.Id> accountsToSkip)	Updates the caches (external ID cache, account cache) and reindexes the accounts for which external IDs were modified.
void	upsert(ExternalId extId)	Inserts or updates an external ID.
void	upsert(Collection<ExternalId> extIds)	Inserts or updates external IDs.

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

commit, commitToNewRef, getObjectId, getPathInfos, getRevision, load, load, load, load, load, openUpdate, openUpdate, readConfig, 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

Method Detail

loadReadOnly

public static ExternalIdNotes loadReadOnly(AllUsersName allUsersName,
                                           org.eclipse.jgit.lib.Repository allUsersRepo)
                                    throws IOException,
                                           org.eclipse.jgit.errors.ConfigInvalidException

Loads the external ID notes for reading only. The external ID notes are loaded from the current tip of the refs/meta/external-ids branch.

Returns:

read-only ExternalIdNotes instance

Throws:

IOException

org.eclipse.jgit.errors.ConfigInvalidException

loadReadOnly

public static ExternalIdNotes loadReadOnly(AllUsersName allUsersName,
                                           org.eclipse.jgit.lib.Repository allUsersRepo,
                                           org.eclipse.jgit.lib.ObjectId rev)
                                    throws IOException,
                                           org.eclipse.jgit.errors.ConfigInvalidException

Loads the external ID notes for reading only. The external ID notes are loaded from the specified revision of the refs/meta/external-ids branch.

Parameters:

rev - the revision from which the external ID notes should be loaded, if null the external ID notes are loaded from the current tip, if ObjectId.zeroId() it's assumed that the refs/meta/external-ids branch doesn't exist and the loaded external IDs will be empty

Returns:

read-only ExternalIdNotes instance

Throws:

IOException

org.eclipse.jgit.errors.ConfigInvalidException

loadNoCacheUpdate

public static ExternalIdNotes loadNoCacheUpdate(AllUsersName allUsersName,
                                                org.eclipse.jgit.lib.Repository allUsersRepo)
                                         throws IOException,
                                                org.eclipse.jgit.errors.ConfigInvalidException

Loads the external ID notes for updates without cache evictions. The external ID notes are loaded from the current tip of the refs/meta/external-ids branch.

Use this only from init, schema upgrades and tests.

Metrics are disabled.

Returns:

ExternalIdNotes instance that doesn't updates caches on save

Throws:

IOException

org.eclipse.jgit.errors.ConfigInvalidException

setAfterReadRevision

public ExternalIdNotes setAfterReadRevision(Runnable afterReadRevision)

getRepository

public org.eclipse.jgit.lib.Repository getRepository()

getRefName

protected String getRefName()

Specified by:

getRefName in class VersionedMetaData

Returns:

name of the reference storing this configuration.

get

public Optional<ExternalId> get(ExternalId.Key key)
                         throws IOException,
                                org.eclipse.jgit.errors.ConfigInvalidException

Parses and returns the specified external ID.

Parameters:

key - the key of the external ID

Returns:

the external ID, Optional.empty() if it doesn't exist

Throws:

IOException

org.eclipse.jgit.errors.ConfigInvalidException

get

public Set<ExternalId> get(Collection<ExternalId.Key> keys)
                    throws IOException,
                           org.eclipse.jgit.errors.ConfigInvalidException

Parses and returns the specified external IDs.

Parameters:

keys - the keys of the external IDs

Returns:

the external IDs

Throws:

IOException

org.eclipse.jgit.errors.ConfigInvalidException

all

public com.google.common.collect.ImmutableSet<ExternalId> all()
                                                       throws IOException

Parses and returns all external IDs.

Invalid external IDs are ignored.

Returns:

all external IDs

Throws:

IOException

insert

public void insert(ExternalId extId)
            throws IOException,
                   DuplicateExternalIdKeyException

Inserts a new external ID.

Throws:

IOException - on IO error while checking if external ID already exists

DuplicateExternalIdKeyException - if the external ID already exists

insert

public void insert(Collection<ExternalId> extIds)
            throws IOException,
                   DuplicateExternalIdKeyException

Inserts new external IDs.

Throws:

IOException - on IO error while checking if external IDs already exist

DuplicateExternalIdKeyException - if any of the external ID already exists

upsert

public void upsert(ExternalId extId)
            throws IOException,
                   org.eclipse.jgit.errors.ConfigInvalidException

Inserts or updates an external ID.

If the external ID already exists, it is overwritten, otherwise it is inserted.

Throws:

IOException

org.eclipse.jgit.errors.ConfigInvalidException

upsert

public void upsert(Collection<ExternalId> extIds)
            throws IOException,
                   org.eclipse.jgit.errors.ConfigInvalidException

Inserts or updates external IDs.

If any of the external IDs already exists, it is overwritten. New external IDs are inserted.

Throws:

IOException

org.eclipse.jgit.errors.ConfigInvalidException

delete

public void delete(ExternalId extId)

Deletes an external ID.

Throws:

IllegalStateException - is thrown if there is an existing external ID that has the same key, but otherwise doesn't match the specified external ID.

delete

public void delete(Collection<ExternalId> extIds)

Deletes external IDs.

Throws:

IllegalStateException - is thrown if there is an existing external ID that has the same key as any of the external IDs that should be deleted, but otherwise doesn't match the that external ID.

delete

public void delete(Account.Id accountId,
                   ExternalId.Key extIdKey)

Delete an external ID by key.

Throws:

IllegalStateException - is thrown if the external ID does not belong to the specified account.

delete

public void delete(Account.Id accountId,
                   Collection<ExternalId.Key> extIdKeys)

Delete external IDs by external ID key.

Throws:

IllegalStateException - is thrown if any of the external IDs does not belong to the specified account.

deleteByKeys

public void deleteByKeys(Collection<ExternalId.Key> extIdKeys)

Delete external IDs by external ID key.

The external IDs are deleted regardless of which account they belong to.

replace

public void replace(Account.Id accountId,
                    Collection<ExternalId.Key> toDelete,
                    Collection<ExternalId> toAdd)
             throws IOException,
                    DuplicateExternalIdKeyException

Replaces external IDs for an account by external ID keys.

Deletion of external IDs is done before adding the new external IDs. This means if an external ID key is specified for deletion and an external ID with the same key is specified to be added, the old external ID with that key is deleted first and then the new external ID is added (so the external ID for that key is replaced).

Throws:

IllegalStateException - is thrown if any of the specified external IDs does not belong to the specified account.

IOException

DuplicateExternalIdKeyException

replaceByKeys

public void replaceByKeys(Collection<ExternalId.Key> toDelete,
                          Collection<ExternalId> toAdd)
                   throws IOException,
                          DuplicateExternalIdKeyException

Replaces external IDs for an account by external ID keys.

Deletion of external IDs is done before adding the new external IDs. This means if an external ID key is specified for deletion and an external ID with the same key is specified to be added, the old external ID with that key is deleted first and then the new external ID is added (so the external ID for that key is replaced).

The external IDs are replaced regardless of which account they belong to.

Throws:

IOException

DuplicateExternalIdKeyException

replace

public void replace(ExternalId toDelete,
                    ExternalId toAdd)
             throws IOException,
                    DuplicateExternalIdKeyException

Replaces an external ID.

Throws:

IllegalStateException - is thrown if the specified external IDs belong to different accounts.

IOException

DuplicateExternalIdKeyException

replace

public void replace(Collection<ExternalId> toDelete,
                    Collection<ExternalId> toAdd)
             throws IOException,
                    DuplicateExternalIdKeyException

Replaces external IDs.

Deletion of external IDs is done before adding the new external IDs. This means if an external ID is specified for deletion and an external ID with the same key is specified to be added, the old external ID with that key is deleted first and then the new external ID is added (so the external ID for that key is replaced).

Throws:

IllegalStateException - is thrown if the specified external IDs belong to different accounts.

IOException

DuplicateExternalIdKeyException

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

updateCaches

public void updateCaches()
                  throws IOException

Updates the caches (external ID cache, account cache) and reindexes the accounts for which external IDs were modified.

Must only be called after committing changes.

No-op if this instance was created by loadNoCacheUpdate(AllUsersName, Repository).

No eviction from account cache and no reindex if this instance was created by ExternalIdNotes.FactoryNoReindex.

Throws:

IOException

updateCaches

public void updateCaches(Collection<Account.Id> accountsToSkip)
                  throws IOException

Updates the caches (external ID cache, account cache) and reindexes the accounts for which external IDs were modified.

Must only be called after committing changes.

No-op if this instance was created by loadNoCacheUpdate(AllUsersName, Repository).

No eviction from account cache if this instance was created by ExternalIdNotes.FactoryNoReindex.

Parameters:

accountsToSkip - set of accounts that should not be evicted from the account cache, in this case the caller must take care to evict them otherwise

Throws:

IOException

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

checkSameAccount

public static Account.Id checkSameAccount(Iterable<ExternalId> extIds,
                                          Account.Id accountId)

Checks that all specified external IDs belong to specified account. If no account is specified it is checked that all specified external IDs belong to the same account.

Returns:

the ID of the account to which all specified external IDs belong.