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