001/* 002 * Copyright 2022-2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.soklet; 018 019import org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021 022import javax.annotation.concurrent.Immutable; 023import javax.annotation.concurrent.ThreadSafe; 024import java.util.Collections; 025import java.util.LinkedHashMap; 026import java.util.LinkedHashSet; 027import java.util.List; 028import java.util.Map; 029import java.util.Objects; 030import java.util.Optional; 031import java.util.Set; 032import java.util.regex.Pattern; 033import java.util.stream.Collectors; 034 035import static com.soklet.Utilities.trimAggressively; 036import static java.lang.String.format; 037import static java.util.Arrays.asList; 038import static java.util.Collections.emptyList; 039import static java.util.Collections.unmodifiableList; 040import static java.util.Objects.requireNonNull; 041import static java.util.stream.Collectors.toList; 042 043/** 044 * A compile-time HTTP URL path declaration associated with an annotated <em>Resource Method</em>, such as {@code /users/{userId}}. 045 * <p> 046 * You may obtain instances via the {@link #fromPath(String)} factory method. 047 * <p> 048 * <strong>Note: this type is not normally used by Soklet applications unless they support <a href="https://www.soklet.com/docs/server-sent-events">Server-Sent Events</a> or choose to implement a custom {@link ResourceMethodResolver}.</strong> 049 * <p> 050 * {@link ResourcePathDeclaration} instances must start with the {@code /} character and may contain placeholders denoted by single-mustache syntax. 051 * For example, the {@link ResourcePathDeclaration} {@code /users/{userId}} has a placeholder named {@code userId}. 052 * <p> 053 * A {@link ResourcePathDeclaration} is intended for compile-time <em>Resource Method</em> HTTP URL path declarations. 054 * The corresponding runtime type is {@link ResourcePath} and functionality is provided to check if the two "match" via {@link #matches(ResourcePath)}. 055 * <p> 056 * For example, a {@link ResourcePathDeclaration} {@code /users/{userId}} would match {@link ResourcePath} {@code /users/123}. 057 * <p> 058 * <strong>Please note the following restrictions on {@link ResourcePathDeclaration} structure:</strong> 059 * <p> 060 * 1. It is not legal to use the same placeholder name more than once in a {@link ResourcePathDeclaration}. 061 * <p> 062 * For example: 063 * <ul> 064 * <li>{@code /users/{userId}} is valid resource path</li> 065 * <li>{@code /users/{userId}/roles/{roleId}} is valid resource path</li> 066 * <li>{@code /users/{userId}/other/{userId}} is an <em>invalid</em> resource path</li> 067 * </ul> 068 * 2. Placeholders must span the entire {@code /}-delimited path component in which they reside. 069 * <p> 070 * For example: 071 * <ul> 072 * <li>{@code /users/{userId}} is a valid resource path</li> 073 * <li>{@code /users/{userId}/details} is a valid resource path</li> 074 * <li>{@code /users/prefix{userId}} is an <em>invalid</em> resource path</li> 075 * </ul> 076 * <p> 077 * In addition to simple placeholders, this version supports a special "varargs" placeholder indicated by a trailing {@code *} 078 * in the placeholder name. For example, {@code /static/{filePath*}}. When present, the varargs placeholder must appear only once 079 * and as the last component in the path. 080 * 081 * @author <a href="https://www.revetkn.com">Mark Allen</a> 082 */ 083@ThreadSafe 084public final class ResourcePathDeclaration { 085 /** 086 * Pattern which matches a placeholder in a path component. 087 * <p> 088 * Placeholders are bracked-enclosed segments of text, for example {@code {languageId}} 089 * <p> 090 * A path component is either literal text or a placeholder. There is no concept of multiple placeholders in a 091 * component. 092 */ 093 @NonNull 094 private static final Pattern COMPONENT_PLACEHOLDER_PATTERN; 095 096 static { 097 COMPONENT_PLACEHOLDER_PATTERN = Pattern.compile("^\\{.+\\}$"); 098 } 099 100 @NonNull 101 private final String path; 102 @NonNull 103 private final List<@NonNull Component> components; 104 105 /** 106 * Vends an instance that represents a compile-time path declaration, for example {@code /users/{userId}}. 107 * 108 * @param path a compile-time path declaration that may include placeholders 109 */ 110 @NonNull 111public static ResourcePathDeclaration fromPath(@NonNull String path) { 112 requireNonNull(path); 113 return new ResourcePathDeclaration(path); 114 } 115 116 private ResourcePathDeclaration(@NonNull String path) { 117 requireNonNull(path); 118 this.path = normalizePath(path); 119 120 List<Component> components = extractComponents(this.path); 121 122 // Validate varargs: if any component is VARARGS then it must be the last one and only occur once. 123 int varargsCount = 0; 124 125 for (int i = 0; i < components.size(); i++) { 126 if (components.get(i).getType() == ComponentType.VARARGS) { 127 varargsCount++; 128 129 if (i != components.size() - 1) 130 throw new IllegalArgumentException(format("Varargs placeholder must be the last component in the path declaration: %s", path)); 131 } 132 } 133 134 Set<String> pathParameterNames = new LinkedHashSet<String>(); 135 136 for (var component : components) 137 if (component.getType() == ComponentType.PLACEHOLDER && !pathParameterNames.add(component.getValue())) 138 throw new IllegalArgumentException( 139 String.format("Duplicate placeholder name '%s' in resource path declaration: %s", component.getValue(), path)); 140 141 if (varargsCount > 1) 142 throw new IllegalArgumentException(format("Only one varargs placeholder is allowed in the path declaration: %s", path)); 143 144 this.components = unmodifiableList(components); 145 } 146 147 /** 148 * Gets the {@link ComponentType#VARARGS} component in this declaration, if any. 149 * 150 * @return the {@link ComponentType#VARARGS} component in this declaration, or {@link Optional#empty()} if none exists. 151 */ 152 @NonNull 153 public Optional<Component> getVarargsComponent() { 154 if (getComponents().size() == 0) 155 return Optional.empty(); 156 157 Component lastComponent = getComponents().get(getComponents().size() - 1); 158 159 if (lastComponent.getType() == ComponentType.VARARGS) 160 return Optional.of(lastComponent); 161 162 return Optional.empty(); 163 } 164 165 /** 166 * Does this resource path declaration match the given resource path (taking placeholders/varargs into account, if present)? 167 * <p> 168 * For example, resource path declaration {@code /users/{userId}} would match {@code /users/123}. 169 * 170 * @param resourcePath the resource path against which to match 171 * @return {@code true} if the paths match, {@code false} otherwise 172 */ 173 @NonNull 174 public Boolean matches(@NonNull ResourcePath resourcePath) { 175 requireNonNull(resourcePath); 176 177 if (resourcePath == ResourcePath.OPTIONS_SPLAT_RESOURCE_PATH) 178 return false; 179 180 List<Component> declarationComponents = getComponents(); 181 List<String> pathComponents = resourcePath.getComponents(); 182 183 // If the last declaration component is a varargs placeholder, allow extra path components. 184 if (!declarationComponents.isEmpty() && declarationComponents.get(declarationComponents.size() - 1).getType() == ComponentType.VARARGS) { 185 if (pathComponents.size() < declarationComponents.size() - 1) 186 return false; 187 188 // Check the prefix components 189 for (int i = 0; i < declarationComponents.size() - 1; i++) { 190 Component comp = declarationComponents.get(i); 191 String pathComp = pathComponents.get(i); 192 if (comp.getType() == ComponentType.LITERAL && !comp.getValue().equals(pathComp)) 193 return false; 194 } 195 196 return true; 197 } else { 198 if (pathComponents.size() != declarationComponents.size()) 199 return false; 200 201 for (int i = 0; i < declarationComponents.size(); i++) { 202 Component comp = declarationComponents.get(i); 203 String pathComp = pathComponents.get(i); 204 205 if (comp.getType() == ComponentType.LITERAL && !comp.getValue().equals(pathComp)) 206 return false; 207 } 208 209 return true; 210 } 211 } 212 213 /** 214 * What is the mapping between this resource path declaration's placeholder names to the given resource path's placeholder values? 215 * <p> 216 * For example, placeholder extraction for resource path declaration {@code /users/{userId}} and resource path {@code /users/123} 217 * would result in a value equivalent to {@code Map.of("userId", "123")}. 218 * <p> 219 * Resource path declaration placeholder values are automatically URL-decoded. For example, placeholder extraction for resource path declaration {@code /users/{userId}} 220 * and resource path {@code /users/ab%20c} would result in a value equivalent to {@code Map.of("userId", "ab c")}. 221 * <p> 222 * Varargs placeholders will combine all remaining path components (joined with @{code /}). 223 * 224 * @param resourcePath runtime version of this resource path declaration, used to provide placeholder values 225 * @return a mapping of placeholder names to values, or the empty map if there were no placeholders 226 * @throws IllegalArgumentException if the provided resource path does not match this resource path declaration, i.e. {@link #matches(ResourcePath)} is {@code false} 227 */ 228 @NonNull 229 public Map<@NonNull String, @NonNull String> extractPlaceholders(@NonNull ResourcePath resourcePath) { 230 requireNonNull(resourcePath); 231 232 if (!matches(resourcePath)) 233 throw new IllegalArgumentException(format("%s is not a match for %s so we cannot extract placeholders", this, resourcePath)); 234 235 Map<String, String> placeholders = new LinkedHashMap<>(); 236 List<Component> declarationComponents = getComponents(); 237 List<String> pathComponents = resourcePath.getComponents(); 238 239 // If varargs is present as the last component, process accordingly. 240 if (!declarationComponents.isEmpty() && declarationComponents.get(declarationComponents.size() - 1).getType() == ComponentType.VARARGS) { 241 // Process all but the last component normally. 242 for (int i = 0; i < declarationComponents.size() - 1; i++) { 243 Component comp = declarationComponents.get(i); 244 245 if (comp.getType() == ComponentType.PLACEHOLDER) 246 placeholders.put(comp.getValue(), pathComponents.get(i)); 247 } 248 249 // For varargs, join all remaining path components. 250 String varargsValue = pathComponents.subList(declarationComponents.size() - 1, pathComponents.size()) 251 .stream().collect(Collectors.joining("/")); 252 placeholders.put(declarationComponents.get(declarationComponents.size() - 1).getValue(), varargsValue); 253 } else { 254 // Normal processing: one-to-one mapping. 255 for (int i = 0; i < declarationComponents.size(); i++) { 256 Component comp = declarationComponents.get(i); 257 258 if (comp.getType() == ComponentType.PLACEHOLDER) 259 placeholders.put(comp.getValue(), pathComponents.get(i)); 260 } 261 } 262 263 return Collections.unmodifiableMap(placeholders); 264 } 265 266 /** 267 * What is the string representation of this resource path declaration? 268 * 269 * @return the string representation of this resource path declaration, which must start with {@code /} 270 */ 271 @NonNull 272 public String getPath() { 273 return this.path; 274 } 275 276 /** 277 * What are the {@code /}-delimited components of this resource path declaration? 278 * 279 * @return the components, or the empty list if this path is equal to {@code /} 280 */ 281 @NonNull 282 public List<@NonNull Component> getComponents() { 283 return this.components; 284 } 285 286 /** 287 * Is this resource path declaration comprised of all "literal" components (that is, no placeholders)? 288 * 289 * @return {@code true} if this resource path declaration is entirely literal, {@code false} otherwise 290 */ 291 @NonNull 292 public Boolean isLiteral() { 293 for (Component component : components) 294 if (component.getType() != ComponentType.LITERAL) 295 return false; 296 297 return true; 298 } 299 300 @NonNull 301 static String normalizePath(@NonNull String path) { 302 requireNonNull(path); 303 304 path = trimAggressively(path); 305 306 if (path.length() == 0) 307 return "/"; 308 309 // Remove any duplicate slashes, e.g. //test///something -> /test/something 310 path = path.replaceAll("(/)\\1+", "$1"); 311 312 if (!path.startsWith("/")) 313 path = format("/%s", path); 314 315 if ("/".equals(path)) 316 return path; 317 318 if (path.endsWith("/")) 319 path = path.substring(0, path.length() - 1); 320 321 return path; 322 } 323 324 /** 325 * Assumes {@code path} is already normalized via {@link #normalizePath(String)}. 326 * <p> 327 * If a component is a placeholder, determines whether it is a varargs placeholder (trailing {@code *}). 328 * 329 * @param path path from which components are extracted 330 * @return logical components of the supplied {@code path} 331 */ 332 @NonNull 333 protected List<@NonNull Component> extractComponents(@NonNull String path) { 334 requireNonNull(path); 335 336 if ("/".equals(path)) 337 return emptyList(); 338 339 // Strip off leading / 340 path = path.substring(1); 341 342 List<String> parts = asList(path.split("/")); 343 344 return parts.stream().map(part -> { 345 if (COMPONENT_PLACEHOLDER_PATTERN.matcher(part).matches()) { 346 // Remove the enclosing '{' and '}' 347 String inner = part.substring(1, part.length() - 1); 348 ComponentType type; 349 350 if (inner.endsWith("*")) { 351 type = ComponentType.VARARGS; 352 inner = inner.substring(0, inner.length() - 1); 353 } else { 354 type = ComponentType.PLACEHOLDER; 355 } 356 357 return Component.with(inner, type); 358 } else { 359 return Component.with(part, ComponentType.LITERAL); 360 } 361 }).collect(toList()); 362 } 363 364 @Override 365 public String toString() { 366 return format("%s{path=%s, components=%s}", getClass().getSimpleName(), getPath(), getComponents()); 367 } 368 369 @Override 370 public boolean equals(@Nullable Object object) { 371 if (this == object) 372 return true; 373 if (!(object instanceof ResourcePathDeclaration resourcePathDeclaration)) 374 return false; 375 return Objects.equals(getPath(), resourcePathDeclaration.getPath()) 376 && Objects.equals(getComponents(), resourcePathDeclaration.getComponents()); 377 } 378 379 @Override 380 public int hashCode() { 381 return Objects.hash(getPath(), getComponents()); 382 } 383 384 /** 385 * How to interpret a {@link Component} of a {@link ResourcePathDeclaration} - is it literal text or a placeholder? 386 * <p> 387 * For example, given the path declaration <code>/languages/{languageId}</code>: 388 * <ul> 389 * <li>{@code ComponentType} at index 0 would be {@code LITERAL} 390 * <li>{@code ComponentType} at index 1 would be {@code PLACEHOLDER} 391 * </ul> 392 * <p> 393 * <strong>Note: this type is not normally used by Soklet applications unless they choose to implement a custom {@link ResourceMethodResolver}.</strong> 394 * 395 * @author <a href="https://www.revetkn.com">Mark Allen</a> 396 * @see ResourcePathDeclaration 397 */ 398 public enum ComponentType { 399 /** 400 * A literal component of a resource path declaration. 401 * <p> 402 * For example, given resource path declaration {@code /users/{userId}}, the {@code users} component would be of type {@code LITERAL}. 403 */ 404 LITERAL, 405 /** 406 * A placeholder component (that is, one whose value is provided at runtime) of a resource path declaration. 407 * <p> 408 * For example, given resource path declaration {@code /users/{userId}}, the {@code userId} component would be of type {@code PLACEHOLDER}. 409 */ 410 PLACEHOLDER, 411 /** 412 * A "varargs" placeholder component that may match multiple path segments. 413 * <p> 414 * For example, given resource path declaration {@code /static/{filepath*}}, the {@code filepath*} component would be of type {@code VARARGS}. 415 */ 416 VARARGS 417 } 418 419 /** 420 * Represents a {@code /}-delimited part of a {@link ResourcePathDeclaration}. 421 * <p> 422 * For example, given the path declaration <code>/languages/{languageId}</code>: 423 * <ul> 424 * <li>{@code Component} 0 would have type {@code LITERAL} and value {@code languages} 425 * <li>{@code Component} 1 would have type {@code PLACEHOLDER} and value {@code languageId} 426 * </ul> 427 * <p> 428 * You may obtain instances via the {@link #with(String, ComponentType)} factory method. 429 * <p> 430 * <strong>Note: this type is not normally used by Soklet applications unless they choose to implement a custom {@link ResourceMethodResolver}.</strong> 431 * 432 * @author <a href="https://www.revetkn.com">Mark Allen</a> 433 * @see ResourcePathDeclaration 434 */ 435 @Immutable 436 public static final class Component { 437 @NonNull 438 private final String value; 439 @NonNull 440 private final ComponentType type; 441 442 /** 443 * Acquires a {@link Component} instance given a {@code value} and {@code type}. 444 * 445 * @param value the value of this component 446 * @param type the type of this component (literal or placeholder) 447 * @return a {@link Component} instance 448 */ 449 @NonNull 450 public static Component with(@NonNull String value, 451 @NonNull ComponentType type) { 452 requireNonNull(value); 453 requireNonNull(type); 454 455 return new Component(value, type); 456 } 457 458 private Component(@NonNull String value, 459 @NonNull ComponentType type) { 460 requireNonNull(value); 461 requireNonNull(type); 462 463 this.value = value; 464 this.type = type; 465 } 466 467 @Override 468 public String toString() { 469 return format("%s{value=%s, type=%s}", getClass().getSimpleName(), getValue(), getType()); 470 } 471 472 @Override 473 public boolean equals(@Nullable Object object) { 474 if (this == object) 475 return true; 476 477 if (!(object instanceof Component component)) 478 return false; 479 480 return Objects.equals(getValue(), component.getValue()) 481 && Objects.equals(getType(), component.getType()); 482 } 483 484 @Override 485 public int hashCode() { 486 return Objects.hash(getValue(), getType()); 487 } 488 489 /** 490 * What is the value of this resource path declaration component? 491 * <p> 492 * Note that the value of a {@link ComponentType#PLACEHOLDER} component does not include enclosing braces. 493 * For example, given the path declaration <code>/languages/{languageId}</code>, 494 * the component at index 1 would have value {@code languageId}, not {@code {languageId}}. 495 * 496 * @return the value of this component 497 */ 498 @NonNull 499 public String getValue() { 500 return value; 501 } 502 503 /** 504 * What type of resource path declaration component is this? 505 * 506 * @return the type of component, e.g. {@link ComponentType#LITERAL} or {@link ComponentType#PLACEHOLDER} 507 */ 508 @NonNull 509 public ComponentType getType() { 510 return type; 511 } 512 } 513}