net.sf.saxon.om

Class NamePool

java.lang.Object

net.sf.saxon.om.NamePool

public final class NamePool
extends Object

A NamePool holds a collection of expanded names, each containing a namespace URI, a namespace prefix, and a local name.

Each expanded name is allocated a unique integer namecode. The namecode enables all three parts of the expanded name to be determined, that is, the prefix, the URI, and the local name.

The equivalence between names depends only on the URI and the local name. The namecode is designed so that if two namecodes represent names with the same URI and local name, the two namecodes are the same in the bottom 20 bits. It is therefore possible to compare two names for equivalence by performing an integer comparison of these 20 bits. The bottom 20 bits of a namecode are referred to as a fingerprint.

The NamePool eliminates duplicate names if they have the same prefix, uri, and local part. It retains duplicates if they have different prefixes

The NamePool has been redesigned in Saxon 9.7 to make use of two Java ConcurrentHashMaps, one from QNames to integers, one from integers to QNames. This gives better scaleability in terms of multithreaded concurrency and in terms of the capacity of the NamePool and retention of performance as the size of the vocabulary increases.

Fingerprints in the range 0 to 1023 are reserved for system use, and are allocated as constants mainly to names in the XSLT and XML Schema namespaces: constants representing these names are found in StandardNames.

A nameCode contains the fingerprint in the bottom 20 bits. It also contains a 10-bit prefix index. This distinguishes the prefix used, among all the prefixes that have been used with this namespace URI. If the prefix index is zero, the prefix is null. Otherwise, it indexes an array of prefix Strings associated with the namespace URI. Note that the data structures and algorithms are optimized for the case where URIs usually use the same prefix.

The nameCode -1 is reserved to mean "not known" or inapplicable. The fingerprint -1 has the same meaning. Note that masking the nameCode -1 to extract its bottom 20 bits is incorrect, and will lead to errors.

Modified in 9.4 to remove namespace codes.

Modified in 9.7 to remove URI codes.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NamePool.NamePoolLimitException Unchecked Exception raised when some limit in the design of the name pool is exceeded

Field Summary

Fields

Modifier and Type	Field and Description
static int	FP_MASK FP_MASK is a mask used to obtain a fingerprint from a nameCode.
static int	USER_DEFINED_MASK

Constructor Summary

Constructors

Constructor and Description
NamePool() Create a NamePool

Method Summary

Methods

