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=f70a736217a554bb2271dbcf4b2f507c07746473;hb=c7e8081901536d97a12b141cbb538f70c7a93d61;hp=46dfbc6242edbd82198fa8be1879fe8b6e04deff;hpb=3e0b6245313682a974e16b83b45aa146cd1a7e03;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 46dfbc6242..f70a736217 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,27 +7,35 @@ */ package org.opendaylight.yangtools.yang.common; -import static org.opendaylight.yangtools.yang.common.SimpleDateFormatUtil.getRevisionFormat; - -import java.io.Serializable; +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.net.URI; import java.net.URISyntaxException; -import java.text.ParseException; -import java.util.Date; 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. + * + *

+ * 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 { - private static final long serialVersionUID = 5398411242927766414L; +public final class QName extends AbstractQName implements Comparable { + private static final Interner 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("^(.+)$"); - - private static final char[] ILLEGAL_CHARACTERS = new char[] { '?', '(', ')', '&' }; + @Regex + private static final String QNAME_STRING_FULL = "^\\((.+)\\?revision=(.+)\\)(.+)$"; + private static final Pattern QNAME_PATTERN_FULL = Pattern.compile(QNAME_STRING_FULL); - // Mandatory - private final QNameModule module; - // Mandatory - private final String localName; - // Nullable - private final String prefix; + @Regex + private static final String QNAME_STRING_NO_REVISION = "^\\((.+)\\)(.+)$"; + private static final Pattern QNAME_PATTERN_NO_REVISION = Pattern.compile(QNAME_STRING_NO_REVISION); - private QName(final QNameModule module, final String prefix, final String localName) { - this.localName = checkLocalName(localName); - this.prefix = prefix; - this.module = module; - } + private final @NonNull QNameModule module; + private transient int hash = 0; - /** - * 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 - * - * @deprecated Prefix storage in QNames is deprecated. - */ - @Deprecated - 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); } /** @@ -98,350 +79,304 @@ public final class QName implements Immutable, Serializable, Comparable { * @param localName * YANG schema identifier */ - public QName(final URI namespace, final String localName) { - this(namespace, null, "", localName); + private QName(final URI 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."); - } - - for (char c : ILLEGAL_CHARACTERS) { - if (localName.indexOf(c) != -1) { - throw new IllegalArgumentException(String.format( - "Parameter 'localName':'%s' contains illegal character '%s'", localName, c)); - } - } - return localName; - } - - public static QName create(final String input) { + public static @NonNull 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); + final String namespace = matcher.group(1); + final String revision = matcher.group(2); + final 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); + final URI namespace = URI.create(matcher.group(1)); + final 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); + throw new IllegalArgumentException("Invalid input: " + input); + } + + public static @NonNull QName create(final QName base, final String localName) { + return create(base.getModule(), localName); } /** - * Get the module component of the QName. + * Creates new QName. * - * @return Module component + * @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 QNameModule getModule() { - return module; + public static @NonNull QName create(final QNameModule qnameModule, final String localName) { + return new QName(requireNonNull(qnameModule, "module may not be null"), checkLocalName(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 URI namespace, final @Nullable Revision revision, + final String localName) { + return create(QNameModule.create(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 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 String getLocalName() { - return localName; + public static @NonNull QName create(final URI namespace, final Optional revision, + final String localName) { + return create(QNameModule.create(namespace, revision), localName); } /** - * Returns revision of the YANG module if the module has defined revision, - * otherwise returns null + * Creates new QName. * - * @return revision of the YANG module if the module has defined revision, - * otherwise returns null + * @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 Date getRevision() { - return module.getRevision(); + public static @NonNull QName create(final String namespace, final String localName, final Revision revision) { + return create(QNameModule.create(parseNamespace(namespace), revision), localName); } /** - * Returns locally defined prefix assigned to local name - * - * @return locally defined prefix assigned to local name + * Creates new QName. * - * @deprecated Prefix storage in QNames is deprecated. + * @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}. */ - @Deprecated - public String getPrefix() { - return prefix; + public static @NonNull QName create(final String namespace, final String revision, final String localName) { + return create(parseNamespace(namespace), Revision.of(revision), localName); } - @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; + /** + * Creates new QName. + * + * @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 static @NonNull QName create(final String namespace, final String localName) { + return create(parseNamespace(namespace), localName); } /** + * Creates new QName. * - * Compares the specified object with this list for equality. Returns - * 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 o the object to be compared for equality with this QName - * @return true if the specified object is equal to this QName - * + * @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 namespace is not valid URI. */ - @Override - public boolean equals(final Object obj) { - if (this == obj) { - return true; - } - 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 @NonNull QName create(final URI namespace, final String localName) { + return new QName(namespace, localName); } - public static QName create(final QName base, final String localName) { - return new QName(base.getModule(), base.getPrefix(), localName); + /** + * Read a QName from a DataInput. The format is expected to match the output format of {@link #writeTo(DataOutput)}. + * + * @param in DataInput to read + * @return A QName instance + * @throws IOException if I/O error occurs + */ + public static @NonNull QName readFrom(final DataInput in) throws IOException { + 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. - * @return Instance of QName + *

+ * When in doubt, use {@link #create(QNameModule, String)} instead. * - * @deprecated Prefix storage in QNames is deprecated. + * @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 */ - @Deprecated - 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 URI 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 YYYY-mm-dd. - * @param localName - * Local name part of QName. MUST NOT BE null. - * @return - * @throws NullPointerException - * If any of paramaters is null. - * @throws IllegalArgumentException - * If namespace is not valid URI or - * revision is not according to format - * YYYY-mm-dd. + * @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 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(); + + // 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()); - Date revisionDate = parseRevision(revision); - return create(namespaceUri, revisionDate, localName); + 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 - * YYYY-mm-dd - * - * YANG Specification defines format for revision 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); } - /** - * Creates copy of this with revision and prefix unset. - * - * @return copy of this QName with revision and prefix unset. - */ - public QName withoutRevision() { - return QName.create(getNamespace(), null, localName); + 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); + } } - 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); + @Override + public @NonNull String toString() { + 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()); } + 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); + } + + /** + * 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 a QName with the same namespace and local name, but with no revision. + */ + public @NonNull QName withoutRevision() { + final QNameModule newModule; + return (newModule = module.withoutRevision()) == module ? this : new QName(newModule, getLocalName()); } /** - * Formats {@link Date} representing revision to format - * YYYY-mm-dd + * Formats {@link Revision} representing revision to format {@code YYYY-mm-dd} * - * YANG Specification defines format for revision as - * YYYY-mm-dd. This format for revision is reused accross multiple places - * such as capabilities URI, YANG modules, etc. + *

+ * 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) { + 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 localName ({@link #getLocalName()} - * ) and namespace ({@link #getNamespace()}). + *

+ * 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 other 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? @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; - } - } else { - if (other.getRevision() == null) { - return 1; - } - result = getRevision().compareTo(other.getRevision()); - if (result != 0) { - return result; - } - } - - return result; + @Override + public void writeTo(final DataOutput out) throws IOException { + module.writeTo(out); + out.writeUTF(getLocalName()); } + @Override + Object writeReplace() { + return new QNv1(this); + } }