Add XMLNamespace
[yangtools.git] / yang / yang-common / src / main / java / org / opendaylight / yangtools / yang / common / QName.java
index d2ccf637d78ec6096daeb56ddbf2a3b3380ffc76..d74786b910fabc6ad8efa51eabb6b9381928731d 100644 (file)
@@ -7,27 +7,33 @@
  */
 package org.opendaylight.yangtools.yang.common;
 
-import static org.opendaylight.yangtools.yang.common.SimpleDateFormatUtil.getRevisionFormat;
-
-import java.io.Serializable;
-import java.net.URI;
-import java.net.URISyntaxException;
-import java.text.ParseException;
-import java.util.Date;
+import static java.util.Objects.requireNonNull;
+
+import com.google.common.annotations.Beta;
+import com.google.common.collect.Interner;
+import com.google.common.collect.Interners;
+import java.io.DataInput;
+import java.io.DataOutput;
+import java.io.IOException;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
-
-import org.opendaylight.yangtools.concepts.Immutable;
+import org.checkerframework.checker.regex.qual.Regex;
+import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.Nullable;
 
 /**
- * The QName from XML consists of local name of element and XML namespace, but
- * for our use, we added module revision to it.
+ * The QName from XML consists of local name of element and XML namespace, but for our use, we added module revision to
+ * it.
+ *
+ * <p>
+ * In YANG context QName is full name of defined node, type, procedure or notification. QName consists of XML namespace,
+ * YANG model revision and local name of defined type. It is used to prevent name clashes between nodes with same local
+ * name, but from different schemas.
  *
- * In YANG context QName is full name of defined node, type, procedure or
- * notification. QName consists of XML namespace, YANG model revision and local
- * name of defined type. It is used to prevent name clashes between nodes with
- * same local name, but from different schemas.
+ * <p>
+ * The local name must conform to <a href="https://tools.ietf.org/html/rfc7950#section-6.2">RFC7950 Section 6.2</a>.
  *
  * <ul>
  * <li><b>XMLNamespace</b> - {@link #getNamespace()} - the namespace assigned to the YANG module which
@@ -37,55 +43,55 @@ import org.opendaylight.yangtools.concepts.Immutable;
  * <li><b>LocalName</b> - {@link #getLocalName()} - the YANG schema identifier which were defined for this
  * node in the YANG module</li>
  * </ul>
- *
- * QName may also have <code>prefix</code> assigned, but prefix does not
- * affect equality and identity of two QNames and carry only information
- * which may be useful for serializers / deserializers.
- *
- *
  */
