Package growthbook.sdk.java.util

Class GrowthBookUtils

java.lang.Object
growthbook.sdk.java.util.GrowthBookUtils
public class GrowthBookUtils extends Object
INTERNAL: Implementation of for internal utility methods to support GrowthBook

  • Constructor Details

    • GrowthBookUtils

      public GrowthBookUtils()

  • Method Details

    • hash

      @Nullable public static Float hash(String stringValue, Integer hashVersion, String seed)
      Hashes a string to a float between 0 and 1, or null if the hash version is unsupported. Uses the simple Fowler–Noll–Vo algorithm, specifically fnv32a.
      Parameters:
      stringValue - Input string
      hashVersion - The hash version
      seed - A seed value that can be used instead of the experiment key for hashing
      Returns:
      hashed float value or null if the hash version is unsupported.

    • inNameSpace

      public static Boolean inNameSpace(String userId, Namespace namespace)
      This checks if a userId is within an experiment namespace or not.
      Parameters:
      userId - The user identifier
      namespace - Namespace to check the user identifier against
      Returns:
      whether the user is in the namespace

    • chooseVariation

      public static Integer chooseVariation(@NotNull @NotNull Float n, ArrayList<BucketRange> bucketRanges)
      Given a hash and bucket ranges, assign one of the bucket ranges. Returns -1 if none can be found
      Parameters:
      n - hash
      bucketRanges - list of BucketRange
      Returns:
      index of the BucketRange list to assign

    • getEqualWeights

      public static ArrayList<Float> getEqualWeights(Integer numberOfVariations)
      Returns an array of floats with numVariations items that are all equal and sum to 1. For example, getEqualWeights(2) would return [0.5, 0.5]
      Parameters:
      numberOfVariations - The number of variations you would like
      Returns:
      A list of variations

    • getQueryStringOverride

      @Nullable public static Integer getQueryStringOverride(String id, String urlString, Integer numberOfVariations)
      This checks if an experiment variation is being forced via a URL query string. This may not be applicable for all SDKs (e.g. mobile).

      As an example, if the id is my-test and url is ..., it would return 1.

      Returns null if any of these are true:

      • There is no query string
      • The id is not a key in the query string
      • The variation is not an integer
      • The variation is less than 0 or greater than or equal to numVariations
      Parameters:
      id - the identifier
      urlString - the desired page URL as a string
      numberOfVariations - the number of variations
      Returns:
      integer or null

    • getQueryStringOverride

      @Nullable public static Integer getQueryStringOverride(String id, URL url, Integer numberOfVariations)
      This checks if an experiment variation is being forced via a URL query string. This may not be applicable for all SDKs (e.g. mobile).

      As an example, if the id is my-test and url is ..., it would return 1.

      Returns null if any of these are true:

      • There is no query string
      • The id is not a key in the query string
      • The variation is not an integer
      • The variation is less than 0 or greater than or equal to numVariations
      Parameters:
      id - the identifier
      url - the desired page URL
      numberOfVariations - the number of variations
      Returns:
      integer or null

    • getForcedBooleanValueFromUrl

      @Nullable public static Boolean getForcedBooleanValueFromUrl(String featureKey, URL url)
      Evaluate a forced boolean value from a URL. If the provided key is not present in the URL, return null.
      Parameters:
      featureKey - feature ID/key (not prefixed with gb~)
      url - Page URL to evaluate for forced feature values
      Returns:
      value or null

    • getForcedStringValueFromUrl

      @Nullable public static String getForcedStringValueFromUrl(String featureKey, URL url)
      Evaluate a forced string value from a URL. If the provided key is not present in the URL, return null.
      Parameters:
      featureKey - feature ID/key (not prefixed with gb~)
      url - Page URL to evaluate for forced feature values
      Returns:
      value or null

    • getForcedFloatValueFromUrl

      @Nullable public static Float getForcedFloatValueFromUrl(String featureKey, URL url)
      Evaluate a forced float value from a URL. If the provided key is not present in the URL, return null.
      Parameters:
      featureKey - feature ID/key (not prefixed with gb~)
      url - Page URL to evaluate for forced feature values
      Returns:
      value or null

    • getForcedDoubleValueFromUrl

      @Nullable public static Double getForcedDoubleValueFromUrl(String featureKey, URL url)
      Evaluate a forced float value from a URL. If the provided key is not present in the URL, return null.
      Parameters:
      featureKey - feature ID/key (not prefixed with gb~)
      url - Page URL to evaluate for forced feature values
      Returns:
      value or null

    • getForcedIntegerValueFromUrl

      @Nullable public static Integer getForcedIntegerValueFromUrl(String featureKey, URL url)
      Evaluate a forced integer value from a URL. If the provided key is not present in the URL, return null.
      Parameters:
      featureKey - feature ID/key (not prefixed with gb~)
      url - Page URL to evaluate for forced feature values
      Returns:
      value or null

    • getForcedSerializableValueFromUrl

      @Nullable public static <ValueType> ValueType getForcedSerializableValueFromUrl(String featureKey, URL url, Class<ValueType> valueTypeClass, com.google.gson.Gson gson)

    • getBucketRanges

      public static ArrayList<BucketRange> getBucketRanges(Integer numberOfVariations, @NotNull @NotNull Float coverage, @Nullable ArrayList<Float> weights)
      This converts and experiment's coverage and variation weights into an array of bucket ranges. Defaults to equal weights if the sum of the weight is not equal to 1 (rounded).
      Parameters:
      numberOfVariations - number of variations
      coverage - the amount that should be covered, e.g. 0.5 is 50%
      weights - List of weights. If these do not sum to 1, equal weights will be applied.
      Returns:
      list of BucketRange

    • inRange

      public static Boolean inRange(Float n, BucketRange range)
      Determines if a number n is within the provided range. Verifies if the provided float is within the lower (inclusive) and upper (exclusive) bounds of the provided BucketRange.
      Parameters:
      n - Float value to check if it's in range
      range - BucketRange
      Returns:
      whether to include this hash value is within range. Returns false if either arguments are null.

    • isFilteredOut

      public static Boolean isFilteredOut(List<Filter> filters, com.google.gson.JsonObject attributes)
      Evaluates whether a user should be filtered out based on the given filters.

      This method processes each filter in the provided list and performs the following steps:

      • Iterates through the list of filters.
      • Retrieves the hash attribute and hash value from the user attributes.
      • If the hash value is empty, the user is filtered out (returns true).
      • Computes a hash-based bucket value for the user.
      • If none of the specified bucket ranges match, the user is filtered out.
      If all filters are processed without an early return, the method returns false, meaning the user is not filtered out.
      Parameters:
      filters - The list of Filter objects that define filtering criteria.
      attributes - A JsonObject containing user attributes.
      Returns:
      true if the user is filtered out, otherwise false.

    • isIncludedInRollout

      public static Boolean isIncludedInRollout(com.google.gson.JsonObject attributes, String seed, String hashAttribute, String fallbackAttribute, @Nullable BucketRange range, @Nullable Float coverage, @Nullable Integer hashVersion)
      Determines if the user is part of a gradual feature rollout.
      • Either coverage or range are required. If both are null, return true immediately
      • If range is null and coverage is zero, return false immediately. This catches an edge case where the bucket is zero and users are let through when they shouldn't be
      • If hashValue is empty, return false immediately
      Parameters:
      attributes - JsonObject
      seed - String
      hashAttribute - String
      fallbackAttribute - String
      range - BucketRange
      coverage - Float
      hashVersion - Integer
      Returns:
      Boolean - check if user is included

    • refreshStickyBuckets

      public static void refreshStickyBuckets(GBContext context, String featuresDataModel, com.google.gson.JsonObject attributeOverrides)
      Retrieves cached assignments and sets them in the context's Sticky Bucket Assignments documents.
      Parameters:
      context - GBContext that contains sticky bucketing attributes and sticky bucket service
      featuresDataModel - A string representing the features data model.
      attributeOverrides - JsonObject containing attribute overrides.

    • getStickyBucketAttributes

      public static Map<String,String> getStickyBucketAttributes(GBContext context, String featuresDataModel, com.google.gson.JsonObject attributeOverrides)
      Supportive method to get attribute values from the context.
      Parameters:
      context - GBContext The context containing user attributes.
      featuresDataModel - A string representing the features data model.
      attributeOverrides - A JsonObject containing attribute overrides.
      Returns:
      Map<String, String> A map of sticky bucket attributes.

    • getStickyBucketAssignments

      public static Map<String,String> getStickyBucketAssignments(EvaluationContext context, @Nullable String expHashAttribute, @Nullable String expFallbackAttribute)
      Method to get actual Sticky Bucket assignments. Also, this method handles if assignments belong to the user.
      Parameters:
      context - EvaluationContext
      expHashAttribute - String (nullable)
      expFallbackAttribute - String (nullable)
      Returns:
      Map<String, String> containing sticky bucket assignments.

    • getStickyBucketVariation

      public static StickyBucketVariation getStickyBucketVariation(EvaluationContext context, String experimentKey, @Nullable String experimentHashAttribute, @Nullable String experimentFallbackAttribute, @Nullable Integer experimentBucketVersion, @Nullable Integer minExperimentBucketVersion, @Nullable List<VariationMeta> meta)
      Method to get StickyBucketVariation: variation and versionIsBlocked.
      Parameters:
      context - EvaluationContext
      experimentKey - String
      experimentHashAttribute - String (nullable)
      experimentFallbackAttribute - String (nullable)
      experimentBucketVersion - Integer (nullable)
      minExperimentBucketVersion - Integer (nullable)
      meta - List<VariationMeta> (nullable)
      Returns:
      StickyBucketVariation

    • getStickyBucketExperimentKey

      public static String getStickyBucketExperimentKey(String experimentKey, @Nullable Integer experimentBucketVersion)
      Method to get Experiment key from cache
      Parameters:
      experimentKey - String
      experimentBucketVersion - Integer
      Returns:
      key in String format

    • generateStickyBucketAssignmentDoc

      public static GeneratedStickyBucketAssignmentDocModel generateStickyBucketAssignmentDoc(Map<String,StickyAssignmentsDocument> stickyBucketAssignmentDocs, String attributeName, String attributeValue, Map<String,String> assignments)
      Method for generating a Sticky Bucket Assignment document.
      Parameters:
      stickyBucketAssignmentDocs - Map<String, StickyAssignmentsDocument>
      attributeName - String
      attributeValue - String
      assignments - Map<String, String>
      Returns:
      GeneratedStickyBucketAssignmentDocModel

    • getHashAttribute

      public static HashAttributeAndHashValue getHashAttribute(@Nullable String attr, @Nullable String fallbackAttribute, com.google.gson.JsonObject attributes)
      Method for get hash value by identifier. User attribute used for hashing, defaulting to id if not set.
      Parameters:
      attr - String
      fallbackAttribute - String
      attributes - JsonObject
      Returns:
      HashAttributeAndHashValue

    • mergeMaps

      public static <K, V> Map<K,V> mergeMaps(List<Map<K,V>> maps)