public interface

RepositoryHookService

com.atlassian.bitbucket.hook.repository.RepositoryHookService

Class Overview

Handles the aggregation of hooks and their enabled status. Settings for these hooks are handled elsewhere.

Summary

Public Methods
@Nonnull SettingsBuilder createSettingsBuilder()
Create a new SettingsBuilder which can be used to create a Settings instance.
void delete(DeleteRepositoryHookRequest request)
Delete the hook configuration specified in the request.
@Nonnull RepositoryHook disable(DisableRepositoryHookRequest request)
Disable the hook specified in the request.
@Deprecated @Nonnull RepositoryHook disable(Repository repository, String hookKey)
This method is deprecated. in 5.2 for removal in 6.0. Use disable(DisableRepositoryHookRequest) instead.
@Deprecated @Nonnull RepositoryHook enable(Repository repository, String hookKey, Settings settings)
This method is deprecated. in 5.2 for removal in 6.0. Use enable(EnableRepositoryHookRequest) instead.
@Nonnull RepositoryHook enable(EnableRepositoryHookRequest request)
Enable and apply settings for the hook specified in the request.
@Deprecated @Nonnull RepositoryHook enable(Repository repository, String hookKey)
This method is deprecated. in 5.2 for removal in 6.0. Use enable(EnableRepositoryHookRequest) instead.
@Nonnull @Deprecated Page<RepositoryHook> findAll(Repository repository, PageRequest pageRequest)
This method is deprecated. in 5.2 for removal in 6.0. Use search(RepositoryHookSearchRequest, PageRequest) instead.
@Nonnull @Deprecated Page<RepositoryHook> findByType(Repository repository, RepositoryHookType type, PageRequest pageRequest)
This method is deprecated. in 5.2 for removal in 6.0. Use search(RepositoryHookSearchRequest, PageRequest) instead.
@Nonnull CacheableAvatarSupplier getAvatar(String hookKey)
Returns a supplier of an avatar for this hook, either one specified in the module or a default.
@Nullable @Deprecated RepositoryHook getByKey(Repository repository, String hookKey)
This method is deprecated. in 5.2 for removal in 6.0. Use getByKey(Scope, String) instead.
@Nullable RepositoryHook getByKey(Scope scope, String hookKey)
Find an effective installed hook with the specified key enabled status for this scope.
@Nullable RepositoryHookSettings getSettings(GetRepositoryHookSettingsRequest request)
Gets the effective settings for the hook specified in the request.
@Deprecated @Nullable Settings getSettings(Repository repository, String hookKey)
This method is deprecated. in 5.2 for removal in 6.0. Use getSettings(GetRepositoryHookSettingsRequest) instead.
int migrateSettings(String oldHookKey, String newHookKey)
Migrates settings between the specified hook keys.
<T extends RepositoryHookRequest> void postUpdate(T request)
Calls all registered and enabled repository-hook modules (PostRepositoryHook)
@Nonnull <T extends RepositoryHookRequest> RepositoryHookResult preUpdate(T request)
Calls all registered and enabled repository-hook modules (PreRepositoryHook)
@Nonnull Page<RepositoryHook> search(RepositoryHookSearchRequest request, PageRequest pageRequest)
Searches for repository hooks that match the provided request.
@Deprecated @Nonnull Settings setSettings(Repository repository, String hookKey, Settings settings)
This method is deprecated. in 5.2 for removal in 6.0. Use setSettings(SetRepositoryHookSettingsRequest) instead.
@Nonnull Settings setSettings(SetRepositoryHookSettingsRequest request)
Sets the settings for the hook specified in the request.

Public Methods

@Nonnull public SettingsBuilder createSettingsBuilder ()

Create a new SettingsBuilder which can be used to create a Settings instance.

Returns
  • a new builder

public void delete (DeleteRepositoryHookRequest request)

Delete the hook configuration specified in the request.

Parameters
request describes the hook for which the configuration should be deleted
Throws
ArgumentValidationException if the provided request is for any Scope other than REPOSITORY

@Nonnull public RepositoryHook disable (DisableRepositoryHookRequest request)

Disable the hook specified in the request.

Parameters
request describing the hook to be disabled
Returns

@Deprecated @Nonnull public RepositoryHook disable (Repository repository, String hookKey)

This method is deprecated.
in 5.2 for removal in 6.0. Use disable(DisableRepositoryHookRequest) instead.

Disable the hook identified by the supplied key for the specified repository.

Parameters
repository the repository this hook is being disabled on
hookKey the hook to be disabled
Returns

@Deprecated @Nonnull public RepositoryHook enable (Repository repository, String hookKey, Settings settings)

This method is deprecated.
in 5.2 for removal in 6.0. Use enable(EnableRepositoryHookRequest) instead.

Enable the hook identified by the supplied key for the specified repository and apply the new settings.

This is a convenient method which performs enable(Repository, String) and setSettings(Repository, String, Settings) in the same transaction

Parameters
repository the repository this hook is being enabled on
hookKey the hook to be enabled
settings the new settings.
Returns
Throws
FormValidationException when settings are invalid, leaving the existing version unchanged
ArgumentValidationException if the settings to be saved are too large, the current limit is 32KB once serialized.

@Nonnull public RepositoryHook enable (EnableRepositoryHookRequest request)

Enable and apply settings for the hook specified in the request.

