Package com.launchdarkly.sdk

Class LDContext

  • All Implemented Interfaces:
    JsonSerializable
    public final class LDContext
extends java.lang.Object
implements JsonSerializable
    A collection of attributes that can be referenced in flag evaluations and analytics events.

    LDContext is the newer replacement for the previous, less flexible LDUser type. The current SDK still supports LDUser, but LDContext is now the preferred model and may entirely replace LDUser in the future.

    To create an LDContext of a single kind, such as a user, you may use create(String) or create(ContextKind, String) when only the key matters; or, to specify other attributes, use builder(String).

    To create an LDContext with multiple kinds, use createMulti(LDContext...) or multiBuilder().

    An LDContext can be in an error state if it was built with invalid attributes. See isValid() and getError().

    LaunchDarkly defines a standard JSON encoding for contexts, used by the JavaScript SDK and also in analytics events. LDContext can be converted to and from JSON in any of these ways:

    1. With JsonSerialization.
    2. With Gson, if and only if you configure your Gson instance with LDGson.
    3. With Jackson, if and only if you configure your ObjectMapper instance with LDJackson.

    To learn more about contexts, read the documentation.

    • Method Detail

      • createMulti

        public static LDContext createMulti​(LDContext... contexts)
        Creates a multi-kind LDContext out of the specified single-kind LDContexts.

        To create a single-kind Context, use create(String), create(ContextKind, String), or builder(String).

        For the returned LDContext to be valid, the contexts list must not be empty, and all of its elements must be valid LDContexts. Otherwise, the returned LDContext will be invalid as reported by getError().

        If only one context parameter is given, the method returns that same context.

        If the nested context is multi-kind, this is exactly equivalent to adding each of the individual kinds from it separately. For instance, in the following example, "multi1" and "multi2" end up being exactly the same: 

        
     LDContext c1 = LDContext.create(ContextKind.of("kind1"), "key1");
     LDContext c2 = LDContext.create(ContextKind.of("kind2"), "key2");
     LDContext c3 = LDContext.create(ContextKind.of("kind3"), "key3");

     LDContext multi1 = LDContext.createMulti(c1, c2, c3);

     LDContext c1plus2 = LDContext.createMulti(c1, c2);
     LDContext multi2 = LDContext.createMulti(c1plus2, c3);
        Parameters:
        contexts - a list of contexts
        Returns:
        an LDContext
        See Also:
        multiBuilder()

      • fromUser

        @Deprecated
