Package com.launchdarkly.sdk

Class AttributeRef

  • All Implemented Interfaces:
    JsonSerializable, java.lang.Comparable<AttributeRef>
    public final class AttributeRef
extends java.lang.Object
implements JsonSerializable, java.lang.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 Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(AttributeRef o)  
      boolean equals​(java.lang.Object other)  
      static AttributeRef fromLiteral​(java.lang.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.
      static AttributeRef fromPath​(java.lang.String refPath)
      Creates an AttributeRef from a string.
      java.lang.String getComponent​(int index)
      Retrieves a single path component from the attribute reference.
      int getDepth()
      The number of path components in the AttributeRef.
      java.lang.String getError()
      Null for a valid AttributeRef, or a non-null error message for an invalid AttributeRef.
      int hashCode()  
      boolean isValid()
      True for a valid AttributeRef, false for an invalid AttributeRef.
      java.lang.String toString()
      Returns the attribute reference as a string, in the same format used by fromPath(String).

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • fromPath

        public static AttributeRef fromPath​(java.lang.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(String)

      • fromLiteral

        public static AttributeRef fromLiteral​(java.lang.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:
        fromPath(String)

      • 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()

      • getError

        public java.lang.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:
        isValid()

      • 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 java.lang.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 java.lang.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 java.lang.Object
        Returns:
        the attribute reference string (guaranteed non-null)

      • 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

      • compareTo

        public int compareTo​(AttributeRef o)
        Specified by:
        compareTo in interface java.lang.Comparable<AttributeRef>