protocol/restconf-api/src/main/java/org/opendaylight/restconf/api/ApiPath.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.restconf.api;
   9
  10 import static com.google.common.base.Verify.verifyNotNull;
  11 import static java.util.Objects.requireNonNull;
  12
  13 import com.google.common.base.MoreObjects;
  14 import com.google.common.base.MoreObjects.ToStringHelper;
  15 import com.google.common.collect.ImmutableList;
  16 import com.google.common.escape.Escaper;
  17 import com.google.common.escape.Escapers;
  18 import java.io.IOException;
  19 import java.io.NotSerializableException;
  20 import java.io.ObjectInputStream;
  21 import java.io.ObjectOutputStream;
  22 import java.io.ObjectStreamException;
  23 import java.text.ParseException;
  24 import java.util.HexFormat;
  25 import java.util.List;
  26 import java.util.Objects;
  27 import org.eclipse.jdt.annotation.NonNullByDefault;
  28 import org.eclipse.jdt.annotation.Nullable;
  29 import org.opendaylight.yangtools.concepts.HierarchicalIdentifier;
  30 import org.opendaylight.yangtools.concepts.Immutable;
  31 import org.opendaylight.yangtools.yang.common.UnresolvedQName;
  32 import org.opendaylight.yangtools.yang.common.UnresolvedQName.Unqualified;
  33
  34 /**
  35  * Intermediate representation of a parsed {@code api-path} string as defined in
  36  * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-3.5.3.1">RFC section 3.5.3.1</a>. It models the path
  37  * as a series of {@link Step}s.
  38  */
  39 @NonNullByDefault
  40 public record ApiPath(ImmutableList<Step> steps) implements HierarchicalIdentifier<ApiPath> {
  41     @java.io.Serial
  42     private static final long serialVersionUID = 1L;
  43
  44     /**
  45      * A single step in an {@link ApiPath}.
  46      */
  47     public abstract static sealed class Step implements Immutable {
  48         private final @Nullable String module;
  49         private final Unqualified identifier;
  50
  51         Step(final @Nullable String module, final String identifier) {
  52             this.identifier = verifyNotNull(UnresolvedQName.tryLocalName(identifier),
  53                 "Unexpected invalid identifier %s", identifier);
  54             this.module = module;
  55         }
  56
  57         public Unqualified identifier() {
  58             return identifier;
  59         }
  60
  61         public @Nullable String module() {
  62             return module;
  63         }
  64
  65         @Override
  66         public abstract int hashCode();
  67
  68         @Override
  69         public abstract boolean equals(@Nullable Object obj);
  70
  71         final boolean equals(final Step other) {
  72             return Objects.equals(module, other.module) && identifier.equals(other.identifier);
  73         }
  74
  75         @Override
  76         public final String toString() {
  77             return addToStringAttributes(MoreObjects.toStringHelper(this).omitNullValues()).toString();
  78         }
  79
  80         ToStringHelper addToStringAttributes(final ToStringHelper helper) {
  81             return helper.add("module", module).add("identifier", identifier);
  82         }
  83
  84         void appendTo(final StringBuilder sb) {
  85             if (module != null) {
  86                 sb.append(module).append(':');
  87             }
  88             sb.append(identifier.getLocalName());
  89         }
  90     }
  91
  92     /**
  93      * An {@code api-identifier} step in a {@link ApiPath}.
  94      */
  95     public static final class ApiIdentifier extends Step {
  96         public ApiIdentifier(final @Nullable String module, final String identifier) {
  97             super(module, identifier);
  98         }
  99
 100         @Override
 101         public int hashCode() {
 102             return Objects.hash(module(), identifier());
 103         }
 104
 105         @Override
 106         public boolean equals(final @Nullable Object obj) {
 107             return this == obj || obj instanceof ApiIdentifier other && equals(other);
 108         }
 109     }
 110
 111     /**
 112      * A {@code list-instance} step in a {@link ApiPath}.
 113      */
 114     public static final class ListInstance extends Step {
 115         private final ImmutableList<String> keyValues;
 116
 117         public ListInstance(final @Nullable String module, final String identifier,
 118                 final ImmutableList<String> keyValues) {
 119             super(module, identifier);
 120             this.keyValues = requireNonNull(keyValues);
 121         }
 122
 123         public ImmutableList<String> keyValues() {
 124             return keyValues;
 125         }
 126
 127         @Override
 128         public int hashCode() {
 129             return Objects.hash(module(), identifier(), keyValues);
 130         }
 131
 132         @Override
 133         public boolean equals(final @Nullable Object obj) {
 134             return this == obj || obj instanceof ListInstance other && equals(other)
 135                 && keyValues.equals(other.keyValues);
 136         }
 137
 138         @Override
 139         ToStringHelper addToStringAttributes(final ToStringHelper helper) {
 140             return super.addToStringAttributes(helper).add("keyValues", keyValues);
 141         }
 142
 143         @Override
 144         void appendTo(final StringBuilder sb) {
 145             super.appendTo(sb);
 146             sb.append('=');
 147             final var it = keyValues.iterator();
 148             while (true) {
 149                 sb.append(PERCENT_ESCAPER.escape(it.next()));
 150                 if (it.hasNext()) {
 151                     sb.append(',');
 152                 } else {
 153                     break;
 154                 }
 155             }
 156         }
 157     }
 158
 159     // Escaper based on RFC8040-requirement to percent-encode reserved characters, as defined in
 160     // https://tools.ietf.org/html/rfc3986#section-2.2
 161     public static final Escaper PERCENT_ESCAPER;
 162
 163     static {
 164         final var hexFormat = HexFormat.of().withUpperCase();
 165         final var builder = Escapers.builder();
 166         for (char ch : new char[] {
 167             // Reserved characters as per https://tools.ietf.org/html/rfc3986#section-2.2
 168             ':', '/', '?', '#', '[', ']', '@',
 169             '!', '$', '&', '\'', '(', ')', '*', '+', ',', ';', '=',
 170         }) {
 171             builder.addEscape(ch, "%" + hexFormat.toHighHexDigit(ch) + hexFormat.toLowHexDigit(ch));
 172         }
 173         PERCENT_ESCAPER = builder.build();
 174     }
 175
 176     private static final ApiPath EMPTY = new ApiPath(ImmutableList.of());
 177
 178     public ApiPath {
 179         requireNonNull(steps);
 180     }
 181
 182     /**
 183      * Return an empty ApiPath.
 184      *
 185      * @return An empty ApiPath.
 186      */
 187     public static ApiPath empty() {
 188         return EMPTY;
 189     }
 190
 191     public static ApiPath of(final List<Step> steps) {
 192         return steps.isEmpty() ? EMPTY : new ApiPath(ImmutableList.copyOf(steps));
 193     }
 194
 195     /**
 196      * Parse an {@link ApiPath} from a raw Request URI fragment or another source. The string is expected to contain
 197      * percent-encoded bytes. Any sequence of such bytes is interpreted as a {@code UTF-8}-encoded string. Invalid
 198      * sequences are rejected.
 199      *
 200      * @param str Request URI part
 201      * @return An {@link ApiPath}
 202      * @throws NullPointerException if {@code str} is {@code null}
 203      * @throws ParseException if the string cannot be parsed
 204      */
 205     public static ApiPath parse(final String str) throws ParseException {
 206         return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newStrict(), str);
 207     }
 208
 209     /**
 210      * Parse an {@link ApiPath} from a raw Request URI fragment. The string is expected to contain percent-encoded
 211      * bytes. Any sequence of such bytes is interpreted as a {@code UTF-8}-encoded string. Invalid sequences are
 212      * rejected, but consecutive slashes may be tolerated, depending on runtime configuration.
 213      *
 214      * @param str Request URI part
 215      * @return An {@link ApiPath}
 216      * @throws NullPointerException if {@code str} is {@code null}
 217      * @throws ParseException if the string cannot be parsed
 218      */
 219     public static ApiPath parseUrl(final String str) throws ParseException {
 220         return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newUrl(), str);
 221     }
 222
 223     /**
 224      * Return the {@link Step}s of this path.
 225      *
 226      * @return Path steps
 227      */
 228     public ImmutableList<Step> steps() {
 229         return steps;
 230     }
 231
 232     @Override
 233     public boolean contains(final ApiPath other) {
 234         if (this == other) {
 235             return true;
 236         }
 237         final var oit = other.steps.iterator();
 238         for (var step : steps) {
 239             if (!oit.hasNext() || !step.equals(oit.next())) {
 240                 return false;
 241             }
 242         }
 243         return true;
 244     }
 245
 246     /**
 247      * Returns the index of a Step in this path matching specified module and identifier. This method is equivalent to
 248      * {@code indexOf(module, identifier, 0)}.
 249      *
 250      * @param module Requested {@link Step#module()}
 251      * @param identifier Requested {@link Step#identifier()}
 252      * @return Index of the step in {@link #steps}, or {@code -1} if a matching step is not found
 253      * @throws NullPointerException if {@code identifier} is {@code null}
 254      */
 255     public int indexOf(final String module, final String identifier) {
 256         return indexOf(module, identifier, 0);
 257     }
 258
 259     /**
 260      * Returns the index of a Step in this path matching specified module and identifier, starting search at specified
 261      * index.
 262      *
 263      * @param module Requested {@link Step#module()}
 264      * @param identifier Requested {@link Step#identifier()}
 265      * @param fromIndex index from which to search
 266      * @return Index of the step in {@link #steps}, or {@code -1} if a matching step is not found
 267      * @throws NullPointerException if {@code identifier} is {@code null}
 268      */
 269     public int indexOf(final String module, final String identifier, final int fromIndex) {
 270         final var id = requireNonNull(identifier);
 271         for (int i = fromIndex, size = steps.size(); i < size; ++i) {
 272             final var step = steps.get(i);
 273             if (id.equals(step.identifier.getLocalName()) && Objects.equals(module, step.module)) {
 274                 return i;
 275             }
 276         }
 277         return -1;
 278     }
 279
 280     public ApiPath subPath(final int fromIndex) {
 281         return subPath(fromIndex, steps.size());
 282     }
 283
 284     public ApiPath subPath(final int fromIndex, final int toIndex) {
 285         final var subList = steps.subList(fromIndex, toIndex);
 286         return subList == steps ? this : of(subList);
 287     }
 288
 289     @Override
 290     public int hashCode() {
 291         return steps.hashCode();
 292     }
 293
 294     @Override
 295     public boolean equals(final @Nullable Object obj) {
 296         return obj == this || obj instanceof ApiPath other && steps.equals(other.steps());
 297     }
 298
 299     @Override
 300     public String toString() {
 301         if (steps.isEmpty()) {
 302             return "";
 303         }
 304         final var sb = new StringBuilder();
 305         final var it = steps.iterator();
 306         while (true) {
 307             it.next().appendTo(sb);
 308             if (it.hasNext()) {
 309                 sb.append('/');
 310             } else {
 311                 break;
 312             }
 313         }
 314         return sb.toString();
 315     }
 316
 317     @java.io.Serial
 318     Object writeReplace() throws ObjectStreamException {
 319         return new APv1(toString());
 320     }
 321
 322     @java.io.Serial
 323     private void writeObject(final ObjectOutputStream stream) throws IOException {
 324         throw nse();
 325     }
 326
 327     @java.io.Serial
 328     private void readObject(final ObjectInputStream stream) throws IOException, ClassNotFoundException {
 329         throw nse();
 330     }
 331
 332     @java.io.Serial
 333     private void readObjectNoData() throws ObjectStreamException {
 334         throw nse();
 335     }
 336
 337     private NotSerializableException nse() {
 338         return new NotSerializableException(getClass().getName());
 339     }
 340
 341     private static ApiPath parseString(final ApiPathParser parser, final String str) throws ParseException {
 342         return of(parser.parseSteps(str));
 343     }
 344 }