-public final class QName implements Immutable, Serializable, Comparable<QName> {
-    private static final long serialVersionUID = 5398411242927766414L;
+public final class QName extends AbstractQName implements Comparable<QName> {
+    /**
+     * A {@link DataInput} which has an understanding of {@link QName}'s semantics.
+     */
+    @Beta
+    public interface QNameAwareDataInput extends DataInput {
+        /**
+         * Read a {@link QName} from the stream.
+         *
+         * @return A QName
+         * @throws IOException if an I/O error occurs.
+         */
+        @NonNull QName readQName() throws IOException;
+    }
+
+    @Beta
+    public interface QNameAwareDataOutput extends DataOutput {
+        /**
+         * Write a {@link QName} into the stream.
+         *
+         * @param qname A QName
+         * @throws  IOException if an I/O error occurs.
+         */
+        void writeQName(@NonNull QName qname) throws IOException;
+    }
+
+    private static final Interner<QName> INTERNER = Interners.newWeakInterner();
+    // Note: 5398411242927766414L is used for versions < 3.0.0 without writeReplace
+    private static final long serialVersionUID = 1L;
 
     static final String QNAME_REVISION_DELIMITER = "?revision=";
     static final String QNAME_LEFT_PARENTHESIS = "(";
     static final String QNAME_RIGHT_PARENTHESIS = ")";
 
-    private static final Pattern QNAME_PATTERN_FULL = Pattern.compile("^\\((.+)\\" + QNAME_REVISION_DELIMITER
-            + "(.+)\\)(.+)$");
-    private static final Pattern QNAME_PATTERN_NO_REVISION = Pattern.compile("^\\((.+)\\)(.+)$");
-    private static final Pattern QNAME_PATTERN_NO_NAMESPACE_NO_REVISION = Pattern.compile("^(.+)$");
+    @Regex
+    private static final String QNAME_STRING_FULL = "^\\((.+)\\?revision=(.+)\\)(.+)$";
+    private static final Pattern QNAME_PATTERN_FULL = Pattern.compile(QNAME_STRING_FULL);
 
-    private static final char[] ILLEGAL_CHARACTERS = new char[] { '?', '(', ')', '&' };
+    @Regex
+    private static final String QNAME_STRING_NO_REVISION = "^\\((.+)\\)(.+)$";
+    private static final Pattern QNAME_PATTERN_NO_REVISION = Pattern.compile(QNAME_STRING_NO_REVISION);
 
-    // Mandatory
-    private final QNameModule module;
-    // Mandatory
-    private final String localName;
-    // Nullable
-    private final String prefix;
+    private final @NonNull QNameModule module;
+    private transient int hash = 0;
 
-    private QName(final QNameModule module, final String prefix, final String localName) {
-        this.localName = checkLocalName(localName);
-        this.prefix = prefix;
-        this.module = module;
-    }
-
-    /**
-     * QName Constructor.
-     *
-     * @param namespace
-     *            the namespace assigned to the YANG module
-     * @param revision
-     *            the revision of the YANG module
-     * @param prefix
-     *            locally defined prefix assigned to local name
-     * @param localName
-     *            YANG schema identifier
-     *
-     */
-    public QName(final URI namespace, final Date revision, final String prefix, final String localName) {
-        this(QNameModule.create(namespace, revision), prefix, localName);
+    QName(final QNameModule module, final @NonNull String localName) {
+        super(localName);
+        this.module = requireNonNull(module);
     }
 
     /**
@@ -96,397 +102,304 @@ public final class QName implements Immutable, Serializable, Comparable<QName> {
      * @param localName
      *            YANG schema identifier
      */
-    public QName(final URI namespace, final String localName) {
-        this(namespace, null, "", localName);
+    private QName(final XMLNamespace namespace, final String localName) {
+        this(QNameModule.create(namespace), checkLocalName(localName));
     }
 
-    private static String checkLocalName(final String localName) {
-        if (localName == null) {
-            throw new IllegalArgumentException("Parameter 'localName' may not be null.");
-        }
-        if (localName.length() == 0) {
-            throw new IllegalArgumentException("Parameter 'localName' must be a non-empty string.");
+    public static @NonNull QName create(final String input) {
+        Matcher matcher = QNAME_PATTERN_FULL.matcher(input);
+        if (matcher.matches()) {
+            final String namespace = matcher.group(1);
+            final String revision = matcher.group(2);
+            final String localName = matcher.group(3);
+            return create(namespace, revision, localName);
         }
-
-        for (char c : ILLEGAL_CHARACTERS) {
-            if (localName.indexOf(c) != -1) {
-                throw new IllegalArgumentException(String.format(
-                        "Parameter 'localName':'%s' contains illegal character '%s'", localName, c));
-            }
+        matcher = QNAME_PATTERN_NO_REVISION.matcher(input);
+        if (matcher.matches()) {
+            final XMLNamespace namespace = XMLNamespace.of(matcher.group(1));
+            final String localName = matcher.group(2);
+            return new QName(namespace, localName);
         }
-        return localName;
+        throw new IllegalArgumentException("Invalid input: " + input);
     }
 
-    /**
-     * QName Constructor.
-     *
-     * @param namespace
-     *            the namespace assigned to the YANG module
-     * @param revision
-     *            the revision of the YANG module
-     * @param localName
-     *            YANG schema identifier
-     *
-     * @deprecated Use {@link #create(URI, Date, String)} instead.
-     */
-    @Deprecated
-    public QName(final URI namespace, final Date revision, final String localName) {
-        this(QNameModule.create(namespace, revision), null, localName);
+    public static @NonNull QName create(final QName base, final String localName) {
+        return create(base.getModule(), localName);
     }
 
     /**
-     * Construct new QName which reuses namespace, revision and prefix from
-     * base.
+     * Creates new QName.
      *
-     * @param base
-     * @param localName
-     * @deprecated Use {@link #create(QName, String)} instead.
+     * @param qnameModule Namespace and revision enclosed as a QNameModule
+     * @param localName Local name part of QName. MUST NOT BE null.
+     * @return Instance of QName
+     * @throws NullPointerException if any argument is null
+     * @throws IllegalArgumentException if localName is not a valid YANG identifier
      */
-    @Deprecated
-    public QName(final QName base, final String localName) {
-        this(base.getModule(), base.getPrefix(), localName);
+    public static @NonNull QName create(final QNameModule qnameModule, final String localName) {
+        return new QName(requireNonNull(qnameModule, "module may not be null"), checkLocalName(localName));
     }
 
     /**
-     * @deprecated Use {@link #create(String)} instead. This implementation is
-     *             broken.
+     * Creates new QName.
+     *
+     * @param namespace Namespace of QName or null if namespace is undefined.
+     * @param revision Revision of namespace or null if revision is unspecified.
+     * @param localName Local name part of QName. MUST NOT BE null.
+     * @return Instance of QName
      */
-    @Deprecated
-    public QName(final String input) throws ParseException {
-        final String nsAndRev = input.substring(input.indexOf("(") + 1, input.indexOf(")"));
-        final Date revision;
-        final URI namespace;
-        if (nsAndRev.contains("?")) {
-            String[] splitted = nsAndRev.split("\\?");
-            namespace = URI.create(splitted[0]);
-            revision = getRevisionFormat().parse(splitted[1]);
-        } else {
-            namespace = URI.create(nsAndRev);
-            revision = null;
-        }
-
-        this.localName = checkLocalName(input.substring(input.indexOf(")") + 1));
-        this.prefix = null;
-        this.module = QNameModule.create(namespace, revision);
-    }
-
-    public static QName create(final String input) {
-        Matcher matcher = QNAME_PATTERN_FULL.matcher(input);
-        if (matcher.matches()) {
-            String namespace = matcher.group(1);
-            String revision = matcher.group(2);
-            String localName = matcher.group(3);
-            return create(namespace, revision, localName);
-        }
-        matcher = QNAME_PATTERN_NO_REVISION.matcher(input);
-        if (matcher.matches()) {
-            URI namespace = URI.create(matcher.group(1));
-            String localName = matcher.group(2);
-            return new QName(namespace, localName);
-        }
-        matcher = QNAME_PATTERN_NO_NAMESPACE_NO_REVISION.matcher(input);
-        if (matcher.matches()) {
-            String localName = matcher.group(1);
-            return new QName((URI) null, localName);
-        }
-        throw new IllegalArgumentException("Invalid input:" + input);
+    public static @NonNull QName create(final XMLNamespace namespace, final @Nullable Revision revision,
+            final String localName) {
+        return create(QNameModule.create(namespace, revision), localName);
     }
 
     /**
-     * Get the module component of the QName.
+     * Creates new QName.
      *
-     * @return Module component
+     * @param namespace Namespace of QName or null if namespace is undefined.
+     * @param revision Revision of namespace.
+     * @param localName Local name part of QName. MUST NOT BE null.
+     * @return Instance of QName
      */
-    public QNameModule getModule() {
-        return module;
+    public static @NonNull QName create(final XMLNamespace namespace, final Optional<Revision> revision,
+            final String localName) {
+        return create(QNameModule.create(namespace, revision), localName);
     }
 
     /**
-     * Returns XMLNamespace assigned to the YANG module.
+     * Creates new QName.
      *
-     * @return XMLNamespace assigned to the YANG module.
+     * @param namespace Namespace of QName or null if namespace is undefined.
+     * @param revision Revision of namespace or null if revision is unspecified.
+     * @param localName Local name part of QName. MUST NOT BE null.
+     * @return Instance of QName
      */
-    public URI getNamespace() {
-        return module.getNamespace();
+    public static @NonNull QName create(final String namespace, final String localName, final Revision revision) {
+        return create(QNameModule.create(XMLNamespace.of(namespace), revision), localName);
     }
 
     /**
-     * Returns YANG schema identifier which were defined for this node in the
-     * YANG module
+     * Creates new QName.
      *
-     * @return YANG schema identifier which were defined for this node in the
-     *         YANG module
+     * @param namespace Namespace of QName, MUST NOT BE Null.
+     * @param revision Revision of namespace / YANG module. MUST NOT BE null, MUST BE in format {@code YYYY-mm-dd}.
+     * @param localName Local name part of QName. MUST NOT BE null.
+     * @return A new QName
+     * @throws NullPointerException If any of parameters is null.
+     * @throws IllegalArgumentException If {@code namespace} is not valid URI or {@code revision} does not conform
+     *         to {@code YYYY-mm-dd}.
      */
-    public String getLocalName() {
-        return localName;
+    public static @NonNull QName create(final String namespace, final String revision, final String localName) {
+        return create(XMLNamespace.of(namespace), Revision.of(revision), localName);
     }
 
     /**
-     * Returns revision of the YANG module if the module has defined revision,
-     * otherwise returns <code>null</code>
+     * Creates new QName.
      *
-     * @return revision of the YANG module if the module has defined revision,
-     *         otherwise returns <code>null</code>
+     * @param namespace Namespace of QName, MUST NOT BE Null.
+     * @param localName Local name part of QName. MUST NOT BE null.
+     * @return A new QName
+     * @throws NullPointerException If any of parameters is null.
+     * @throws IllegalArgumentException If {@code namespace} is not valid URI.
      */
-    public Date getRevision() {
-        return module.getRevision();
+    public static @NonNull QName create(final String namespace, final String localName) {
+        return create(XMLNamespace.of(namespace), localName);
     }
 
     /**
-     * Returns locally defined prefix assigned to local name
+     * Creates new QName.
      *
-     * @return locally defined prefix assigned to local name
+     * @param namespace Namespace of QName, MUST NOT BE null.
+     * @param localName Local name part of QName. MUST NOT BE null.
+     * @return A new QName
+     * @throws NullPointerException If any of parameters is null.
+     * @throws IllegalArgumentException If <code>namespace</code> is not valid URI.
      */
-    public String getPrefix() {
-        return prefix;
-    }
-
-    @Override
-    public int hashCode() {
-        final int prime = 31;
-        int result = 1;
-        result = prime * result + ((localName == null) ? 0 : localName.hashCode());
-        result = prime * result + module.hashCode();
-        return result;
+    public static @NonNull QName create(final XMLNamespace namespace, final String localName) {
+        return new QName(namespace, localName);
     }
 
     /**
+     * Read a QName from a DataInput. The format is expected to match the output format of {@link #writeTo(DataOutput)}.
      *
-     * Compares the specified object with this list for equality.  Returns
-     * <tt>true</tt> if and only if the specified object is also instance of
-     * {@link QName} and its {@link #getLocalName()}, {@link #getNamespace()} and
-     * {@link #getRevision()} are equals to same properties of this instance.
-     *
-     * @param o the object to be compared for equality with this QName
-     * @return <tt>true</tt> if the specified object is equal to this QName
-     *
+     * @param in DataInput to read
+     * @return A QName instance
+     * @throws IOException if I/O error occurs
      */
-    @Override
-    public boolean equals(final Object obj) {
-        if (this == obj) {
-            return true;
+    public static @NonNull QName readFrom(final DataInput in) throws IOException {
+        if (in instanceof QNameAwareDataInput) {
+            return ((QNameAwareDataInput) in).readQName();
         }
-        if (!(obj instanceof QName)) {
-            return false;
-        }
-        final QName other = (QName) obj;
-        if (localName == null) {
-            if (other.localName != null) {
-                return false;
-            }
-        } else if (!localName.equals(other.localName)) {
-            return false;
-        }
-        return module.equals(other.module);
-    }
 
-    public static QName create(final QName base, final String localName) {
-        return new QName(base.getModule(), base.getPrefix(), localName);
+        final QNameModule module = QNameModule.readFrom(in);
+        return new QName(module, checkLocalName(in.readUTF()));
     }
 
     /**
-     * Creates new QName.
+     * Creates new QName composed of specified module and local name. This method does not perform lexical checking of
+     * localName, and it is the caller's responsibility to performs these checks.
      *
-     * @param qnameModule
-     *            Namespace and revision enclosed as a QNameModule
-     * @param prefix
-     *            Namespace prefix
-     * @param localName
-     *            Local name part of QName. MUST NOT BE null.
+     * <p>
+     * When in doubt, use {@link #create(QNameModule, String)} instead.
+     *
+     * @param qnameModule Namespace and revision enclosed as a QNameModule
+     * @param localName Local name part of QName, required to have been validated
      * @return Instance of QName
+     * @throws NullPointerException if any of the arguments is null
      */
-    public static QName create(final QNameModule module, final String prefix, final String localName) {
-        if (module == null) {
-            throw new NullPointerException("module may not be null");
-        }
-        return new QName(module, prefix, localName);
+    @Beta
+    public static @NonNull QName unsafeOf(final @NonNull QNameModule qnameModule, final @NonNull String localName) {
+        return new QName(qnameModule, localName);
     }
 
     /**
-     * Creates new QName.
+     * Get the module component of the QName.
      *
-     * @param qnameModule
-     *            Namespace and revision enclosed as a QNameModule
-     * @param localName
-     *            Local name part of QName. MUST NOT BE null.
-     * @return Instance of QName
+     * @return Module component
      */
-    public static QName create(final QNameModule qnameModule, final String localName) {
-        return new QName(qnameModule, null, localName);
+    public @NonNull QNameModule getModule() {
+        return module;
     }
 
     /**
-     * Creates new QName.
+     * Returns XMLNamespace assigned to the YANG module.
      *
-     * @param namespace
-     *            Namespace of QName or null if namespace is undefined.
-     * @param revision
-     *            Revision of namespace or null if revision is unspecified.
-     * @param localName
-     *            Local name part of QName. MUST NOT BE null.
-     * @return Instance of QName
+     * @return XMLNamespace assigned to the YANG module.
      */
-    public static QName create(final URI namespace, final Date revision, final String localName) {
-        return new QName(QNameModule.create(namespace, revision), null, localName);
+    public @NonNull XMLNamespace getNamespace() {
+        return module.getNamespace();
     }
 
     /**
+     * Returns revision of the YANG module if the module has defined revision.
      *
-     * Creates new QName.
-     *
-     * @param namespace
-     *            Namespace of QName, MUST NOT BE Null.
-     * @param revision
-     *            Revision of namespace / YANG module. MUST NOT BE null, MUST BE
-     *            in format <code>YYYY-mm-dd</code>.
-     * @param localName
-     *            Local name part of QName. MUST NOT BE null.
-     * @return
-     * @throws NullPointerException
-     *             If any of paramaters is null.
-     * @throws IllegalArgumentException
-     *             If <code>namespace</code> is not valid URI or
-     *             <code>revision</code> is not according to format
-     *             <code>YYYY-mm-dd</code>.
+     * @return revision of the YANG module if the module has defined revision.
      */
-    public static QName create(final String namespace, final String revision, final String localName)
-            throws IllegalArgumentException {
-        final URI namespaceUri;
-        try {
-            namespaceUri = new URI(namespace);
-        } catch (URISyntaxException ue) {
-            throw new IllegalArgumentException(String.format("Namespace '%s' is not a valid URI", namespace), ue);
-        }
+    public @NonNull Optional<Revision> getRevision() {
+        return module.getRevision();
+    }
+
+    @Override
+    public @NonNull QName intern() {
+        // We also want to make sure we keep the QNameModule cached
+        final QNameModule cacheMod = module.intern();
 
-        Date revisionDate = parseRevision(revision);
-        return create(namespaceUri, revisionDate, localName);
+        // Identity comparison is here on purpose, as we are deciding whether to potentially store 'qname' into the
+        // interner. It is important that it does not hold user-supplied reference (such a String instance from
+        // parsing of an XML document).
+        final QName template = cacheMod == module ? this : new QName(cacheMod, getLocalName().intern());
+
+        return INTERNER.intern(template);
     }
 
     @Override
-    public String toString() {
-        StringBuilder sb = new StringBuilder();
-        if (getNamespace() != null) {
-            sb.append(QNAME_LEFT_PARENTHESIS + getNamespace());
-
-            if (getFormattedRevision() != null) {
-                sb.append(QNAME_REVISION_DELIMITER + getFormattedRevision());
-            }
-            sb.append(QNAME_RIGHT_PARENTHESIS);
+    public int hashCode() {
+        if (hash == 0) {
+            hash = Objects.hash(module, getLocalName());
         }
-        sb.append(localName);
-        return sb.toString();
+        return hash;
     }
 
     /**
-     * Return string representation of revision in format
-     * <code>YYYY-mm-dd</code>
-     *
-     * YANG Specification defines format for <code>revision</code> as
-     * YYYY-mm-dd. This format for revision is reused accross multiple places
-     * such as capabilities URI, YANG modules, etc.
+     * Compares the specified object with this list for equality.  Returns {@code true} if and only if the specified
+     * object is also instance of {@link QName} and its {@link #getLocalName()}, {@link #getNamespace()} and
+     * {@link #getRevision()} are equals to same properties of this instance.
      *
-     * @return String representation of revision or null, if revision is not
-     *         set.
+     * @param obj the object to be compared for equality with this QName
+     * @return {@code true} if the specified object is equal to this QName
      */
-    public String getFormattedRevision() {
-        return module.getFormattedRevision();
+    @Override
+    public boolean equals(final Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (!(obj instanceof QName)) {
+            return false;
+        }
+        final QName other = (QName) obj;
+        return Objects.equals(getLocalName(), other.getLocalName()) && module.equals(other.module);
+    }
+
+    @Override
+    public @NonNull String toString() {
+        final StringBuilder sb = new StringBuilder().append(QNAME_LEFT_PARENTHESIS).append(getNamespace());
+        final Optional<Revision> rev = getRevision();
+        if (rev.isPresent()) {
+            sb.append(QNAME_REVISION_DELIMITER).append(rev.get());
+        }
+        return sb.append(QNAME_RIGHT_PARENTHESIS).append(getLocalName()).toString();
+    }
+
+    @Override
+    public @NonNull QName bindTo(final QNameModule namespace) {
+        return module.equals(namespace) ? this : super.bindTo(namespace);
     }
 
     /**
-     * Creates copy of this with revision and prefix unset.
+     * Returns a QName with the same namespace and local name, but with no revision. If this QName does not have
+     * a Revision, this object is returned.
      *
-     * @return copy of this QName with revision and prefix unset.
+     * @return a QName with the same namespace and local name, but with no revision.
      */
-    public QName withoutRevision() {
-        return QName.create(getNamespace(), null, localName);
-    }
-
-    public static Date parseRevision(final String formatedDate) {
-        try {
-            return getRevisionFormat().parse(formatedDate);
-        } catch (ParseException | RuntimeException e) {
-            throw new IllegalArgumentException(
-                    String.format("Revision '%s'is not in a supported format", formatedDate), e);
-        }
+    public @NonNull QName withoutRevision() {
+        final QNameModule newModule;
+        return (newModule = module.withoutRevision()) == module ? this : new QName(newModule, getLocalName());
     }
 
     /**
-     * Formats {@link Date} representing revision to format
-     * <code>YYYY-mm-dd</code>
+     * Formats {@link Revision} representing revision to format {@code YYYY-mm-dd}
      *
-     * YANG Specification defines format for <code>revision</code> as
-     * YYYY-mm-dd. This format for revision is reused accross multiple places
-     * such as capabilities URI, YANG modules, etc.
+     * <p>
+     * YANG Specification defines format for {@code revision<} as YYYY-mm-dd. This format for revision is reused across
+     * multiple places such as capabilities URI, YANG modules, etc.
      *
-     * @param revision
-     *            Date object to format or null
+     * @param revision Date object to format
      * @return String representation or null if the input was null.
      */
-    public static String formattedRevision(final Date revision) {
-        if (revision == null) {
-            return null;
-        }
-        return getRevisionFormat().format(revision);
+    public static @Nullable String formattedRevision(final Optional<Revision> revision) {
+        return revision.map(Revision::toString).orElse(null);
     }
 
     /**
-     *
      * Compares this QName to other, without comparing revision.
      *
-     * Compares instance of this to other instance of QName and returns true if
-     * both instances have equal <code>localName</code> ({@link #getLocalName()}
-     * ) and <code>namespace</code> ({@link #getNamespace()}).
+     * <p>
+     * Compares instance of this to other instance of QName and returns true if both instances have equal
+     * {@code localName} ({@link #getLocalName()}) and @{code namespace} ({@link #getNamespace()}).
      *
-     * @param other
-     *            Other QName. Must not be null.
-     * @return true if this instance and other have equals localName and
-     *         namespace.
-     * @throws NullPointerException
-     *             if <code>other</code> is null.
+     * @param other Other QName. Must not be null.
+     * @return true if this instance and other have equals localName and namespace.
+     * @throws NullPointerException if {@code other} is null.
      */
     public boolean isEqualWithoutRevision(final QName other) {
-        return localName.equals(other.getLocalName()) && Objects.equals(getNamespace(), other.getNamespace());
+        return getLocalName().equals(other.getLocalName()) && Objects.equals(getNamespace(), other.getNamespace());
     }
 
+    // FIXME: this comparison function looks odd. We are sorting first by local name and then by module? What is
+    //        the impact on iteration order of SortedMap<QName, ?>?
     @Override
-    public int compareTo(final QName other) {
+    @SuppressWarnings("checkstyle:parameterName")
+    public int compareTo(final QName o) {
         // compare mandatory localName parameter
-        int result = localName.compareTo(other.localName);
+        int result = getLocalName().compareTo(o.getLocalName());
         if (result != 0) {
             return result;
         }
+        return module.compareTo(o.module);
+    }
 
-        // compare nullable namespace parameter
-        if (getNamespace() == null) {
-            if (other.getNamespace() != null) {
-                return -1;
-            }
-        } else {
-            if (other.getNamespace() == null) {
-                return 1;
-            }
-            result = getNamespace().compareTo(other.getNamespace());
-            if (result != 0) {
-                return result;
-            }
-        }
-
-        // compare nullable revision parameter
-        if (getRevision() == null) {
-            if (other.getRevision() != null) {
-                return -1;
-            }
+    @Override
+    public void writeTo(final DataOutput out) throws IOException {
+        if (out instanceof QNameAwareDataOutput) {
+            ((QNameAwareDataOutput) out).writeQName(this);
         } else {
-            if (other.getRevision() == null) {
-                return 1;
-            }
-            result = getRevision().compareTo(other.getRevision());
-            if (result != 0) {
-                return result;
-            }
+            module.writeTo(out);
+            out.writeUTF(getLocalName());
         }
-
-        return result;
     }
 
+    @Override
+    Object writeReplace() {
+        return new QNv1(this);
+    }
 }