com.almworks.jira.structure.api.StructureConfiguration Maven / Gradle / Ivy
Show all versions of structure-api Show documentation
package com.almworks.jira.structure.api;
import com.almworks.integers.LongList;
import com.almworks.jira.structure.api.settings.UISettings;
import com.almworks.jira.structure.api2g.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.List;
/**
* StructureConfiguration provides access to the configuration parameters of the Structure plugin.
*
* Typically, only JIRA administrators have write access to the plugin 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 plugin 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 plugin. 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 plugin. 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 plugin is enabled for all users (that have access to the enabled projects)
* @see Restricting User Access to Structure
*/
boolean isEnabledForAnyone();
/**
* Used to get the list of groups (possibly other permission subjects) that the plugin is enabled for.
* Note that if the plugin 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 plugin is enabled for (when not enabled for anyone)
* @see PermissionSubject.JiraGroup
* @see Restricting User Access to Structure
*/
@NotNull
List getEnabledPermissionSubjects();
/**
* @return true if creating new structures is enabled for all users (that have access to Structure plugin at all)
* @see Changing Permission to Create New Structures
*/
boolean isCreateEnabledForAnyone();
/**
* 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
List getCreatorPermissionSubjects();
/**
* @return true if synchronization is available for all users who have control access to the structure
* @since 8.5.0 (Structure 2.8)
*/
boolean isSynchronizationEnabledForAnyone();
/**
* 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
List getSynchronizationPermissionSubjects();
/**
* @return true if automation is available for all users who have control access to the structure
* @since 10.0.0 (Structure 3.0)
*/
boolean isAutomationEnabledForAnyone();
/**
* 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
List getAutomationPermissionSubjects();
/**
* Changes whether the plugin is enabled for all projects.
*
* @param enabled if true, Structure plugin will be enabled for all projects
* @see Selecting Structure-Enabled Projects
*/
void setEnabledForAllProjects(boolean enabled);
/**
* Changes projects that Structure plugin 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 whether the plugin is available for all users.
*
* @param enabled if true, Structure plugin will be available to all users that have access to at least one structure-enabled project.
* @see Restricting User Access to Structure
*/
void setEnabledForAnyone(boolean enabled);
/**
* Changes the list of the users / groups that the Structure plugin 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 com.almworks.jira.structure.api.PermissionSubject#toEncodedString()
* @see Restricting User Access to Structure
*/
void setEnabledPermissionSubjectsEncoded(@Nullable String 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
*/
void setCreateEnabledForAnyone(boolean 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 com.almworks.jira.structure.api.PermissionSubject#toEncodedString()
* @see Changing Permission to Create New Structures
*/
void setCreatorPermissionSubjectsEncoded(@Nullable String 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)
*/
void setSynchronizationEnabledForAnyone(boolean 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)
*/
void setSynchronizationPermissionSubjectsEncoded(@Nullable String 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)
*/
void setAutomationEnabledForAnyone(boolean 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)
*/
void setAutomationPermissionSubjectsEncoded(@Nullable String 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 plugin is available for the specified user.
*
* @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
*/
boolean isStructureCreationAllowed(@Nullable ApplicationUser 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)
*/
boolean isSynchronizationAllowed(@Nullable ApplicationUser 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)
*/
boolean isAutomationAccessAllowed(@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.
* Structure plugin 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);
}