org.jboss.cache
Class Fqn<E>

java.lang.Object
  org.jboss.cache.Fqn<E>

All Implemented Interfaces:

Externalizable, Serializable, Cloneable, Comparable<Fqn<?>>

Direct Known Subclasses:

StringFqn

@Immutable
public class Fqn<E>
extends Object
implements Cloneable, Externalizable, 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 = Fqn.fromElements("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.

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

NOTE public constructors of this class are deprectaed and will be removed in JBoss Cache 3.0.0. The factory methods provided are the correct way get an instance of an Fqn, since these allow for numerous optimisations.

Version:

$Revision: 6413 $

See Also:

Serialized Form

Field Summary

protected List<E>	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() Deprecated. use ROOT instead. This constructor will be removed in 3.0.0.
protected	Fqn(boolean internalMarker)
protected	Fqn(boolean internalMarker, Fqn<?> base, List<?> relative)
protected	Fqn(boolean internalMarker, List<?> names, boolean safe)
	Fqn(E... names) Deprecated. use fromElements(Object[]) instead. This constructor will be removed in 3.0.0.
	Fqn(Fqn<E> base, E... childNames) Deprecated. use fromRelativeElements(Fqn, Object[]) instead. This constructor will be removed in 3.0.0.
	Fqn(Fqn<E> base, Fqn<E> relative) Deprecated. use fromRelativeFqn(Fqn, Fqn) instead. This constructor will be removed in 3.0.0.
	Fqn(Fqn<E> base, List<E> relative) Deprecated. use fromRelativeList(Fqn, java.util.List) instead. This constructor will be removed in 3.0.0.
	Fqn(List<E> names) Deprecated. use fromList(java.util.List) instead. This constructor will be removed in 3.0.0.
	Fqn(List<E> names, boolean safe) Deprecated. use fromList(java.util.List) instead. The boolean "safety" hint is calculated internally. This constructor will be removed in 3.0.0.

Method Summary

protected int	calculateHashCode() Calculates a hash code by summing the hash code of all elements.
Fqn<E>	clone() Clones the Fqn.
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 <E> Fqn<E>	fromElements(E... elements) Retrieves an Fqn that represents the array of elements passed in.
static Fqn<Object>	fromExternalStream(ObjectInput in) Retrieves an Fqn read from an object input stream, typically written to using writeExternal(java.io.ObjectOutput).
static <E> Fqn<E>	fromList(List<E> names) Retrieves an Fqn that represents the list of elements passed in.
static <E> Fqn<E>	fromList(List<E> elements, boolean safe) Retrieves an Fqn that represents the list of elements passed in.
static Fqn<Object>	fromRelativeElements(Fqn<?> base, Object... relativeElements) Retrieves an Fqn that represents the array of elements passed in, relative to the base Fqn.
static Fqn<Object>	fromRelativeFqn(Fqn<?> base, Fqn<?> relative) Retrieves an Fqn that represents the absolute Fqn of the relative Fqn passed in.
static Fqn<Object>	fromRelativeList(Fqn<?> base, List<?> relativeElements) Retrieves an Fqn that represents the List of elements passed in, relative to the base Fqn.
static Fqn<String>	fromString(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()
String	getLastElementAsString() If this is the root, returns SEPARATOR.
Fqn<E>	getParent() Returns the parent of this Fqn.
protected String	getStringRepresentation(List elements)
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	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<E>	peekElements() Peeks into the elements that build up this Fqn.
void	readExternal(ObjectInput in)
static <T> Fqn<T>	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

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

protected Fqn(boolean internalMarker)

Fqn

protected Fqn(boolean internalMarker,
              List<?> names,
              boolean safe)

Fqn

protected Fqn(boolean internalMarker,
              Fqn<?> base,
              List<?> relative)

Fqn

@Deprecated
public Fqn()

Deprecated. use ROOT instead. This constructor will be removed in 3.0.0.

Constructs a root Fqn

Fqn

@Deprecated
public Fqn(List<E> names)

Deprecated. use fromList(java.util.List) instead. This constructor will be removed in 3.0.0.

Constructs a FQN from a list of names.

Parameters:

names - List of names

Fqn

@Deprecated
public Fqn(List<E> names,
                      boolean safe)

Deprecated. use fromList(java.util.List) instead. The boolean "safety" hint is calculated internally. This constructor will be removed in 3.0.0.

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

@Deprecated
public Fqn(E... names)

Deprecated. use fromElements(Object[]) instead. This constructor will be removed in 3.0.0.

Constructs a Fqn from an array of names.

Parameters:

names - Names that comprose this Fqn

Fqn

@Deprecated
public Fqn(Fqn<E> base,
                      Fqn<E> relative)

Deprecated. use fromRelativeFqn(Fqn, Fqn) instead. This constructor will be removed in 3.0.0.

Constructs a Fqn from a base and relative Fqn.

Parameters:

base - parent Fqn

relative - Sub-Fqn relative to the parent

Fqn

@Deprecated
public Fqn(Fqn<E> base,
                      List<E> relative)

Deprecated. use fromRelativeList(Fqn, java.util.List) instead. This constructor will be removed in 3.0.0.

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

@Deprecated
public Fqn(Fqn<E> base,
                      E... childNames)

Deprecated. use fromRelativeElements(Fqn, Object[]) instead. This constructor will be removed in 3.0.0.

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

fromList

public static <E> Fqn<E> fromList(List<E> 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:

2.2.0

fromList

public static <E> Fqn<E> fromList(List<E> elements,
                                  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 <E> Fqn<E> fromElements(E... 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:

2.2.0

fromRelativeFqn

public static Fqn<Object> 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:

2.2.0

fromRelativeList

public static Fqn<Object> 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:

2.2.0

fromRelativeElements

public static Fqn<Object> 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:

2.2.0

fromString

public static Fqn<String> 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:

 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[])

fromExternalStream

public static Fqn<Object> 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:

2.2.0

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 CloneNotSupportedException

Clones the Fqn.

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

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<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

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<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.

calculateHashCode

protected int calculateHashCode()

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

Returns:

a cached hashcode

getStringRepresentation

protected String getStringRepresentation(List elements)

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

root

public static <T> Fqn<T> 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<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 Comparable<Fqn<?>>