eu.bandm.tools.util

Class NamespaceName

java.lang.Object

eu.bandm.tools.util.NamespaceName

All Implemented Interfaces:

Serializable

@Runtime
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 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

Field Summary

Fields

Modifier and Type	Field and Description
static String	curlyBrace_close
static String	curlyBrace_open
static String	namespace_prefix_xml The reserved prefix for the "xml:" namespace.
static String	namespace_uri_xml The reserved URI for the "xml:" namespace.
static char	prefixSeparator

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
static NamespaceName	attribute(Function<? super String,? extends String> namespaceMapping, String qname) Like above, but the prefix mapping is a function, non-namespace-mode not supported.
static NamespaceName	attribute(Map<? extends String,? extends String> namespaceMapping, String qname, boolean namespacesEnabled) Parsing function for a qualified name which stands for an attribute name.
static NamespaceName	element(Function<? super String,? extends String> namespaceMapping, String qname) Like above, but the prefix mapping is a function, non-namespace-mode not supported.
static NamespaceName	element(Map<? extends String,? extends String> namespaceMapping, 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(Object o)
String	getLocalName() Local names are only defined in namespace mode.
boolean	getNamespacesEnabled()
String	getNamespaceURI()
String	getPrefix()
String	getQName()
int	hashCode()
boolean	matches(String namespaceURI, String localName, 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(String s) Parse the input in the "curly brace" syntax of an "universal name".
String	toString() Render this to a string in the "curly brace" format, similar to a "universal name".
String	universalName() Render this to a string in the "curly brace" format of a "universal name".
static @Opt String[]	validQName(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

prefixSeparator

public static final char prefixSeparator

See Also:

Constant Field Values

curlyBrace_open

public static final String curlyBrace_open

See Also:

Constant Field Values

curlyBrace_close

public static final String curlyBrace_close

See Also:

Constant Field Values

namespace_prefix_xml

public static final String namespace_prefix_xml

The reserved prefix for the "xml:" namespace.

See Also:

Constant Field Values

namespace_uri_xml

public static final String namespace_uri_xml

The reserved URI for the "xml:" namespace.

See Also:

Constant Field Values

Constructor Detail

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"

NamespaceName

public NamespaceName(String namespaceURI,
                     String prefix,
                     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(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 http://www.w3.org/TR/xhtml1/, not those of .

Parameters:

qname - a name containing arbitrary many colons, but not considered in namespace mode. It will be returned by getQName().

Method Detail

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, use getQName() instead.//FIXME SINNVOLL??

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

Overrides:

equals in class Object

equals

protected boolean equals(NamespaceName n)

Compares only namespaceURI and localname, prefix is irrelevant.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

parseInlineURIFormat

public static NamespaceName parseInlineURIFormat(String s)
                                          throws 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:

IllegalArgumentException

matches

public boolean matches(String namespaceURI,
                       String localName,
                       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 String[] validQName(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(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. 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:

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

Like above, but the prefix mapping is a function, non-namespace-mode not supported.

Throws:

IllegalArgumentException - iff illegal colon positions or prefix not in map.

attribute

public static NamespaceName attribute(Function<? super String,? extends String> namespaceMapping,
                                      String qname)
                               throws IllegalArgumentException

Like above, but the prefix mapping is a function, non-namespace-mode not supported.

Throws:

IllegalArgumentException - iff illegal colon positions or prefix not in map.