com.almworks.jira.structure.api.settings.StructureConfiguration Maven / Gradle / Ivy
Show all versions of structure-api Show documentation
package com.almworks.jira.structure.api.settings;
import com.almworks.integers.*;
import com.almworks.jira.structure.api.permissions.*;
import com.almworks.jira.structure.api.structure.StructureManager;
import com.atlassian.jira.jql.builder.JqlClauseBuilder;
import com.atlassian.jira.project.Project;
import com.atlassian.jira.user.ApplicationUser;
import com.atlassian.query.Query;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.*;
import static com.almworks.jira.structure.api.permissions.CoreAppPermissions.*;
import static java.util.stream.Collectors.joining;
/**
* StructureConfiguration provides access to the configuration parameters of the Structure app.
*
* Typically, only Jira administrators have write access to the app configuration, so before changing
* anything you should check if the user has enough privileges - no checking is done by this component.
*
* This service also provides some utility methods that are based on the Structure configuration.
*
* All methods in this component are thread-safe.
*/
public interface StructureConfiguration {
/**
* @return true if Structure is enabled for all projects
* @see Selecting Structure-Enabled Projects
*/
boolean isEnabledForAllProjects();
/**
* This method returns a list of IDs of projects picked by the administrator for the Structure app. It
* returns a list of IDs of picked projects even if "enable for all projects" is turned on - so for the purposes
* of checking whether Structure is available for a project, you need to use {@link #getCurrentlyEnabledProjects()}.
*
* @return a list of IDs of projects picked by Jira administrator on the configuration page
* @see Selecting Structure-Enabled Projects
* @since 8.2.0 (Structure 2.5)
*/
@NotNull
LongList getPickedProjectIds();
/**
* This method returns a list of projects picked by the administrator for the Structure app. It
* returns a list of picked projects even if "enable for all projects" is turned on - so for the purposes
* of checking whether Structure is available for a project, you need to use {@link #getCurrentlyEnabledProjects()}.
*
* @return a list of projects picked by Jira administrator on the configuration page
* @see Selecting Structure-Enabled Projects
*/
@NotNull
List getPickedProjects();
/**
* @return a list of projects that are allowed to use Structure (if Structure is enabled for all projects,
* returns all projects)
* @see Selecting Structure-Enabled Projects
*/
@NotNull
List getCurrentlyEnabledProjects();
/**
* Checks if a given project is enabled for Structure
*
* @param project project to check
* @return true if the project is not null and available for Structure
* @see #getCurrentlyEnabledProjects()
*/
boolean isProjectEnabled(@Nullable Project project);
/**
* @return true if Structure is enabled for all users (that have access to the enabled projects)
* @see Restricting User Access to Structure
*/
default boolean isEnabledForAnyone() {
return isAllowedForAnyone(USE);
}
/**
* Used to get the list of groups (possibly other permission subjects) that the app is enabled for.
* Note that if the app is enabled for all users, this method would still return the groups that
* an administrator has previously picked, but those groups are not used to check the permissions.
*
* @return a list of subjects that the Structure app is enabled for (when not enabled for anyone)
* @see PermissionSubject.JiraGroup
* @see Restricting User Access to Structure
*/
@NotNull
default List getEnabledPermissionSubjects() {
return getPermissionSubjects(USE);
}
/**
* @return true if creating new structures is enabled for all users (that have access to Structure at all)
* @see Changing Permission to Create New Structures
*/
default boolean isCreateEnabledForAnyone() {
return isAllowedForAnyone(CREATE_STRUCTURE);
}
/**
* Used to get the list of groups (possibly other permission subjects) that are allowed to create
* new structures.
* Note that if structure creation is enabled for all users, this method would still return the groups that
* an administrator has previously picked, but those groups are not used to check the permissions.
*
* @return a list of subjects that are allowed to create new structures (when not enabled for anyone)
* @see PermissionSubject.JiraGroup
* @see Changing Permission to Create New Structures
*/
@NotNull
default List getCreatorPermissionSubjects() {
return getPermissionSubjects(CREATE_STRUCTURE);
}
/**
* @return true if synchronization is available for all users who have control access to the structure
* @since 8.5.0 (Structure 2.8)
*/
default boolean isSynchronizationEnabledForAnyone() {
return isAllowedForAnyone(SYNCHRONIZATION);
}
/**
* Used to get the list of groups (possibly other permission subjects) that are allowed to configure and control synchronizers of controlled structures.
* @return a list of subjects that are allowed to configure and control synchronizers (when not enabled for anyone)
* @since 8.5.0 (Structure 2.8)
*/
@NotNull
default List getSynchronizationPermissionSubjects() {
return getPermissionSubjects(SYNCHRONIZATION);
}
/**
* @return true if automation is available for all users who have control access to the structure
* @since 10.0.0 (Structure 3.0)
*/
default boolean isAutomationEnabledForAnyone() {
return isAllowedForAnyone(AUTOMATION);
}
/**
* Used to get the list of groups (possibly other permission subjects) that are allowed to configure and control automation of controlled structures.
* @return a list of subjects that are allowed to configure and control automation (when not enabled for anyone)
* @since 10.0.0 (Structure 3.0)
*/
@NotNull
default List getAutomationPermissionSubjects() {
return getPermissionSubjects(AUTOMATION);
}
/**
* Changes whether the app is enabled for all projects.
*
* @param enabled if true, Structure will be enabled for all projects
* @see Selecting Structure-Enabled Projects
*/
void setEnabledForAllProjects(boolean enabled);
/**
* Changes projects that Structure is enabled for. The setting is effective only if
* {@link #isEnabledForAllProjects} returns false.
*
* @param idList a comma-delimited list of project IDs
* @see Selecting Structure-Enabled Projects
*/
void setPickedProjectIds(@Nullable String idList);
/**
* Changes projects that Structure is enabled for. The setting is effective only if
* {@link #isEnabledForAllProjects} returns false.
*
* @param projectIds collection of project IDs
* @see Selecting Structure-Enabled Projects
*/
default void setPickedProjectIds(@Nullable LongIterable projectIds) {
if (projectIds == null) {
setPickedProjectIds("");
return;
}
StringJoiner joiner = new StringJoiner(",");
for (LongIterator it : projectIds) {
joiner.add(Long.toString(it.value()));
}
setPickedProjectIds(joiner.toString());
}
/**
* Changes projects that Structure is enabled for. The setting is effective only if
* {@link #isEnabledForAllProjects} returns false.
*
* @param projectIds collection of project IDs
* @see Selecting Structure-Enabled Projects
*/
default void setPickedProjectIds(@Nullable Collection projectIds) {
setPickedProjectIds(projectIds == null ? "" :
projectIds.stream().map(String::valueOf).collect(joining(",")));
}
/**
* Changes whether the app is available for all users.
*
* @param enabled if true, Structure will be available to all users that have access to at least one structure-enabled project.
* @see Restricting User Access to Structure
*/
default void setEnabledForAnyone(boolean enabled) {
setAllowedForAnyone(USE, enabled);
}
/**
* Changes the list of the users / groups that the Structure app is enabled for. When Structure
* is configured to be enabled for anyone, this method has no effect.
*
* @param subjects comma-delimited list of string-encoded permission subjects
* @see PermissionSubject#toEncodedString()
* @see Restricting User Access to Structure
*/
default void setEnabledPermissionSubjectsEncoded(@Nullable String subjects) {
setPermissionSubjectsEncoded(USE, subjects);
}
/**
* Changes whether the creation of new structures is available for all users.
*
* @param enabled if true, anyone who has access to Structure can create new structures.
* @see Changing Permission to Create New Structures
*/
default void setCreateEnabledForAnyone(boolean enabled) {
setAllowedForAnyone(CREATE_STRUCTURE, enabled);
}
/**
* Changes the list of the users / groups that are allowed to create new structures. When Structure is configured
* to allow anyone to create new structures, this setting has no effect.
*
* @param subjects comma-delimited list of string-encoded permission subjects
* @see PermissionSubject#toEncodedString()
* @see Changing Permission to Create New Structures
*/
default void setCreatorPermissionSubjectsEncoded(@Nullable String subjects) {
setPermissionSubjectsEncoded(CREATE_STRUCTURE, subjects);
}
/**
* Changes whether the synchronization is available for all users.
*
* @param enabled if true, anyone who has control access to the structure can configure and control synchronizers.
* @since 8.5.0 (Structure 2.8)
*/
default void setSynchronizationEnabledForAnyone(boolean enabled) {
setAllowedForAnyone(SYNCHRONIZATION, enabled);
}
/**
* Changes the list of the users / groups that are allowed to configure and control synchronizers in controlled structures.
*
* @param subjects comma-delimited list of string-encoded permission subjects
* @since 8.5.0 (Structure 2.8)
*/
default void setSynchronizationPermissionSubjectsEncoded(@Nullable String subjects) {
setPermissionSubjectsEncoded(SYNCHRONIZATION, subjects);
}
/**
* Changes whether the automation is available for all users.
*
* @param enabled if true, anyone who has control access to the structure can configure and control automation.
* @since 10.0.0 (Structure 3.0)
*/
default void setAutomationEnabledForAnyone(boolean enabled) {
setAllowedForAnyone(AUTOMATION, enabled);
}
/**
* Changes the list of the users / groups that are allowed to configure and control automation in controlled structures.
*
* @param subjects comma-delimited list of string-encoded permission subjects
* @since 10.0.0 (Structure 3.0)
*/
default void setAutomationPermissionSubjectsEncoded(@Nullable String subjects) {
setPermissionSubjectsEncoded(AUTOMATION, subjects);
}
/**
* Adds to the JQL builder a condition that limits the result set to the projects enabled for Structure.
* This method adds JQL constraint project IN (....) in case Structure is allowed only for
* specific projects and does nothing if Structure is allowed for all projects. The condition is added at the
* current level in the clause builder.
*
* @param builder a clause builder to be modified; if null, a new clause builder is created
* @return the builder that was passed as the parameter or the newly created builder
*/
@NotNull
JqlClauseBuilder addConfigurationScopeClause(@Nullable JqlClauseBuilder builder);
/**
* Utility method that returns a JQL query that selects all issues in the projects that are available for Structure.
* This is a convenience method that uses {@link #addConfigurationScopeClause}.
*
* @return a query that selects issues enabled for Structure, or null if all issues are enabled
*/
@Nullable
Query getConfigurationScopeQuery();
/**
* Checks if Structure is available for the specified user.
*
*
This is not the same as {@code isAllowed(CoreAppPermissions.USE, user)},
* because it also checks user's access to enabled projects.
*
* @param user the user, null means anonymous
* @return true if the user can use Structure
* @see Who Has Access to the Structure
*/
boolean isStructureAvailable(@Nullable ApplicationUser user);
/**
* Checks if the user is allowed to create new structures.
*
* @param user the user, null means anonymous
* @return true if the user can create new structures
* @see Who Has Access to the Structure
*/
default boolean isStructureCreationAllowed(@Nullable ApplicationUser user) {
return isAllowed(CREATE_STRUCTURE, user);
}
/**
* Checks if the user is allowed to configure and control synchronizers.
*
* @param user the user, null means anonymous
* @return true if the user can configure and control synchronizers
* @since 8.5.0 (Structure 2.8)
*/
default boolean isSynchronizationAllowed(@Nullable ApplicationUser user) {
return isAllowed(SYNCHRONIZATION, user);
}
/**
* Checks if the user is allowed to configure and use automation.
*
* @param user the user, null means anonymous
* @return true if the user can configure and control automation
* @since 10.0.0 (Structure 3.0)
*/
default boolean isAutomationAccessAllowed(@Nullable ApplicationUser user){
return isAllowed(AUTOMATION, user);
}
/**
* Checks if the given Structure app permission is granted to all users.
*
* @param permission the permission
* @return true if the permission is granted to all users
* @see CoreAppPermissions
*/
boolean isAllowedForAnyone(@NotNull StructureAppPermission permission);
/**
* Returns the list of groups (possibly other permission subjects) that are
* granted the given Structure app permission.
*
* @param permission the permission
* @return the list of subjects that are granted the permission
* @see CoreAppPermissions
*/
@NotNull
List getPermissionSubjects(@NotNull StructureAppPermission permission);
/**
* Grant the given Structure app permission to anyone.
*
* @param permission the permission
* @param allowed true to grant the permission to anyone
* @see CoreAppPermissions
*/
void setAllowedForAnyone(@NotNull StructureAppPermission permission, boolean allowed);
/**
* Changes the list of the users / groups that are granted the given
* Structure app permission.
*
* @param permission the permission
* @param subjects comma-delimited list of string-encoded permission subjects
* @see CoreAppPermissions
*/
void setPermissionSubjectsEncoded(@NotNull StructureAppPermission permission, @Nullable String subjects);
/**
* Changes the list of the users / groups that are granted the given
* Structure app permission.
*
* @param permission the permission
* @param subjects the collection of permission subjects
* @see CoreAppPermissions
*/
default void setPermissionSubjects(@NotNull StructureAppPermission permission, @Nullable Collection subjects) {
setPermissionSubjectsEncoded(permission, subjects == null ? "" :
subjects.stream().map(PermissionSubject::toEncodedString).collect(joining(",")));
}
/**
* Checks if the user is granted the given Structure app permission.
*
* @param permission the permission
* @param user the user, null means anonymous
* @return true if the user is granted the permission
* @see CoreAppPermissions
*/
boolean isAllowed(@NotNull StructureAppPermission permission, @Nullable ApplicationUser user);
/**
* Returns the ID of the default structure for a given project. If project is null, return system-wide
* default structure.
* Returns 0 if there's no default structure available.
* The Structure app stores a system default structure. It also allows project administrator to change default structure for a project.
* Structure user interface can be configured to switch to the project default structure when that project
* or issue from that project is opened.
*
* Important: It is not guaranteed that the structure with this given ID exists! The preference
* is stored independently from the structures.
*
*
* @param project the project for which default structure is requested; null to get a system-wide default structure
* @return the ID of the default structure for the specified project, or 0
* @see StructureManager#getStructure(Long, PermissionLevel)
* @see #setDefaultStructureId(com.atlassian.jira.project.Project, Long)
*/
long getDefaultStructureId(@Nullable Project project);
/**
* Changes the ID of the default structure for the specified project. If project is null,
* updates system-wide default structure.
* See {@link #getDefaultStructureId(com.atlassian.jira.project.Project)} for more details about default structures.
*
* @param project the project for which to set the default structure, null to set system-wide default
* @param structureId the ID of the default structure, null to clear the value (project-level default structure
* will use system-level default structure, and system-level default structure ID will be reset to 0 - no structure)
* @see #getDefaultStructureId(com.atlassian.jira.project.Project)
*/
void setDefaultStructureId(@Nullable Project project, @Nullable Long structureId);
/**
* Used to check whether a specific project has system-level default structure overridden with project-level default structure.
*
* @param project project to check
* @return true if a project-level default structure has been specified
* @see #setDefaultStructureId(com.atlassian.jira.project.Project, Long)
*/
boolean isDefaultStructureSetForProject(@NotNull Project project);
/**
* Retrieves user interface settings for the specified user and project.
*
* UI settings are typically defined at a system level by Jira administrator
* and can be overridden by each user and for each project. This method calculates the final UI settings
* given which user is viewing Structure widget and the project context (such as viewing an issue or a project tab).
*
*
* The following is the order in which settings are applied:
*
*
* - Per-user per-project value, if set
* - Per-user value, if set
* - Per-project value, if set
* - System default value
*
*
* @param user the user to retrieve UI settings for, or null for anonymous user
* @param project the project to retrieve UI settings for, or null for non-project-specific settings
* @return an instance of {@link UISettings} that details how Structure Widget should work
*/
@NotNull
UISettings getUISettings(@Nullable ApplicationUser user, @Nullable Project project);
/**
* This method is used to update the user interface settings - either system-wide default
* settings or per-user settings or per-project settings. See {@link #getUISettings(ApplicationUser, Project)}
* for details.
*
* Per-project UI settings are not yet supported.
* Using project argument currently has no effect -
* it would work as if project was null. The argument is added for
* the sake of forward compatibility as we expect to support it soon.
*
* Use {@link com.almworks.jira.structure.api.settings.UISettingsBean} to
* specify the settings you want to change. If a certain setting has null
* value, it is treated as "not set" and the value is inherited from generic settings.
*
* To unset a specific setting and make it inherit a default value, use {@link #clearUISettings}
* to clear all settings and then this method to restore all overridden settings you'd like to keep.
*
* @param user the user to apply the settings for, or null to apply globally
* @param project (currently not used) the project to apply settings for, or null to apply across all projects
* @param settings an instance of settings
*/
void setUISettings(@Nullable ApplicationUser user, @Nullable Project project, @NotNull UISettings settings);
/**
* Completely removes per-user or per-project settings. Next time settings are retrieved,
* default/inherited settings will take effect.
*
* Either user or project settings must be specified. This method
* has no effect on the system defaults.
*
* @param user the user to clear settings for
* @param project the project to clear settings for
* @see #setUISettings
* @see UISettings
*/
void clearUISettings(@Nullable ApplicationUser user, @Nullable Project project);
@NotNull
AttributeSensitivitySettings getAttributeSensitivitySettings();
void setAttributeSensitivitySettings(@NotNull AttributeSensitivitySettings settings);
}