common/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/UnresolvedQName.java

   1 /*
   2  * Copyright (c) 2021 PANTHEON.tech, s.r.o. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.yangtools.yang.common;
   9
  10 import static java.util.Objects.requireNonNull;
  11
  12 import com.google.common.base.MoreObjects;
  13 import com.google.common.collect.Interner;
  14 import com.google.common.collect.Interners;
  15 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
  16 import java.io.DataInput;
  17 import java.io.DataOutput;
  18 import java.io.IOException;
  19 import java.util.Optional;
  20 import org.eclipse.jdt.annotation.NonNull;
  21 import org.eclipse.jdt.annotation.NonNullByDefault;
  22 import org.eclipse.jdt.annotation.Nullable;
  23
  24 /**
  25  * A {@link QName} equivalent which has not been resolved. There are two subclasses:
  26  * <ol>
  27  *   <li>{@link Unqualified}, which holds only a local name available through {@link #getLocalName()}.<li>
  28  *   <li>{@link Qualified}, which also holds a string prefix available via {@link Qualified#getPrefix()}.</li>
  29  * </ol>
  30  */
  31 @NonNullByDefault
  32 public abstract sealed class UnresolvedQName extends AbstractQName {
  33     /**
  34      * An unresolved, qualified {@link QName}. It is guaranteed to hold a valid {@link #getLocalName()} bound to a
  35      * namespace identified through a prefix string, but remains unresolved. A resolved {@link QName} can be obtained
  36      * through {@link #bindTo(YangNamespaceContext)}.
  37      */
  38     public static final class Qualified extends UnresolvedQName implements Comparable<Qualified> {
  39         private static final long serialVersionUID = 1L;
  40         private static final Interner<Qualified> INTERNER = Interners.newWeakInterner();
  41
  42         private final String prefix;
  43
  44         private Qualified(final String prefix, final String localName) {
  45             super(localName);
  46             this.prefix = requireNonNull(prefix);
  47         }
  48
  49         /**
  50          * Create a new qualified unresolved QName.
  51          *
  52          * @param prefix The prefix on this qualified QName
  53          * @param localName The local name of this qualified QName
  54          * @return An UnqualifiedQName instance
  55          * @throws NullPointerException if any argument is {@code null}
  56          * @throws IllegalArgumentException if {@code localName} is not a valid YANG identifier
  57          */
  58         public static Qualified of(final String prefix, final String localName) {
  59             return new Qualified(checkLocalName(prefix), checkLocalName(localName));
  60         }
  61
  62         /**
  63          * Read an QualifiedQName from a DataInput. The format is expected to match the output format of
  64          * {@link #writeTo(DataOutput)}.
  65          *
  66          * @param in DataInput to read
  67          * @return An QualifiedQName instance
  68          * @throws IOException if I/O error occurs
  69          */
  70         public static Qualified readFrom(final DataInput in) throws IOException {
  71             return of(in.readUTF(), in.readUTF());
  72         }
  73
  74         @Override
  75         public @NonNull String getPrefix() {
  76             return prefix;
  77         }
  78
  79         public Optional<QName> bindTo(final YangNamespaceContext namespaceContext) {
  80             return namespaceContext.findNamespaceForPrefix(prefix).map(this::bindTo);
  81         }
  82
  83         @Override
  84         @SuppressFBWarnings(value = "ES_COMPARING_STRINGS_WITH_EQ", justification = "Interning identity check")
  85         public Qualified intern() {
  86             // Make sure to intern the string and check whether it refers to the same name as we are
  87             final String name = getLocalName();
  88             final String internedName = name.intern();
  89             final Qualified template = internedName == name ? this : new Qualified(prefix.intern(), internedName);
  90             return INTERNER.intern(template);
  91         }
  92
  93         @Override
  94         public Qualified withPrefix(final String newPrefix) {
  95             return prefix.equals(newPrefix) ? this : new Qualified(newPrefix, getLocalName());
  96         }
  97
  98         @Override
  99         @SuppressWarnings("checkstyle:parameterName")
 100         public int compareTo(final Qualified o) {
 101             return getLocalName().compareTo(o.getLocalName());
 102         }
 103
 104         @Override
 105         public void writeTo(final DataOutput out) throws IOException {
 106             out.writeUTF(getLocalName());
 107         }
 108
 109         @Override
 110         public int hashCode() {
 111             return getLocalName().hashCode();
 112         }
 113
 114         @Override
 115         public boolean equals(final @Nullable Object obj) {
 116             return this == obj || obj instanceof Qualified other && getLocalName().equals(other.getLocalName());
 117         }
 118
 119         @Override
 120         public String toString() {
 121             return MoreObjects.toStringHelper(this).add("localName", getLocalName()).toString();
 122         }
 123
 124         @Override
 125         Object writeReplace() {
 126             return new QQNv1(this);
 127         }
 128     }
 129
 130     /**
 131      * An unresolved, unqualified {@link QName}. It is guaranteed to hold a valid {@link #getLocalName()}, in the
 132      * default namespace, which is not resolved. A resolved {@link QName} can be constructed through
 133      * {@link #bindTo(QNameModule)}.
 134      */
 135     public static final class Unqualified extends UnresolvedQName implements Comparable<Unqualified> {
 136         private static final long serialVersionUID = 1L;
 137         private static final Interner<Unqualified> INTERNER = Interners.newWeakInterner();
 138
 139         private Unqualified(final String localName) {
 140             super(localName);
 141         }
 142
 143         /**
 144          * Create a new unqualified unresolved QName.
 145          *
 146          * @param localName The local name of this unqualified QName
 147          * @return An UnqualifiedQName instance
 148          * @throws NullPointerException if localName is {@code null}
 149          * @throws IllegalArgumentException if {@code localName} is not a valid YANG identifier
 150          */
 151         public static Unqualified of(final String localName) {
 152             return new Unqualified(checkLocalName(localName));
 153         }
 154
 155         /**
 156          * Read an UnqualifiedQName from a DataInput. The format is expected to match the output format of
 157          * {@link #writeTo(DataOutput)}.
 158          *
 159          * @param in DataInput to read
 160          * @return An UnqualifiedQName instance
 161          * @throws IOException if I/O error occurs
 162          */
 163         public static Unqualified readFrom(final DataInput in) throws IOException {
 164             return of(in.readUTF());
 165         }
 166
 167         @Override
 168         @SuppressFBWarnings(value = "ES_COMPARING_STRINGS_WITH_EQ", justification = "Interning identity check")
 169         public Unqualified intern() {
 170             // Make sure to intern the string and check whether it refers to the same name as we are
 171             final String name = getLocalName();
 172             final String internedName = name.intern();
 173             final Unqualified template = internedName == name ? this : new Unqualified(internedName);
 174             return INTERNER.intern(template);
 175         }
 176
 177         @Override
 178         public @Nullable String getPrefix() {
 179             return null;
 180         }
 181
 182         @Override
 183         public Qualified withPrefix(final String newPrefix) {
 184             return new Qualified(newPrefix, getLocalName());
 185         }
 186
 187         @Override
 188         @SuppressWarnings("checkstyle:parameterName")
 189         public int compareTo(final Unqualified o) {
 190             return getLocalName().compareTo(o.getLocalName());
 191         }
 192
 193         @Override
 194         public void writeTo(final DataOutput out) throws IOException {
 195             out.writeUTF(getLocalName());
 196         }
 197
 198         @Override
 199         public int hashCode() {
 200             return getLocalName().hashCode();
 201         }
 202
 203         @Override
 204         public boolean equals(final @Nullable Object obj) {
 205             return this == obj || obj instanceof Unqualified other && getLocalName().equals(other.getLocalName());
 206         }
 207
 208         @Override
 209         public String toString() {
 210             return MoreObjects.toStringHelper(this).add("localName", getLocalName()).toString();
 211         }
 212
 213         @Override
 214         Object writeReplace() {
 215             return new UQNv1(this);
 216         }
 217     }
 218
 219     private static final long serialVersionUID = 1L;
 220
 221     private UnresolvedQName(final String localName) {
 222         super(localName);
 223     }
 224
 225     /**
 226      * Create a new qualified unresolved QName.
 227      *
 228      * @param prefix The prefix on this qualified QName
 229      * @param localName The local name of this qualified QName
 230      * @return An UnqualifiedQName instance
 231      * @throws NullPointerException if any argument is {@code null}
 232      * @throws IllegalArgumentException if {@code localName} is not a valid YANG identifier
 233      * @deprecated Use {@link Qualified#of(String, String)} instead.
 234      */
 235     @Deprecated(since = "9.0.0", forRemoval = true)
 236     public static Qualified qualified(final String prefix, final String localName) {
 237         return Qualified.of(prefix, localName);
 238     }
 239
 240     /**
 241      * Create a new unqualified unresolved QName.
 242      *
 243      * @param localName The local name of this unqualified QName
 244      * @return An UnqualifiedQName instance
 245      * @throws NullPointerException if localName is {@code null}
 246      * @throws IllegalArgumentException if {@code localName} is not a valid YANG identifier
 247      * @deprecated Use {@link Unqualified#of(String)} instead.
 248      */
 249     @Deprecated(since = "9.0.0", forRemoval = true)
 250     public static Unqualified unqualified(final String localName) {
 251         return Unqualified.of(localName);
 252     }
 253
 254     /**
 255      * Try to create a new unqualified QName.
 256      *
 257      * @param localName The local name of this unqualified QName
 258      * @return An UnqualifiedQName instance, or null if localName is not valid
 259      */
 260     public static @Nullable Unqualified tryLocalName(final String localName) {
 261         return isValidLocalName(localName) ? new Unqualified(localName) : null;
 262     }
 263
 264     @Override
 265     public abstract UnresolvedQName intern();
 266
 267     /**
 268      * Return the prefix of this unresolved QName.
 269      *
 270      * @return This QName's prefix
 271      */
 272     public abstract @Nullable String getPrefix();
 273
 274     /**
 275      * Return a {@link Qualified} object bound to specified {@code prefix}.
 276      *
 277      * @return a {@link Qualified} object bound to specified {@code prefix}
 278      * @throws NullPointerException if {@code newPrefix} is null
 279      */
 280     public abstract Qualified withPrefix(String newPrefix);
 281 }