Package org.infinispan.tree

Class Fqn

  • All Implemented Interfaces:
    Serializable, Comparable<Fqn>
    @Immutable
public class Fqn
extends Object
implements Comparable<Fqn>, Serializable
    A Fully Qualified Name (Fqn) is a list of names (typically Strings but can be any Object), which represent a path to a particular Node in a TreeCache.

    This name can be absolute (i.e., relative from the root node - ROOT), or relative to any node in the cache. Reading the documentation on each API call that makes use of Fqns will tell you whether the API expects a relative or absolute Fqn.

    For instance, using this class to fetch a particular node might look like this. (Here data on "Joe" is kept under the "Smith" surname node, under the "people" tree.) 

     Fqn abc = Fqn.fromString("/people/Smith/Joe/");
 Node joesmith = Cache.getRoot().getChild(abc);
    Alternatively, the same Fqn could be constructed using a List or varargs: 
     Fqn abc = Fqn.fromElements("people", "Smith", "Joe");
    This is a bit more efficient to construct.

    Note that

    Fqn f = Fqn.fromElements("/a/b/c");

    is not the same as

    Fqn f = Fqn.fromString("/a/b/c");

    The former will result in a single Fqn, called "/a/b/c" which hangs directly under Fqn.ROOT.

    The latter will result in 3 Fqns, called "a", "b" and "c", where "c" is a child of "b", "b" is a child of "a", and "a" hangs off Fqn.ROOT.

    Another way to look at it is that the "/" separarator is only parsed when it forms part of a String passed in to Fqn.fromString() and not otherwise.

    Best practices: Always creating Fqns - even when using some factory methods - can be expensive in the long run, and as far as possible we recommend that client code holds on to their Fqn references and reuse them. E.g.: // BAD!! for (int i=0; i instead, do: // Much better Fqn f = Fqn.fromString("/a/b/c"); for (int i=0; i

    Since:
    4.0
    Author:
    (various)
    See Also:
    Serialized Form

      • Field Detail

        • ROOT

          public static final Fqn ROOT
          Immutable root Fqn.

        • stringRepresentation

          protected String stringRepresentation
          A cached string representation of this Fqn, used by toString to it isn't calculated again every time.

      • Method Detail

        • fromList

          public static Fqn fromList​(List<?> names)
          Retrieves an Fqn that represents the list of elements passed in.
          Parameters:
          names - list of elements that comprise the Fqn
          Returns:
          an Fqn
          Since:
          4.0

        • fromElements

          public static Fqn fromElements​(Object... elements)
          Retrieves an Fqn that represents the array of elements passed in.
          Parameters:
          elements - array of elements that comprise the Fqn
          Returns:
          an Fqn
          Since:
          4.0

        • fromRelativeFqn

          public static Fqn fromRelativeFqn​(Fqn base,
                                  Fqn relative)
          Retrieves an Fqn that represents the absolute Fqn of the relative Fqn passed in.
          Parameters:
          base - base Fqn
          relative - relative Fqn
          Returns:
          an Fqn
          Since:
          4.0

        • fromRelativeList

          public static Fqn fromRelativeList​(Fqn base,
                                   List<?> relativeElements)
          Retrieves an Fqn that represents the List of elements passed in, relative to the base Fqn.
          Parameters:
          base - base Fqn
          relativeElements - relative List of elements
          Returns:
          an Fqn
          Since:
          4.0

          • fromRelativeElements

            public static Fqn fromRelativeElements​(Fqn base,
                                       Object... relativeElements)
            Retrieves an Fqn that represents the array of elements passed in, relative to the base Fqn.
            Parameters:
            base - base Fqn
            relativeElements - relative elements
            Returns:
            an Fqn
            Since:
            4.0

          • fromString

            public static Fqn fromString​(String stringRepresentation)
            Returns a new Fqn from a string, where the elements are deliminated by one or more separator (SEPARATOR) characters.

            Example use:
             Fqn.fromString("/a/b/c/");

            is equivalent to:
             Fqn.fromElements("a", "b", "c");
            Parameters:
            stringRepresentation - String representation of the Fqn
            Returns:
            an Fqn constructed from the string representation passed in

          • getAncestor

            public Fqn getAncestor​(int generation)
            Obtains an ancestor of the current Fqn. Literally performs elements.subList(0, generation) such that if generation == Fqn.size() then the return value is the Fqn itself (current generation), and if generation == Fqn.size() - 1 then the return value is the same as Fqn.getParent() i.e., just one generation behind the current generation. generation == 0 would return Fqn.ROOT.
            Parameters:
            generation - the generation of the ancestor to retrieve
            Returns:
            an ancestor of the current Fqn

          • getSubFqn

            public Fqn getSubFqn​(int startIndex,
                     int endIndex)
            Obtains a sub-Fqn from the given Fqn. Literally performs elements.subList(startIndex, endIndex)
            Parameters:
            startIndex - starting index
            endIndex - end index
            Returns:
            a subFqn

          • size

            public int size()
            Returns:
            the number of elements in the Fqn. The root node contains zero.

          • get

            public Object get​(int n)
            Parameters:
            n - index of the element to return
            Returns:
            Returns the nth element in the Fqn.

          • hasElement

            public boolean hasElement​(Object element)
            Parameters:
            element - element to find
            Returns:
            true if the Fqn contains this element, false otherwise.

          • equals

            public boolean equals​(Object obj)
            Returns true if obj is a Fqn with the same elements.
            Overrides:
            equals in class Object

          • hashCode

            public int hashCode()
            Returns a hash code with Fqn elements.
            Overrides:
            hashCode in class Object

          • toString

            public String toString()
            Returns this Fqn as a string, prefixing the first element with a SEPARATOR and joining each subsequent element with a SEPARATOR. If this is the root Fqn, returns SEPARATOR. Example: 
             new Fqn(new Object[] { "a", "b", "c" }).toString(); // "/a/b/c"
 Fqn.ROOT.toString(); // "/"
            Overrides:
            toString in class Object

          • isChildOf

            public boolean isChildOf​(Fqn parentFqn)
            Returns true if this Fqn is child of parentFqn. Example usage: 
             Fqn f1 = Fqn.fromString("/a/b");
 Fqn f2 = Fqn.fromString("/a/b/c");
 assertTrue(f1.isChildOf(f2));
 assertFalse(f1.isChildOf(f1));
 assertFalse(f2.isChildOf(f1));
            Parameters:
            parentFqn - candidate parent to test against
            Returns:
            true if the target is a child of parentFqn

          • isDirectChildOf

            public boolean isDirectChildOf​(Fqn parentFqn)
            Returns true if this Fqn is a direct child of a given Fqn.
            Parameters:
            parentFqn - parentFqn to compare with
            Returns:
            true if this is a direct child, false otherwise.

          • isChildOrEquals

            public boolean isChildOrEquals​(Fqn parentFqn)
            Returns true if this Fqn is equals or the child of parentFqn. Example usage: 
             Fqn f1 = Fqn.fromString("/a/b");
 Fqn f2 = Fqn.fromString("/a/b/c");
 assertTrue(f1.isChildOrEquals(f2));
 assertTrue(f1.isChildOrEquals(f1));
 assertFalse(f2.isChildOrEquals(f1));
            Parameters:
            parentFqn - candidate parent to test against
            Returns:
            true if this Fqn is equals or the child of parentFqn.

          • calculateHashCode

            protected int calculateHashCode()
            Calculates a hash code by summing the hash code of all elements.
            Returns:
            a calculated hashcode

          • getStringRepresentation

            protected String getStringRepresentation​(Object[] elements)

          • getParent

            public Fqn getParent()
            Returns the parent of this Fqn. The parent of the root node is ROOT. Examples: 
             Fqn f1 = Fqn.fromString("/a");
 Fqn f2 = Fqn.fromString("/a/b");
 assertEquals(f1, f2.getParent());
 assertEquals(Fqn.ROOT, f1.getParent().getParent());
 assertEquals(Fqn.ROOT, Fqn.ROOT.getParent());
            Returns:
            the parent Fqn

          • root

            public static Fqn root()

          • isRoot

            public boolean isRoot()
            Returns true if this is a root Fqn.
            Returns:
            true if the Fqn is Fqn.ROOT.

          • getLastElementAsString

            public String getLastElementAsString()
            If this is the root, returns SEPARATOR.
            Returns:
            a String representation of the last element that makes up this Fqn.

          • peekElements

            public List<Object> peekElements()
            Peeks into the elements that build up this Fqn. The list returned is read-only, to maintain the immutable nature of Fqn.
            Returns:
            an unmodifiable list

          • compareTo

            public int compareTo​(Fqn fqn)
            Compares this Fqn to another
            Specified by:
            compareTo in interface Comparable<Fqn>

          • replaceAncestor

            public Fqn replaceAncestor​(Fqn oldAncestor,
                           Fqn newAncestor)
            Creates a new Fqn whose ancestor has been replaced with the new ancestor passed in.
            Parameters:
            oldAncestor - old ancestor to replace
            newAncestor - nw ancestor to replace with
            Returns:
            a new Fqn with ancestors replaced.