com.atlassian.sal.api.features
Interface DarkFeatureManager

public interface DarkFeatureManager

Provides a cross-product method for determining whether a dark feature is enabled.

Implementing products can back these checks with their own internal dark feature management system, but must follow the enable and disable dark features on startup based on system properties and the contents of an optional properties file. To avoid clashes with other system properties all features specified as system property must be prefixed with ATLASSIAN_DARKFEATURE_PREFIX. The prefix is removed from the feature key when it is processed later. Values must be either true or false. The location of the dark features property file can be overridden with the DARKFEATURES_PROPERTIES_FILE_PROPERTY system property.

See SystemDarkFeatureInitializer in sal-core for an implementation.

Since:

2.10

Field Summary

static String	ATLASSIAN_DARKFEATURE_PREFIX Prefix for all dark feature specified as system property.
static String	DARKFEATURES_PROPERTIES_FILE_PROPERTY System property for overriding location of dark features property file.
static String	DARKFEATURES_PROPERTIES_FILE_PROPERTY_DEFAULT Default properties file name.
static String	DISABLE_ALL_DARKFEATURES_PROPERTY System property for disabling all dark features.

Method Summary

boolean	canManageFeaturesForAllUsers() Returns true if the current acting user has permission to change dark features for all users.
void	disableFeatureForAllUsers(String featureKey) Disable the given dark feature for all users.
void	disableFeatureForCurrentUser(String featureKey) Disable a dark feature for the current user only.
void	disableFeatureForUser(UserKey userKey, String featureKey) Disable a dark feature for the given user only.
void	enableFeatureForAllUsers(String featureKey) Enable the given dark feature all users.
void	enableFeatureForCurrentUser(String featureKey) Enable a dark feature for the current user only.
void	enableFeatureForUser(UserKey userKey, String featureKey) Enable a dark feature for the given user only.
EnabledDarkFeatures	getFeaturesEnabledForAllUsers()
EnabledDarkFeatures	getFeaturesEnabledForCurrentUser() Return features enabled for the current user (must be called within the context of a request).
EnabledDarkFeatures	getFeaturesEnabledForUser(UserKey userKey) Return enabled features for a given user.
boolean	isFeatureEnabledForAllUsers(String featureKey) Checks if a dark feature is enabled for all users, regardless whether the feature can be changed during runtime or not.
boolean	isFeatureEnabledForCurrentUser(String featureKey) Checks if a dark feature is enabled for all users or for the current user only (must be called within the context of a request).
boolean	isFeatureEnabledForUser(UserKey userKey, String featureKey) Checks if a dark feature is enabled for all users or just for the given user.

Field Detail

ATLASSIAN_DARKFEATURE_PREFIX

static final String ATLASSIAN_DARKFEATURE_PREFIX

Prefix for all dark feature specified as system property.

See Also:

Constant Field Values

DISABLE_ALL_DARKFEATURES_PROPERTY

static final String DISABLE_ALL_DARKFEATURES_PROPERTY

System property for disabling all dark features.

See Also:

Constant Field Values

DARKFEATURES_PROPERTIES_FILE_PROPERTY

static final String DARKFEATURES_PROPERTIES_FILE_PROPERTY

System property for overriding location of dark features property file.

See Also:

Constant Field Values

DARKFEATURES_PROPERTIES_FILE_PROPERTY_DEFAULT

static final String DARKFEATURES_PROPERTIES_FILE_PROPERTY_DEFAULT

Default properties file name.

See Also:

Constant Field Values

Method Detail

isFeatureEnabledForAllUsers

boolean isFeatureEnabledForAllUsers(String featureKey)

Checks if a dark feature is enabled for all users, regardless whether the feature can be changed during runtime or not.

Parameters:

featureKey - key of the feature to be checked

Returns:

true if the feature key is valid and enabled, false otherwise

See Also:

ValidFeatureKeyPredicate

isFeatureEnabledForCurrentUser

boolean isFeatureEnabledForCurrentUser(String featureKey)

Checks if a dark feature is enabled for all users or for the current user only (must be called within the context of a request). If the user couldn't be resolved or is anonymous, only features enabled for all users are considered.

Parameters:

featureKey - key of the feature to be checked

Returns:

true if the feature is valid and enabled, either for all users or the current user only; false otherwise.

See Also:

ValidFeatureKeyPredicate

isFeatureEnabledForUser

boolean isFeatureEnabledForUser(@Nullable
                                UserKey userKey,
                                String featureKey)

