Package eu.bandm.tools.util.xml

Class NamespaceName

java.lang.Object
eu.bandm.tools.util.xml.NamespaceName
All Implemented Interfaces:
Serializable
public class NamespaceName extends Object implements Serializable
Models the special "equals()" behaviour of xml identifiers with namespace prefix semantics.
Any instance has algebraic semantics and is implemented immutable.
Instances of this class realize two partly independent layers of information: The front-end-representation, i.e. the chosen prefix, and the semantics, i.e. the namespace uri.

The fields of a NamespaceName are used in different combinations, covering different disciplines for treating identifiers in XML:

  • names without any colon ":", related to a "default namespace"
  • names with a colon-separated prefix, related to an explicitly, individually (and independently from other instances) specified namespace-uri,
  • names containing exactly one colon, but with no namespace semantics, ie. treated as "simple names".
  • names containing arbitrary many "colon"s, (including none) with no namespace semantics, ie. treated as "simple names"
The different modes are established by the different signatures of the public contructors. No string value may ever be ==null, neither input arguments supplied by the user, nor values returned by retrieval methods. They may indeed be =="", which normally stands for "non applicable".
These rules have been chosen to correspond to those used by org.xml.sax.

With name space mode enabled, esp. the "non-namespace-namespace" is encoded by a URI-value =="", and can (typical XML idionsyncratics !-) only be mapped to the empty prefix =="".

ATTENTION: Since frequently NamespaceName objects must be constructed from parameters which have already been verified for multiple use, the constructors do (for efficiency) only a very limited check on the syntax, namely w.r.t the correct count and position of a colon ":" in any prefix and qname. Also the function validQName(String) does no more, despite its name. The check whether a prefix is a valid NameToken must be done by the caller explicitly, e.g. calling NmTokenAttribute.checkNameToken(String). The same holds for the ns-uri, use Transformation.UriSyntaxCheck(String).
Please note that the mapping from prefices to name space identifying URIs is not modelled in this data type, i.e. it can and must be defined independently for each created instance of this class. The only exceptions are the static parsing methods element(Map, String, boolean) and attribute(Map, String, boolean) (and its variants with function parameters), which receive an implementation of this mapping by a parameter. Consistency of this mapping, where necessary, must be maintained by the user of this class.

See Also:

  • Field Details

  • Constructor Details

    • NamespaceName

      public NamespaceName(String namespaceURI, String localName)
      Create a NamespaceName with the given URI and the given localname. Both arguments must be non-null.
      An empty string as local name is not allowed.
      An empty string as namespaceURI inidicates the "no-namespace-namespace"

      An empty string is stored as the prefix. Whether the mapping from prefix to uri is context correct, is not in the scope of this code module. In all methods herein (except getQName() and toString() ) the prefix will be ignored.

    • NamespaceName

      public NamespaceName(String namespaceURI, String prefix, String localName)
      Create a NamespaceName with the given URI and the given localname, and additionally memorize the prefix. All arguments must be non-null.
      An empty string as local name is not allowed.
      An empty string as namespaceURI indicates the "no-namespace-namespace" Whether the mapping from prefix to uri is context correct, is not in the scope of this code module.

      (An empty prefix normally means the name to reside in the "default namespace".) In all methods herein (except getQName() and toString() ) the prefix will be ignored.

    • NamespaceName

      public NamespaceName(String qname)
      Create a NamespaceName representing an identifier not in namespace mode. This mode mostly used for compatibility only: for older implementations which support only the definitions in www.w3.org/TR/xhtml1/, not those of www.w3.org/TR/REC-xml-names.
      Parameters:
      qname - a name containing arbitrary many colons, but not considered in namespace mode. It will be returned by getQName().

  • Method Details

    • getNamespaceURI

      public String getNamespaceURI()
      Returns:
      an empty string, if not in namespace mode.

    • getLocalName

      public String getLocalName()
      Local names are only defined in namespace mode. In non-name-space mode this returns the empty string- To get a name in this case use getQName() instead.

    • getPrefix

      public String getPrefix()
      Returns:
      the prefix, if in namespace mode, otherwise an empty string.

    • getQName

      public String getQName()
      Returns:
      in namespace mode (depending on the emptiness of the prefix) the local name or the local name, preceded by the prefix and a colon. In non-namespace mode return the local name (with arbitrary many colons).

    • getNamespacesEnabled

      public boolean getNamespacesEnabled()
      Returns:
      whether this instance was created with a (possibly empty) ns-URI, i.e. is in namespace mode.

    • toString

      public String toString()
      Render this to a string in the "curly brace" format, similar to a "universal name". The universal name has been introduced at http://www.jclark.com/xml/xmlns.htm. This method is slightly different because the empty namespace is rendered "{}.." and the qualified name is printed with prefix. Thus this format is more convenient for debugging output. In case of namespace mode, it consists of the qualified name (including the prefix, NOT only the local part), preceded by the namspace URI in curly braces (which may be empty). In case of non-namespace mode, it consists of only the local name (which may contain colons).
      Overrides:
      toString in class Object

    • universalName

      public String universalName()
      Render this to a string in the "curly brace" format of a "universal name". The universal name has been introduced at http://www.jclark.com/xml/xmlns.htm. In case of namespace mode, it consists of the local name, preceded by the namespace URI in curly braces, if this is not empty. Otherwise it consists of only the local name, which in our implementaion may contain colons, in case of non-namespace mode.

    • equals

      public boolean equals(Object o)
      Compares only namespaceURI and localname, prefix is irrelevant.
      Overrides:
      equals in class Object

    • equals

      protected boolean equals(NamespaceName n)
      Compares only namespaceURI and localname, prefix is irrelevant.

    • hashCode

      public int hashCode()
      Compares only namespaceURI and localname, prefix is irrelevant.
      Overrides:
      hashCode in class Object

    • parseInlineURIFormat

      public static NamespaceName parseInlineURIFormat(String s) throws IllegalArgumentException
      Parse the input in the "curly brace" syntax simial to a "universal name" as introduced at http://www.jclark.com/xml/xmlns.htm. In case of namespace mode, it consists of the local name, preceded by the namspace URI in curly braces, if this is not empty. Otherwise it consists of only the local name (which may contain colons).
      Example: {http://myUri}element
      In addition to "universal name", this method also accepts empty braces for the empty namespace name. No prefix is memorized, but local name and ns-Uri are set.
      Throws:
      IllegalArgumentException

    • matches

      public boolean matches(String namespaceURI, String localName, String qname)
      Behaves like equals(new NamespaceName(...), but without the overhead of explicitly contructing an instance of NamespaceName. If namespaceURI is not empty, namespace mode is assumed and namespaceUri and localName are compared. Otherwise qname is compared. Is used for comparing "this" to a triple of Strings as produced by the official SAX package api. Currently it is used by SAXEventQueue.Event.lookaheadTag(NamespaceName)

    • validQName

      @Opt public static @Opt String[] validQName(String qname)
      Check for validity of a qualified name and split it into its two components. Both parts are checked not to contain a colon ":", but not yet to conform to the "Name" production, see [XMLNS 1.0:rule 4] and [XML 1.1: rule 5]. For this, NmTokenAttribute.checkNameToken(String) can be called.
      Returns:
      null on error. Otherwise array with two strings, prefix and local-name, the first of which may have length==0. Conformant to XML, the canonical input ":suffix" is not an empty prefix but rejected as an error.

    • element

      public static NamespaceName element(Map<? extends String,? extends String> namespaceMapping, String qname, boolean namespacesEnabled) throws IllegalArgumentException
      Parsing function for a qualified name which stands for an element name.
      Iff namespacesEnabled==true, there must be at most one colon ":", and if there is, it separates prefix and localname. Otherwise the prefix is the empty string. An ill-formed qname raises an IllegalArgumentException.

      Every prefix (incl. the empty string) is looked up in the map to determine the URI. Any non-empty prefix unsuccessfully looked for in the map generates an IllegalArgumentException; the empty prefix not in the map maps (as a default) to the empty URI. Iff namespacesEnabled==false, the qname argument is treated as a local name, as a whole.

      Parameters:
      namespaceMapping - map from prefices to URIs (empty string as a key=prefix represents what is called "default namespace")
      qname - String to parse
      namespacesEnabled - whether to treat colon specially
      Throws:
      IllegalArgumentException

    • attribute

      public static NamespaceName attribute(Map<? extends String,? extends String> namespaceMapping, String qname, boolean namespacesEnabled) throws IllegalArgumentException
      Parsing function for a qualified name which stands for an attribute name.
      Iff namespacesEnabled==true, there must be at most one colon ":", and if there is, it separates a non-empty prefix and a non-empty localname. If there is no colon, the prefix is the empty string.
      An ill-formed qname raises an IllegalArgumentException.

      Only a non-empty prefix is looked up in the map to initialize the URI. An empty prefix is mapped implicity to the empty URI ("no-namespace"). This is the behaviour for attribute names (and some references embedded in XPpath expressions), and different from that of element tags. Any prefix unsuccessfully looked for in the map generates an IllegalArgumentException. Iff namespacesEnabled==false, the qname argument is treated as a local name, as a whole.

      Parameters:
      namespaceMapping - map from prefices to URIs
      qname - String to parse
      namespacesEnabled - whether to treat colon specially
      Throws:
      IllegalArgumentException

    • element

      public static NamespaceName element(Function<? super String,? extends String> namespaceMapping, String qname) throws IllegalArgumentException
      Parsing function for a qualified name which stands for an element name. The map from prefices to namespace uris is given by a function. Non-namespace mode is not supported.
      Throws:
      IllegalArgumentException - iff illegal colon positions or the prefix not in the map.

    • attribute

      public static NamespaceName attribute(Function<? super String,? extends String> namespaceMapping, String qname) throws IllegalArgumentException
      Parsing function for a qualified name which stands for an attribute name, or an xslt function name, etc. The map from prefices to namespace uris is given by a function. Non-namespace mode is not supported.
      Throws:
      IllegalArgumentException - iff illegal colon positions or the prefix not in the map.