Package com.codingchili.core.protocol

Class Protocol<RequestType>

java.lang.Object
com.codingchili.core.protocol.Protocol<RequestType>
public class Protocol<RequestType> extends Object
Maps packet data to authorizer and manages authentication status for authorizer.

Route documentation and listing may be retrieved using #getSchema() or by calling the protocol with the #CoreStrings.PROTOCOL_DOCUMENTATION route. The documentation route is enabled whenever a handler class or route is documented using either #document(String), #setDescription(String) or by adding the #Description annotation to the class or handler method.

Aug, 2020 - removed use of reflectasm as method reflection in J11 is 10% faster. If setAccessible(true) is called then J11 reflection is 50% faster.

  • Constructor Details

    • Protocol

      public Protocol()

    • Protocol

      public Protocol​(Receiver<RequestType> handler)
      Creates a protocol by mapping annotated methods.
      Parameters:
      handler - contains methods to be mapped.

  • Method Details

    • annotated

      public Protocol<RequestType> annotated​(Receiver<RequestType> handler)
      Processes annotations on the given handler.
      Parameters:
      handler - the handler that is annotated
      Returns:
      fluent

    • endpoint

      public Protocol<RequestType> endpoint​(String endpoint)
      Parameters:
      endpoint - sets the endpoint of the api, this is only used for documentation purposes.
      Returns:
      fluent

    • setAuthorizationHandler

      public Protocol<RequestType> setAuthorizationHandler​(AuthorizationHandler<RequestType> authorizer)
      Replaces the authorization handler used to map roles to routes.
      Parameters:
      authorizer - the new authorizer to use
      Returns:
      fluent

    • setDataModel

      public Protocol<RequestType> setDataModel​(Class<?> model)
      Sets the data model used for requests for documentation purposes. Set automatically when using #annotated(Receiver)
      Parameters:
      model - the data transfer object.
      Returns:
      fluent

    • setRole

      public Protocol<RequestType> setRole​(RoleType... role)
      Sets the default role of routes added _after_ this call.

      Annotated alternative #Roles on handler class

      Parameters:
      role - the role to set for requests added after calling this method.
      Returns:
      fluent

    • throwAny

      public static RuntimeException throwAny​(Throwable throwable)

    • throwAsUnchecked

      public static <T extends Exception> void throwAsUnchecked​(Throwable throwable) throws T
      Throws:
      T extends Exception

    • use

      public Protocol<RequestType> use​(String route, RequestHandler<RequestType> handler)
      Registers a handler for the given route.

      Annotated alternative #Api

      Parameters:
      route - the route to register a handler for.
      handler - the handler to be registered for the given route.
      Returns:
      the updated protocol specification for fluent use.

    • use

      public Protocol<RequestType> use​(String route, RequestHandler<RequestType> handler, RoleType... role)
      Registers a handler for the given route with an access level.

      Annotated alternative #Api

      Parameters:
      route - the route to register a handler for.
      handler - the handler to be registered for the given route with the access level.
      role - specifies the authorization level required to access the route.
      Returns:
      the updated protocol specification for fluent use.

    • get

      public RequestHandler<RequestType> get​(String route) throws AuthorizationRequiredException, HandlerMissingException
      Returns the route handler for the given target route and its access level.
      Parameters:
      route - the handler route to find.
      Returns:
      the handler that is mapped to the route.
      Throws:
      AuthorizationRequiredException - when authorization level is not fulfilled for the given route.
      HandlerMissingException - when the requested route handler is not registered.

    • get

      public RequestHandler<RequestType> get​(String route, RoleType role) throws AuthorizationRequiredException, HandlerMissingException
      Returns the route handler for the given target route and its access level.
      Parameters:
      route - the handler route to find
      role - list of roles that are allowed to map to a route
      Returns:
      the handler that is mapped to the route and access level.
      Throws:
      AuthorizationRequiredException - when authorization level is not fulfilled for given route.
      HandlerMissingException - when the requested route handler is not registered.

    • process

      public void process​(Request request)
      Processes a request with some additional error handling. The authenticator authenticator(Function) is invoked with a future to support asynchronous cryptography operations, the request size is checked against the configured maximum value. The route to invoke may be configured by specifying a custom routeMapper(Function). Any exceptions thrown by the invoked route, or if the route is missing or authorization insufficient, an error will be written as a response to the request.
      Parameters:
      request - the request to be processed.

    • routeMapper

      public Protocol<RequestType> routeMapper​(Function<Request,​String> mapper)
      Set the route mapper used to process requests. A route mapper determines which protocol route that is to be invoked for the given request. The default mapper invokes Request.route().
      Parameters:
      mapper - the mapper to use for this protocol instance.
      Returns:
      fluent.

    • authenticator

      public Protocol<RequestType> authenticator​(Function<Request,​io.vertx.core.Future<RoleType>> authenticator)
      Set the authenticator used to process(Request) requests. The authenticator consumes a Request and produces an optionally asynchronous result that indicates which role is valid for the current request. The default authenticator responds with Role.PUBLIC.
      Parameters:
      authenticator - the authenticator to use for this protocol instance.
      Returns:
      fluent.

    • document

      public Protocol<RequestType> document​(String routeDescription)
      Adds a documentation string to the last added route.

      Annotated alternative #Description on requesthandler class

      Parameters:
      routeDescription - route protocol description text
      Returns:
      fluent

    • model

      public Protocol<RequestType> model​(Class<?> model)
      Sets the model of the last added route.
      Parameters:
      model - the model to set for the route.
      Returns:
      fluent

    • getSchema

      public ProtocolDescription<RequestType> getSchema()
      Returns:
      returns a list of all registered routes on the protoocol.

    • setDescription

      public Protocol<RequestType> setDescription​(String description)
      Sets the documentation string for this protocol suite.

      Annotated alternative #Description on Handler class

      Parameters:
      description - description text.
      Returns:
      fluent

    • available

      public Set<String> available()
      Returns:
      a list of all registered routes in the protocol.