public static LDContext fromUser​(LDUser user)
        Deprecated.
        use LDContext directly instead.
        Converts a user to an equivalent LDContext instance.

        This method is used by the SDK whenever an application passes a LDUser instance to methods such as identify. The SDK operates internally on the LDContext model, which is more flexible than the older LDUser model: an L User can always be converted to an LDContext, but not vice versa. The ContextKind of the resulting Context is ContextKind.DEFAULT ("user").

        Because there is some overhead to this conversion, it is more efficient for applications to construct an LDContext and pass that to the SDK, rather than an LDUser. This is also recommended because the LDUser type may be removed in a future version of the SDK.

        If the user parameter is null, or if the user has a null key, the method returns an LDContext in an invalid state (see isValid()).

        Parameters:
        user - an LDUser object
        Returns:
        an LDContext with the same attributes as the LDUser

      • builderFromContext

        public static ContextBuilder builderFromContext​(LDContext context)
        Creates a builder whose properties are the same as an existing single-kind LDContext.

        You may then change the builder's state in any way and call ContextBuilder.build() to create a new independent LDContext.

        Parameters:
        context - the context to copy from
        Returns:
        a builder
        See Also:
        builder(String)

      • isValid

        public boolean isValid()
        Returns true for a valid LDContext, false for an invalid one.

        A valid context is one that can be used in SDK operations. An invalid context is one that is missing necessary attributes or has invalid attributes, indicating an incorrect usage of the SDK API. The only ways for a context to be invalid are:

        • It has a disallowed value for the kind property. See ContextKind.
        • It is a single-kind context whose key is empty.
        • It is a multi-kind context that does not have any kinds. See createMulti(LDContext...).
        • It is a multi-kind context where the same kind appears more than once.
        • It is a multi-kind context where at least one of the nested LDContexts has an error.
        • It was created with fromUser(LDUser) from a null LDUser reference, or from an LDUser that had a null key.

        In any of these cases, isValid() will return false, and getError() will return a description of the error.

        Since in normal usage it is easy for applications to be sure they are using context kinds correctly, and because throwing an exception is undesirable in application code that uses LaunchDarkly, the SDK stores the error state in the LDContext itself and checks for such errors at the time the Context is used, such as in a flag evaluation. At that point, if the context is invalid, the operation will fail in some well-defined way as described in the documentation for that method, and the SDK will generally log a warning as well. But in any situation where you are not sure if you have a valid LDContext, you can check isValid() or getError().

        Returns:
        true if the context is valid
        See Also:
        getError()

      • getError

        public java.lang.String getError()
        Returns null for a valid LDContext, or an error message for an invalid one.

        If this is null, then isValid() is true. If it is non-null, then isValid() is false.

        Returns:
        an error description or null
        See Also:
        isValid()

      • isAnonymous

        public boolean isAnonymous()
        Returns true if this context is only intended for flag evaluations and will 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.

        Returns:
        true if the context should be excluded from the LaunchDarkly database
        See Also:
        ContextBuilder.anonymous(boolean)

      • getValue

        public LDValue getValue​(java.lang.String attributeName)
        Looks up the value of any attribute of the context by name.

        This includes only attributes that are addressable in evaluations-- not metadata such as getPrivateAttribute(int).

        For a single-kind context, the attribute name can be any custom attribute that was set by methods like ContextBuilder.set(String, boolean). It can also be one of the built-in ones like "kind", "key", or "name"; in such cases, it is equivalent to getKind(), getKey(), or getName(), except that the value is returned using the general-purpose LDValue type.

        For a multi-kind context, the only supported attribute name is "kind". Use getIndividualContext(int) or getIndividualContext(ContextKind) to inspect the LDContext for a particular kind and then get its attributes.

        This method does not support complex expressions for getting individual values out of JSON objects or arrays, such as "/address/street". Use getValue(AttributeRef) with an AttributeRef for that purpose.

        If the value is found, the return value is the attribute value, using the type LDValue to represent a value of any JSON type.

        If there is no such attribute, the return value is LDValue.ofNull() (the method never returns a Java null). An attribute that actually exists cannot have a null value.

        Parameters:
        attributeName - the desired attribute name
        Returns:
        the value or LDValue.ofNull()
        See Also:
        getValue(AttributeRef), ContextBuilder.set(String, String)

      • getValue

        public LDValue getValue​(AttributeRef attributeRef)
        Looks up the value of any attribute of the context, or a value contained within an attribute, based on an AttributeRef.

        This includes only attributes that are addressable in evaluations-- not metadata such as getPrivateAttribute(int).

        This implements the same behavior that the SDK uses to resolve attribute references during a flag evaluation. In a single-kind context, the AttributeRef can represent a simple attribute name-- either a built-in one like "name" or "key", or a custom attribute that was set by methods like ContextBuilder.set(String, String)-- or, it can be a slash-delimited path using a JSON-Pointer-like syntax. See AttributeRef for more details.

        For a multi-kind context, the only supported attribute name is "kind". Use getIndividualContext(int) or getIndividualContext(ContextKind) to inspect the LDContext for a particular kind and then get its attributes.

        This method does not support complex expressions for getting individual values out of JSON objects or arrays, such as "/address/street". Use getValue(AttributeRef) with an AttributeRef for that purpose.

        If the value is found, the return value is the attribute value, using the type LDValue to represent a value of any JSON type.

        If there is no such attribute, the return value is LDValue.ofNull() (the method never returns a Java null). An attribute that actually exists cannot have a null value.

        Parameters:
        attributeRef - an attribute reference
        Returns:
        the attribute value

      • getCustomAttributeNames

        public java.lang.Iterable<java.lang.String> getCustomAttributeNames()
        Returns the names of all non-built-in attributes that have been set in this context.

        For a single-kind context, this includes all the names that were passed to any of the overloads of ContextBuilder.set(String, LDValue) as long as the values were not null (since a null value in LaunchDarkly is equivalent to the attribute not being set).

        For a multi-kind context, there are no such names.

        Returns:
        an iterable of strings (may be empty, but will never be null)

      • getIndividualContextCount

        public int getIndividualContextCount()
        Returns the number of context kinds in this context.

        For a valid single-kind context, this returns 1. For a multi-kind context, it returns the number of kinds that were added with createMulti(LDContext...) or multiBuilder(). For an invalid context, it returns zero.

        Returns:
        the number of context kinds

      • getIndividualContext

        public LDContext getIndividualContext​(int index)
        Returns the single-kind LDContext corresponding to one of the kinds in this context.

        If this method is called on a single-kind LDContext, then the only allowable value for index is zero, and the return value on success is the same LDContext. If the method is called on a multi-kind context, then index must be non-negative and less than the number of kinds (that is, less than the return value of getIndividualContextCount()), and the return value on success is one of the individual LDContexts within.

        Parameters:
        index - the zero-based index of the context to get
        Returns:
        an LDContext, or null if the index was out of range

      • getIndividualContext

        public LDContext getIndividualContext​(ContextKind kind)
        Returns the single-kind LDContext corresponding to one of the kinds in this context.

        If this method is called on a single-kind LDContext, then the only allowable value for kind is the same as getKind(), and the return value on success is the same LDContext. If the method is called on a multi-kind context, then kind should be match the kind of one of the contexts that was added with createMulti(LDContext...) or multiBuilder(), and the return value on success is the corresponding individual LDContext within.

        Parameters:
        kind - the context kind to get; if null, defaults to ContextKind.DEFAULT
        Returns:
        an LDContext, or null if that kind was not found

      • getIndividualContext

        public LDContext getIndividualContext​(java.lang.String kind)
        Same as getIndividualContext(ContextKind), but specifies the kind as a plain string.
        Parameters:
        kind - the context kind to get
        Returns:
        an LDContext, or null if that kind was not found

      • getPrivateAttribute

        public AttributeRef getPrivateAttribute​(int index)
        Retrieves one of the private attribute references that were specified for this context.
        Parameters:
        index - a non-negative index that must be less than getPrivateAttributeCount()
        Returns:
        an AttributeRef, or null if the index was out of range

      • getFullyQualifiedKey

        public java.lang.String getFullyQualifiedKey()
        Returns a string that describes the LDContext uniquely based on kind and key values.

        This value is used whenever LaunchDarkly needs a string identifier based on all of the kind and key values in the context; the SDK may use this for caching previously seen contexts, for instance.

        Returns:
        the fully-qualified key

      • toString

        public java.lang.String toString()
        Returns a string representation of the context.

        For a valid context, this is currently defined as being the same as the JSON representation, since that is the simplest way to represent all of the LDContext properties. However, application code should not rely on toString() always being the same as the JSON representation. If you specifically want the latter, use JsonSerialization.serialize(JsonSerializable).

        For an invalid context, toString() returns a description of why it is invalid.

        Overrides:
        toString in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object other)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object