Package com.launchdarkly.sdk

Class ContextBuilder

  • public final class ContextBuilder
extends java.lang.Object
    A mutable object that uses the builder pattern to specify properties for LDContext.

    Use this type if you need to construct a context that has only a single kind. To define a multi-kind context, use LDContext.createMulti(LDContext...) or LDContext.multiBuilder().

    Obtain an instance of ContextBuilder by calling LDContext.builder(String) or LDContext.builder(ContextKind, String). Then, call setter methods such as name(String) or set(String, String) to specify any additional attributes. Then, call build() to create the context. ContextBuilder setters return a reference to the same builder, so calls can be chained: 

    
     LDContext context = LDContext.builder("context-key-123abc")
       .name("my-name)
       .set("country", "us")
       .build();

    A ContextBuilder should not be accessed by multiple threads at once. Once you have called build(), the resulting LDContext is immutable and is safe to use from multiple threads. Instances created with build() are not affected by subsequent actions taken on the builder.

    • Method Detail

      • build

        public LDContext build()
        Creates an LDContext from the current builder properties.

        The LDContext is immutable and will not be affected by any subsequent actions on the ContextBuilder.

        It is possible to specify invalid attributes for a ContextBuilder, such as an empty key. Instead of throwing an exception, the ContextBuilder always returns an LDContext and you can check LDContext.isValid() or LDContext.getError() to see if it has an error. See LDContext.isValid() for more information about invalid conditions. If you pass an invalid LDContext to an SDK method, the SDK will detect this and will log a description of the error.

        Returns:
        a new LDContext

      • kind

        public ContextBuilder kind​(java.lang.String kindString)
        Sets the context's kind attribute, as a string.

        This method is a shortcut for calling kind(ContextKind.of(kindName)), since the method name already prevents ambiguity about the intended type

        Parameters:
        kindString - the context kind
        Returns:
        the builder
        See Also:
        LDContext.getKind()

      • key

        public ContextBuilder key​(java.lang.String key)
        Sets the context's key attribute.

        Every Context has a key, which is always a string. It cannot be an empty string, but there are no other restrictions on its value.

        The key attribute can be referenced by flag rules, flag target lists, and segments.

        Parameters:
        key - the context key
        Returns:
        the builder
        See Also:
        LDContext.getKey()

      • name

        public ContextBuilder name​(java.lang.String name)
        Sets the context's name attribute.

        This attribute is optional. It has the following special rules:

        • Unlike most other attributes, it is always a string if it is specified.
        • The LaunchDarkly dashboard treats this attribute as the preferred display name for contexts.
        Parameters:
        name - the name attribute (null to unset the attribute)
        Returns:
        the builder
        See Also:
        LDContext.getName()

      • anonymous

        public ContextBuilder anonymous​(boolean anonymous)
        Sets whether the context is only intended for flag evaluations and should not be indexed by LaunchDarkly.

        The default value is false. False means that this LDContext represents an entity such as a user that you want to be able to see on the LaunchDarkly dashboard.

        Setting anonymous to true excludes this context from the database that is used by the dashboard. It does not exclude it from analytics event data, so it is not the same as making attributes private; all non-private attributes will still be included in events and data export. There is no limitation on what other attributes may be included (so, for instance, anonymous does not mean there is no name), and the context will still have whatever key you have given it.

        This value is also addressable in evaluations as the attribute name "anonymous". It is always treated as a boolean true or false in evaluations.

        Parameters:
        anonymous - true if the context should be excluded from the LaunchDarkly database
        Returns:
        the builder
        See Also:
        LDContext.isAnonymous()

      • set

        public ContextBuilder set​(java.lang.String attributeName,
                          LDValue value)
        Sets the value of any attribute for the context.

        This includes only attributes that are addressable in evaluations-- not metadata such as privateAttributes(String...). If attributeName is "privateAttributes", you will be setting an attribute with that name which you can use in evaluations or to record data for your own purposes, but it will be unrelated to privateAttributes(String...).

        This method uses the LDValue type to represent a value of any JSON type: null, boolean, number, string, array, or object. For all attribute names that do not have special meaning to LaunchDarkly, you may use any of those types. Values of different JSON types are always treated as different values: for instance, null, false, and the empty string "" are not the the same, and the number 1 is not the same as the string "1".

        The following attribute names have special restrictions on their value types, and any value of an unsupported type will be ignored (leaving the attribute unchanged):

        The attribute name "_meta" is not allowed, because it has special meaning in the JSON schema for contexts; any attempt to set an attribute with this name has no effect. Also, any attempt to set an attribute with an empty or null name has no effect.

        Values that are JSON arrays or objects have special behavior when referenced in flag/segment rules.

        A value of null or LDValue.ofNull() is equivalent to removing any current non-default value of the attribute. Null is not a valid attribute value in the LaunchDarkly model; any expressions in feature flags that reference an attribute with a null value will behave as if the attribute did not exist.

        Parameters:
        attributeName - the attribute name to set
        value - the value to set
        Returns:
        the builder
        See Also:
        set(String, boolean), set(String, int), set(String, double), set(String, String), trySet(String, LDValue)

      • set

        public ContextBuilder set​(java.lang.String attributeName,
                          int value)
        Same as set(String, LDValue) for an integer numeric value.
        Parameters:
        attributeName - the attribute name to set
        value - the value to set
        Returns:
        the builder
        See Also:
        set(String, LDValue)

      • set

        public ContextBuilder set​(java.lang.String attributeName,
                          double value)
        Same as set(String, LDValue) for a double-precision numeric value.
        Parameters:
        attributeName - the attribute name to set
        value - the value to set
        Returns:
        the builder
        See Also:
        set(String, LDValue)

      • set

        public ContextBuilder set​(java.lang.String attributeName,
                          java.lang.String value)
        Same as set(String, LDValue) for a string value.
        Parameters:
        attributeName - the attribute name to set
        value - the value to set
        Returns:
        the builder
        See Also:
        set(String, LDValue)

      • trySet

        public boolean trySet​(java.lang.String attributeName,
                      LDValue value)
        Same as set(String, LDValue), but returns a boolean indicating whether the attribute was successfully set.
        Parameters:
        attributeName - the attribute name to set
        value - the value to set
        Returns:
        true if successful; false if the name was invalid or the value was not an allowed type for that attribute

      • privateAttributes

        public ContextBuilder privateAttributes​(java.lang.String... attributeRefs)
        Designates any number of context attributes, or properties within them, as private: that is, their values will not be recorded by LaunchDarkly.

        Each parameter can be either a simple attribute name (like "email"), or an attribute reference in the syntax described for AttributeRef (like "/address/street").

        Parameters:
        attributeRefs - attribute references to mark as private
        Returns:
        the builder

      • privateAttributes

        public ContextBuilder privateAttributes​(AttributeRef... attributeRefs)
        Equivalent to privateAttributes(String...), but uses the AttributeRef type.

        Application code is unlikely to need to use the AttributeRef type directly; however, in cases where you are constructing LDContexts constructed repeatedly with the same set of private attributes, if you are also using complex private attribute path references such as "/address/street", converting this to an AttributeRef once and reusing it in many privateAttribute calls is slightly more efficient than passing a string (since it does not need to parse the path repeatedly).

        Parameters:
        attributeRefs - attribute references to mark as private
        Returns:
        the builder