HTTP Service Utilities

The class of primary relevance for specifying Arrowhead HTTP services is the HttpService class. After creating an instance of it, four details about the Arrowhead service it represents must be specified, which are
  1. its name,
  2. its base path,
  3. what encodings it supports, as well as
  4. what access policy it should use, unless the system that is to provide it is running in insecure mode.
After having provided these details, each created service must be given at at least one route, and may also be given additional filters and catchers. Routes, filters and catchers are collectively referred to as routables, and are what will receive and handle any incoming service requests.

Route Sequences

Routables are organized into route sequences, which can be visualized as follows:
     +------------+ 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 control are performed before any filters are called.

Routes, filters and catchers are given to a service via the #route(HttpRoute), #filter(HttpFilter) and #catcher(HttpCatcher) methods of the HttpService class, and the many helper methods that exist to make it more convenient to use those three methods.

Route Matching

When a HttpService receives 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 methods and patterns of its 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 here.