sk.uniba.euromath.document
Class NamespaceManager

java.lang.Object
  sk.uniba.euromath.document.NamespaceManager

public final class NamespaceManager
extends Object

Manages prefixes in given document. Upon constructing, namespace prefixes are unified by following algorithm:

• Prefix for all namespace definitions are remembered, one for each namespace definition (by the xmlns attribute). First prefix definition is taken.
• If mapping defines no prefix for non-empty namespace (for example, xmlns="foo:bar"), then this prefix definition is not remembered. Instead, next prefix definition is remembered.
• All xmlns:foo="" definitions are processed as if the xmlns="" was encountered - empty namespaces are thus mapped to empty prefix.
• Then, all xmlns definitions are removed.
• All namespaces, that doesn't have prefix defined, are given new prefix, generated via getPreferredPrefix() function.
• Then, all element's prefixes are set, so following is true: any two elements, that have same namespace, has same prefix.

As a result, document (except descendants of entity reference nodes) is stripped of xmlns attributes.

Thread unsafe.

Even when all elements/attributes from some namespaces are removed the mapping is not deleted automatically. It is removed when the manager is queried for all known namespaces, using getAllNamespaces(), getCounts() or getElementNamespaces() methods.

Author:

Martin Vysny

Nested Class Summary

static class

NamespaceManager.NodeCount Class holding elements and attributes count.

Constructor Summary

NamespaceManager(NamespaceManager parent)
Constructs a namespace manager, that is a child of given namespace manager.

Method Summary

boolean	acceptsNewPrefix(String namespaceUri, String newPrefix) When creating new element/attribute, check, whether chosen prefix can be used.
void	cleanMappings() Removes all mappings of namespaces not present in the document.
Attr	createXmlnsAttribute(Element e, String namespaceUri) Creates an xmlns attribute, that maps known namespace to registered prefix.
void	createXmlnsAttributes(Element e) For each used namespace, except empty namespace, creates xmlns mapping.
void	createXmlnsAttributes(Element e, Set<? extends String> namespaces) Adds and/or replaces xmlns mapping for all given namespaces in given element.
void	declare(String namespaceUri, String prefix) Declares the namespace-prefix pair.
Set<String>	getAllNamespaces() Returns all namespaces known to this manager.
String	getBestPrefix(String namespaceUri) When creating new element/attribute from another namespace as their parent, we can specify new prefix.
Map<String,NamespaceManager.NodeCount>	getCounts() Returns counts of nodes for each namespace.
Set<String>	getElementNamespaces() Returns namespaces of all elements present in the document.Returned set cannot be modified in any way.
String	getNamespace(String prefix) Returns namespace, that is currently mapped to given prefix.
String	getPrefix(String namespaceUri) Returns prefix, that is currently mapped to given namespace.
boolean	isBestPrefixRequired(String namespaceUri) Checks, if the prefix, returned by the getBestPrefix() function, is only the best choice for new prefix, or if returned prefix MUST be used.
boolean	isDefined(String namespaceUri, Element e) Checks, if given namespace is defined in given element.
String	toString()
void	undeclareNamespace(String namespaceUri) Undeclares given namespace.

Methods inherited from class java.lang.Object

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

Constructor Detail

NamespaceManager

public NamespaceManager(NamespaceManager parent)

Constructs a namespace manager, that is a child of given namespace manager. Document is not modified, changes to this namespace manager are not displayed in parent manager.

Parameters:

parent - parent namespace manager.

Method Detail

createXmlnsAttributes

public void createXmlnsAttributes(Element e)

For each used namespace, except empty namespace, creates xmlns mapping. Erases all other xmlns definitions.

Parameters:

e - element, where the xmlns attributes will be re-created.

createXmlnsAttributes

public void createXmlnsAttributes(Element e,
                                  Set<? extends String> namespaces)

Adds and/or replaces xmlns mapping for all given namespaces in given element.

Parameters:

e - the element.

namespaces - Set of Strings. All these namespaces' mappings are added to element.

getAllNamespaces

public Set<String> getAllNamespaces()

Returns all namespaces known to this manager. Returned set cannot be modified in any way. null namespace is represented as empty string (""), and always maps to empty ( "") namespace. It never contains the EuroMath namespace, xmlns namespace nor xml namespace.

All mappings of namespaces no longer present in the document are removed, but only for root manager.

Returns:

all namespaces in document.

getElementNamespaces

public Set<String> getElementNamespaces()

