Package io.github.grumpystuff.grumpyrest

Interface SimpleHandler

public interface SimpleHandler
Interface for a handler in the most common, "simple", case. This handler takes a Request and returns a response value.

Implementing this handler interface should be preferred over ComplexHandler whenever it is sufficient. A simple handler will be passed only a Request, not the whole RequestCycle. This reduces coupling and makes it much easier to mock the argument in tests.

  • Method Summary

    Modifier and Type
    Method
    Description
    Object
    handle(Request request)
    Handles a request.

  • Method Details

    • handle

      Object handle(Request request) throws Exception
      Handles a request.

      The request is passed in its low-level form as a Request object. High-level properties of the request such as path parameters, querystring parameters and the request body (if any) can be obtained from this object by specifying the classes that represent the high-level structure.

      The handler returns a response value. This can be any value for which a ResponseFactory has been registered in the ResponseFactoryRegistry that turns the value into a Response. By default, this includes any JSON-compatible values (see JsonRegistries) as well as pre-built Response instances.

      A handler is expected to throw exceptions for invalid requests as well as internal errors. Thrown exceptions will be formally treated like returned exceptions, which in turn are treated like other returned values, but only few exception types have a corresponding ResponseFactory. Most exception types will instead not have an appropriate factory and will therefore result in an opaque 500 response. This is exactly what is expected for internal errors, to avoid leaking internal data to the client.

      There is one special case to the above rule: Handler code and the methods it calls can throw a FinishRequestException to stop the current request and send a response immediately. This is typically used for error handling, such as sending a 404 response somewhere in the method that could not find a record in a database. This exception can again contain any value for which a response factory has been registered, but simple error responses are likely to create a Response object directly. Formally, it is not FinishRequestException that gets special treatment but rather any exception or returned value that implements ResponseValueWrapper.

      Parameters:
      request - the request, in its low-level form as a Request object
      Returns:
      a response value, typically a JSON-compatible object or a Response
      Throws:
      Exception - any exception that indicates a faulty request, internal error or other problem. Will be converted to a response exactly as if the handler returns it.