JBoss.org Community Documentation
The previous section used the
Fqn
class in its
examples; now let's learn a bit more about that class.
A Fully Qualified Name (Fqn) encapsulates a list of names which represent
a path to a particular location in the cache's tree structure. The
elements in the list are typically
String
s but can be
any
Object
or a mix of different types.
This path can be absolute (i.e., relative to the root node), or relative
to any node in the cache. Reading the documentation on each API call that
makes use of
Fqn
will tell you whether the API expects
a relative or absolute
Fqn
.
The
Fqn
class provides are variety of constructors;
see the javadoc for all the possibilities. The following illustrates the
most commonly used approaches to creating an Fqn:
// Create an Fqn pointing to node 'Joe' under parent node 'Smith'
// under the 'people' section of the tree
// Parse it from a String
Fqn<String> abc = Fqn.fromString("/people/Smith/Joe/");
// Build it directly. Marginally more efficient to construct than parsing
String[] strings = new String[] { "people", "Smith", "Joe" };
Fqn<String> abc = new Fqn<String>(strings);
// Here we want to use types other than String
Object[] objs = new Object[]{ "accounts", "NY", new Integer(12345) };
Fqn<Object> acctFqn = new Fqn<Object>(objs);
Note that
Fqn<String> f = new Fqn<String>("/a/b/c");
is not the same as
Fqn<String> f = Fqn.fromString("/a/b/c");
The former will result in an Fqn with a single element, called "/a/b/c"
which hangs directly under the cache root. The latter will result
in a 3 element Fqn, where "c" idicates a child of "b", which is a child
of "a", and "a" hangs off the cache 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.
The JBoss Cache API in the 1.x releases included many overloaded
convenience methods that took a string in the
/a/b/c
format in place
of an
Fqn
. In the interests of API simplicity, no
such convenience methods are available in the JBC 2.x API.