org.jboss.cache
Class Fqn<E>

java.lang.Object
  extended by org.jboss.cache.Fqn<E>
All Implemented Interfaces:
java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<Fqn>

@Immutable
public class Fqn<E>
extends java.lang.Object
implements java.lang.Cloneable, java.io.Externalizable, java.lang.Comparable<Fqn>

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 or sometimes a Region in a Cache.

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 an array:
 Fqn abc = new Fqn(new String[] { "people", "Smith", "Joe" });
 
This is a bit more efficient to construct.

Note that

Fqn f = new Fqn("/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.

Version:
$Revision: 1.54 $
See Also:
Serialized Form

Field Summary
static Fqn ROOT
          Immutable root FQN.
static java.lang.String SEPARATOR
          Separator between FQN elements.
 
Constructor Summary
  Fqn()
          Constructs a root Fqn
  Fqn(E... names)
          Constructs a Fqn from an array of names.
  Fqn(Fqn<E> base, E... childNames)
          Constructs a Fqn from a base and two relative names.
  Fqn(Fqn<E> base, Fqn<E> relative)
          Constructs a Fqn from a base and relative Fqn.
  Fqn(Fqn<E> base, java.util.List<E> relative)
          Constructs a Fqn from a base and a list of relative names.
  Fqn(java.util.List<E> names)
          Constructs a FQN from a list of names.
protected Fqn(java.util.List<E> names, boolean safe)
          If safe is false, Collections.unmodifiableList() is used to wrap the list passed in.
 
Method Summary
 Fqn<E> clone()
          Clones the Fqn.
 int compareTo(Fqn Fqn)
          Compares this Fqn to another using FqnComparator.
 boolean equals(java.lang.Object obj)
          Returns true if obj is a Fqn with the same elements.
static Fqn<java.lang.String> fromString(java.lang.String stringRepresentation)
          Returns a new Fqn from a string, where the elements are deliminated by one or more separator (SEPARATOR) characters.

Example use:
 E get(int n)
           
 Fqn<E> getAncestor(int generation)
          Obtains an ancestor of the current Fqn.
 E getLastElement()
           
 java.lang.String getLastElementAsString()
          If this is the root, returns SEPARATOR.
 Fqn<E> getParent()
          Returns the parent of this Fqn.
 Fqn<E> getSubFqn(int startIndex, int endIndex)
          Obtains a sub-Fqn from the given Fqn.
 boolean hasElement(E element)
           
 int hashCode()
          Returns a hash code with Fqn elements.
 boolean isChildOf(Fqn<E> parentFqn)
          Returns true if this Fqn is child of parentFqn.
 boolean isChildOrEquals(Fqn<E> parentFqn)
          Returns true if this Fqn is equals or the child of parentFqn.
 boolean isRoot()
          Returns true if this is a root Fqn.
 java.util.List<E> peekElements()
          Peeks into the elements that build up this Fqn.
 void readExternal(java.io.ObjectInput in)
           
 int size()
           
 java.lang.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(java.io.ObjectOutput out)
           
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

SEPARATOR

public static final java.lang.String SEPARATOR
Separator between FQN elements.

See Also:
Constant Field Values

ROOT

public static final Fqn ROOT
Immutable root FQN.

Constructor Detail

Fqn

public Fqn()
Constructs a root Fqn


Fqn

public Fqn(java.util.List<E> names)
Constructs a FQN from a list of names.

Parameters:
names - List of names

Fqn

protected Fqn(java.util.List<E> names,
              boolean safe)
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
safe - whether this list is referenced externally (safe = false) or not (safe = true).

Fqn

public Fqn(E... names)
Constructs a Fqn from an array of names.

Parameters:
names - Names that comprose this Fqn

Fqn

public Fqn(Fqn<E> base,
           Fqn<E> relative)
Constructs a Fqn from a base and relative Fqn.

Parameters:
base - parent Fqn
relative - Sub-Fqn relative to the parent

Fqn

public Fqn(Fqn<E> base,
           java.util.List<E> relative)
Constructs a Fqn from a base and a list of relative names.

Parameters:
base - parent Fqn
relative - List of elements that identify the child Fqn, relative to the parent

Fqn

public Fqn(Fqn<E> base,
           E... childNames)
Constructs a Fqn from a base and two relative names.

Parameters:
base - parent Fqn
childNames - elements that denote the path to the Fqn, under the parent
Method Detail

fromString

public static Fqn<java.lang.String> fromString(java.lang.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:
 new Fqn("a", "b", "c");
 

but not
 new Fqn("/a/b/c");
 

Parameters:
stringRepresentation - String representation of the Fqn
Returns:
an Fqn constructed from the string representation passed in
See Also:
Fqn(Object[])

getAncestor

public Fqn<E> 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<E> getSubFqn(int startIndex,
                        int endIndex)
Obtains a sub-Fqn from the given Fqn. Literally performs elements.subList(startIndex, endIndex)


size

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

get

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

getLastElement

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

hasElement

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

clone

public Fqn<E> clone()
             throws java.lang.CloneNotSupportedException
Clones the Fqn.

Overrides:
clone in class java.lang.Object
Throws:
java.lang.CloneNotSupportedException

equals

public boolean equals(java.lang.Object obj)
Returns true if obj is a Fqn with the same elements.

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Returns a hash code with Fqn elements.

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.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 java.lang.Object

writeExternal

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

readExternal

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

isChildOf

public boolean isChildOf(Fqn<E> 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

isChildOrEquals

public boolean isChildOrEquals(Fqn<E> 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.

getParent

public Fqn<E> 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

isRoot

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

Returns:
true if the Fqn is Fqn.ROOT.

getLastElementAsString

public java.lang.String getLastElementAsString()
If this is the root, returns SEPARATOR.

Returns:
a String representation of the last element that makes up this Fqn.

peekElements

public java.util.List<E> 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 java.lang.Comparable<Fqn>