restconf/restconf-nb/src/main/java/org/opendaylight/restconf/nb/rfc8040/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.nb.rfc8040;
   9
  10 import static com.google.common.base.Verify.verifyNotNull;
  11 import static java.util.Objects.requireNonNull;
  12
  13 import com.google.common.annotations.Beta;
  14 import com.google.common.base.MoreObjects;
  15 import com.google.common.base.MoreObjects.ToStringHelper;
  16 import com.google.common.collect.ImmutableList;
  17 import java.text.ParseException;
  18 import java.util.Objects;
  19 import javax.ws.rs.PathParam;
  20 import org.eclipse.jdt.annotation.NonNullByDefault;
  21 import org.eclipse.jdt.annotation.Nullable;
  22 import org.opendaylight.restconf.common.errors.RestconfDocumentedException;
  23 import org.opendaylight.yangtools.concepts.Immutable;
  24 import org.opendaylight.yangtools.yang.common.ErrorTag;
  25 import org.opendaylight.yangtools.yang.common.ErrorType;
  26 import org.opendaylight.yangtools.yang.common.UnresolvedQName;
  27 import org.opendaylight.yangtools.yang.common.UnresolvedQName.Unqualified;
  28
  29 /**
  30  * Intermediate representation of a parsed {@code api-path} string as defined in
  31  * <a href="https://datatracker.ietf.org/doc/html/rfc8040#section-3.5.3.1">RFC section 3.5.3.1</a>. It models the
  32  * path as a series of {@link Step}s.
  33  */
  34 @Beta
  35 @NonNullByDefault
  36 public final class ApiPath implements Immutable {
  37     /**
  38      * A single step in an {@link ApiPath}.
  39      */
  40     public abstract static class Step implements Immutable {
  41         private final @Nullable String module;
  42         private final Unqualified identifier;
  43
  44         Step(final @Nullable String module, final String identifier) {
  45             this.identifier = verifyNotNull(UnresolvedQName.tryLocalName(identifier),
  46                 "Unexpected invalid identifier %s", identifier);
  47             this.module = module;
  48         }
  49
  50         public Unqualified identifier() {
  51             return identifier;
  52         }
  53
  54         public @Nullable String module() {
  55             return module;
  56         }
  57
  58         @Override
  59         public abstract int hashCode();
  60
  61         @Override
  62         public abstract boolean equals(@Nullable Object obj);
  63
  64         final boolean equals(final Step other) {
  65             return Objects.equals(module, other.module) && identifier.equals(other.identifier);
  66         }
  67
  68         @Override
  69         public final String toString() {
  70             return addToStringAttributes(MoreObjects.toStringHelper(this).omitNullValues()).toString();
  71         }
  72
  73         ToStringHelper addToStringAttributes(final ToStringHelper helper) {
  74             return helper.add("module", module).add("identifier", identifier);
  75         }
  76     }
  77
  78     /**
  79      * An {@code api-identifier} step in a {@link ApiPath}.
  80      */
  81     public static final class ApiIdentifier extends Step {
  82         ApiIdentifier(final @Nullable String module, final String identifier) {
  83             super(module, identifier);
  84         }
  85
  86         @Override
  87         public int hashCode() {
  88             return Objects.hash(module(), identifier());
  89         }
  90
  91         @Override
  92         public boolean equals(final @Nullable Object obj) {
  93             return this == obj || obj instanceof ApiIdentifier && equals((ApiIdentifier) obj);
  94         }
  95     }
  96
  97     /**
  98      * A {@code list-instance} step in a {@link ApiPath}.
  99      */
 100     public static final class ListInstance extends Step {
 101         private final ImmutableList<String> keyValues;
 102
 103         ListInstance(final @Nullable String module, final String identifier, final ImmutableList<String> keyValues) {
 104             super(module, identifier);
 105             this.keyValues = requireNonNull(keyValues);
 106         }
 107
 108         public ImmutableList<String> keyValues() {
 109             return keyValues;
 110         }
 111
 112         @Override
 113         public int hashCode() {
 114             return Objects.hash(module(), identifier(), keyValues);
 115         }
 116
 117         @Override
 118         public boolean equals(final @Nullable Object obj) {
 119             if (this == obj) {
 120                 return true;
 121             }
 122             if (!(obj instanceof ListInstance)) {
 123                 return false;
 124             }
 125             final var other = (ListInstance) obj;
 126             return equals(other) && keyValues.equals(other.keyValues);
 127         }
 128
 129         @Override
 130         ToStringHelper addToStringAttributes(final ToStringHelper helper) {
 131             return super.addToStringAttributes(helper).add("keyValues", keyValues);
 132         }
 133     }
 134
 135     private static final ApiPath EMPTY = new ApiPath(ImmutableList.of());
 136
 137     private final ImmutableList<Step> steps;
 138
 139     private ApiPath(final ImmutableList<Step> steps) {
 140         this.steps = requireNonNull(steps);
 141     }
 142
 143     /**
 144      * Return an empty ApiPath.
 145      *
 146      * @return An empty ApiPath.
 147      */
 148     public static ApiPath empty() {
 149         return EMPTY;
 150     }
 151
 152     /**
 153      * Parse an {@link ApiPath} from a raw Request URI fragment or another source. The string is expected to contain
 154      * percent-encoded bytes. Any sequence of such bytes is interpreted as a {@code UTF-8}-encoded string. Invalid
 155      * sequences are rejected.
 156      *
 157      * @param str Request URI part
 158      * @return An {@link ApiPath}
 159      * @throws NullPointerException if {@code str} is {@code null}
 160      * @throws ParseException if the string cannot be parsed
 161      */
 162     public static ApiPath parse(final String str) throws ParseException {
 163         return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newStrict(), str);
 164     }
 165
 166     /**
 167      * Parse an {@link ApiPath} from a raw Request URI fragment. The string is expected to contain percent-encoded
 168      * bytes. Any sequence of such bytes is interpreted as a {@code UTF-8}-encoded string. Invalid sequences are
 169      * rejected, but consecutive slashes may be tolerated, depending on runtime configuration.
 170      *
 171      * @param str Request URI part
 172      * @return An {@link ApiPath}
 173      * @throws NullPointerException if {@code str} is {@code null}
 174      * @throws ParseException if the string cannot be parsed
 175      */
 176     public static ApiPath parseUrl(final String str) throws ParseException {
 177         return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newUrl(), str);
 178     }
 179
 180     /**
 181      * Parse an {@link ApiPath} from a raw Request URI. The string is expected to contain percent-encoded bytes. Any
 182      * sequence of such bytes is interpreted as a {@code UTF-8}-encoded string. Invalid sequences are rejected.
 183      *
 184      * @param str Request URI part
 185      * @return An {@link ApiPath}
 186      * @throws RestconfDocumentedException if the string cannot be parsed
 187      * @see PathParam
 188      */
 189     public static ApiPath valueOf(final @Nullable String str) {
 190         if (str == null) {
 191             return EMPTY;
 192         }
 193
 194         try {
 195             return parseUrl(str);
 196         } catch (ParseException e) {
 197             throw new RestconfDocumentedException("Invalid path '" + str + "'", ErrorType.APPLICATION,
 198                 ErrorTag.MALFORMED_MESSAGE, e);
 199         }
 200     }
 201
 202     public ImmutableList<Step> steps() {
 203         return steps;
 204     }
 205
 206     public int indexOf(final String module, final String identifier) {
 207         final var m = requireNonNull(module);
 208         final var id = requireNonNull(identifier);
 209         for (int i = 0, size = steps.size(); i < size; ++i) {
 210             final var step = steps.get(i);
 211             if (m.equals(step.module) && id.equals(step.identifier.getLocalName())) {
 212                 return i;
 213             }
 214         }
 215         return -1;
 216     }
 217
 218     public ApiPath subPath(final int fromIndex) {
 219         return subPath(fromIndex, steps.size());
 220     }
 221
 222     public ApiPath subPath(final int fromIndex, final int toIndex) {
 223         final var subList = steps.subList(fromIndex, toIndex);
 224         if (subList == steps) {
 225             return this;
 226         } else if (subList.isEmpty()) {
 227             return EMPTY;
 228         } else {
 229             return new ApiPath(subList);
 230         }
 231     }
 232
 233     @Override
 234     public int hashCode() {
 235         return steps.hashCode();
 236     }
 237
 238     @Override
 239     public boolean equals(final @Nullable Object obj) {
 240         return obj == this || obj instanceof ApiPath && steps.equals(((ApiPath) obj).steps());
 241     }
 242
 243     private static ApiPath parseString(final ApiPathParser parser, final String str) throws ParseException {
 244         final var steps = parser.parseSteps(str);
 245         return steps.isEmpty() ? EMPTY : new ApiPath(steps);
 246     }
 247 }