Deconstructing the Topic Server

Let's continue our journey by examining the details of the service that supports the topic channel. The topic server is implemented in the Bean Shell script, topic-viewer.bsh.

We'll start by looking at the main() method - with beanshell scripts on NetKernel this method is called for each invocation of the script. We will discuss the import code, which is outside the scope of the main method, in a moment.

The first task of the script is to parse the REST interface (/forum/topic/[topic-id]/[page]) to obtain the [topic-id] and [page] values. You can see below that the active URI argument named 'uri' is obtained as a string from the request which began the execution of the script engine. This is done through the context object which is available within all of NetKernel's scripting languages and is the point of entry to the NetKernel Foundation API (NKF) - an in depth guide to NKF, including links to the javadoc, is provided here.

//Retrieve path-based URI from REST interface request
//this has the structure: ffcpl:/forum/topic/[topic]/[page]
uri=context.getThisRequest().getArgument("uri");

StringAspect nvp=parseURL(uri);

                    

The parseURL() method is provided by the url-parser.bsh library - we will discuss how this script library is imported into the execution context in a moment. The parseURL() method parses the URI and obtains the topic and page and forms these into an XML fragment which is wrapped in a StringAspect and which is assigned to the variable 'nvp' (short for name-value-pairs). The nvp resource is used in calls to other services and has the form...

Take a look at url-parser.bsh. It contains a simple function which slices and dices the URI of our REST interface. The scripted library is imported into the main script with the following code...

//Import URL Parser Library Script
parserLibrary = "url-parser.bsh";
interpreter=new bsh.Interpreter();
interpreter.setNameSpace(this.namespace);
interpreter.eval( context.sourceAspect( parserLibrary, IAspectString.class ).getString() );

                    

To use a scripted library in beanshell, it has to be parsed and associated with the execution context of the current script. This is done by instantiating a new beanshell interpreter. The interpreter is supplied with the current script's namespace (ie the execution context containing global variables, methods etc of the importing script). Finally a source request is issued through the context object for the source-code of the imported script in the form of a StringAspect. The string containing the script is then evaluated in the interpreter - this binds the library into the current scripts execution context.

Each script language on NetKernel has its own specific, and more-or-less elegant, way of importing a scripted library into the script's execution context. The script reference guide provides links to the language specific details.

So returning to the main topic script. We have parsed the URI and have a resource containing the information that was extracted. The next stage is to decide if we should record the hit on this page. The global variable 'page' is set by the parseURL() script and contains the value of [page] path in the URI.

When page is not 'last' then the application registers a page hit. First a sub-request is constructed to the ffcpl:/forum-main-logHit service - this service is presented on the public interface of the data services module and unsurprisingly logs-hits! It is not important that we receive a response for this request and so there is no need for us to waste time waiting around whilst it is performed, therefore the request is issued asynchronously - this is the NetKernel equivalent to forking a child process in Unix.

//Asynchronously count the hit
req=context.createSubRequest();
req.setURI("ffcpl:/forum-main-logHit");
req.addArgument("param", nvp);
context.issueAsyncSubRequest(req);

                    

Finally the script executes the inner-topic viewer script which generates the view of the topic.

//Call Inner Topic Viewer
req=context.createSubRequest();
req.setURI("active:beanshell");
req.addArgument("operator","topic-viewer-inner.bsh");
req.addArgument("uri", uri);
result=context.issueSubRequest(req);

                    

Let's now follow the execution and step down into the topic-viewer-inner.bsh. If you examine this script you will see that this script also imports the url-parser.bsh library and it too parses the 'uri' argument. You can see above, that the calling script passed on the 'uri' argument in the sub-request which invoked this inner script.

Now, you may wonder: Why are you parsing this URI twice - surely that's really inefficient? Couldn't you just have passed the nvp value from the outer script? The answer to this is yes, but the approach we have taken is ultimately much more efficient. The reason lies in NetKernel's REST-like model. The actual request that was constructed and issued by the outer script is of the form...

active:[email protected]+uri@ffcpl:/forum/topic/[topic]/[id]
					

This URI uniquely describes the content to be returned by this script and therefore can be used as the key for caching the resource. If we had passed the nvp argument as a StringAspect the URI would not be unique since the information contained within the nvp would vary with each request and therefore the result could not be cached. In short, just like with the web where GETs are cacheable and POSTs are not, in NetKernel a pass-by-reference request is cacheable but pass-by-value is not. Pass-by-reference means the arguments on a constructed request are all URIs - no Aspects or Representation objects.

