Dissemino: What Does It Actually Consist Of?
Dissemino (Latin for disseminate), was the codename given to the HadronZoo HTTP services project (C++ powered websites), and by logical extention to the project emergents. There is the Dissemino method (DM); The Dissemino class group in the library, which together with the HDB class group, implements the bulk of the DM; Programs with a HTTP interface based on the DM, are said to be 'Dissemino programs', with the prime example being HadronZoo::Dissemino, the home-grown HTTP server otherwise known as the Dissemino Web Engine (DWE). The DM is thus primary. Unless otherwise qualified, 'Dissemino' can be taken to mean the DM.
The DM has the same purpose as, was inspired by, and is arguably an adaption of, the LAMP method (Linux, Apache, MySQL and PHP/Python/Perl). As outlined in the introduction, Apache scans page content for scripts, executes them, and substitutes script body with script output (if any) in the final HTML. The DM does the scan-execute-substitute thing, but does it differently. In particular, the DM does not call scripts. These are replaced by HDB and Dissemino tags, which instantiate HDB and Dissemino classes and call HDB and Dissemino class member functions. All functionality in Dissemino webapps, is provided by C++.
The Dissemino Web Engine manual (also available on the HadronZoo website), explains how the DM is used to create webapps. This section of the HadronZoo C++ library manual, explains how the DM works from the C++ standpoint. At least, those are the intentions.
The DM: Things to Note.
For TCP/UPD server programs based on the HadronZoo library, there is a very simple 'rule'. Serve anything? Use the hzIpServer class. Serve HTTP/S? Use the hzIpServer class, and the Dissemino method! Both are straightforward from a C++ developer perspective. hzIpServer gives you an edge-triggered epoll server, which can listen on multiple ports simultaneously, for both TCP and UPD. There must be a handler function for each listening port. How hard handlers are to write, depends on the applicable protocol. With the DM, the handler is part of the library. The hard part is working out what the webapp will do and putting that in the config file.
The DWE is considered to be a 'web engine' rather than a 'web server' because of the way the DM works. Apache serves HTML pages that are primarily files in particular locations, in an essentially disparate process. All processing takes place within the web server and not in program space assigned to a website. Scripts within pages can reference entities in an external database and declare persitent variables, but beyond this there is little to tie website components together. By contrast, Dissemino webapps are 'whole'. Although a webapp can access external single repository services, all resources available via a URL are manifest within the Dissemino program space. In a crude sense, web servers host websites while Dissemino programs actually are websites.
Because the HTTP server functionality is entirely provided by Dissemino classes, Dissemino programs or at least the part of them responsible for serving HTTP, tend to be small. The necessary resources are declared and initialized, a hzIpServer instance is invoked and the HTTP service is online! Every web resource is an instance of a Dissemino class and whilst these can be declared and initialized like all other C++ class instances, they are usually created and initialized by a config read. The config regime, also part of the library, is standarized on XML. It uses XML for everything - to define data object model entities, the Dissemino class instances and as the framework for page HTML.
The Dissemino classes are defined in $HADRONZOO/code/hzlib.ver/inc/hzDissemino.h and implemented across several source files (prefixed with 'hds') in $HADRONZOO/code/hzlib.ver/src. As a HadronZoo dependent system program, the source for the Dissemino web engine is found in $HADRONZOO/code/syst/dissemino. It comprises a single source file, dissemino.cpp which is under 2,000 lines - the modest size reflecting the fact that virtually all the functionality is derived from the Dissemino classes.
It makes sense for the demarcation to be a strongly library-centric. Regardless of whether the objective is a simple control panel front end or a sophisticated website, adding HTTP server capability to a program is an all or nothing proposition. The difference between a web front end and a full blown website is semantic. Both are web applications and as such, have quite a long list of things to do as a minimum.
The hdsDissemino and hdsApp classes
The most important Dissemino class is hdsApp which forms the core of a web application. Each application has exactly one instance and it is the container for the definitave set of resources the application commands. hdsApp has numerous config read functions, initialization functions for assigning ids and generating scripts and numerous maps for trying names and URLs to forms, pages and other frontline resources, as well as maps to keep track of a host of intermediate entities.
In the general case, a program based on the Dissemino classes will be single application. The Dissemino web engine is an exception. If the web engine is being used to host multiple websites on the same physical server, all will expect to listen on the standard HTTP and HTTPS ports. For this to work the hostname heading in the incoming HTTP requests is used to route the requests through to the correct application, and there has to be a means of supporting multiple web applications. The is the job of the hdsDissemino class.
Dissemino Resources
A Dissemino resource is any entity for which a unique URL has been assigned within the application. Dissemino resources are derivatives of the base class hdsResource as follows:-
| hdsPage | Pages direct generation of a complete HTML document, including any supporting javascript. The javascript is compiled once at program startup and thereafter written out verbatim each time the page is requested. |
| hdsArticle | Articles are partial HTML documents, intended for display within a host page. In the general case, the host page is a supporting frame for a set of related articles, giving them a standard 'look and feel'. There are two methods of article selection; by naming the article in a query to the host page URL, and by AJAX calls driven by JavaScript controlled links, commonly held in a navigation tree. Note that there are some restrictions of what an article may contain. For example, an article may only hold a single form. |
| hdsFile | A standalone file defined as a servable resource. hdsFile instances are created for each <xfixfile> tag in the configs. There are a number of ways Dissemino can be made to serve files of HTML or other content, all of which are rudimentary. The files, which can be of any MIME type and be for any purpose, are sent to the client as-is. No processing is applied. A hsFile must have a raw value (the file content), may have a zipped value and must have a full path and MIME type. |
| hdsCIFunc | Instead of HTML being assembled by evaluation of the visible entities in a page, it is directly generated by a C-Interface function. |
All Dissemino resources are controlled by access flags as follows:-
| ACCESS_PUBLIC | Access by anyone (login status ignored) |
| ACCESS_NOBODY | Access by anyone who is NOT logged in |
| ACCESS_ADMIN | Access by site administrators only |
| ACCESS_MASTER | Access by web-master only |
| ACCESS_MASK | Bits 0 - 29 reserved for up to 30 types of users |
Dissemino Intermediates
Dissemino intermediates are resources that don't have a URL. They are operational entities that are either components or attributes of Dissemino resources that do have a URL.
| hdsSubject | Ties a subject category to the set of pages deemed to be of the subject |
| hdsTree | Navigation tree for selection of articles. |
| hdsFldspec | These are field specifications for standardizing the HTML parameters for fields in form definitions. Instances are created by <fldspec> tags in the configs. They are also used in data class defiitions. This is unorthodox as it is a 'golden rule' that databases should not know or care how the data is presented or collected. For the purpose of the database, data class members need only a name and data type, and flags to state if the value is compulsory and if multiple values are allowed. However as a development aid, Dissemino generates default forms and form handlers directly from data class definitions. For this reason field specifications are a convienient means of guiding the HTML generation of default forms. |
| hdsInfo | User Sessions. Please see article 6.5 |
Percent Entities
Dissemino Percent Entities are character sequences of a particular form that act as macros. Each percent entity relates to some variable or class member and when invoked, evaluates to the current value of that variable, effecting a text substitution or a data translation. Percent entity evaluation ocurrs in only two scenarios, in form handlers when processing form submissions and during HTML generation.
There are six general classes of percent entity as follows:-
| X-class | Standard system values. The entity either exists and is valid or does not exist and is invalid. |
| U-class | Standard user values. Must also exist but fail the scope test if they exist within a page or a form within a page, whose access settings exclude logged in users. |
| S-class | Independent user session variables. As these can be set up in any form handler, not necessarily related to the form in which the S-class percent entity appears, these are currently not tested. |
| E-class | Event values. These are tested against the fields known to exist in the supplied form. |
| I-class | In-situ values. These are valid if they name members of the applicable class and not otherwise. The applicable class is the host class of the supplied form. If no form is supplied, these are invalid. |
| V-class | Session object values. These are valid if the name members of a session object that an earlier <procdata> command has brought into focus. Currently this is not tested. |
All percent entities have the form of a percent sign followed by a letter indicating the entity class (either x, u, s, e, i or v), a colon, the name (of the variable or member) and finally a semi-colon. The class indicator is always lower case even though the classes of percent entities are named with upper case letters. It looks neater in the configs.