public class Namespace
extends java.lang.Object
SchemaDictionary
to perform lookups
of schema entity (i.e., database, table, field) names within various
scopes.
A namespace contains a pool of NameNode
s, each of which in turn
contains its own Namespace
object. This hierarchy goes at most
three levels deep, reflecting the qualified name hierarchy represented by
the Progress language naming conventions for schema entity references:
database.table.field database.table table.field database table fieldwhere each part of a fully qualified name represents an entity which has a one-to-many relationship with the entity to its right (if any), and a one-to-one relationship with the entity to its left (if any).
Additional, global namespaces for lookups of unqualified database, table,
and field names are maintained by SchemaDictionary
.
Namespace
supports lookups of both unabbreviated and
abbreviated names. Whether abbreviation lookups are supported is determined
at construction. An exact match will always be preferred to an abbreviated
match. Only one exact match or one abbreviated match is permitted. If more
are detected, the search is considered ambiguous, and an exception will be
thrown by the findUnambiguously(com.goldencode.p2j.schema.NameNode, java.util.Comparator<com.goldencode.p2j.schema.NameNode>, java.util.Set<com.goldencode.p2j.schema.NameNode>)
method.
Modifier and Type | Field and Description |
---|---|
private boolean |
abbreviations
Permit lookups using abbreviated names
|
private java.util.Set<NameNode> |
maskable
Name nodes which can be excluded from the namespace iterator.
|
private java.util.List<NameNode> |
nodes
Pool of name nodes comprising the namespace
|
Constructor and Description |
---|
Namespace(boolean abbreviations)
Constructor which sets abbreviated name lookup behavior.
|
Namespace(Namespace other)
Copy constructor which creates a separate and independent instance.
|
Modifier and Type | Method and Description |
---|---|
void |
add(NameNode node)
Add a name node to the namespace node pool at its naturally ordered
index (such that the pool is always sorted).
|
void |
add(NameNode node,
boolean exclude)
Add a name node to the namespace node pool at its naturally ordered
index (such that the pool is always sorted).
|
boolean |
contains(NameNode node)
Indicate whether this namespace contains the specified name node.
|
private int |
find(NameNode key,
java.util.Comparator<NameNode> comparator)
The actual implementation of the find node algorithm, this method lazily
sorts all name nodes in this namespace into their natural order, then
performs a binary search using
comparator . |
NameNode |
find(java.lang.String name,
boolean exact)
Find a name node with the specified name in the pool of nodes.
|
NameNode |
find(java.lang.String name,
boolean exact,
java.util.Set<NameNode> preferred)
Find a name node with the specified name in the pool of nodes.
|
private NameNode |
findPreferred(java.util.List<NameNode> matches,
java.util.Set<NameNode> preferred)
Returns the only match that is preferred or
null if there
are no preferred matches or if there is more than 1 preferred match. |
private NameNode |
findUnambiguously(NameNode key,
java.util.Comparator<NameNode> comparator,
java.util.Set<NameNode> preferred)
Find the name node in the pool which matches the specified search key,
using
comparator to perform a binary search. |
java.util.Iterator<NameNode> |
nodes()
Get read-only iterator over ALL name nodes in this namespace.
|
java.util.Iterator<NameNode> |
nodes(boolean exclude)
Get read-only iterator over the name nodes in this namespace.
|
java.util.Iterator<NameNode> |
nodes(boolean exclude,
boolean sort)
Get read-only iterator over the name nodes in this namespace.
|
boolean |
remove(NameNode node)
Remove a name node from the namespace node pool and, if successful, set
a flag to indicate the list needs to be sorted.
|
java.util.List<NameNode> |
removeAll(java.util.Set<NameNode> except)
Remove all name nodes from the namespace, except those specified.
|
private java.util.List<NameNode> nodes
private java.util.Set<NameNode> maskable
private boolean abbreviations
public Namespace(boolean abbreviations)
abbreviations
- true
to allow abbreviations, false
to disallow.public Namespace(Namespace other)
other
- The instance from which to pattern.public void add(NameNode node)
node
- Name node to be added to the pool.public void add(NameNode node, boolean exclude)
node
- Name node to be added to the pool.exclude
- true
to mark this node as one that can be
optionally excluded from an iterator.public boolean remove(NameNode node)
node
- The node to be removed from the pool.true
if the node was removed; false
if it was not present in the pool.public java.util.List<NameNode> removeAll(java.util.Set<NameNode> except)
except
- Set of name nodes to preserve.public java.util.Iterator<NameNode> nodes()
java.util.ConcurrentModificationException
- if the backing node list is modified while this iterator is
in use.public java.util.Iterator<NameNode> nodes(boolean exclude)
exclude
- true
to exclude nodes (marked as maskable) from
the iterator. false
to return all contained nodes.java.util.ConcurrentModificationException
- if the backing node list is modified while this iterator is
in use.public java.util.Iterator<NameNode> nodes(boolean exclude, boolean sort)
exclude
- true
to exclude nodes (marked as maskable) from
the iterator. false
to return all contained nodes.sort
- Used only by fields; provide them by their ORDER clause. This must not affect the
nodes()
list, thus it will return a copy.java.util.ConcurrentModificationException
- if the backing node list is modified while this iterator is
in use.public boolean contains(NameNode node)
node
- Name node for which to test.true
if node is found, else false
.public NameNode find(java.lang.String name, boolean exact) throws AmbiguousSchemaNameException
name
- Name for which to search (may be an unambiguous abbreviation
for the target node's name if this namespace instance permits
abbreviation lookups). Name may match no more than one node in
this namespace.exact
- true
to require an exact match;
false
to allow an exact or an abbreviated name to
match.NameNode
object from the node pool, if an
unambiguous match was found, or null
if no match
was found. Also returns null
if the internal pool
of name nodes has not yet been initialized.AmbiguousSchemaNameException
- if name
represents an ambiguous search key (i.e.,
matches more than one node in the pool).public NameNode find(java.lang.String name, boolean exact, java.util.Set<NameNode> preferred) throws AmbiguousSchemaNameException
name
- Name for which to search (may be an unambiguous abbreviation
for the target node's name if this namespace instance permits
abbreviation lookups). Name may match no more than one node in
this namespace.exact
- true
to require an exact match;
false
to allow an exact or an abbreviated name to
match.preferred
- A set of priority nodes used to disambiguate abbreviated fields. This set is
populated with the fields for the tables which have weak references. May be null.NameNode
object from the node pool, if an
unambiguous match was found, or null
if no match
was found. Also returns null
if the internal pool
of name nodes has not yet been initialized.AmbiguousSchemaNameException
- if name
represents an ambiguous search key (i.e.,
matches more than one node in the pool).private NameNode findUnambiguously(NameNode key, java.util.Comparator<NameNode> comparator, java.util.Set<NameNode> preferred) throws AmbiguousSchemaNameException
comparator
to perform a binary search. If a match
is found, test the nodes immediately before and after the found node
for matches using the same match criteria. If any are found, the
search key is determined to be ambiguous and an exception is thrown.key
- Search key node used for comparison with nodes in the pool.
Only the name stored in this key node is used in the search;
other attributes are not considered and are therefore not
necessary.comparator
- Comparator which is used to find a match in a binary search.preferred
- A set of priority nodes used to disambiguate abbreviated fields. This set is
populated with the fields for the tables which have weak references. May be null.NameNode
object from the node pool,
if an unambiguous match was found, or null
if no
match was found.AmbiguousSchemaNameException
- if the search key is ambiguous (i.e., matches more than one
node in the pool).private NameNode findPreferred(java.util.List<NameNode> matches, java.util.Set<NameNode> preferred)
null
if there
are no preferred matches or if there is more than 1 preferred match.matches
- The list of all matches from which to find a preferred match.preferred
- A set of priority nodes used to disambiguate abbreviated fields. This set is
populated with the fields for the tables which have weak references. May be null.null
if there is
no single match that is preferred.private int find(NameNode key, java.util.Comparator<NameNode> comparator)
comparator
. If the list of
nodes has not yet been initialized at the time this method is invoked,
it returns -1
immediately.
See also the java.util.Collections binarySearch method description.
key
- A name node whose name matches the target node.comparator
- Comparator which directs the binary search algorithm.nodes
, or -1
to indicate that the
search found no match.