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