Module dev.metaschema.core

Package dev.metaschema.core.qname

package dev.metaschema.core.qname
Enhanced qualified name (QName) support with efficient caching and namespace management.

This package provides an optimized implementation of XML qualified names that reduces memory footprint through integer-based caching and instance reuse. It extends the standard QName functionality with additional features needed for Metaschema and XPath processing.

Key Interfaces and Classes

  • IEnhancedQName - Enhanced qualified name interface with caching, namespace URI access, and extended QName formatting (EQName)
  • QNameCache - Thread-safe cache for managing commonly reused qualified names with integer index-based lookup
  • NamespaceCache - Thread-safe cache for namespace URIs to reduce memory duplication
  • EQNameFactory - Factory for creating and retrieving cached qualified names
  • WellKnown - Registry of well-known XML namespaces and their conventional prefixes (xml, xs, xsi, etc.)

Caching Strategy

The caching mechanism works on two levels:

  1. Namespace Cache - Assigns unique integer indices to namespace URIs
  2. QName Cache - Uses namespace indices and local names as keys to cache qualified names

Each IEnhancedQName is assigned a unique integer index position that can be used for efficient storage and lookup via IEnhancedQName.of(int). This allows qualified names to be referenced by integer indices rather than full objects, reducing memory overhead in data structures that reference many qualified names.

Extended QName Format (EQName)

The package supports the XPath 3.1 Extended QName format:

  • Q{namespace}localName - For names in a namespace
  • prefix:localName - When a prefix is known
  • localName - For names in no namespace

The IEnhancedQName.toEQName() method automatically resolves prefixes using well-known namespaces or falls back to the braced URI notation.

Thread Safety

Both QNameCache and NamespaceCache use concurrent data structures (ConcurrentHashMap) to ensure thread-safe operation in multi-threaded environments. The cache instances are singleton objects shared across the application.

Well-Known Namespaces

The WellKnown class maintains a registry of standard XML namespaces including:

  • xml - XML namespace (http://www.w3.org/XML/1998/namespace)
  • xs - XML Schema (http://www.w3.org/2001/XMLSchema)
  • xsi - XML Schema Instance (http://www.w3.org/2001/XMLSchema-instance)
  • Metaschema-specific namespaces

Usage Context

This package is used throughout the Metaschema framework:

  • dev.metaschema.core.metapath - For XPath/Metapath QName literals and namespace resolution
  • dev.metaschema.core.model - For storing element and attribute qualified names in model definitions
  • The databind module - For mapping between Java classes and XML/JSON element names
  • XML/JSON serialization components throughout the framework

Performance Considerations

The caching strategy is optimized for read-heavy workloads common in Metaschema processing. The integer-based indexing allows for:

  • Reduced memory footprint when many references to the same QName exist
  • Fast equality comparisons using index values
  • Efficient storage in data structures

Note: The global shared cache may grow large in long-running processes. Consider the implications for your use case (see QNameCache for details).

See Also: