Package eu.bandm.tools.util

Class NamespaceName

  • All Implemented Interfaces:
    java.io.Serializable
    @Runtime
public class NamespaceName
extends java.lang.Object
implements java.io.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 model two partly indendent 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, with the parameters already verified, the constructors do 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 an 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 the function based variants, which receive an implementation of this mapping by a parameter.
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      NamespaceName​(java.lang.String qname)
      Create a NamespaceName representing an identifier not in namespace mode.
      NamespaceName​(java.lang.String namespaceURI, java.lang.String localName)
      Create a NamespaceName with the given URI and the given localname.
      NamespaceName​(java.lang.String namespaceURI, java.lang.String prefix, java.lang.String localName)
      Create a NamespaceName with the given URI and the given localname, and additionally memoize the prefix.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static NamespaceName attribute​(java.util.function.Function<? super java.lang.String,​? extends java.lang.String> namespaceMapping, java.lang.String qname)
      Like above, but the prefix mapping is a function, non-namespace-mode not supported.
      static NamespaceName attribute​(java.util.Map<? extends java.lang.String,​? extends java.lang.String> namespaceMapping, java.lang.String qname, boolean namespacesEnabled)
      Parsing function for a qualified name which stands for an attribute name.
      static NamespaceName element​(java.util.function.Function<? super java.lang.String,​? extends java.lang.String> namespaceMapping, java.lang.String qname)
      Like above, but the prefix mapping is a function, non-namespace-mode not supported.
      static NamespaceName element​(java.util.Map<? extends java.lang.String,​? extends java.lang.String> namespaceMapping, java.lang.String qname, boolean namespacesEnabled)
      Parsing function for a qualified name which stands for an element name.
      protected boolean equals​(NamespaceName n)
      Compares only namespaceURI and localname, prefix is irrelevant.
      boolean equals​(java.lang.Object o)  
      java.lang.String getLocalName()
      Local names are only defined in namespace mode.
      boolean getNamespacesEnabled()  
      java.lang.String getNamespaceURI()  
      java.lang.String getPrefix()  
      java.lang.String getQName()  
      int hashCode()  
      boolean matches​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qname)
      Behaves like equals(NamespaceName), but without explicitly contructing an instance of NamespaceName! Is used for comparing "this" to a triple of Strings a produced by the sax project api.
      static NamespaceName parseInlineURIFormat​(java.lang.String s)
      Parse the input in the "curly brace" syntax of an "universal name".
      java.lang.String toString()
      Render this to a string in the "curly brace" format, similar to a "universal name".
      java.lang.String universalName()
      Render this to a string in the "curly brace" format of a "universal name".
      static @Opt java.lang.String[] validQName​(java.lang.String qname)
      Check for validity of a qualified name and split into its two components.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • curlyBrace_close

        public static final java.lang.String curlyBrace_close
        See Also:
        Constant Field Values

      • namespace_prefix_xml

        public static final java.lang.String namespace_prefix_xml
        The reserved prefix for the "xml:" namespace.
        See Also:
        Constant Field Values

      • namespace_uri_xml

        public static final java.lang.String namespace_uri_xml
        The reserved URI for the "xml:" namespace.
        See Also:
        Constant Field Values

    • Constructor Detail

      • NamespaceName

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

      • NamespaceName

        public NamespaceName​(java.lang.String namespaceURI,
                     java.lang.String prefix,
                     java.lang.String localName)
        Create a NamespaceName with the given URI and the given localname, and additionally memoize 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​(java.lang.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 {@link http://www.w3.org/TR/xhtml1/}, not those of {@ http://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 Detail

      • getNamespaceURI

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

      • getLocalName

        public java.lang.String getLocalName()
        Local names are only defined in namespace mode. In non-name-space mode this returns the empty string, use getQName() instead.//FIXME SINNVOLL??

      • getPrefix

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

      • getQName

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

      • universalName

        public java.lang.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​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • equals

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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • parseInlineURIFormat

        public static NamespaceName parseInlineURIFormat​(java.lang.String s)
                                          throws java.lang.IllegalArgumentException
        Parse the input in the "curly brace" syntax of an "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 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
        No prefix is memorized, but local name and ns-Uri are set accoringly.
        Throws:
        java.lang.IllegalArgumentException

      • matches

        public boolean matches​(java.lang.String namespaceURI,
                       java.lang.String localName,
                       java.lang.String qname)
        Behaves like equals(NamespaceName), but without explicitly contructing an instance of NamespaceName! Is used for comparing "this" to a triple of Strings a produced by the sax project api. Currently it is used by eu.bandm.tools.util.SAXEventQueue.Event#lookaheadTag(NamespaceName)

      • validQName

        @Opt
public static @Opt java.lang.String[] validQName​(java.lang.String qname)
        Check for validity of a qualified name and split into its two components. ATTENTION: 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) must be called, which is not yet compiled when this is compiled. (in the current metatools Makefile boot process).
        Returns:
        null on error. Otherwise array with two strings, prefix and local-name, the first of which may have length==0.

      • element

        public static NamespaceName element​(java.util.Map<? extends java.lang.String,​? extends java.lang.String> namespaceMapping,
                                    java.lang.String qname,
                                    boolean namespacesEnabled)
                             throws java.lang.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. 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 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:
        java.lang.IllegalArgumentException

      • attribute

        public static NamespaceName attribute​(java.util.Map<? extends java.lang.String,​? extends java.lang.String> namespaceMapping,
                                      java.lang.String qname,
                                      boolean namespacesEnabled)
                               throws java.lang.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:
        java.lang.IllegalArgumentException

      • element

        public static NamespaceName element​(java.util.function.Function<? super java.lang.String,​? extends java.lang.String> namespaceMapping,
                                    java.lang.String qname)
                             throws java.lang.IllegalArgumentException
        Like above, but the prefix mapping is a function, non-namespace-mode not supported.
        Throws:
        java.lang.IllegalArgumentException - iff illegal colon positions or prefix not in map.

      • attribute

        public static NamespaceName attribute​(java.util.function.Function<? super java.lang.String,​? extends java.lang.String> namespaceMapping,
                                      java.lang.String qname)
                               throws java.lang.IllegalArgumentException
        Like above, but the prefix mapping is a function, non-namespace-mode not supported.
        Throws:
        java.lang.IllegalArgumentException - iff illegal colon positions or prefix not in map.