Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  package org.infinispan.tree;
  
  
  
 
 import java.util.List;
 import java.util.Set;

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<String> abc = Fqn.fromString("/people/Smith/Joe/");
 Node joesmith = Cache.getRoot().getChild(abc);
 
Alternatively, the same Fqn could be constructed using a List<Object> or varargs:
 Fqn<String> abc = Fqn.fromElements("people", "Smith", "Joe");
 
This is a bit more efficient to construct.

Note that

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

is not the same as

Fqn<String> 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<someBigNumber; i++) { cache.get(Fqn.fromString("/a/b/c"), "key" + i); } instead, do: // Much better Fqn f = Fqn.fromString("/a/b/c"); for (int i=0; i<someBigNumber; i++) { cache.get(f, "key" + i); }

Author(s):
(various)
Since:
4.0
 
 public class Fqn implements Comparable<Fqn>, Serializable {
   
Separator between FQN elements.
 
    public static final String SEPARATOR = "/";
 
    private final Object[] elements;
    private transient int hash_code = 0;

   
Immutable root Fqn.
 
    public static final Fqn ROOT = new Fqn();

   
A cached string representation of this Fqn, used by toString to it isn't calculated again every time.
 
    protected String stringRepresentation;
    private static final Object[] EMPTY_ARRAY = .;
 
    // ----------------- START: Private constructors for use by factory methods only. ----------------------
 
    private Fqn(Object... elements) {
       this. = elements;
    }

   
If safe is false, Collections.unmodifiableList() is used to wrap the list passed in. This is an optimisation so Fqn.fromString(), probably the most frequently used factory method, doesn't end up needing to use the unmodifiableList() since it creates the list internally.

Parameters:
names List of names
 
    private Fqn(List<?> names) {
       if (names != null)
          = names.toArray();
      else
          = ;
   }
   private Fqn(Fqn baseObject... relative) {
       = new Object[base.elements.length + relative.length];
      System.arraycopy(base.elements, 0, , 0, base.elements.length);
      System.arraycopy(relative, 0, base.elements.lengthrelative.length);
   }
   // ----------------- END: Private constructors for use by factory methods only. ----------------------

   
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
   @SuppressWarnings("unchecked")
   public static Fqn fromList(List<?> names) {
      return new Fqn(names);
   }

   
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
   public static Fqn fromElements(Object... elements) {
      Object[] copy = new Object[elements.length];
      System.arraycopy(elements, 0, copy, 0, elements.length);
      return new Fqn(copy);
   }

   
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
   public static Fqn fromRelativeFqn(Fqn baseFqn relative) {
      return new Fqn(baserelative.elements);
   }

   
Retrieves an Fqn that represents the List<Object> of elements passed in, relative to the base Fqn.

Parameters:
base base Fqn
relativeElements relative List<Object> of elements
Returns:
an Fqn
Since:
4.0
   public static Fqn fromRelativeList(Fqn baseList<?> relativeElements) {
      return new Fqn(baserelativeElements.toArray());
   }

   
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
   public static Fqn fromRelativeElements(Fqn baseObject... relativeElements) {
      return new Fqn(baserelativeElements);
   }

   
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<String> constructed from the string representation passed in
   public static Fqn fromString(String stringRepresentation) {
      if (stringRepresentation == null || stringRepresentation.equals() || stringRepresentation.length() == 0)
         return root();
      String toMatch = stringRepresentation.startsWith() ? stringRepresentation.substring(1) : stringRepresentation;
      Object[] el = toMatch.split();
      return new Fqn(el);
   }

   
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
   public Fqn getAncestor(int generation) {
      if (generation == 0) return root();
      return getSubFqn(0, generation);
   }

   
Obtains a sub-Fqn from the given Fqn. Literally performs elements.subList(startIndex, endIndex)

Parameters:
startIndex starting index
endIndex end index
Returns:
a subFqn
   public Fqn getSubFqn(int startIndexint endIndex) {
      if (endIndex < startIndexthrow new IllegalArgumentException("End index cannot be less than the start index!");
      int len = endIndex - startIndex;
      Object[] el = new Object[len];
      System.arraycopy(startIndexel, 0, len);
      return new Fqn(el);
   }

   

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

   

Parameters:
n index of the element to return
Returns:
Returns the nth element in the Fqn.
   public Object get(int n) {
      return [n];
   }

   

Returns:
the last element in the Fqn.
See also:
getLastElementAsString()
   public Object getLastElement() {
      if (isRoot()) return null;
      return [. - 1];
   }

   

Parameters:
element element to find
Returns:
true if the Fqn contains this element, false otherwise.
   public boolean hasElement(Object element) {
      return indexOf(element) != -1;
   }
   private int indexOf(Object element) {
      if (element == null) {
         for (int i = 0; i < .i++) {
            if ([i] == nullreturn i;
         }
      } else {
         for (int i = 0; i < .i++) {
            if (element.equals([i])) return i;
         }
      }
      return -1;
   }

   
Returns true if obj is a Fqn with the same elements.
   public boolean equals(Object obj) {
      if (this == obj) {
         return true;
      }
      if (!(obj instanceof Fqn)) {
         return false;
      }
      Fqn other = (Fqnobj;
      if (. != other.elements.lengthreturn false;
      for (int i = . - 1; i >= 0; i--) {
         if (!Util.safeEquals([i], other.elements[i])) return false;
      }
      return true;
   }

   
Returns a hash code with Fqn elements.
   public int hashCode() {
      if ( == 0) {
          = calculateHashCode();
      }
      return ;
   }

   
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(); // "/"
 
   public String toString() {
      if ( == null) {
      }
      return ;
   }

   
Returns true if this Fqn is child of parentFqn. Example usage:
 Fqn<String> f1 = Fqn.fromString("/a/b");
 Fqn<String> 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
   public boolean isChildOf(Fqn parentFqn) {
      return parentFqn.elements.length != . && isChildOrEquals(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.
   public boolean isDirectChildOf(Fqn parentFqn) {
      return . == parentFqn.elements.length + 1 && isChildOf(parentFqn);
   }

   
Returns true if this Fqn is equals or the child of parentFqn. Example usage:
 Fqn<String> f1 = Fqn.fromString("/a/b");
 Fqn<String> 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.
   public boolean isChildOrEquals(Fqn parentFqn) {
      Object[] parentEl = parentFqn.elements;
      if (parentEl.length > .) {
         return false;
      }
      for (int i = parentEl.length - 1; i >= 0; i--) {
         if (!Util.safeEquals(parentEl[i], [i])) return false;
      }
      return true;
   }

   
Calculates a hash code by summing the hash code of all elements.

Returns:
a calculated hashcode
   protected int calculateHashCode() {
      int hashCode = 19;
      for (Object o : hashCode = 31 * hashCode + (o == null ? 0 : o.hashCode());
      if (hashCode == 0) hashCode = 0xDEADBEEF; // degenerate case
      return hashCode;
   }
   protected String getStringRepresentation(Object[] elements) {
      StringBuilder builder = new StringBuilder();
      for (Object e : elements) {
         // incase user element 'e' does not implement equals() properly, don't rely on their implementation.
         if (!.equals(e) && !"".equals(e)) {
            builder.append();
            builder.append(e);
         }
      }
      return builder.length() == 0 ?  : builder.toString();
   }


   
Returns the parent of this Fqn. The parent of the root node is ROOT. Examples:
 Fqn<String> f1 = Fqn.fromString("/a");
 Fqn<String> 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
   public Fqn getParent() {
      switch (.) {
         case 0:
         case 1:
            return root();
         default:
            return getSubFqn(0, . - 1);
      }
   }
   public static Fqn root()  // declared final so compilers can optimise and in-line.
   {
      return ;
   }

   
Returns true if this is a root Fqn.

Returns:
true if the Fqn is Fqn.ROOT.
   public boolean isRoot() {
      return . == 0;
   }

   
If this is the root, returns SEPARATOR.

Returns:
a String representation of the last element that makes up this Fqn.
   public String getLastElementAsString() {
      if (isRoot()) {
         return ;
      } else {
         Object last = getLastElement();
         if (last instanceof String)
            return (Stringlast;
         else
            return String.valueOf(getLastElement());
      }
   }

   
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
   public List<ObjectpeekElements() {
      return Arrays.asList();
   }

   
Compares this Fqn to another
   public int compareTo(Fqn fqn) {
      return ..compare(thisfqn);
   }

   
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.
   public Fqn replaceAncestor(Fqn oldAncestorFqn newAncestor) {
      if (!isChildOf(oldAncestor))
         throw new IllegalArgumentException("Old ancestor must be an ancestor of the current Fqn!");
      Fqn subFqn = this.getSubFqn(oldAncestor.size(), size());
      return Fqn.fromRelativeFqn(newAncestorsubFqn);
   }
   public static class Externalizer extends AbstractExternalizer<Fqn> {
      @Override
      public void writeObject(ObjectOutput outputFqn fqnthrows IOException {
         output.writeInt(fqn.elements.length);
         for (Object element : fqn.elementsoutput.writeObject(element);
      }
      @Override
      public Fqn readObject(ObjectInput inputthrows IOExceptionClassNotFoundException {
         int size = input.readInt();
         Object[] elements = new Object[size];
         for (int i = 0; i < sizei++) elements[i] = input.readObject();
         return new Fqn(elements);
      }
      @Override
      public Set<Class<? extends Fqn>> getTypeClasses() {
         return Util.<Class<? extends Fqn>>asSet(Fqn.class);
      }
   }
New to GrepCode? Check out our FAQ X