Checks if a dark feature is enabled for all users or just for the given user. In case the user is anonymous, only features enabled for all users are considered.

Parameters:

userKey - the key of the user being queried; null represents the anonymous user

featureKey - key of the feature to be checked

Returns:

true if the feature key is valid and enabled, either for all users or the current user only; false otherwise.

Throws:

IllegalArgumentException - if the user doesn't exist

See Also:

ValidFeatureKeyPredicate

canManageFeaturesForAllUsers

boolean canManageFeaturesForAllUsers()

Returns true if the current acting user has permission to change dark features for all users. This is a nothrow method and should return a value instead of throw an exception.

Returns:

true iff the current acting user has permission to change dark features for all users, false otherwise

enableFeatureForAllUsers

void enableFeatureForAllUsers(String featureKey)

Enable the given dark feature all users. The acting user must have permission to change dark features for all users.

Parameters:

featureKey - key of the feature to be enabled

Throws:

InvalidFeatureKeyException - if the feature key is not valid

MissingPermissionException - if the user has not the required permission

IllegalStateException - if the update failed

See Also:

ValidFeatureKeyPredicate, canManageFeaturesForAllUsers()

disableFeatureForAllUsers

void disableFeatureForAllUsers(String featureKey)

Disable the given dark feature for all users. The acting user must have permission to change dark features for all users.

Parameters:

featureKey - key of the feature to be disabled

Throws:

InvalidFeatureKeyException - if the feature key is not valid

MissingPermissionException - if the user has not the required permission

IllegalStateException - if the update failed

See Also:

ValidFeatureKeyPredicate, canManageFeaturesForAllUsers()

enableFeatureForCurrentUser

void enableFeatureForCurrentUser(String featureKey)

Enable a dark feature for the current user only. Anonymous users are not supported. If the feature is already enabled for all users, the user will still be able to use it.

Parameters:

featureKey - key of the feature to enable

Throws:

InvalidFeatureKeyException - if the feature key is not valid

IllegalStateException - if the current user could not be resolved, is anonymous or the update failed due to any other reason

See Also:

ValidFeatureKeyPredicate

enableFeatureForUser

void enableFeatureForUser(UserKey userKey,
                          String featureKey)

Enable a dark feature for the given user only. Anonymous users are not supported. If the feature is already enabled for all users, the user will still be able to use it.

Parameters:

userKey - key of the user to enable the feature for; not null

featureKey - key of the feature to be enabled

Throws:

IllegalArgumentException - if the user does not exist or is anonymous

InvalidFeatureKeyException - if the feature key is not valid

IllegalStateException - if the update failed

See Also:

ValidFeatureKeyPredicate

disableFeatureForCurrentUser

void disableFeatureForCurrentUser(String featureKey)

Disable a dark feature for the current user only. Anonymous users are not supported. If the feature is enabled for all users, the current user will still be able to use it.

Parameters:

featureKey - key of the feature to be disabled

Throws:

InvalidFeatureKeyException - if the feature key is not valid

IllegalStateException - if the current user could not be resolved, is anonymous or the update failed due to any other reason

See Also:

ValidFeatureKeyPredicate

disableFeatureForUser

void disableFeatureForUser(UserKey userKey,
                           String featureKey)

Disable a dark feature for the given user only. Anonymous users are not supported. If the feature is enabled for all users, the user will still be able to use it.

Parameters:

userKey - key of the user to disable the feature for; not null

featureKey - key of the feature to be disabled

Throws:

IllegalArgumentException - if the user does not exist or is anonymous

InvalidFeatureKeyException - if the feature key is not valid

IllegalStateException - if the update failed

See Also:

ValidFeatureKeyPredicate

getFeaturesEnabledForAllUsers

EnabledDarkFeatures getFeaturesEnabledForAllUsers()

Returns:

all dark features enabled for all users.

getFeaturesEnabledForCurrentUser

EnabledDarkFeatures getFeaturesEnabledForCurrentUser()

Return features enabled for the current user (must be called within the context of a request). In case the current user could not be resolved or is anonymous, all dark features enabled for all users are returned instead.

Returns:

all dark features applicable for the current user.

getFeaturesEnabledForUser

EnabledDarkFeatures getFeaturesEnabledForUser(@Nullable
                                              UserKey userKey)

Return enabled features for a given user. In case the current user is anonymous, all global enabled features are returned.

Parameters:

userKey - key of the user being queried; null represents the anonymous user

Returns:

all dark features applicable for the given user

Throws:

IllegalArgumentException - if the user doesn't exist