Getting Started: Learn
Understanding the Message Flow
This section describes the following topics:
When the Akula Server receives an HTTP(s) request from the client, the dispatcher extracts all the information from the request and constructs a request object from it. The request is attached to the exchange so that it can be accessed from any part of the app scope. The Akula Server then determines which route to send the request to, based on the structure of the request.
Each route defines one or more modules that process the request or the output of other modules in the route. Typically a message is processed by a module such as the HTTP or SQL module. These modules send the request to a back end server. Other modules in the route might then transform the data, by sorting, filtering, joining, or converting its contents. As each module completes its processing, it creates a new message and attaches it to the exchange so that the next module in the route can access it.
After all modules in the route have processed the message, the dispatcher constructs an HTTP response from the last module's output and returns an HTTP response to the client.
The following image illustrates this flow:
The Akula Server processes HTTP requests and returns results as HTTP responses. While a request is being processed in the Akula Server, it is a message managed by the exchange.
The following example illustrates the parts of an HTTP request as the dispatcher views it:
The following table describes the parts of the URL as seen by the Akula Server:
|HTTP server||The location of the server running the Akula Server. For a simple installation, this is the root URL that you use to access your Java app server.|
|Akula Server||The name of the Akula Server. This value is the same as the name of the Akula WAR file you deployed when installing Akula.|
|Akula project||The name of your Akula project (also known as the "app scope"). This value matches the name of your deployed AKZ file.|
The service to use when accessing the endpoint. Akula supports
You can only create endpoints for the data service (that matches
|Endpoint||The URL that you defined in your endpoint configuration file. The Akula Server matches the endpoint to a route for the request to be processed by.|
|Path parameters||Optional values in the path that are separated by slashes.|
|Query string parameters||Optional parameters on the query string that occur after the question mark (?) in the URL. These are name/value pairs separated by ampersands (&).|
In this example:
- The Java app server server receives a request for the server's URL.
- The Java app server recognizes the "akula" portion of the URL and forwards the request to the Akula Server.
- The dispatcher examines the next portion of the URL,
/RequestObjectTest, and the service,
/data, and determines that the RequestObjectTest app scope should find an endpoint that matches the next portion of the URL (
- The dispatcher matches the endpoint from the URL with the request method (in this case, GET) to determine which route to execute.
- The first module in the chosen route constructs a new message object and populates the values of the request's path parameters and query string parameters with the values in the URL. The message's body is also populated with the contents of HTTP request, if the request is anything other than GET and DELETE.
- Finally, the Akula Server calls the first module in the route.
The Akula Server API contains a number of classes that manage the request/response flow through the Akula Server. These classes include:
- AKMessage – The input and output of modules in the route. Each modules accesses the previous module's output as its input, and creates a new message as its own output.
- AKExchange – The backbone of the routing mechanism. The AKExchange manages all the messages that each module creates. The exchange is also responsible for caching messages, if necessary, so that all modules in the route can share data.
- AKRequest – The original HTTP request from the client. This object is created by the Akula Server when the original HTTP request comes in from the client. A reference to this object is available from within any module in the route.
When you issue an HTTP request from the client to the Akula Server, the following order of events takes place:
- The dispatcher receives the request from the app server and examines the URL and method that was used to execute the HTTP request.
- Based on the URL and method, the dispatcher determines which route to send the HTTP request to.
- The dispatcher then sends the request to the first module in the selected route.
- The first module in the route constructs an AKRequest object from the properties of the HTTP request. These include the body of the original request as an InputStream, query string parameters, HTTP headers, and other aspects of the HTTP request. After constructing the AKRequest, the module attaches the AKRequest object to the AKExchange object. The first module also creates a new AKMessage object that contains the same data as the HTTP request.
- The first module then attaches the new AKMessage object to the exchange. The next module in the route can access this message as its input.
- The second and subsequent modules accept the AKMessage object as their input and process it. Each module creates a new output AKMessage, and the module populates this object with its results. At any point in the route, any module can access the methods and properties of the original AKRequest object. This object does not change while the route is being executed.
- When the last module in a route is called, the last AKMessage is returned to the dispatcher.
- The dispatcher then converts the output message of the last module into an HTTP response and returns the response to the client.
The following image illustrates this flow:
Supported content types
HTTP requests to the Akula Server can be of any content type, including plain text, form, multi-part form, binary (such as PDFs, audio files, and video files), and strings, including formatted strings such as XML and JSON. Responses can also be of any type. Requests with no
Content-Type header specified in the header are also supported.
On the server side, the module or modules that accept input data must be written to handle the content type that they process. For example, a module that accepts image data as input should open an input stream to handle it. Similarly, on the client side, client apps that accept binary data from the server (such as image downloads) must be written in such a way as to accept and process data in that format.
For these reasons, you should specify the content type of your requests or responses, even though this is not required. This helps your application determine how to handle the data.
About the dispatcher
When a client sends a request to an endpoint defined by the Akula Server, the dispatcher is invoked. The dispatcher is responsible for receiving HTTP requests from the client and converting them to a message. It then sends the message to the appropriate route.
On each client request, the dispatcher:
- Receives the HTTP request from the client.
- Creates a new AKRequest object.
- Sets the body of the AKRequest object to the contents of HTTP request body. For GET and DELETE requests, the body is null.
- Sets the AKRequest object's
Content-Typeheader to the value of the HTTP
Content-Typeheader. For GET and DELETE requests, the content type is null.
- Copies other HTTP request attributes (method, query parameters, form parameters, attachments, and other headers) to the new AKRequest object, as appropriate.
When the route is complete, the dispatcher is again invoked to perform operations on the output of the route, before returning the response to the client.
When each route is complete, the dispatcher:
- Sets the HTTP response's content body to the content of the final module's output message body.
- Sets the HTTP response
Content-Typeheader to the value of the final output message's
- Copies other headers from the final output message to the HTTP response as appropriate.
- Sets the HTTP response status to the value of the final output message's status.
- Sends the completed HTTP response back to client.