Class ResourcePathDeclaration

java.lang.Object
com.soklet.ResourcePathDeclaration
@ThreadSafe public final class ResourcePathDeclaration extends Object
A compile-time HTTP URL path declaration associated with an annotated Resource Method, such as /users/{userId}.

You may obtain instances via the fromPath(String) factory method.

Note: this type is not normally used by Soklet applications unless they support Server-Sent Events or choose to implement a custom ResourceMethodResolver.

ResourcePathDeclaration instances must start with the / character and may contain placeholders denoted by single-mustache syntax. For example, the ResourcePathDeclaration /users/{userId} has a placeholder named userId.

A ResourcePathDeclaration is intended for compile-time Resource Method HTTP URL path declarations. The corresponding runtime type is ResourcePath and functionality is provided to check if the two "match" via matches(ResourcePath).

For example, a ResourcePathDeclaration /users/{userId} would match ResourcePath /users/123.

Please note the following restrictions on ResourcePathDeclaration structure:

1. It is not legal to use the same placeholder name more than once in a ResourcePathDeclaration.

For example:

  • /users/{userId} is valid resource path
  • /users/{userId}/roles/{roleId} is valid resource path
  • /users/{userId}/other/{userId} is an invalid resource path
2. Placeholders must span the entire /-delimited path component in which they reside.

For example:

  • /users/{userId} is a valid resource path
  • /users/{userId}/details is a valid resource path
  • /users/prefix{userId} is an invalid resource path

In addition to simple placeholders, this version supports a special "varargs" placeholder indicated by a trailing * in the placeholder name. For example, /static/{filePath*}. When present, the varargs placeholder must appear only once and as the last component in the path.

Author:
Mark Allen

  • Method Details

    • fromPath

      public static @NonNull ResourcePathDeclaration fromPath(@NonNull String path)
      Vends an instance that represents a compile-time path declaration, for example /users/{userId}.
      Parameters:
      path - a compile-time path declaration that may include placeholders

    • getVarargsComponent

      public @NonNull Optional<ResourcePathDeclaration.Component> getVarargsComponent()
      Gets the ResourcePathDeclaration.ComponentType.VARARGS component in this declaration, if any.
      Returns:
      the ResourcePathDeclaration.ComponentType.VARARGS component in this declaration, or Optional.empty() if none exists.

    • matches

      public @NonNull Boolean matches(@NonNull ResourcePath resourcePath)
      Does this resource path declaration match the given resource path (taking placeholders/varargs into account, if present)?

      For example, resource path declaration /users/{userId} would match /users/123.

      Parameters:
      resourcePath - the resource path against which to match
      Returns:
      true if the paths match, false otherwise

    • extractPlaceholders

      public @NonNull Map<@NonNull String, @NonNull String> extractPlaceholders(@NonNull ResourcePath resourcePath)
      What is the mapping between this resource path declaration's placeholder names to the given resource path's placeholder values?

      For example, placeholder extraction for resource path declaration /users/{userId} and resource path /users/123 would result in a value equivalent to Map.of("userId", "123").

      Resource path declaration placeholder values are automatically URL-decoded. For example, placeholder extraction for resource path declaration /users/{userId} and resource path /users/ab%20c would result in a value equivalent to Map.of("userId", "ab c").

      Varargs placeholders will combine all remaining path components (joined with @{code /}).

      Parameters:
      resourcePath - runtime version of this resource path declaration, used to provide placeholder values
      Returns:
      a mapping of placeholder names to values, or the empty map if there were no placeholders
      Throws:
      IllegalArgumentException - if the provided resource path does not match this resource path declaration, i.e. matches(ResourcePath) is false

    • getPath

      public @NonNull String getPath()
      What is the string representation of this resource path declaration?
      Returns:
      the string representation of this resource path declaration, which must start with /

    • getComponents

      public @NonNull List<@NonNull ResourcePathDeclaration.Component> getComponents()
      What are the /-delimited components of this resource path declaration?
      Returns:
      the components, or the empty list if this path is equal to /

    • isLiteral

      public @NonNull Boolean isLiteral()
      Is this resource path declaration comprised of all "literal" components (that is, no placeholders)?
      Returns:
      true if this resource path declaration is entirely literal, false otherwise

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(@Nullable Object object)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object