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