Parameters
request details for enabling a repository hook
Returns
Throws
FormValidationException when settings are invalid, leaving the existing version unchanged
ArgumentValidationException if the settings to be saved are too large, the current limit is 32KB once serialized.

@Deprecated @Nonnull public RepositoryHook enable (Repository repository, String hookKey)

This method is deprecated.
in 5.2 for removal in 6.0. Use enable(EnableRepositoryHookRequest) instead.

Enable the hook identified by the supplied key for the specified repository.

Parameters
repository the repository this hook is being enabled on
hookKey the hook to be enabled
Returns

@Nonnull @Deprecated public Page<RepositoryHook> findAll (Repository repository, PageRequest pageRequest)

This method is deprecated.
in 5.2 for removal in 6.0. Use search(RepositoryHookSearchRequest, PageRequest) instead.

Find all installed hooks of the specified repository with their enabled status.

Parameters
repository the repository to load the hook from
pageRequest paging options
Returns

@Nonnull @Deprecated public Page<RepositoryHook> findByType (Repository repository, RepositoryHookType type, PageRequest pageRequest)

This method is deprecated.
in 5.2 for removal in 6.0. Use search(RepositoryHookSearchRequest, PageRequest) instead.

Find all installed hooks of the specified RepositoryHookType with enabled status for this repository

Parameters
repository the repository to load the hook from
type the type of hooks to be looked for
pageRequest paging options
Returns

@Nonnull public CacheableAvatarSupplier getAvatar (String hookKey)

Returns a supplier of an avatar for this hook, either one specified in the module or a default.

Parameters
hookKey the hook key with the desired avatar
Returns
  • an supplier for streaming the avatar

@Nullable @Deprecated public RepositoryHook getByKey (Repository repository, String hookKey)

This method is deprecated.
in 5.2 for removal in 6.0. Use getByKey(Scope, String) instead.

Find an installed hook with the specified key enabled status for this repository

Parameters
repository the repository to load the hook from
hookKey the hook to lookup
Returns

@Nullable public RepositoryHook getByKey (Scope scope, String hookKey)

Find an effective installed hook with the specified key enabled status for this scope.

An effective hook is a hook that is either:

  • configured at the given scope,
  • or configured at a higher scope.
Repository hooks can be configured at project scope or repository scope

Parameters
scope the scope to load the hook from
hookKey the hook to lookup
Returns

@Nullable public RepositoryHookSettings getSettings (GetRepositoryHookSettingsRequest request)

Gets the effective settings for the hook specified in the request.

Parameters
request details to get the settings for the specified hook
Returns
  • the effective settings currently stored or null if no settings are stored.

@Deprecated @Nullable public Settings getSettings (Repository repository, String hookKey)

This method is deprecated.
in 5.2 for removal in 6.0. Use getSettings(GetRepositoryHookSettingsRequest) instead.

Gets the settings for the specified hook and repository.

Parameters
repository the repository the settings apply to.
hookKey the complete module key of the hook which the settings are associated with.
Returns
  • the settings currently stored or null if no settings are stored.

public int migrateSettings (String oldHookKey, String newHookKey)

Migrates settings between the specified hook keys.

Hook keys are based on the combination of the plugin's key and the <repository-hook/>'s key attribute. Changing either key will result in a new hook key, and the "loss" of all existing settings in all repositories (because they remain associated with the old key).

When calling this method, the <repository-hook/> for the specified oldHookKey must no longer be installed, and the <repository-hook/> for the new key must be present.

Calling this method requires ADMIN permission. Apps may need to use the SecurityService to apply that permission.

Parameters
oldHookKey the hook's old key
newHookKey the hook's new key
Returns
  • the number of projects/repositories for which hook settings were migrated
Throws
ArgumentValidationException if the old hook is still installed, or the new hook is not installed

public void postUpdate (T request)

Calls all registered and enabled repository-hook modules (PostRepositoryHook)

Parameters
request describes the ref changes that have been applied

@Nonnull public RepositoryHookResult preUpdate (T request)

Calls all registered and enabled repository-hook modules (PreRepositoryHook)

Parameters
request describes the ref changes that are about to be made
Returns
  • the outcome of the repository-hook modules

@Nonnull public Page<RepositoryHook> search (RepositoryHookSearchRequest request, PageRequest pageRequest)

Searches for repository hooks that match the provided request.

Parameters
request a request object describing the repository hooks to return
pageRequest paging options
Returns

@Deprecated @Nonnull public Settings setSettings (Repository repository, String hookKey, Settings settings)

This method is deprecated.
in 5.2 for removal in 6.0. Use setSettings(SetRepositoryHookSettingsRequest) instead.

Sets the settings for the specified hook and repository.

Parameters
repository the repository the settings apply to.
hookKey the complete module key of the hook which the settings are associated with.
settings the new settings to save
Returns
  • the settings saved.
Throws
FormValidationException when settings are invalid, leaving the existing version unchanged
ArgumentValidationException if the settings to be saved are too large, the current limit is 32KB once serialized.

@Nonnull public Settings setSettings (SetRepositoryHookSettingsRequest request)

Sets the settings for the hook specified in the request.

Parameters
request describing the update settings request
Returns
  • the saved settings.
Throws
FormValidationException when settings are invalid, leaving the existing version unchanged
ArgumentValidationException if the settings to be saved are too large, the current limit is 32KB once serialized.