Package com.launchdarkly.sdk

Class LDValue

java.lang.Object
com.launchdarkly.sdk.LDValue
All Implemented Interfaces:
JsonSerializable
public abstract class LDValue extends Object implements JsonSerializable
An immutable instance of any data type that is allowed in JSON.

An LDValue instance can be a null (that is, an instance that represents a JSON null value, rather than a Java null reference), a boolean, a number (always encoded internally as double-precision floating-point, but can be treated as an integer), a string, an ordered list of LDValue values (a JSON array), or a map of strings to LDValue values (a JSON object). It is easily convertible to standard Java types.

This can be used to represent complex data in a context attribute (see ContextBuilder.set(String, LDValue)), or to get a feature flag value that uses a complex type or that does not always use the same type (see the client's jsonValueVariation methods).

While the LaunchDarkly SDK uses Gson internally for JSON parsing, it uses LDValue rather than Gson's JsonElement type for two reasons. First, this allows Gson types to be excluded from the API, so the SDK does not expose this dependency and cannot cause version conflicts in applications that use Gson themselves. Second, Gson's array and object types are mutable, which can cause concurrency risks.

LDValue can be converted to and from JSON in any of these ways:

  1. With the LDValue methods toJsonString() and parse(String).
  2. With JsonSerialization.
  3. With Gson, if and only if you configure your Gson instance with LDGson.
  4. With Jackson, if and only if you configure your ObjectMapper instance with LDJackson.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    LDValue.Convert
    Predefined instances of LDValue.Converter for commonly used types.
    static class 
    LDValue.Converter<T>
    Defines a conversion between LDValue and some other type.

  • Constructor Summary

    Constructors
    Constructor
    Description
    LDValue()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static LDValue
    arrayOf(LDValue... values)
    Creates an array value from the specified values.
    boolean
    booleanValue()
    Returns this value as a boolean if it is explicitly a boolean.
    static ArrayBuilder
    buildArray()
    Starts building an array value.
    static ObjectBuilder
    buildObject()
    Starts building an object value.
    double
    doubleValue()
    Returns this value as a double if it is numeric.
    boolean
    equals(Object o)
    Returns true if the other object is an LDValue that is logically equal.
    float
    floatValue()
    Returns this value as a float if it is numeric.
    LDValue
    get(int index)
    Returns an array element by index.
    LDValue
    get(String name)
    Returns an object property by name.
    abstract LDValueType
    getType()
    Gets the JSON type for this value.
    int
    hashCode()
     
    int
    intValue()
    Returns this value as an int if it is numeric.
    boolean
    isInt()
    Tests whether this value is a number that is also an integer.
    boolean
    isNull()
    Tests whether this value is a null.
    boolean
    isNumber()
    Tests whether this value is a number (not a numeric string).
    boolean
    isString()
    Tests whether this value is a string.
    Iterable<String>
    keys()
    Enumerates the property names in an object.
    long
    longValue()
    Returns this value as a long if it is numeric.
    static LDValue
    normalize(LDValue value)
    Returns the same value if non-null, or ofNull() if null.
    static LDValue
    of(boolean value)
    Returns an instance for a boolean value.
    static LDValue
    of(double value)
    Returns an instance for a numeric value.
    static LDValue
    of(float value)
    Returns an instance for a numeric value.
    static LDValue
    of(int value)
    Returns an instance for a numeric value.
    static LDValue
    of(long value)
    Returns an instance for a numeric value.
    static LDValue
    of(String value)
    Returns an instance for a string value (or a null).
    static LDValue
    ofNull()
    Returns an instance for a null value.
    static LDValue
    parse(String json)
    Parses an LDValue from a JSON representation.
    int
    size()
    Returns the number of elements in an array or object.
    String
    stringValue()
    Returns this value as a String if it is a string.
    String
    toJsonString()
    Converts this value to its JSON serialization.
    String
    toString()
    Returns a string representation of this value.
    Iterable<LDValue>
    values()
    Enumerates the values in an array or object.
    <T> Iterable<T>
    valuesAs(LDValue.Converter<T> converter)
    Enumerates the values in an array or object, converting them to a specific type.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • LDValue

      public LDValue()

  • Method Details

    • normalize

      public static LDValue normalize(LDValue value)
      Returns the same value if non-null, or ofNull() if null.
      Parameters:
      value - an LDValue or null
      Returns:
      an LDValue which will never be a null reference

    • ofNull

      public static LDValue ofNull()
      Returns an instance for a null value. The same instance is always used.
      Returns:
      an LDValue containing null

    • of

      public static LDValue of(boolean value)
      Returns an instance for a boolean value. The same instances for true and false are always used.
      Parameters:
      value - a boolean value
      Returns:
      an LDValue containing that value

    • of

      public static LDValue of(int value)
      Returns an instance for a numeric value.
      Parameters:
      value - an integer numeric value
      Returns:
      an LDValue containing that value

    • of

      public static LDValue of(long value)
      Returns an instance for a numeric value.

      Note that the LaunchDarkly service, and most of the SDKs, represent numeric values internally in 64-bit floating-point, which has slightly less precision than a signed 64-bit long; therefore, the full range of long values cannot be accurately represented. If you need to set a context attribute to a numeric value with more significant digits than will fit in a double, it is best to encode it as a string.

      Parameters:
      value - a long integer numeric value
      Returns:
      an LDValue containing that value

    • of

      public static LDValue of(float value)
      Returns an instance for a numeric value.
      Parameters:
      value - a floating-point numeric value
      Returns:
      an LDValue containing that value

    • of

      public static LDValue of(double value)
      Returns an instance for a numeric value.
      Parameters:
      value - a floating-point numeric value
      Returns:
      an LDValue containing that value

    • of

      public static LDValue of(String value)
      Returns an instance for a string value (or a null).
      Parameters:
      value - a nullable String reference
      Returns:
      an LDValue containing a string, or ofNull() if the value was null.

    • buildArray

      public static ArrayBuilder buildArray()
      Starts building an array value. The elements can be of any type supported by LDValue. 
      
     LDValue arrayOfInts = LDValue.buildArray().add(2).add("three").build():
      If the values are all of the same type, you may also use LDValue.Converter.arrayFrom(Iterable) or LDValue.Converter.arrayOf(Object...).
      Returns:
      an ArrayBuilder

    • arrayOf

      public static LDValue arrayOf(LDValue... values)
      Creates an array value from the specified values. The elements can be of any type supported by LDValue. 
      
     LDValue arrayOfMixedValues = LDValue.arrayOf(LDValue.of(2), LDValue.of("three"));
      If the values are all of the same type, you may also use LDValue.Converter.arrayFrom(Iterable) or LDValue.Converter.arrayOf(Object...).
      Parameters:
      values - any number of values
      Returns:
      an immutable array value

    • buildObject

      public static ObjectBuilder buildObject()
      Starts building an object value. 
      
     LDValue objectVal = LDValue.buildObject().put("key", LDValue.int(1)).build():
      If the values are all of the same type, you may also use LDValue.Converter.objectFrom(Map).
      Returns:
      an ObjectBuilder

    • parse

      public static LDValue parse(String json)
      Parses an LDValue from a JSON representation.

      This convenience method is equivalent to using JsonSerialization.deserialize(String, Class) with the LDValue class, except for two things:

      1. You do not have to provide the class parameter.

      2. Parsing errors are thrown as an unchecked RuntimeException that wraps the checked SerializationException, making this method somewhat more convenient in cases such as test code where explicit error handling is less important.

      Parameters:
      json - a JSON string
      Returns:
      an LDValue

    • getType

      public abstract LDValueType getType()
      Gets the JSON type for this value.
      Returns:
      the appropriate LDValueType

    • isNull

      public boolean isNull()
      Tests whether this value is a null.
      Returns:
      true if this is a null value

    • booleanValue

      public boolean booleanValue()
      Returns this value as a boolean if it is explicitly a boolean. Otherwise returns false.
      Returns:
      a boolean

    • isNumber

      public boolean isNumber()
      Tests whether this value is a number (not a numeric string).
      Returns:
      true if this is a numeric value

    • isInt

      public boolean isInt()
      Tests whether this value is a number that is also an integer.

      JSON does not have separate types for integer and floating-point values; they are both just numbers. This method returns true if and only if the actual numeric value has no fractional component, so LDValue.of(2).isInt() and LDValue.of(2.0f).isInt() are both true.

      Returns:
      true if this is an integer value

    • intValue

      public int intValue()
      Returns this value as an int if it is numeric. Returns zero for all non-numeric values.

      If the value is a number but not an integer, it will be rounded toward zero (truncated). This is consistent with Java casting behavior, and with most other LaunchDarkly SDKs.

      Returns:
      an int value

    • longValue

      public long longValue()
      Returns this value as a long if it is numeric. Returns zero for all non-numeric values.

      If the value is a number but not an integer, it will be rounded toward zero (truncated). This is consistent with Java casting behavior, and with most other LaunchDarkly SDKs.

      Returns:
      a long value

    • floatValue

      public float floatValue()
      Returns this value as a float if it is numeric. Returns zero for all non-numeric values.
      Returns:
      a float value

    • doubleValue

      public double doubleValue()
      Returns this value as a double if it is numeric. Returns zero for all non-numeric values.
      Returns:
      a double value

    • isString

      public boolean isString()
      Tests whether this value is a string.
      Returns:
      true if this is a string value

    • stringValue

      public String stringValue()
      Returns this value as a String if it is a string. Returns null for all non-string values.
      Returns:
      a nullable string value

    • size

      public int size()
      Returns the number of elements in an array or object. Returns zero for all other types.
      Returns:
      the number of array elements or object properties

    • keys

      public Iterable<String> keys()
      Enumerates the property names in an object. Returns an empty iterable for all other types.
      Returns:
      the property names

    • values

      public Iterable<LDValue> values()
      Enumerates the values in an array or object. Returns an empty iterable for all other types.
      Returns:
      an iterable of LDValue values

    • valuesAs

      public <T> Iterable<T> valuesAs(LDValue.Converter<T> converter)
      Enumerates the values in an array or object, converting them to a specific type. Returns an empty iterable for all other types.

      This is an efficient method because it does not copy values to a new list, but returns a view into the existing array.

      Example: 

      
     LDValue anArrayOfInts = LDValue.Convert.Integer.arrayOf(1, 2, 3);
     for (int i: anArrayOfInts.valuesAs(LDValue.Convert.Integer)) { println(i); }

      For boolean and numeric types, even though the corresponding Java type is a nullable class like Boolean or Integer, valuesAs will never return a null element; instead, it will use the appropriate default value for the primitive type (false or zero).

      Type Parameters:
      T - the desired type
      Parameters:
      converter - the LDValue.Converter for the specified type
      Returns:
      an iterable of values of the specified type

    • get

      public LDValue get(int index)
      Returns an array element by index. Returns ofNull() if this is not an array or if the index is out of range (will never throw an exception).
      Parameters:
      index - the array index
      Returns:
      the element value or ofNull()

    • get

      public LDValue get(String name)
      Returns an object property by name. Returns ofNull() if this is not an object or if the key is not found (will never throw an exception).
      Parameters:
      name - the property name
      Returns:
      the property value or ofNull()

    • toJsonString

      public String toJsonString()
      Converts this value to its JSON serialization.

      This method is equivalent to passing the LDValue instance to JsonSerialization.serialize(JsonSerializable).

      Returns:
      a JSON string

    • toString

      public String toString()
      Returns a string representation of this value.

      This method currently returns the same JSON serialization as toJsonString(). However, like most toString() implementations, it is intended mainly for convenience in debugging or other use cases where the goal is simply to have a human-readable format; it is not guaranteed to always match toJsonString() in the future. If you need to verify the value type or other properties programmatically, use the getter methods of LDValue.

      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Returns true if the other object is an LDValue that is logically equal.

      This is a deep equality comparison: for JSON arrays each element is compared recursively, and for JSON objects all property names and values must be deeply equal regardless of ordering.

      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object