/*
* JBoss, the OpenSource J2EE webOS
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
package org.jboss.cache;
import net.jcip.annotations.Immutable;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import java.io.Externalizable;
import java.io.IOException;
import java.io.ObjectInput;
import java.io.ObjectOutput;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.StringTokenizer;
/**
* A Fully Qualified Name (Fqn) is a list of names (typically Strings but can be any Object),
* which represent a path to a particular {@link Node} or sometimes a {@link Region} in a {@link Cache}.
* <p/>
* This name can be absolute (i.e., relative from the root node - {@link #ROOT}), or relative to any node in the cache. Reading the
* documentation on each API call that makes use of {@link org.jboss.cache.Fqn}s will tell you whether the API expects a
* relative or absolute Fqn.
* <p/>
* 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.)
* <pre>
* Fqn<String> abc = Fqn.fromString("/people/Smith/Joe/");
* Node joesmith = Cache.getRoot().getChild(abc);
* </pre>
* Alternatively, the same Fqn could be constructed using an array:
* <pre>
* Fqn<String> abc = new Fqn<String>(new String[] { "people", "Smith", "Joe" });
* </pre>
* This is a bit more efficient to construct.
* <p/>
* <p/>
* Note that<br>
* <p/>
* <code>Fqn<String> f = new Fqn<String>("/a/b/c");</code>
* <p/>
* is <b>not</b> the same as
* <p/>
* <code>Fqn<String> f = Fqn.fromString("/a/b/c");</code>
* <p/>
* The former will result in a single Fqn, called "/a/b/c" which hangs directly under Fqn.ROOT.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* <B>NOTE</B> that support for custom object elements of Fqns will be <i>dropped</i> from JBoss Cache 3.0.0 onwards. Consider
* it's use in 2.x as a deprecated feature.. From 3.0.0 onwards, Fqns will only be able to contain <tt>String</tt>s or
* Java primitives (<tt>byte</tt>, <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, <tt>float</tt>, <tt>double</tt>, <tt>char</tt> and <tt>boolean</tt>).
*
* @version $Revision: 4997 $
*/
@Immutable
public class Fqn<E> implements Cloneable, Externalizable, Comparable<Fqn<?>>
{
/**
* Separator between FQN elements.
*/
public static final String SEPARATOR = "/";
private static final long serialVersionUID = -5351930616956603651L;
private static final Log log = LogFactory.getLog(Fqn.class);
private List<E> elements;
private transient int hash_code = 0;
private int size = 0;
/**
* Immutable root FQN.
*/
@SuppressWarnings("unchecked")
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.
*/
private String cachedStringRep;
/**
* Constructs a root Fqn
*/
public Fqn()
{
elements = Collections.emptyList();
size = 0;
}
/**
* Constructs a FQN from a list of names.
*
* @param names List of names
*/
public Fqn(List<E> names)
{
// the list is unsafe - may be referenced externally
this(names, false);
}
/**
* 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.
*
* @param names List of names
* @param safe whether this list is referenced externally (safe = false) or not (safe = true).
*/
public Fqn(List<E> names, boolean safe)
{
if (names != null)
{
// if not safe make a defensive copy
elements = safe ? names : new ArrayList<E>(names);
size = elements.size();
}
else
{
elements = Collections.emptyList();
size = 0;
}
}
/**
* Constructs a Fqn from an array of names.
*
* @param names Names that comprose this Fqn
*/
public Fqn(E... names)
{
// safe - the list is created here.
this(Arrays.asList(names), true);
}
/**
* Constructs a Fqn from a base and relative Fqn.
*
* @param base parent Fqn
* @param relative Sub-Fqn relative to the parent
*/
public Fqn(Fqn<E> base, Fqn<E> relative)
{
this(base, relative.elements);
}
/**
* Constructs a Fqn from a base and a list of relative names.
*
* @param base parent Fqn
* @param relative List of elements that identify the child Fqn, relative to the parent
*/
public Fqn(Fqn<E> base, List<E> relative)
{
List<E> elements = new ArrayList<E>(base.elements.size() + relative.size());
elements.addAll(base.elements);
elements.addAll(relative);
this.elements = elements;
size = elements.size();
}
/**
* Constructs a Fqn from a base and two relative names.
*
* @param base parent Fqn
* @param childNames elements that denote the path to the Fqn, under the parent
*/
public Fqn(Fqn<E> base, E... childNames)
{
List<E> elements = new ArrayList<E>(base.elements.size() + childNames.length);
elements.addAll(base.elements);
elements.addAll(Arrays.asList(childNames));
this.elements = elements;
size = elements.size();
}
/**
* Returns a new Fqn from a string, where the elements are deliminated by
* one or more separator ({@link #SEPARATOR}) characters.<br><br>
* Example use:<br>
* <pre>
* Fqn.fromString("/a/b/c/");
* </pre><br>
* is equivalent to:<br>
* <pre>
* new Fqn("a", "b", "c");
* </pre><br>
* but not<br>
* <pre>
* new Fqn("/a/b/c");
* </pre>
*
* @param stringRepresentation String representation of the Fqn
* @return an Fqn<String> constructed from the string representation passed in
* @see #Fqn(Object[])
*/
public static Fqn<String> fromString(String stringRepresentation)
{
if (stringRepresentation == null)
{
return root();
}
List<String> list = new ArrayList<String>();
StringTokenizer tok = new StringTokenizer(stringRepresentation, SEPARATOR);
while (tok.hasMoreTokens()) list.add(tok.nextToken());
return new Fqn<String>(list, true);
}
/**
* Obtains an ancestor of the current Fqn. Literally performs <code>elements.subList(0, generation)</code>
* such that if
* <code>
* generation == Fqn.size()
* </code>
* then the return value is the Fqn itself (current generation), and if
* <code>
* generation == Fqn.size() - 1
* </code>
* then the return value is the same as
* <code>
* Fqn.getParent()
* </code>
* i.e., just one generation behind the current generation.
* <code>
* generation == 0
* </code>
* would return Fqn.ROOT.
*
* @param generation the generation of the ancestor to retrieve
* @return an ancestor of the current Fqn
*/
public Fqn<E> getAncestor(int generation)
{
if (generation == 0) return root();
return getSubFqn(0, generation);
}
/**
* Obtains a sub-Fqn from the given Fqn. Literally performs <code>elements.subList(startIndex, endIndex)</code>
*/
public Fqn<E> getSubFqn(int startIndex, int endIndex)
{
return new Fqn<E>(elements.subList(startIndex, endIndex), true);
}
/**
* @return the number of elements in the Fqn. The root node contains zero.
*/
public int size()
{
return size;
}
/**
* @param n index of the element to return
* @return Returns the nth element in the Fqn.
*/
public E get(int n)
{
return elements.get(n);
}
/**
* @return the last element in the Fqn.
* @see #getLastElementAsString
*/
public E getLastElement()
{
if (isRoot()) return null;
return elements.get(size - 1);
}
/**
* @param element element to find
* @return true if the Fqn contains this element, false otherwise.
*/
public boolean hasElement(E element)
{
return elements.indexOf(element) != -1;
}
/**
* Clones the Fqn.
*/
@SuppressWarnings("unchecked")
public Fqn<E> clone() throws CloneNotSupportedException
{
try
{
return (Fqn<E>) super.clone();
}
catch (CloneNotSupportedException e)
{
log.error("Unable to clone Fqn " + this, e);
return null;
}
}
/**
* 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 = (Fqn<?>) obj;
return size == other.size() && elements.equals(other.elements);
}
/**
* Returns a hash code with Fqn elements.
*/
public int hashCode()
{
if (hash_code == 0)
{
hash_code = _hashCode();
}
return hash_code;
}
/**
* Returns this Fqn as a string, prefixing the first element with a {@link Fqn#SEPARATOR} and
* joining each subsequent element with a {@link Fqn#SEPARATOR}.
* If this is the root Fqn, returns {@link Fqn#SEPARATOR}.
* Example:
* <pre>
* new Fqn(new Object[] { "a", "b", "c" }).toString(); // "/a/b/c"
* Fqn.ROOT.toString(); // "/"
* </pre>
*/
public String toString()
{
if (cachedStringRep == null)
{
if (isRoot())
{
cachedStringRep = SEPARATOR;
}
else
{
StringBuilder sb = new StringBuilder();
for (E element : elements)
{
sb.append(SEPARATOR).append(element);
}
cachedStringRep = sb.toString();
}
}
return cachedStringRep;
}
public void writeExternal(ObjectOutput out) throws IOException
{
out.writeShort(size);
for (E element : elements)
{
out.writeObject(element);
}
}
@SuppressWarnings("unchecked")
public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
{
size = in.readShort();
this.elements = new ArrayList<E>(size);
for (int i = 0; i < size; i++)
{
E e = (E) in.readObject();
elements.add(e);
}
}
/**
* Returns true if this Fqn is child of parentFqn.
* Example usage:
* <pre>
* 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));
* </pre>
*
* @param parentFqn candidate parent to test against
* @return true if the target is a child of parentFqn
*/
public boolean isChildOf(Fqn<E> parentFqn)
{
return parentFqn.size() != size && isChildOrEquals(parentFqn);
}
/**
* Returns true if this Fqn is equals or the child of parentFqn.
* Example usage:
* <pre>
* 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));
* </pre>
*
* @param parentFqn candidate parent to test against
* @return true if this Fqn is equals or the child of parentFqn.
*/
public boolean isChildOrEquals(Fqn<E> parentFqn)
{
List<E> parentList = parentFqn.elements;
if (parentList.size() > size)
{
return false;
}
for (int i = parentList.size() - 1; i >= 0; i--)
{
if (!parentList.get(i).equals(elements.get(i)))
{
return false;
}
}
return true;
}
/**
* Calculates a hash code by summing the hash code of all elements.
*
* @return a cached hashcode
*/
private int _hashCode()
{
int hashCode = 0;
int count = 1;
Object o;
for (E element : elements)
{
o = element;
hashCode += (o == null) ? 0 : o.hashCode() * count++;
}
if (hashCode == 0)// fix degenerate case
{
hashCode = 0xFEED;
}
return hashCode;
}
/**
* Returns the parent of this Fqn.
* The parent of the root node is {@link #ROOT}.
* Examples:
* <pre>
* 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());
* </pre>
*
* @return the parent Fqn
*/
public Fqn<E> getParent()
{
switch (size)
{
case 0:
case 1:
return root();
default:
return new Fqn<E>(elements.subList(0, size - 1));
}
}
@SuppressWarnings("unchecked")
public static <T> Fqn<T> root()
{
return ROOT;
}
/**
* Returns true if this is a root Fqn.
*
* @return true if the Fqn is Fqn.ROOT.
*/
public boolean isRoot()
{
return size == 0;
}
/**
* If this is the root, returns {@link Fqn#SEPARATOR}.
*
* @return a String representation of the last element that makes up this Fqn.
*/
public String getLastElementAsString()
{
if (isRoot())
{
return SEPARATOR;
}
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.
*
* @return an unmodifiable list
*/
public List<E> peekElements()
{
return elements;
}
/**
* Compares this Fqn to another using {@link FqnComparator}.
*/
public int compareTo(Fqn<?> Fqn)
{
return FqnComparator.INSTANCE.compare(this, Fqn);
}
}
|