HTTP Service UtilitiesThe class of primary relevance for specifying Arrowhead HTTP
HttpServiceclass. After creating an instance of it, four details about the Arrowhead service it represents must be specified, which are
encodingsit supports, as well as
access policyit should use, unless the
systemthat is to
provide itis running in
route, and may also be given additional
catchers. Routes, filters and catchers are collectively referred to as
routables, and are what will receive and handle any incoming
Route SequencesRoutables are organized into route sequences, which can be visualized as follows:
REQUEST RECEIVED | V +------------+ responds | Filter 1 |---------------------------------+ | Filter 2 | | | Filter 3 | +-------------+ | | Filter ... | throws | Catcher 1 | | | Filter N |------->| Catcher 2 | | +-----+------+ | Catcher 3 | responds | | delegates | Catcher ... |----------+ | | Catcher M | | | +-------------+ | | A | V throws | | +------------+ | responds V | Route |---------------+---------> RESPONSE SENT +------------+When an incoming request is received, a route sequence with a matching route is identified. If the sequence contains any filters, those are executed in order from most to least specialized (i.e. filters with more requirements for being matched are always executed first). If any filter decides to respond to the request, the response is returned immediately to the sender and the route never receives the request. If a filter or the route throws an exception, the catcher sequence is executed in order, from the most to the least specialized. If no catcher is available, no catcher decided to respond to the request, or a catcher threw an exception and no other catcher caught it, any exceptions are logged and the request is replied to with a 500 INTERNAL SERVER ERROR message. Note that certificate validation and
access controlare performed before any filters are called.
Routes, filters and catchers are given to a service via the
#catcher(HttpCatcher) methods of the
HttpService class, and the many
helper methods that exist to make it more convenient to use those three
Route MatchingWhen a
HttpServicereceives a request, it must be able to tell what route sequence, as described above, to provide the request to. This is done by matching the request against the
routes. While matching methods is rather straightforward, either it matches or it doesn't, matching the path of a request against a path pattern is more involved. How path pattern matching is performed is explained in detail
Interface Summary Interface Description HttpCatcherHandler<T extends java.lang.Throwable>A handler meant to process exceptions occurring while handling incoming
HTTP requests, or while responding to them.
HttpFilterHandlerA route filter, meant to validate or handle incoming HTTP requests matching some
set of preconditions.
HttpRoutable HttpRouteHandlerA route handler, meant to process incoming HTTP requests matching some
set of preconditions.
HttpConnectionWithArSystemestablished to allow a remote system consume a service provided by a local one.
HttpServiceRequestThe head and body of an incoming HTTP request. HttpServiceResponseAn outgoing HTTP response, to be sent by an
Class Summary Class Description HttpCatcher<T extends java.lang.Throwable>A
HttpServiceexception catcher, useful for handling errors occurring while receiving or responding to HTTP requests.
HttpFilter HttpPatternA pattern that matches a well-defined set of paths. HttpRouteDescribes the conditions for and where to route matching incoming
HttpRouteTaskKeeps track of state related to an incoming HTTP request. HttpRouteTask.BuilderBuilder useful for creating
HttpServiceA concrete Arrowhead service, exposing its functions as HTTP endpoints.
Exception Summary Exception Description HttpServiceRequestExceptionSignifies that some HTTP request received by a
HttpServicecontains an error and, therefore, will not be processed.