We shall see in a moment that this apparently convoluted approach pays us back with interest.

Let's continue on to see how the inner script generates the topic view. After parsing the uri and assigning it to the 'param' variable, the next stage of the script requests the metadata for the topic. This is achieved by creating and issuing a sub-request to the topic metadata service ffcpl:/forum-main-getTopicMeta. This service is presented on the public interface of the forum-services module which the forum-web application imports (we will examine the ffcpl:/form-main-* data services in more detail later). The param aspect is placed as the 'param' argument on the sub-request. The constructed request is issued through the context and the resource which is returned is assigned to the variable 'meta'.

//Get Forum MetaData
req=context.createSubRequest();
req.setURI("ffcpl:/forum-main-getTopicMeta");
req.addArgument("param", param);
meta=context.issueSubRequest(req);

                    

The script now chooses one of two paths based upon the value of the global variable 'page' (again set by the url parser library). The script treats as a special case the value "last" - in which case the following request is issued...

//Redirect to last page
req=context.createSubRequest();
req.setURI("active:dpml");
req.addArgument("operand", "ffcpl:/main/forum/topic/topic-viewer-redirect-last.idoc");
req.addArgument("param", param);
req.addArgument("meta", meta);
result=context.issueSubRequest(req);
                    

This sub-request invokes the dpml script engine to run the script topic-viewer-redirect-last.idoc - this script uses the 'meta' metadata resource which contains the number of pages associated with this topic to construct an HTTP Redirect to the last page of this topic. The net effect of this 'trick' is that the topic-viewer.bsh script is causing an indirect re-execution of itself with the correct value of [page] for the last page of the topic.

If the page is not 'last' then normal execution continues. First the entries for this topic are requested from the ffcpl:/forum-main-getEntries services in the forum-services module.

//Get Entries
req=context.createSubRequest();
req.setURI("ffcpl:/forum-main-getEntries");
req.addArgument("param", param);
entries=context.issueSubRequest(req);

                    

Finally the entries can the rendered into the XHTML view. The rendering is performed using XRL templating which is described in detail in the XRL guide. The XRL mapper is called with an operand argument of ffcpl:/forum/render/topic/, the metadata, entries, and parameter are all passed as arguments to be managed by the mapper. We will deconstruct the XRL template rendering in detail below - for now we should consider this as an instance of the black-box design pattern and assume that the XRL mapper will locate the topic rendering service and return the XHTML view.

//Hand off to XRL mapper to compose the view
req=context.createSubRequest();
req.setURI("active:mapper");
req.addArgument("operand", "ffcpl:/forum/render/topic/");
req.addArgument("operator", "ffcpl:/links.xml");
req.addArgument("entries", entries);
req.addArgument("meta", meta);
req.addArgument("param", param);
result=context.issueSubRequest(req);

                    

Lastly the script uses the attachGoldenThread accessor to attach a golden thread URI gt:/topic/[topic] to the rendered representation. This is part of a golden thread pattern which we will see later creates a loosely coupled dependency on the cacheable response of this script and which allows another independent part of the application to signal when the database has been changed and trigger the invalidation of the cached response.

//Attach a golden thread for caching
eq=context.createSubRequest();
req.setURI("active:attachGoldenThread");
req.addArgument("operand", result);
req.addArgument("param", "gt:/topic/"+topic);
result=context.issueSubRequest(req);

                    

Finally a response is constructed from the result. The response is marked as cacheable and issued back to the outer script requestor through the context.

//Return Response
resp=context.createResponseFrom(result);
resp.setCacheable();
context.setResponse(resp);

                    

As we have discussed. Since this script was invoked with a unique URI and the response is marked as cacheable. NetKernel will transparently cache the response. The consequence is that if in future the same script request is issued - ie when this topic is next viewed - the script response will most likely be in the cache (provided the golden thread attachment is still valid - which we will discuss in later sections). Therefore the cached resource will be served straight away and so this inner script will never be called - this is incredibly efficient and worth the cost of parsing the URI twice!

Back in the outer script. The response of the inner is returned as it's own response, but note that this time it is does not set the response cacheable. We could cache the outer response but if we did then the hit-counter would only get triggered once instead of for each page view! Finally, the net end-user result of this channel is then the rendered and paginated XHTML view of the entries in a topic.

As an exercise, try following the RSS path to understand how the RSS feeds are composed.