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.api;
10 import static com.google.common.base.Verify.verifyNotNull;
11 import static java.util.Objects.requireNonNull;
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.text.ParseException;
19 import java.util.HexFormat;
20 import java.util.Objects;
21 import org.eclipse.jdt.annotation.NonNullByDefault;
22 import org.eclipse.jdt.annotation.Nullable;
23 import org.opendaylight.yangtools.concepts.Immutable;
24 import org.opendaylight.yangtools.yang.common.UnresolvedQName;
25 import org.opendaylight.yangtools.yang.common.UnresolvedQName.Unqualified;
28 * Intermediate representation of a parsed {@code api-path} string as defined in
29 * <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
30 * as a series of {@link Step}s.
33 public final class ApiPath implements Immutable {
35 * A single step in an {@link ApiPath}.
37 public abstract static sealed class Step implements Immutable {
38 private final @Nullable String module;
39 private final Unqualified identifier;
41 Step(final @Nullable String module, final String identifier) {
42 this.identifier = verifyNotNull(UnresolvedQName.tryLocalName(identifier),
43 "Unexpected invalid identifier %s", identifier);
47 public Unqualified identifier() {
51 public @Nullable String module() {
56 public abstract int hashCode();
59 public abstract boolean equals(@Nullable Object obj);
61 final boolean equals(final Step other) {
62 return Objects.equals(module, other.module) && identifier.equals(other.identifier);
66 public final String toString() {
67 return addToStringAttributes(MoreObjects.toStringHelper(this).omitNullValues()).toString();
70 ToStringHelper addToStringAttributes(final ToStringHelper helper) {
71 return helper.add("module", module).add("identifier", identifier);
74 void appendTo(final StringBuilder sb) {
76 sb.append(module).append(':');
78 sb.append(identifier.getLocalName());
83 * An {@code api-identifier} step in a {@link ApiPath}.
85 public static final class ApiIdentifier extends Step {
86 public ApiIdentifier(final @Nullable String module, final String identifier) {
87 super(module, identifier);
91 public int hashCode() {
92 return Objects.hash(module(), identifier());
96 public boolean equals(final @Nullable Object obj) {
97 return this == obj || obj instanceof ApiIdentifier other && equals(other);
102 * A {@code list-instance} step in a {@link ApiPath}.
104 public static final class ListInstance extends Step {
105 private final ImmutableList<String> keyValues;
107 ListInstance(final @Nullable String module, final String identifier, final ImmutableList<String> keyValues) {
108 super(module, identifier);
109 this.keyValues = requireNonNull(keyValues);
112 public ImmutableList<String> keyValues() {
117 public int hashCode() {
118 return Objects.hash(module(), identifier(), keyValues);
122 public boolean equals(final @Nullable Object obj) {
123 return this == obj || obj instanceof ListInstance other && equals(other)
124 && keyValues.equals(other.keyValues);
128 ToStringHelper addToStringAttributes(final ToStringHelper helper) {
129 return super.addToStringAttributes(helper).add("keyValues", keyValues);
133 void appendTo(final StringBuilder sb) {
136 final var it = keyValues.iterator();
138 sb.append(PERCENT_ESCAPER.escape(it.next()));
148 // Escaper based on RFC8040-requirement to percent-encode reserved characters, as defined in
149 // https://tools.ietf.org/html/rfc3986#section-2.2
150 public static final Escaper PERCENT_ESCAPER;
153 final var hexFormat = HexFormat.of().withUpperCase();
154 final var builder = Escapers.builder();
155 for (char ch : new char[] {
156 // Reserved characters as per https://tools.ietf.org/html/rfc3986#section-2.2
157 ':', '/', '?', '#', '[', ']', '@',
158 '!', '$', '&', '\'', '(', ')', '*', '+', ',', ';', '=',
160 builder.addEscape(ch, "%" + hexFormat.toHighHexDigit(ch) + hexFormat.toLowHexDigit(ch));
162 PERCENT_ESCAPER = builder.build();
165 private static final ApiPath EMPTY = new ApiPath(ImmutableList.of());
167 private final ImmutableList<Step> steps;
169 private ApiPath(final ImmutableList<Step> steps) {
170 this.steps = requireNonNull(steps);
174 * Return an empty ApiPath.
176 * @return An empty ApiPath.
178 public static ApiPath empty() {
183 * Parse an {@link ApiPath} from a raw Request URI fragment or another source. The string is expected to contain
184 * percent-encoded bytes. Any sequence of such bytes is interpreted as a {@code UTF-8}-encoded string. Invalid
185 * sequences are rejected.
187 * @param str Request URI part
188 * @return An {@link ApiPath}
189 * @throws NullPointerException if {@code str} is {@code null}
190 * @throws ParseException if the string cannot be parsed
192 public static ApiPath parse(final String str) throws ParseException {
193 return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newStrict(), str);
197 * Parse an {@link ApiPath} from a raw Request URI fragment. The string is expected to contain percent-encoded
198 * bytes. Any sequence of such bytes is interpreted as a {@code UTF-8}-encoded string. Invalid sequences are
199 * rejected, but consecutive slashes may be tolerated, depending on runtime configuration.
201 * @param str Request URI part
202 * @return An {@link ApiPath}
203 * @throws NullPointerException if {@code str} is {@code null}
204 * @throws ParseException if the string cannot be parsed
206 public static ApiPath parseUrl(final String str) throws ParseException {
207 return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newUrl(), str);
210 public ImmutableList<Step> steps() {
214 public int indexOf(final String module, final String identifier) {
215 final var m = requireNonNull(module);
216 final var id = requireNonNull(identifier);
217 for (int i = 0, size = steps.size(); i < size; ++i) {
218 final var step = steps.get(i);
219 if (m.equals(step.module) && id.equals(step.identifier.getLocalName())) {
226 public ApiPath subPath(final int fromIndex) {
227 return subPath(fromIndex, steps.size());
230 public ApiPath subPath(final int fromIndex, final int toIndex) {
231 final var subList = steps.subList(fromIndex, toIndex);
232 if (subList == steps) {
234 } else if (subList.isEmpty()) {
237 return new ApiPath(subList);
242 public int hashCode() {
243 return steps.hashCode();
247 public boolean equals(final @Nullable Object obj) {
248 return obj == this || obj instanceof ApiPath other && steps.equals(other.steps());
252 public String toString() {
253 if (steps.isEmpty()) {
256 final var sb = new StringBuilder();
257 final var it = steps.iterator();
259 it.next().appendTo(sb);
266 return sb.toString();
269 private static ApiPath parseString(final ApiPathParser parser, final String str) throws ParseException {
270 final var steps = parser.parseSteps(str);
271 return steps.isEmpty() ? EMPTY : new ApiPath(steps);