Package net.sf.saxon.om

## Class NamePool

- java.lang.Object
- - net.sf.saxon.om.NamePool

-     public final class NamePool
      extends java.lang.Object

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

  Each expanded name is allocated a unique 20-bit fingerprint. The fingerprint enables the URI and the local name to be determined. Some subsystems (notably the Tinytree) use the top 10 bits to represent the prefix, but the NamePool is no longer concerned with managing prefixes, and prefixes do not have global codes.

  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`.

  The fingerprint -1 is reserved to mean "not known" or inapplicable.

  Modified in 9.4 to remove namespace codes.

  Modified in 9.7 to remove URI codes.

  Modified in 9.8 to remove namecodes and all handling of prefixes.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | 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 | 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 | Description
    --- | ---
    `NamePool()` | Create a NamePool

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `allocateClarkName​(java.lang.String expandedName)` | Allocate a fingerprint given a Clark Name
    `int` | `allocateFingerprint​(java.lang.String uri, java.lang.String local)` | Allocate a fingerprint from the pool, or a new Name if there is not a matching one there
    `java.lang.String` | `getClarkName​(int nameCode)` | Get the Clark form of a name, given its name code or fingerprint
    `java.lang.String` | `getDisplayName​(int nameCode)` | Get the display form of a name (the QName), given its name code or fingerprint
    `java.lang.String` | `getEQName​(int nameCode)` | Get the EQName form of a name, given its name code or fingerprint
    `int` | `getFingerprint​(java.lang.String uri, java.lang.String localName)` | Get a fingerprint for the name with a given uri and local name.
    `java.lang.String` | `getLocalName​(int nameCode)` | Get the local part of a name, given its name code or fingerprint
    `StructuredQName` | `getStructuredQName​(int fingerprint)` | Get a QName for a given fingerprint.
    `StructuredQName` | `getUnprefixedQName​(int nameCode)` | Get a QName for a given namecode.
    `java.lang.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
    `void` | `suggestPrefix​(java.lang.String prefix, java.lang.String uri)` | Suggest a preferred prefix to be used with a given URI
    `java.lang.String` | `suggestPrefixForURI​(java.lang.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

    - #### suggestPrefix

          public void suggestPrefix​(java.lang.String prefix,
                                    java.lang.String uri)

      Suggest a preferred prefix to be used with a given URI
      Parameters:
        `uri` - the URI
        `prefix` - the suggested prefix

    - #### 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 fingerprint)

      Get a QName for a given fingerprint.
      Parameters:
        `fingerprint` - 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 fingerprint. There will be no prefix

    - #### 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 java.lang.String suggestPrefixForURI​(java.lang.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

    - #### allocateFingerprint

          public int allocateFingerprint​(java.lang.String uri,
                                         java.lang.String local)

      Allocate a fingerprint from the pool, or a new Name if there is not a matching one there
      Parameters:
        `uri` - the namespace URI. Use "" or null for the non-namespace.
        `local` - the local part of the name
      Returns:
        an integer (the "fingerprint") identifying the name within the namepool. The fingerprint omits information about the prefix, and is the same as the nameCode for the same name with a prefix equal to "".

    - #### getURI

          public java.lang.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:
        `java.lang.IllegalArgumentException` - if the nameCode is not known to the NamePool.

    - #### getLocalName

          public java.lang.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

    - #### getDisplayName

          public java.lang.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 java.lang.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 java.lang.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​(java.lang.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​(java.lang.String uri,
                                    java.lang.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