org.infinispan.tree
Class Fqn

java.lang.Object
  extended by org.infinispan.tree.Fqn
All Implemented Interfaces:
Externalizable, Serializable, Comparable<Fqn>

@Immutable
public class Fqn
extends Object
implements Comparable<Fqn>, Externalizable

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 Summary
protected  List<Object> elements
           
static Fqn ROOT
          Immutable root Fqn.
static String SEPARATOR
          Separator between FQN elements.
protected  int size
           
protected  String stringRepresentation
          A cached string representation of this Fqn, used by toString to it isn't calculated again every time.
 
Constructor Summary
Fqn()
          Public to satisfy Externalization.
 
Method Summary
protected  int calculateHashCode()
          Calculates a hash code by summing the hash code of all elements.
 int compareTo(Fqn fqn)
          Compares this Fqn to another using FqnComparator.
 boolean equals(Object obj)
          Returns true if obj is a Fqn with the same elements.
static Fqn fromElements(Object... elements)
          Retrieves an Fqn that represents the array of elements passed in.
static Fqn fromExternalStream(ObjectInput in)
          Retrieves an Fqn read from an object input stream, typically written to using writeExternal(java.io.ObjectOutput).
static Fqn fromList(List names)
          Retrieves an Fqn that represents the list of elements passed in.
static Fqn fromList(List names, boolean safe)
          Retrieves an Fqn that represents the list of elements passed in.
static Fqn fromRelativeElements(Fqn base, Object... relativeElements)
          Retrieves an Fqn that represents the array of elements passed in, relative to the base Fqn.
static Fqn fromRelativeFqn(Fqn base, Fqn relative)
          Retrieves an Fqn that represents the absolute Fqn of the relative Fqn passed in.
static Fqn fromRelativeList(Fqn base, List relativeElements)
          Retrieves an Fqn that represents the List of elements passed in, relative to the base Fqn.
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:
 Object get(int n)
           
 Fqn getAncestor(int generation)
          Obtains an ancestor of the current Fqn.
 Object getLastElement()
           
 String getLastElementAsString()
          If this is the root, returns SEPARATOR.
 Fqn getParent()
          Returns the parent of this Fqn.
protected  String getStringRepresentation(List elements)
           
 Fqn getSubFqn(int startIndex, int endIndex)
          Obtains a sub-Fqn from the given Fqn.
 boolean hasElement(Object element)
           
 int hashCode()
          Returns a hash code with Fqn elements.
 boolean isChildOf(Fqn parentFqn)
          Returns true if this Fqn is child of parentFqn.
 boolean isChildOrEquals(Fqn parentFqn)
          Returns true if this Fqn is equals or the child of parentFqn.
 boolean isDirectChildOf(Fqn parentFqn)
          Returns true if this Fqn is a direct child of a given Fqn.
 boolean isRoot()
          Returns true if this is a root Fqn.
 List peekElements()
          Peeks into the elements that build up this Fqn.
 void readExternal(ObjectInput in)
           
 Fqn replaceAncestor(Fqn oldAncestor, Fqn newAncestor)
          Creates a new Fqn whose ancestor has been replaced with the new ancestor passed in.
static Fqn root()
           
 int size()
           
 String toString()
          Returns this Fqn as a string, prefixing the first element with a SEPARATOR and joining each subsequent element with a SEPARATOR.
 void writeExternal(ObjectOutput out)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

SEPARATOR

public static final String SEPARATOR
Separator between FQN elements.

See Also:
Constant Field Values

elements

protected List<Object> elements

size

protected int size

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.

Constructor Detail

Fqn

public Fqn()
Public to satisfy Externalization. // TODO: Remove this ctor as well as Externalization!!

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

fromList

public static Fqn fromList(List names,
                           boolean safe)
Retrieves an Fqn that represents the list of elements passed in.

Parameters:
names - list of elements that comprise the Fqn
safe - if true, the list passed in is not defensively copied but used directly. Use with care. Make sure you know what you are doing before you pass in a true value to safe, as it can have adverse effects on performance or correctness. The defensive copy of list elements is not just for safety but also for performance as an appropriare List implementation is used, which works well with Fqn operations.
Returns:
an Fqn

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

fromExternalStream

public static Fqn fromExternalStream(ObjectInput in)
                              throws IOException,
                                     ClassNotFoundException
Retrieves an Fqn read from an object input stream, typically written to using writeExternal(java.io.ObjectOutput).

Parameters:
in - input stream
Returns:
an Fqn
Throws:
IOException - in the event of a problem reading the stream
ClassNotFoundException - in the event of classes that comprise the element list of this Fqn not being found
Since:
4.0

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.

getLastElement

public Object getLastElement()
Returns:
the last element in the Fqn.
See Also:
getLastElementAsString()

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

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException
Specified by:
writeExternal in interface Externalizable
Throws:
IOException

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException
Specified by:
readExternal in interface Externalizable
Throws:
IOException
ClassNotFoundException

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(List 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 final 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 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 using FqnComparator.

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.


Copyright © 2009 JBoss, a division of Red Hat. All Rights Reserved.