Modifier and Type	Method and Description
int	allocate(String prefix, String uri, String localName) Allocate a name code from the pool, or return an existing one if it already exists
int	allocateClarkName(String expandedName) Allocate a fingerprint given a Clark Name
String	getClarkName(int nameCode) Get the Clark form of a name, given its name code or fingerprint
String	getDisplayName(int nameCode) Get the display form of a name (the QName), given its name code or fingerprint
String	getEQName(int nameCode) Get the EQName form of a name, given its name code or fingerprint
int	getFingerprint(String uri, String localName) Get a fingerprint for the name with a given uri and local name.
String	getLocalName(int nameCode) Get the local part of a name, given its name code or fingerprint
NamespaceBinding	getNamespaceBinding(int nameCode) Get a namespace binding for a given namecode.
String	getPrefix(int nameCode) Get the prefix part of a name, given its name code
StructuredQName	getStructuredQName(int nameCode) Get a QName for a given namecode.
StructuredQName	getUnprefixedQName(int nameCode) Get a QName for a given namecode.
String	getURI(int nameCode) Get the namespace-URI of a name, given its name code or fingerprint
static boolean	isPrefixed(int nameCode) Determine whether a given namecode has a non-empty prefix (and therefore, in the case of attributes, whether the name is in a non-null namespace
String	suggestPrefixForURI(String uri) Suggest a prefix for a given URI.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FP_MASK

public static final int FP_MASK

FP_MASK is a mask used to obtain a fingerprint from a nameCode. Given a nameCode nc, the fingerprint is nc & NamePool.FP_MASK. (In practice, Saxon code often uses the literal constant 0xfffff, to extract the bottom 20 bits).

The difference between a fingerprint and a nameCode is that a nameCode contains information about the prefix of a name, the fingerprint depends only on the namespace URI and local name. Note that the "null" nameCode (-1) does not produce the "null" fingerprint (also -1) when this mask is applied.

See Also:

Constant Field Values

USER_DEFINED_MASK

public static final int USER_DEFINED_MASK

See Also:

Constant Field Values

Constructor Detail

NamePool

public NamePool()

Create a NamePool

Method Detail

getNamespaceBinding

public NamespaceBinding getNamespaceBinding(int nameCode)

Get a namespace binding for a given namecode.

Parameters:

nameCode - a code identifying an expanded QName, e.g. of an element or attribute

Returns:

an object identifying the namespace binding used in the given name. The namespace binding identifies both the prefix and the URI.

getUnprefixedQName

public StructuredQName getUnprefixedQName(int nameCode)

Get a QName for a given namecode.

Parameters:

nameCode - a code identifying an expanded QName, e.g. of an element or attribute

Returns:

a qName containing the URI and local name corresponding to the supplied name code. The prefix will be set to an empty string.

getStructuredQName

public StructuredQName getStructuredQName(int nameCode)

Get a QName for a given namecode.

Parameters:

nameCode - a code identifying an expanded QName, e.g. of an element or attribute

Returns:

a qName containing the URI and local name corresponding to the supplied name code. The prefix will be set according to the value supplied in nameCode.

isPrefixed

public static boolean isPrefixed(int nameCode)

Determine whether a given namecode has a non-empty prefix (and therefore, in the case of attributes, whether the name is in a non-null namespace

Parameters:

nameCode - the name code to be tested

Returns:

true if the name has a non-empty prefix

suggestPrefixForURI

public String suggestPrefixForURI(String uri)

Suggest a prefix for a given URI. If there are several, it's undefined which one is returned. If there are no prefixes registered for this URI, return null.

Parameters:

uri - the namespace URI

Returns:

a prefix that has previously been associated with this URI, if available; otherwise null

allocate

public int allocate(String prefix,
           String uri,
           String localName)

Allocate a name code from the pool, or return an existing one if it already exists

Parameters:

prefix - the namespace prefix. Use "" for the null prefix, representing the absent namespace

uri - the namespace URI. Use "" or null for the non-namespace.

localName - the local part of the name

Returns:

an integer (the "namecode") identifying the name within the namepool. The namecode includes information about the prefix

getURI

public String getURI(int nameCode)

Get the namespace-URI of a name, given its name code or fingerprint

Parameters:

nameCode - the name code or fingerprint of a name

Returns:

the namespace URI corresponding to this name code. Returns "" for the no-namespace.

Throws:

IllegalArgumentException - if the nameCode is not known to the NamePool.

getLocalName

public String getLocalName(int nameCode)

Get the local part of a name, given its name code or fingerprint

Parameters:

nameCode - the integer name code or fingerprint of the name

Returns:

the local part of the name represented by this name code or fingerprint

getPrefix

public String getPrefix(int nameCode)

Get the prefix part of a name, given its name code

Parameters:

nameCode - the integer name code of a name in the name pool

Returns:

the prefix of this name. Note that if a fingerprint rather than a full name code is supplied the returned prefix will be ""

getDisplayName

public String getDisplayName(int nameCode)

Get the display form of a name (the QName), given its name code or fingerprint

Parameters:

nameCode - the integer name code or fingerprint of a name in the name pool

Returns:

the corresponding lexical QName (if a fingerprint was supplied, this will simply be the local name)

getClarkName

public String getClarkName(int nameCode)

Get the Clark form of a name, given its name code or fingerprint

Parameters:

nameCode - the integer name code or fingerprint of a name in the name pool

Returns:

the local name if the name is in the null namespace, or "{uri}local" otherwise. The name is always interned.

getEQName

public String getEQName(int nameCode)

Get the EQName form of a name, given its name code or fingerprint

Parameters:

nameCode - the integer name code or fingerprint of a name in the name pool

Returns:

the name in the form Q{}local for a name in no namespace, or Q{uri}local for a name in a namespace

allocateClarkName

public int allocateClarkName(String expandedName)

Allocate a fingerprint given a Clark Name

Parameters:

expandedName - the name in Clark notation, that is "localname" or "{uri}localName"

Returns:

the fingerprint of the name, which need not previously exist in the name pool

getFingerprint

public int getFingerprint(String uri,
                 String localName)

Get a fingerprint for the name with a given uri and local name. These must be present in the NamePool. The fingerprint has the property that if two fingerprint are the same, the names are the same (ie. same local name and same URI).

Parameters:

uri - the namespace URI of the required QName

localName - the local part of the required QName

Returns:

the integer fingerprint, or -1 if this is not found in the name pool