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.io.IOException;
19 import java.io.NotSerializableException;
20 import java.io.ObjectInputStream;
21 import java.io.ObjectOutputStream;
22 import java.io.ObjectStreamException;
23 import java.text.ParseException;
24 import java.util.HexFormat;
25 import java.util.Objects;
26 import org.eclipse.jdt.annotation.NonNullByDefault;
27 import org.eclipse.jdt.annotation.Nullable;
28 import org.opendaylight.yangtools.concepts.HierarchicalIdentifier;
29 import org.opendaylight.yangtools.concepts.Immutable;
30 import org.opendaylight.yangtools.yang.common.UnresolvedQName;
31 import org.opendaylight.yangtools.yang.common.UnresolvedQName.Unqualified;
34 * Intermediate representation of a parsed {@code api-path} string as defined in
35 * <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
36 * as a series of {@link Step}s.
39 public final class ApiPath implements HierarchicalIdentifier<ApiPath> {
41 private static final long serialVersionUID = 1L;
44 * A single step in an {@link ApiPath}.
46 public abstract static sealed class Step implements Immutable {
47 private final @Nullable String module;
48 private final Unqualified identifier;
50 Step(final @Nullable String module, final String identifier) {
51 this.identifier = verifyNotNull(UnresolvedQName.tryLocalName(identifier),
52 "Unexpected invalid identifier %s", identifier);
56 public Unqualified identifier() {
60 public @Nullable String module() {
65 public abstract int hashCode();
68 public abstract boolean equals(@Nullable Object obj);
70 final boolean equals(final Step other) {
71 return Objects.equals(module, other.module) && identifier.equals(other.identifier);
75 public final String toString() {
76 return addToStringAttributes(MoreObjects.toStringHelper(this).omitNullValues()).toString();
79 ToStringHelper addToStringAttributes(final ToStringHelper helper) {
80 return helper.add("module", module).add("identifier", identifier);
83 void appendTo(final StringBuilder sb) {
85 sb.append(module).append(':');
87 sb.append(identifier.getLocalName());
92 * An {@code api-identifier} step in a {@link ApiPath}.
94 public static final class ApiIdentifier extends Step {
95 public ApiIdentifier(final @Nullable String module, final String identifier) {
96 super(module, identifier);
100 public int hashCode() {
101 return Objects.hash(module(), identifier());
105 public boolean equals(final @Nullable Object obj) {
106 return this == obj || obj instanceof ApiIdentifier other && equals(other);
111 * A {@code list-instance} step in a {@link ApiPath}.
113 public static final class ListInstance extends Step {
114 private final ImmutableList<String> keyValues;
116 ListInstance(final @Nullable String module, final String identifier, final ImmutableList<String> keyValues) {
117 super(module, identifier);
118 this.keyValues = requireNonNull(keyValues);
121 public ImmutableList<String> keyValues() {
126 public int hashCode() {
127 return Objects.hash(module(), identifier(), keyValues);
131 public boolean equals(final @Nullable Object obj) {
132 return this == obj || obj instanceof ListInstance other && equals(other)
133 && keyValues.equals(other.keyValues);
137 ToStringHelper addToStringAttributes(final ToStringHelper helper) {
138 return super.addToStringAttributes(helper).add("keyValues", keyValues);
142 void appendTo(final StringBuilder sb) {
145 final var it = keyValues.iterator();
147 sb.append(PERCENT_ESCAPER.escape(it.next()));
157 // Escaper based on RFC8040-requirement to percent-encode reserved characters, as defined in
158 // https://tools.ietf.org/html/rfc3986#section-2.2
159 public static final Escaper PERCENT_ESCAPER;
162 final var hexFormat = HexFormat.of().withUpperCase();
163 final var builder = Escapers.builder();
164 for (char ch : new char[] {
165 // Reserved characters as per https://tools.ietf.org/html/rfc3986#section-2.2
166 ':', '/', '?', '#', '[', ']', '@',
167 '!', '$', '&', '\'', '(', ')', '*', '+', ',', ';', '=',
169 builder.addEscape(ch, "%" + hexFormat.toHighHexDigit(ch) + hexFormat.toLowHexDigit(ch));
171 PERCENT_ESCAPER = builder.build();
174 private static final ApiPath EMPTY = new ApiPath(ImmutableList.of());
176 private final ImmutableList<Step> steps;
178 private ApiPath(final ImmutableList<Step> steps) {
179 this.steps = requireNonNull(steps);
183 * Return an empty ApiPath.
185 * @return An empty ApiPath.
187 public static ApiPath empty() {
192 * Parse an {@link ApiPath} from a raw Request URI fragment or another source. The string is expected to contain
193 * percent-encoded bytes. Any sequence of such bytes is interpreted as a {@code UTF-8}-encoded string. Invalid
194 * sequences are rejected.
196 * @param str Request URI part
197 * @return An {@link ApiPath}
198 * @throws NullPointerException if {@code str} is {@code null}
199 * @throws ParseException if the string cannot be parsed
201 public static ApiPath parse(final String str) throws ParseException {
202 return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newStrict(), str);
206 * Parse an {@link ApiPath} from a raw Request URI fragment. The string is expected to contain percent-encoded
207 * bytes. Any sequence of such bytes is interpreted as a {@code UTF-8}-encoded string. Invalid sequences are
208 * rejected, but consecutive slashes may be tolerated, depending on runtime configuration.
210 * @param str Request URI part
211 * @return An {@link ApiPath}
212 * @throws NullPointerException if {@code str} is {@code null}
213 * @throws ParseException if the string cannot be parsed
215 public static ApiPath parseUrl(final String str) throws ParseException {
216 return str.isEmpty() ? EMPTY : parseString(ApiPathParser.newUrl(), str);
220 * Return the {@link Step}s of this path.
224 public ImmutableList<Step> steps() {
229 public boolean contains(final ApiPath other) {
233 final var oit = other.steps.iterator();
234 for (var step : steps) {
235 if (!oit.hasNext() || !step.equals(oit.next())) {
243 * Returns the index of a Step in this path matching specified module and identifier. This method is equivalent to
244 * {@code indexOf(module, identifier, 0)}.
246 * @param module Requested {@link Step#module()}
247 * @param identifier Requested {@link Step#identifier()}
248 * @return Index of the step in {@link #steps}, or {@code -1} if a matching step is not found
249 * @throws NullPointerException if {@code identifier} is {@code null}
251 public int indexOf(final String module, final String identifier) {
252 return indexOf(module, identifier, 0);
256 * Returns the index of a Step in this path matching specified module and identifier, starting search at specified
259 * @param module Requested {@link Step#module()}
260 * @param identifier Requested {@link Step#identifier()}
261 * @param fromIndex index from which to search
262 * @return Index of the step in {@link #steps}, or {@code -1} if a matching step is not found
263 * @throws NullPointerException if {@code identifier} is {@code null}
265 public int indexOf(final String module, final String identifier, final int fromIndex) {
266 final var id = requireNonNull(identifier);
267 for (int i = fromIndex, size = steps.size(); i < size; ++i) {
268 final var step = steps.get(i);
269 if (id.equals(step.identifier.getLocalName()) && Objects.equals(module, step.module)) {
276 public ApiPath subPath(final int fromIndex) {
277 return subPath(fromIndex, steps.size());
280 public ApiPath subPath(final int fromIndex, final int toIndex) {
281 final var subList = steps.subList(fromIndex, toIndex);
282 if (subList == steps) {
284 } else if (subList.isEmpty()) {
287 return new ApiPath(subList);
292 public int hashCode() {
293 return steps.hashCode();
297 public boolean equals(final @Nullable Object obj) {
298 return obj == this || obj instanceof ApiPath other && steps.equals(other.steps());
302 public String toString() {
303 if (steps.isEmpty()) {
306 final var sb = new StringBuilder();
307 final var it = steps.iterator();
309 it.next().appendTo(sb);
316 return sb.toString();
320 Object writeReplace() throws ObjectStreamException {
321 return new APv1(toString());
325 private void writeObject(final ObjectOutputStream stream) throws IOException {
330 private void readObject(final ObjectInputStream stream) throws IOException, ClassNotFoundException {
335 private void readObjectNoData() throws ObjectStreamException {
339 private NotSerializableException nse() {
340 return new NotSerializableException(getClass().getName());
343 private static ApiPath parseString(final ApiPathParser parser, final String str) throws ParseException {
344 final var steps = parser.parseSteps(str);
345 return steps.isEmpty() ? EMPTY : new ApiPath(steps);