Package com.launchdarkly.sdk

Class AttributeRef

java.lang.Object
com.launchdarkly.sdk.AttributeRef
All Implemented Interfaces:
JsonSerializable, Comparable<AttributeRef>
public final class AttributeRef extends Object implements JsonSerializable, Comparable<AttributeRef>
An attribute name or path expression identifying a value within an LDContext.

Applications are unlikely to need to use the AttributeRef type directly, but see below for details of the string attribute reference syntax used by methods like ContextBuilder.privateAttributes(String...).

The reason to use this type directly is to avoid repetitive string parsing in code where efficiency is a priority; AttributeRef parses its contents once when it is created, and is immutable afterward. If an AttributeRef instance was created from an invalid string, it is considered invalid and its getError() method will return a non-null error.

The string representation of an attribute reference in LaunchDarkly JSON data uses the following syntax:

  • If the first character is not a slash, the string is interpreted literally as an attribute name. An attribute name can contain any characters, but must not be empty.
  • If the first character is a slash, the string is interpreted as a slash-delimited path where the first path component is an attribute name, and each subsequent path component is the name of a property in a JSON object. Any instances of the characters "/" or "~" in a path component are escaped as "~1" or "~0" respectively. This syntax deliberately resembles JSON Pointer, but no JSON Pointer behaviors other than those mentioned here are supported.

  • Method Details

    • fromPath

      public static AttributeRef fromPath(String refPath)
      Creates an AttributeRef from a string. For the supported syntax and examples, see comments on the AttributeRef type.

      This method always returns an AttributeRef that preserves the original string, even if validation fails, so that calling toString() (or serializing the AttributeRef to JSON) will produce the original string. If validation fails, getError() will return a non-null error and any SDK method that takes this AttributeRef as a parameter will consider it invalid.

      Parameters:
      refPath - an attribute name or path
      Returns:
      an AttributeRef
      See Also:

    • fromLiteral

      public static AttributeRef fromLiteral(String attributeName)
      Similar to fromPath(String), except that it always interprets the string as a literal attribute name, never as a slash-delimited path expression.

      There is no escaping or unescaping, even if the name contains literal '/' or '~' characters. Since an attribute name can contain any characters, this method always returns a valid AttributeRef unless the name is empty.

      For example: AttributeRef.fromLiteral("name") is exactly equivalent to AttributeRef.fromPath("name"). AttributeRef.fromLiteral("a/b") is exactly equivalent to AttributeRef.fromPath("a/b") (since the syntax used by fromPath(String) treats the whole string as a literal as long as it does not start with a slash), or to AttributeRef.fromPath("/a~1b").

      Parameters:
      attributeName - an attribute name
      Returns:
      an AttributeRef
      See Also:

    • isValid

      public boolean isValid()
      True for a valid AttributeRef, false for an invalid AttributeRef.

      An AttributeRef can only be invalid for the following reasons:

      • The input string was empty, or consisted only of "/".
      • A slash-delimited string had a double slash causing one component to be empty, such as "/a//b".
      • A slash-delimited string contained a "~" character that was not followed by "0" or "1".

      Otherwise, the AttributeRef is valid, but that does not guarantee that such an attribute exists in any given LDContext. For instance, fromLiteral("name") is a valid AttributeRef, but a specific LDContext might or might not have a name.

      See comments on the AttributeRef type for more details of the attribute reference synax.

      Returns:
      true if the instance is valid
      See Also:

    • getError

      public String getError()
      Null for a valid AttributeRef, or a non-null error message for an invalid AttributeRef.

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

      Returns:
      an error string or null
      See Also:

    • getDepth

      public int getDepth()
      The number of path components in the AttributeRef.

      For a simple attribute reference such as "name" with no leading slash, this returns 1.

      For an attribute reference with a leading slash, it is the number of slash-delimited path components after the initial slash. For instance, AttributeRef.fromPath("/a/b").getDepth() returns 2.

      For an invalid attribute reference, it returns zero

      Returns:
      the number of path components

    • getComponent

      public String getComponent(int index)
      Retrieves a single path component from the attribute reference.

      For a simple attribute reference such as "name" with no leading slash, getComponent returns the attribute name if index is zero, and null otherwise.

      For an attribute reference with a leading slash, if index is non-negative and less than getDepth(), getComponent returns the path component string at that position.

      Parameters:
      index - the zero-based index of the desired path component
      Returns:
      the path component, or null if not available

    • toString

      public String toString()
      Returns the attribute reference as a string, in the same format used by fromPath(String).

      If the AttributeRef was created with fromPath(String), this value is identical to to the original string. If it was created with fromLiteral(String), the value may be different due to unescaping (for instance, an attribute whose name is "/a" would be represented as "~1a").

      Overrides:
      toString in class Object
      Returns:
      the attribute reference string (guaranteed non-null)

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • compareTo

      public int compareTo(AttributeRef o)
      Specified by:
      compareTo in interface Comparable<AttributeRef>