Returns namespaces of all elements present in the document.Returned set cannot be modified in any way. null namespace is represented as empty string (""), and always maps to empty ( "") namespace. It never contains the EuroMath namespace, xmlns namespace nor xml namespace.

All mappings of namespaces no longer present in the document are removed.

Returns:

set of all namespaces present in elements.

getCounts

public Map<String,NamespaceManager.NodeCount> getCounts()

Returns counts of nodes for each namespace. Clones internal map, therefore the result may be cached when used multiple times.

All mappings of namespaces no longer present in the document are removed.

Returns:

maps namespace URI to a count of nodes with given namespace. null namespace is represented as an empty string.

cleanMappings

public void cleanMappings()

Removes all mappings of namespaces not present in the document. Cleans only mappings registered in this instance of manager, it does not clean parent manager.

getBestPrefix

public String getBestPrefix(String namespaceUri)

When creating new element/attribute from another namespace as their parent, we can specify new prefix. This function returns the best suggestion of new prefix.

However, you can ask for every element/attribute's prefix, but there are cases, when this prefix is not changeable.

Warning: when creating attributes with same namespace as their owner element (local namespaces), their prefix AND namespace MUST be null.

Parameters:

namespaceUri - namespace of new nametree being created.

Returns:

best prefix name. If no prefix is the best choice, then null is returned.

isBestPrefixRequired

public boolean isBestPrefixRequired(String namespaceUri)

Checks, if the prefix, returned by the getBestPrefix() function, is only the best choice for new prefix, or if returned prefix MUST be used.

Parameters:

namespaceUri - namespace to check.

Returns:

false, if user can choose virtually any prefix, that is accepted by the acceptsNewPrefix() function. True, if only one prefix can be used.

acceptsNewPrefix

public boolean acceptsNewPrefix(String namespaceUri,
                                String newPrefix)

When creating new element/attribute, check, whether chosen prefix can be used.

Parameters:

namespaceUri - namespace.

newPrefix - desired prefix. When no prefix is desired, null must be specified. Only null namespace may have null prefix.

Returns:

true, if this prefix can be set to new element/attribute, false if not. The function will not check if the prefix contains illegal characters, it merely checks if there is no other registered prefix with same name.

createXmlnsAttribute

public Attr createXmlnsAttribute(Element e,
                                 String namespaceUri)

Creates an xmlns attribute, that maps known namespace to registered prefix. EuroMath namespace is always mapped to emp: prefix. When an empty namespace is given, function returns null: empty namespace is always mapped to empty prefix, and thus need not to be declared by the xmlns: attribute. When an XML namespace is given then null is returned aswell.

Parameters:

e - element, where to create element.

namespaceUri - creates xmlns mapping for this namespace.

Returns:

xmlns attribute node, or null if no prefix is currently mapped to given namespace.

getPrefix

public String getPrefix(String namespaceUri)

Returns prefix, that is currently mapped to given namespace. If no prefix is currently mapped, function returns null. EuroMath namespace is always mapped to emp: prefix. Empty or null namespace ("") is always mapped to empty prefix (""). XML namespace is always mapped to xml prefix.

Parameters:

namespaceUri - namespace.

Returns:

prefix, that maps to given namespace. If no prefix is currently known for given namespace, it return null.

getNamespace

public String getNamespace(String prefix)

Returns namespace, that is currently mapped to given prefix. If no namespace is currently mapped, function returns null. EuroMath namespace is always mapped to emp: prefix. Empty or null prefix is always mapped to empty namespace ("").

Parameters:

prefix - the prefix.

Returns:

namespace, that maps to given prefix. If no namespace is currently known for given prefix, it returns null.

isDefined

public boolean isDefined(String namespaceUri,
                         Element e)

Checks, if given namespace is defined in given element. For empty namespace always returns true.

Parameters:

namespaceUri - namespace

e - element

Returns:

true if this namespace is defined in given element with the xmlns: attribute, or if a prefix is registered.

declare

public void declare(String namespaceUri,
                    String prefix)

Declares the namespace-prefix pair. This operation is not applicable to a default namespace manager - it is updated automatically when the document is modified. Neither the namespace, nor the prefix can exist in a parent.

Parameters:

namespaceUri - the namespace.

prefix - the prefix.

Throws:

IllegalArgumentException - if such prefix-namespace pair cannot be registered.

undeclareNamespace

public void undeclareNamespace(String namespaceUri)

Undeclares given namespace. If the namespace is not declared in this manager then the function will fail - we cannot modify parent.

Parameters:

namespaceUri - the namespace part of pair.

toString

public String toString()

Overrides:

toString in class Object