|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.jboss.cache.Fqn<E>
@Immutable public class Fqn<E>
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
.
ROOT
), or relative to any node in the cache. Reading the
documentation on each API call that makes use of Fqn
s 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.)
FqnAlternatively, the same Fqn could be constructed using an array:abc = Fqn.fromString("/people/Smith/Joe/"); Node joesmith = Cache.getRoot().getChild(abc);
FqnThis is a bit more efficient to construct. Note thatabc = Fqn.fromElements("people", "Smith", "Joe");
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 namessafe
- 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 Fqnrelative
- 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 Fqnrelative
- 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 FqnchildNames
- 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 Fqnsafe
- 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 Fqnrelative
- 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 FqnrelativeElements
- 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 FqnrelativeElements
- 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<?>>
Overview
Package
Class
Use
Tree
Deprecated
Index
Help
PREV CLASS
NEXT CLASS
FRAMES
NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD
DETAIL: FIELD | CONSTR | METHOD
Copyright © 2009 JBoss, a division of Red Hat. All Rights Reserved.