2 * Copyright (c) 2021 PANTHEON.tech, s.r.o. and others. All rights reserved.
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
8 package org.opendaylight.restconf.nb.rfc8040;
10 import static com.google.common.base.Verify.verifyNotNull;
11 import static java.util.Objects.requireNonNull;
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;
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.
36 public final class ApiPath implements Immutable {
38 * A single step in an {@link ApiPath}.
40 public abstract static class Step implements Immutable {
41 private final @Nullable String module;
42 private final Unqualified identifier;
44 Step(final @Nullable String module, final String identifier) {
45 this.identifier = verifyNotNull(UnresolvedQName.tryLocalName(identifier),
46 "Unexpected invalid identifier %s", identifier);
50 public Unqualified identifier() {
54 public @Nullable String module() {
59 public abstract int hashCode();
62 public abstract boolean equals(@Nullable Object obj);
64 final boolean equals(final Step other) {
65 return Objects.equals(module, other.module) && identifier.equals(other.identifier);
69 public final String toString() {
70 return addToStringAttributes(MoreObjects.toStringHelper(this).omitNullValues()).toString();
73 ToStringHelper addToStringAttributes(final ToStringHelper helper) {
74 return helper.add("module", module).add("identifier", identifier);
79 * An {@code api-identifier} step in a {@link ApiPath}.
81 public static final class ApiIdentifier extends Step {
82 ApiIdentifier(final @Nullable String module, final String identifier) {
83 super(module, identifier);
87 public int hashCode() {
88 return Objects.hash(module(), identifier());
92 public boolean equals(final @Nullable Object obj) {
93 return this == obj || obj instanceof ApiIdentifier && equals((ApiIdentifier) obj);
98 * A {@code list-instance} step in a {@link ApiPath}.
100 public static final class ListInstance extends Step {
101 private final ImmutableList<String> keyValues;
103 ListInstance(final @Nullable String module, final String identifier, final ImmutableList<String> keyValues) {
104 super(module, identifier);
105 this.keyValues = requireNonNull(keyValues);
108 public ImmutableList<String> keyValues() {
113 public int hashCode() {
114 return Objects.hash(module(), identifier(), keyValues);
118 public boolean equals(final @Nullable Object obj) {
122 if (!(obj instanceof ListInstance)) {
125 final var other = (ListInstance) obj;
126 return equals(other) && keyValues.equals(other.keyValues);
130 ToStringHelper addToStringAttributes(final ToStringHelper helper) {
131 return super.addToStringAttributes(helper).add("keyValues", keyValues);
135 private static final ApiPath EMPTY = new ApiPath(ImmutableList.of());
137 private final ImmutableList<Step> steps;
139 private ApiPath(final ImmutableList<Step> steps) {
140 this.steps = requireNonNull(steps);
144 * Return an empty ApiPath.
146 * @return An empty ApiPath.
148 public static ApiPath empty() {
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.
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
162 public static ApiPath parse(final String str) throws ParseException {
163 return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newStrict(), str);
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.
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
176 public static ApiPath parseUrl(final String str) throws ParseException {
177 return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newUrl(), str);
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.
184 * @param str Request URI part
185 * @return An {@link ApiPath}
186 * @throws RestconfDocumentedException if the string cannot be parsed
189 public static ApiPath valueOf(final @Nullable String str) {
195 return parseUrl(str);
196 } catch (ParseException e) {
197 throw new RestconfDocumentedException("Invalid path '" + str + "'", ErrorType.APPLICATION,
198 ErrorTag.MALFORMED_MESSAGE, e);
202 public ImmutableList<Step> steps() {
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())) {
218 public ApiPath subPath(final int fromIndex) {
219 return subPath(fromIndex, steps.size());
222 public ApiPath subPath(final int fromIndex, final int toIndex) {
223 final var subList = steps.subList(fromIndex, toIndex);
224 if (subList == steps) {
226 } else if (subList.isEmpty()) {
229 return new ApiPath(subList);
234 public int hashCode() {
235 return steps.hashCode();
239 public boolean equals(final @Nullable Object obj) {
240 return obj == this || obj instanceof ApiPath && steps.equals(((ApiPath) obj).steps());
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);