PathDirectives

Path Matchers

A path matcher is a description of a part of a path to match. The simplest path matcher is PathMatcher.segment which matches exactly one path segment against the supplied constant string.

Other path matchers defined in PathMatchers match the end of the path (PathMatchers.END), a single slash (PathMatchers.SLASH), or nothing at all (PathMatchers.NEUTRAL).

Many path matchers are hybrids that can both match (by using them with one of the PathDirectives) and extract values, Extracting a path matcher value (i.e. using it with handleWithX) is only allowed if it nested inside a path directive that uses that path matcher and so specifies at which position the value should be extracted from the path.

Predefined path matchers allow extraction of various types of values:

PathMatchers.segment(String)

Strings simply match themselves and extract no value. Note that strings are interpreted as the decoded representation of the path, so if they include a '/' character this character will match "%2F" in the encoded raw URI!

PathMatchers.regex

You can use a regular expression instance as a path matcher, which matches whatever the regex matches and extracts one String value. A PathMatcher created from a regular expression extracts either the complete match (if the regex doesn't contain a capture group) or the capture group (if the regex contains exactly one capture group). If the regex contains more than one capture group an IllegalArgumentException will be thrown.

PathMatchers.SLASH

Matches exactly one path-separating slash (/) character.

PathMatchers.END

Matches the very end of the path, similar to $ in regular expressions.

PathMatchers.Segment

Matches if the unmatched path starts with a path segment (i.e. not a slash). If so the path segment is extracted as a String instance.

PathMatchers.Remaining

Matches and extracts the complete remaining unmatched part of the request's URI path as an (encoded!) String. If you need access to the remaining decoded elements of the path use RemainingPath instead.

PathMatchers.intValue

Efficiently matches a number of decimal digits (unsigned) and extracts their (non-negative) Int value. The matcher will not match zero digits or a sequence of digits that would represent an Int value larger than Integer.MAX_VALUE.

PathMatchers.longValue

Efficiently matches a number of decimal digits (unsigned) and extracts their (non-negative) Long value. The matcher will not match zero digits or a sequence of digits that would represent an Long value larger than Long.MAX_VALUE.

PathMatchers.hexIntValue

Efficiently matches a number of hex digits and extracts their (non-negative) Int value. The matcher will not match zero digits or a sequence of digits that would represent an Int value larger than Integer.MAX_VALUE.

PathMatchers.hexLongValue

Efficiently matches a number of hex digits and extracts their (non-negative) Long value. The matcher will not match zero digits or a sequence of digits that would represent an Long value larger than Long.MAX_VALUE.

PathMatchers.uuid

Matches and extracts a java.util.UUID instance.

PathMatchers.NEUTRAL

A matcher that always matches, doesn't consume anything and extracts nothing. Serves mainly as a neutral element in PathMatcher composition.

PathMatchers.segments

Matches all remaining segments as a list of strings. Note that this can also be "no segments" resulting in the empty list. If the path has a trailing slash this slash will not be matched, i.e. remain unmatched and to be consumed by potentially nested directives.

Here's a collection of path matching examples:

// matches "/test"
path("test", () ->
  complete(StatusCodes.OK)
);

// matches "/test", as well
path(PathMatchers.segment("test"), () ->
  complete(StatusCodes.OK)
);

// matches "/admin/user"
path(PathMatchers.segment("admin")
  .slash("user"), () ->
  complete(StatusCodes.OK)
);

// matches "/admin/user", as well
pathPrefix("admin", () ->
  path("user", () ->
    complete(StatusCodes.OK)
  )
);

// matches "/admin/user/<user-id>"
path(PathMatchers.segment("admin")
  .slash("user")
  .slash(PathMatchers.integerSegment()), userId -> {
    return complete("Hello user " + userId);
  }
);

// matches "/admin/user/<user-id>", as well
pathPrefix("admin", () ->
  path("user", () ->
    path(PathMatchers.integerSegment(), userId ->
      complete("Hello user " + userId)
    )
  )
);

// never matches
path("admin", () -> // oops this only matches "/admin", and no sub-paths
  path("user", () ->
    complete(StatusCodes.OK)
  )
);

// matches "/user/" with the first subroute, "/user" (without a trailing slash)
// with the second subroute, and "/user/<user-id>" with the last one.
pathPrefix("user", () -> route(
  pathSingleSlash(() ->
    complete(StatusCodes.OK)
  ),
  pathEnd(() ->
    complete(StatusCodes.OK)
  ),
  path(PathMatchers.integerSegment(), userId ->
    complete("Hello user " + userId)
  )
));