X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=yang%2Fyang-common%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fyangtools%2Fyang%2Fcommon%2FQName.java;h=d74786b910fabc6ad8efa51eabb6b9381928731d;hb=c4517068c0183a892703b26baf098c97bfb2a854;hp=ffdf08bb87663dd03e68b6cb36ff1520bf6f01ce;hpb=bc36bd98457adbbc00152958531b08e0e2b4f11d;p=yangtools.git diff --git a/yang/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/QName.java b/yang/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/QName.java index ffdf08bb87..d74786b910 100644 --- a/yang/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/QName.java +++ b/yang/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/QName.java @@ -7,37 +7,33 @@ */ package org.opendaylight.yangtools.yang.common; -import static com.google.common.base.Preconditions.checkArgument; 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.io.Serializable; -import java.net.URI; -import java.net.URISyntaxException; import java.util.Objects; import java.util.Optional; import java.util.regex.Matcher; import java.util.regex.Pattern; -import javax.annotation.RegEx; +import org.checkerframework.checker.regex.qual.Regex; import org.eclipse.jdt.annotation.NonNull; import org.eclipse.jdt.annotation.Nullable; -import org.opendaylight.yangtools.concepts.Identifier; -import org.opendaylight.yangtools.concepts.Immutable; -import org.opendaylight.yangtools.concepts.WritableObject; /** - * 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. * *

- * 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. + * + *

+ * The local name must conform to RFC7950 Section 6.2. * *

- * - *

- * QName may also have prefix 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, Identifier, WritableObject { +public final class QName extends AbstractQName implements Comparable { + /** + * 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 INTERNER = Interners.newWeakInterner(); - private static final long serialVersionUID = 5398411242927766414L; + // 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 = ")"; - @RegEx + @Regex private static final String QNAME_STRING_FULL = "^\\((.+)\\?revision=(.+)\\)(.+)$"; private static final Pattern QNAME_PATTERN_FULL = Pattern.compile(QNAME_STRING_FULL); - @RegEx + @Regex private static final String QNAME_STRING_NO_REVISION = "^\\((.+)\\)(.+)$"; private static final Pattern QNAME_PATTERN_NO_REVISION = Pattern.compile(QNAME_STRING_NO_REVISION); - private static final char[] ILLEGAL_CHARACTERS = { '?', '(', ')', '&', ':' }; - private final @NonNull QNameModule module; - private final @NonNull String localName; private transient int hash = 0; - private QName(final QNameModule module, final @NonNull String localName) { + QName(final QNameModule module, final @NonNull String localName) { + super(localName); this.module = requireNonNull(module); - this.localName = requireNonNull(localName); } /** @@ -88,23 +102,10 @@ public final class QName implements Immutable, Serializable, Comparable, * @param localName * YANG schema identifier */ - private QName(final URI namespace, final String localName) { + private QName(final XMLNamespace namespace, final String localName) { this(QNameModule.create(namespace), checkLocalName(localName)); } - private static @NonNull String checkLocalName(final String localName) { - checkArgument(localName != null, "Parameter 'localName' may not be null."); - checkArgument(!localName.isEmpty(), "Parameter 'localName' must be a non-empty string."); - - for (final char c : ILLEGAL_CHARACTERS) { - if (localName.indexOf(c) != -1) { - throw new IllegalArgumentException("Parameter 'localName':'" + localName - + "' contains illegal character '" + c + "'"); - } - } - return localName; - } - public static @NonNull QName create(final String input) { Matcher matcher = QNAME_PATTERN_FULL.matcher(input); if (matcher.matches()) { @@ -115,7 +116,7 @@ public final class QName implements Immutable, Serializable, Comparable, } matcher = QNAME_PATTERN_NO_REVISION.matcher(input); if (matcher.matches()) { - final URI namespace = URI.create(matcher.group(1)); + final XMLNamespace namespace = XMLNamespace.of(matcher.group(1)); final String localName = matcher.group(2); return new QName(namespace, localName); } @@ -129,11 +130,11 @@ public final class QName implements Immutable, Serializable, Comparable, /** * Creates new QName. * - * @param qnameModule - * Namespace and revision enclosed as a QNameModule - * @param localName - * Local name part of QName. MUST NOT BE null. + * @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 */ public static @NonNull QName create(final QNameModule qnameModule, final String localName) { return new QName(requireNonNull(qnameModule, "module may not be null"), checkLocalName(localName)); @@ -147,7 +148,7 @@ public final class QName implements Immutable, Serializable, Comparable, * @param localName Local name part of QName. MUST NOT BE null. * @return Instance of QName */ - public static @NonNull QName create(final URI namespace, final @Nullable Revision revision, + public static @NonNull QName create(final XMLNamespace namespace, final @Nullable Revision revision, final String localName) { return create(QNameModule.create(namespace, revision), localName); } @@ -160,7 +161,7 @@ public final class QName implements Immutable, Serializable, Comparable, * @param localName Local name part of QName. MUST NOT BE null. * @return Instance of QName */ - public static @NonNull QName create(final URI namespace, final Optional revision, + public static @NonNull QName create(final XMLNamespace namespace, final Optional revision, final String localName) { return create(QNameModule.create(namespace, revision), localName); } @@ -174,7 +175,7 @@ public final class QName implements Immutable, Serializable, Comparable, * @return Instance of QName */ public static @NonNull QName create(final String namespace, final String localName, final Revision revision) { - return create(QNameModule.create(parseNamespace(namespace), revision), localName); + return create(QNameModule.create(XMLNamespace.of(namespace), revision), localName); } /** @@ -189,7 +190,7 @@ public final class QName implements Immutable, Serializable, Comparable, * to {@code YYYY-mm-dd}. */ public static @NonNull QName create(final String namespace, final String revision, final String localName) { - return create(parseNamespace(namespace), Revision.of(revision), localName); + return create(XMLNamespace.of(namespace), Revision.of(revision), localName); } /** @@ -202,7 +203,7 @@ public final class QName implements Immutable, Serializable, Comparable, * @throws IllegalArgumentException If {@code namespace} is not valid URI. */ public static @NonNull QName create(final String namespace, final String localName) { - return create(parseNamespace(namespace), localName); + return create(XMLNamespace.of(namespace), localName); } /** @@ -214,7 +215,7 @@ public final class QName implements Immutable, Serializable, Comparable, * @throws NullPointerException If any of parameters is null. * @throws IllegalArgumentException If namespace is not valid URI. */ - public static @NonNull QName create(final URI namespace, final String localName) { + public static @NonNull QName create(final XMLNamespace namespace, final String localName) { return new QName(namespace, localName); } @@ -225,11 +226,32 @@ public final class QName implements Immutable, Serializable, Comparable, * @return A QName instance * @throws IOException if I/O error occurs */ - public static QName readFrom(final DataInput in) throws IOException { + public static @NonNull QName readFrom(final DataInput in) throws IOException { + if (in instanceof QNameAwareDataInput) { + return ((QNameAwareDataInput) in).readQName(); + } + final QNameModule module = QNameModule.readFrom(in); return new QName(module, checkLocalName(in.readUTF())); } + /** + * 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. + * + *

+ * 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 + */ + @Beta + public static @NonNull QName unsafeOf(final @NonNull QNameModule qnameModule, final @NonNull String localName) { + return new QName(qnameModule, localName); + } + /** * Get the module component of the QName. * @@ -244,21 +266,10 @@ public final class QName implements Immutable, Serializable, Comparable, * * @return XMLNamespace assigned to the YANG module. */ - public @NonNull URI getNamespace() { + public @NonNull XMLNamespace getNamespace() { return module.getNamespace(); } - /** - * Returns YANG schema identifier which were defined for this node in the - * YANG module. - * - * @return YANG schema identifier which were defined for this node in the - * YANG module - */ - public @NonNull String getLocalName() { - return localName; - } - /** * Returns revision of the YANG module if the module has defined revision. * @@ -268,11 +279,7 @@ public final class QName implements Immutable, Serializable, Comparable, return module.getRevision(); } - /** - * Return an interned reference to a equivalent QName. - * - * @return Interned reference, or this object if it was interned. - */ + @Override public @NonNull QName intern() { // We also want to make sure we keep the QNameModule cached final QNameModule cacheMod = module.intern(); @@ -280,7 +287,7 @@ public final class QName implements Immutable, Serializable, Comparable, // 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 : QName.create(cacheMod, localName.intern()); + final QName template = cacheMod == module ? this : new QName(cacheMod, getLocalName().intern()); return INTERNER.intern(template); } @@ -288,18 +295,18 @@ public final class QName implements Immutable, Serializable, Comparable, @Override public int hashCode() { if (hash == 0) { - hash = Objects.hash(module, localName); + hash = Objects.hash(module, getLocalName()); } return hash; } /** - * Compares the specified object with this list for equality. Returns true if and only if the specified + * 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. * * @param obj the object to be compared for equality with this QName - * @return true if the specified object is equal to this QName + * @return {@code true} if the specified object is equal to this QName */ @Override public boolean equals(final Object obj) { @@ -310,41 +317,22 @@ public final class QName implements Immutable, Serializable, Comparable, return false; } final QName other = (QName) obj; - return Objects.equals(localName, other.localName) && module.equals(other.module); - } - - private static @NonNull URI parseNamespace(final String namespace) { - try { - return new URI(namespace); - } catch (final URISyntaxException ue) { - throw new IllegalArgumentException("Namespace '" + namespace + "' is not a valid URI", ue); - } + return Objects.equals(getLocalName(), other.getLocalName()) && module.equals(other.module); } @Override public @NonNull String toString() { - final StringBuilder sb = new StringBuilder(); - if (getNamespace() != null) { - sb.append(QNAME_LEFT_PARENTHESIS).append(getNamespace()); - - final Optional rev = getRevision(); - if (rev.isPresent()) { - sb.append(QNAME_REVISION_DELIMITER).append(rev.get()); - } - sb.append(QNAME_RIGHT_PARENTHESIS); + final StringBuilder sb = new StringBuilder().append(QNAME_LEFT_PARENTHESIS).append(getNamespace()); + final Optional rev = getRevision(); + if (rev.isPresent()) { + sb.append(QNAME_REVISION_DELIMITER).append(rev.get()); } - sb.append(localName); - return sb.toString(); + return sb.append(QNAME_RIGHT_PARENTHESIS).append(getLocalName()).toString(); } - /** - * Returns a QName with the specified QNameModule and the same localname as this one. - * - * @param newModule New QNameModule to use - * @return a QName with specified QNameModule and same local name as this one - */ - public @NonNull QName withModule(final QNameModule newModule) { - return new QName(newModule, localName); + @Override + public @NonNull QName bindTo(final QNameModule namespace) { + return module.equals(namespace) ? this : super.bindTo(namespace); } /** @@ -354,7 +342,8 @@ public final class QName implements Immutable, Serializable, Comparable, * @return a QName with the same namespace and local name, but with no revision. */ public @NonNull QName withoutRevision() { - return getRevision().isPresent() ? new QName(module.withoutRevision(), localName) : this; + final QNameModule newModule; + return (newModule = module.withoutRevision()) == module ? this : new QName(newModule, getLocalName()); } /** @@ -383,7 +372,7 @@ public final class QName implements Immutable, Serializable, Comparable, * @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 @@ -392,7 +381,7 @@ public final class QName implements Immutable, Serializable, Comparable, @SuppressWarnings("checkstyle:parameterName") public int compareTo(final QName o) { // compare mandatory localName parameter - int result = localName.compareTo(o.localName); + int result = getLocalName().compareTo(o.getLocalName()); if (result != 0) { return result; } @@ -401,7 +390,16 @@ public final class QName implements Immutable, Serializable, Comparable, @Override public void writeTo(final DataOutput out) throws IOException { - module.writeTo(out); - out.writeUTF(localName); + if (out instanceof QNameAwareDataOutput) { + ((QNameAwareDataOutput) out).writeQName(this); + } else { + module.writeTo(out); + out.writeUTF(getLocalName()); + } + } + + @Override + Object writeReplace() { + return new QNv1(this); } }