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