How does JDisc work?
Describing the basic flow of incoming requests in the JDisc Container from the network and into application specific plug-ins requires explaining the JDisc usage of the general terms binding, server and so on. Let's start with an informal data flow diagram. Click on a component to jump to an explanation, or start reading from the top:
A server, or server provider, in JDisc Context is a server protocol implementation. A server will usually be bound to some network port, and has the responsibility of creating JDisc requests from the incoming data and also transmitting the JDisc response back to the client in a pertinent manner. A server does not fetch content, that is the responsibility of a processor or request handler.
A binding is a pattern, or rule, matching a URI which is used to route incoming requests to the correct filter chain or request handler, and route outgoing requests to the correct client. For instance, the binding http://*/* would match any HTTP request, while http://*/processing would only match that specific path. If several bindings match, the most specific one is chosen.
A server binding is a rule for matching incoming requests to the correct request handler, basically the JDisc building block for implementing RESTful APIs.
A client binding is a pattern which is used to match requests originating inside the container, e.g. when doing federation, to a client provider. That is, it is a rule which determines what code should handle a given outgoing request.
A filter is a lightweight request checker. It may set some specific request property, or it may do security checking and simply block requests missing some mandatory property or header.
Requests and responses
Requests are modelled as key-value stores, as in many other systems, while responses are meta information (like HTTP status) and a binary stream of content (the ContentChannel API).
The response handler is passed along with the request, it is the link back to the external client, as it contains the infrastructure for passing binary data back to the network.
A content channel is the basic I/O building block of JDisc. It is conceptually similar to a stream, but the basic unit is the ByteBuffer instead of the native byte. A content channel will take ownership of a ByteBuffer written to it.
A request handler accepts a request, and returns a response. All applications will use a request handler, either by implementing their own, or indirectly by using the processing framework, as the processing handler is a request handler as well. A client provider is-a request handler.
Processing is a light-weight, low latency request-response framework built on decomposition by chaining. It is a multi-threaded API, each processor must be written thread safe.
As a request handler, a processor accepts a response and returns a response. There are two central differences in the processor API from request handler API. First of all, a processor may invoke other processors directly, as processors are organized in chains, like filters. Second, processing responses are structured trees, as opposed to a binary stream. This makes processors suited to both request and response transformation, as working on both the request and response is possible.
As a processing response is a tree, there must be some way to transform that to a binary representation. To support multiple output formats, e.g. JSON and XML, the marshalling work is placed in the plug-in type Renderer.
A default renderer is always available, this renders a simple JSON format.
Clients, or client providers, are implementations of clients for different protocols, or special rules for given protocols. When a JDisc application acts as a client, e.g. fetches a web page from another host, it is a client provider that handles the transaction. Bindings are used, as with request handlers and filters, to choose the correct client, matching protocol, server, etc, and then hands off the request to the client provider. There is no problem in using arbitrary other types of clients for external services in processors and request handlers.