Application Structure

Now that we have a high-level understanding of the relationship between the application's modules we can look inside at the application structure. To do this we will explore the source code so you should now take the time to unzip each of the forum-*.jar modules (found in the [install]/modules/ directory) to individual directories.

Web Interface

If you have spent time playing with the locally installed application (or used the public forum on 1060.org) you will know that the web-application consists of groups of one or more forums. Each forum contains topics and each topic contains entries.

One of the responsibilities of the forum-web module is to accept, interpret, and respond to requests for resources sent from a browser and expressed as REST-based URL paths. When a user enters a URL in a browser, such as http://.../forum/index/5/1, this is a request for specific information from the forum application. (In this example the request is for the list of all topics in forum five that fit on the first display page.)

The resource requests that the forum application can fulfill are expressed as URLs as shown in the tables below.

Path	Description
/forum/	The set of summary information about all forums. Displays a list of all forums arranged in groups.
/forum/index/[forum-id]	The set of information in the specified forum. Displays a listing of all topics in date order - newest first. Topics marked 'sticky' or 'announce' float to the top of the listing.
/forum/topic/[topic-id]	The set of all entries for the specified topic. Displays a date-ordered listing of entries, oldest first.
/forum/entry/[entry-id]	The text associated with the specified entry. This path can be thought of as a permalink to an entry.
/forum/search/[search-id]	The set of entries that match the previously stored search. Any given search is a view across the application data and can be permalinked.
/forum/index/[forum-id]/[page]	Paginated version of forum resource request.
/forum/topic/[topic-id]/[page]	Paginated version of the topic resource request.

In addition to the direct web-application a number of feed services are provided for indirect access via feed readers or feed aggregators...

Path	Description
/forum/rss/recent/	An RSS 2.0 feed providing the most recent entries across all forums.
/forum/rss/forum/[forum-id]	RSS 2.0 feeds of most recent topics in a forum.
/forum/rss/topic/[topic-id]	RSS 2.0 feeds of most recent entries in a given topic.
/forum/atom/recent/	An Atom 1.0 feed providing the most recent entries across all forums.
/forum/atom/forum/[forum-id]	Atom 1.0 feeds of most recent topics in a forum.
/forum/atom/topic/[topic-id]	Atom 1.0 feeds of most recent entries in a given topic.

Transport Mapping

All URL paths described above constitute the public interface of the forum application. We now examine how requests in the public URL space are mapped to the private URI address space of the forum-web module. To follow the discussion, examine the forum-web module definition [forum-web]/module.xml (where [forum-web] is the directory in which you unzipped the forum-web.jar).

In NetKernel, requests arrive from the outside and replies are returned on a transport. A module that manages a transport is called a fulcrum. For the forum application, the mapping of the public URL address space to the internal address space is handled by the HTTP transport managed by the front end fulcrum.

The front end fulcrum takes care of mapping external http://.../forum/ URI requests onto internal ffcpl:/forum/ address space. In addition to address mapping, it uses the httpBridge accessor to aggregate dispersed HTTP transport information such as POST data, GET query parameters, cookies, headers, etc, and presents these uniformly as active URI arguments in the ffcpl:/ address space. This bridge pattern effectively decouples NetKernel applications from the external transport mapping, rendering them easily adapted to other protocols and mappings.

To enable the front end fulcrum to map external requests, the forum-web module is imported into the fulcrum. When an imported module, such as the forum-web, has an entry in the export section it declares ownership of and responsibility for a particular address space. In this example, the forum-web module promises to fulfill all requests that match the ffcpl:/forum/ space. This relevant entry can be seen in first match of the following export section.

The net result is that all HTTP requests that enter NetKernel on the front end fulcrum's transport that match the /forum/ path are sucked into the forum-web module - its like a black-hole capturing all /forum/ URIs.

Once captured by the forum-web module, the requested URI is matched to finer granularity interfaces. You can see in the module definition that this is achieved by a set of rewrite rules which match a given URI interface path to an active URI service responsible for fulfilling the request. Unsurprisingly there is a corresponding service for each of the application regions we described above.

In general it is highly desirable to construct an application's public URL regions (spaces) as a set of linearly independent channels each of which maps to a service which fulfills requests that match the space. Collectively this can appear complex but taken individually each is just a simple independent REST service providing an application channel.