Package io.github.grumpystuff.grumpyrest

Record Class Route

java.lang.Object
java.lang.Record
io.github.grumpystuff.grumpyrest.Route
Record Components:
method - the HTTP method to match
path - the path pattern to match. May include path parameters.
handler - the handler to invoke for requests that match this route
public record Route(HttpMethod method, Path path, ComplexHandler handler) extends Record
A route is, conceptually, a set of criteria that determine whether the route matches a specific requests, as well as a handler that defines what to do for requests that match. The RestApi handles a request by picking the first route that matches, then handing the request to that route. Routes are the main mechanism to distinguish requests by HTTP method and path.

In a more practical sense,

  • routes always distinguish by HTTP method. That is, you cannot (currently) define a route that matches multiple or all HTTP methods. You'll have to add multiple routes for that.
  • each route uses a path (actually, a path pattern) and only handles requests that match this path. The path can contain literal path segments (strings that must match the request exactly) as well as path variables (a.k.a. path parameters) that will match any path segment from the request, and also capture the provided path segment for use in the handler. This is used mainly for paths that contain entity IDs.
  • the handler is simply a callback that gets called if the route matches. There are two possible interfaces to implement as a handler, SimpleHandler and ComplexHandler. You should implement SimpleHandler if possible, and ComplexHandler if necessary, because it reduces coupling and simplifies testing and mocking. Refer to these interfaces for details

The canonical constructor takes a ComplexHandler because this is the more general case.

  • Constructor Details

    • Route

      public Route(HttpMethod method, Path path, ComplexHandler handler)
      Standard constructor.
      Parameters:
      method - the HTTP method to match
      path - the path pattern to match. May include path parameters.
      handler - the handler to invoke for requests that match this route

    • Route

      public Route(HttpMethod method, String path, ComplexHandler handler)
      This constructor specifies the path pattern as a string instead of a Path object. Leading and trailing slashes are ignored. A path parameter is specified as a path segment that starts with a ':' character.
      Parameters:
      method - the HTTP method to match
      path - the path pattern to match. May include path parameters.
      handler - the handler to invoke for requests that match this route

    • Route

      public Route(HttpMethod method, Path path, SimpleHandler handler)
      Constructor for a SimpleHandler.
      Parameters:
      method - the HTTP method to match
      path - the path pattern to match. May include path parameters.
      handler - the handler to invoke for requests that match this route

    • Route

      public Route(HttpMethod method, String path, SimpleHandler handler)
      Constructor for a SimpleHandler which also specifies the path pattern as a string instead of a Path object. Leading and trailing slashes are ignored. A path parameter is specified as a path segment that starts with a ':' character.
      Parameters:
      method - the HTTP method to match
      path - the path pattern to match. May include path parameters.
      handler - the handler to invoke for requests that match this route

  • Method Details

    • match

      public RouteMatchResult match(RequestCycle requestCycle)
      Tries to match the specified request cycle against this route.
      Parameters:
      requestCycle - the request cycle that contains the request for matching
      Returns:
      if matched, a match result that contains this route. Otherwise null.

    • invokeHandler

      public Object invokeHandler(RequestCycle requestCycle) throws Exception
      Calls the handler for the specified request cycle. This should only be done if the request cycle has been successfully matched against this route and the match result has been applied to the request cycle -- otherwise, the request cycle will not contain path arguments which the handler will likely want to use.
      Parameters:
      requestCycle - the request cycle to pass to the handler
      Returns:
      the response value
      Throws:
      Exception - on errors -- will be treated like a response value.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • method

      public HttpMethod method()
      Returns the value of the method record component.
      Returns:
      the value of the method record component

    • path

      public Path path()
      Returns the value of the path record component.
      Returns:
      the value of the path record component

    • handler

      public ComplexHandler handler()
      Returns the value of the handler record component.
      Returns:
      the value of the handler record component