Package 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 Details

    • ATLASSIAN_DARKFEATURE_PREFIX

      static final String ATLASSIAN_DARKFEATURE_PREFIX
      Prefix for all dark feature specified as system property.
      See Also:

    • DISABLE_ALL_DARKFEATURES_PROPERTY

      static final String DISABLE_ALL_DARKFEATURES_PROPERTY
      System property for disabling all dark features.
      See Also:

    • DARKFEATURES_PROPERTIES_FILE_PROPERTY

      static final String DARKFEATURES_PROPERTIES_FILE_PROPERTY
      System property for overriding location of dark features property file.
      See Also:

    • DARKFEATURES_PROPERTIES_FILE_PROPERTY_DEFAULT

      static final String DARKFEATURES_PROPERTIES_FILE_PROPERTY_DEFAULT
      Default properties file name.
      See Also:

  • Method Details

    • isEnabledForAllUsers

      @Nonnull Optional<Boolean> isEnabledForAllUsers(@Nonnull String featureKey)
      Checks whether the product contains the given feature for all users, regardless whether the feature can be changed during runtime or not.
      Parameters:
      featureKey - key of the feature to be checked
      Returns:
      Optional boolean, true if the feature key is valid and enabled, false otherwise; Optional.empty() when the featureKey is not know or is invalid as per ValidFeatureKeyPredicate.isValidFeatureKey(String)
      See Also:

    • isEnabledForCurrentUser

      @Nonnull Optional<Boolean> isEnabledForCurrentUser(@Nonnull String featureKey)
      Checks whether the product contains the given feature 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:
      Optional boolean, true if the feature is valid and enabled, either for all users or the current user only; false otherwise. Optional.empty() when the featureKey is not know or is invalid as per ValidFeatureKeyPredicate.isValidFeatureKey(String)
      See Also:

    • isEnabledForUser

      @Nonnull Optional<Boolean> isEnabledForUser(@Nullable UserKey userKey, @Nonnull String featureKey)
      Checks whether the product contains the given feature 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:
      Optional boolean, true if the feature key is valid and enabled, either for all users or the current user only; false otherwise; Optional.empty() when the featureKey is not know or is invalid as per ValidFeatureKeyPredicate.isValidFeatureKey(String)
      Throws:
      IllegalArgumentException - if the user doesn't exist
      See Also:

    • isFeatureEnabledForAllUsers

      @Deprecated boolean isFeatureEnabledForAllUsers(String featureKey)
      Deprecated.
      use isEnabledForAllUsers(String) instead
      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:

    • isFeatureEnabledForCurrentUser

      @Deprecated boolean isFeatureEnabledForCurrentUser(String featureKey)
      Deprecated.
      use isEnabledForCurrentUser(String) instead
      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:

    • isFeatureEnabledForUser

      @Deprecated boolean isFeatureEnabledForUser(@Nullable UserKey userKey, String featureKey)
      Deprecated.
      use isEnabledForUser(UserKey, String) instead
      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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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