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         @java.io.Serial
  40         private static final long serialVersionUID = 1L;
  41         private static final Interner<Qualified> INTERNER = Interners.newWeakInterner();
  42
  43         private final String prefix;
  44
  45         private Qualified(final String prefix, final String localName) {
  46             super(localName);
  47             this.prefix = requireNonNull(prefix);
  48         }
  49
  50         /**
  51          * Create a new qualified unresolved QName.
  52          *
  53          * @param prefix The prefix on this qualified QName
  54          * @param localName The local name of this qualified QName
  55          * @return An UnqualifiedQName instance
  56          * @throws NullPointerException if any argument is {@code null}
  57          * @throws IllegalArgumentException if {@code localName} is not a valid YANG identifier
  58          */
  59         public static Qualified of(final String prefix, final String localName) {
  60             return new Qualified(checkLocalName(prefix), checkLocalName(localName));
  61         }
  62
  63         /**
  64          * Read an QualifiedQName from a DataInput. The format is expected to match the output format of
  65          * {@link #writeTo(DataOutput)}.
  66          *
  67          * @param in DataInput to read
  68          * @return An QualifiedQName instance
  69          * @throws IOException if I/O error occurs
  70          */
  71         public static Qualified readFrom(final DataInput in) throws IOException {
  72             return of(in.readUTF(), in.readUTF());
  73         }
  74
  75         @Override
  76         public @NonNull String getPrefix() {
  77             return prefix;
  78         }
  79
  80         public Optional<QName> bindTo(final YangNamespaceContext namespaceContext) {
  81             return namespaceContext.findNamespaceForPrefix(prefix).map(this::bindTo);
  82         }
  83
  84         @Override
  85         @SuppressFBWarnings(value = "ES_COMPARING_STRINGS_WITH_EQ", justification = "Interning identity check")
  86         public Qualified intern() {
  87             // Make sure to intern the string and check whether it refers to the same name as we are
  88             final String name = getLocalName();
  89             final String internedName = name.intern();
  90             final Qualified template = internedName == name ? this : new Qualified(prefix.intern(), internedName);
  91             return INTERNER.intern(template);
  92         }
  93
  94         @Override
  95         public Qualified withPrefix(final String newPrefix) {
  96             return prefix.equals(newPrefix) ? this : new Qualified(newPrefix, getLocalName());
  97         }
  98
  99         @Override
 100         @SuppressWarnings("checkstyle:parameterName")
 101         public int compareTo(final Qualified o) {
 102             return getLocalName().compareTo(o.getLocalName());
 103         }
 104
 105         @Override
 106         public void writeTo(final DataOutput out) throws IOException {
 107             out.writeUTF(getLocalName());
 108         }
 109
 110         @Override
 111         public int hashCode() {
 112             return getLocalName().hashCode();
 113         }
 114
 115         @Override
 116         public boolean equals(final @Nullable Object obj) {
 117             return this == obj || obj instanceof Qualified other && getLocalName().equals(other.getLocalName());
 118         }
 119
 120         @Override
 121         public String toString() {
 122             return MoreObjects.toStringHelper(this).add("localName", getLocalName()).toString();
 123         }
 124
 125         @Override
 126         Object writeReplace() {
 127             return new QQNv1(this);
 128         }
 129     }
 130
 131     /**
 132      * An unresolved, unqualified {@link QName}. It is guaranteed to hold a valid {@link #getLocalName()}, in the
 133      * default namespace, which is not resolved. A resolved {@link QName} can be constructed through
 134      * {@link #bindTo(QNameModule)}.
 135      */
 136     public static final class Unqualified extends UnresolvedQName implements Comparable<Unqualified> {
 137         @java.io.Serial
 138         private static final long serialVersionUID = 1L;
 139         private static final Interner<Unqualified> INTERNER = Interners.newWeakInterner();
 140
 141         Unqualified(final String localName) {
 142             super(localName);
 143         }
 144
 145         /**
 146          * Create a new unqualified unresolved QName.
 147          *
 148          * @param localName The local name of this unqualified QName
 149          * @return An UnqualifiedQName instance
 150          * @throws NullPointerException if localName is {@code null}
 151          * @throws IllegalArgumentException if {@code localName} is not a valid YANG identifier
 152          */
 153         public static Unqualified of(final String localName) {
 154             return new Unqualified(checkLocalName(localName));
 155         }
 156
 157         /**
 158          * Read an UnqualifiedQName from a DataInput. The format is expected to match the output format of
 159          * {@link #writeTo(DataOutput)}.
 160          *
 161          * @param in DataInput to read
 162          * @return An UnqualifiedQName instance
 163          * @throws IOException if I/O error occurs
 164          */
 165         public static Unqualified readFrom(final DataInput in) throws IOException {
 166             return of(in.readUTF());
 167         }
 168
 169         @Override
 170         public Unqualified unbind() {
 171             return this;
 172         }
 173
 174         @Override
 175         @SuppressFBWarnings(value = "ES_COMPARING_STRINGS_WITH_EQ", justification = "Interning identity check")
 176         public Unqualified intern() {
 177             // Make sure to intern the string and check whether it refers to the same name as we are
 178             final String name = getLocalName();
 179             final String internedName = name.intern();
 180             final Unqualified template = internedName == name ? this : new Unqualified(internedName);
 181             return INTERNER.intern(template);
 182         }
 183
 184         @Override
 185         public @Nullable String getPrefix() {
 186             return null;
 187         }
 188
 189         @Override
 190         public Qualified withPrefix(final String newPrefix) {
 191             return new Qualified(newPrefix, getLocalName());
 192         }
 193
 194         @Override
 195         @SuppressWarnings("checkstyle:parameterName")
 196         public int compareTo(final Unqualified o) {
 197             return getLocalName().compareTo(o.getLocalName());
 198         }
 199
 200         @Override
 201         public void writeTo(final DataOutput out) throws IOException {
 202             out.writeUTF(getLocalName());
 203         }
 204
 205         @Override
 206         public int hashCode() {
 207             return getLocalName().hashCode();
 208         }
 209
 210         @Override
 211         public boolean equals(final @Nullable Object obj) {
 212             return this == obj || obj instanceof Unqualified other && getLocalName().equals(other.getLocalName());
 213         }
 214
 215         @Override
 216         public String toString() {
 217             return MoreObjects.toStringHelper(this).add("localName", getLocalName()).toString();
 218         }
 219
 220         @Override
 221         Object writeReplace() {
 222             return new UQNv1(this);
 223         }
 224     }
 225
 226     @java.io.Serial
 227     private static final long serialVersionUID = 1L;
 228
 229     private UnresolvedQName(final String localName) {
 230         super(localName);
 231     }
 232
 233     /**
 234      * Try to create a new unqualified QName.
 235      *
 236      * @param localName The local name of this unqualified QName
 237      * @return An UnqualifiedQName instance, or null if localName is not valid
 238      */
 239     public static @Nullable Unqualified tryLocalName(final String localName) {
 240         return isValidLocalName(localName) ? new Unqualified(localName) : null;
 241     }
 242
 243     @Override
 244     public abstract UnresolvedQName intern();
 245
 246     /**
 247      * Return the prefix of this unresolved QName.
 248      *
 249      * @return This QName's prefix
 250      */
 251     public abstract @Nullable String getPrefix();
 252
 253     /**
 254      * Return a {@link Qualified} object bound to specified {@code prefix}.
 255      *
 256      * @return a {@link Qualified} object bound to specified {@code prefix}
 257      * @throws NullPointerException if {@code newPrefix} is null
 258      */
 259     public abstract Qualified withPrefix(String newPrefix);
 260 }