Introduction
Server Platform
Application Server
   Operation
   Directory
   Database
   Runtime
   Surface
   Shell-Tool
   Creation
Content Generation
Class Library API
Manual Index

next | previous

Runtime System

The Maxscape Web Application Server is build on top of the generic web server platform. The Maxscape Server Library implements a layer between the platform and the application processes of special projects. Content generation takes place within application servers , each having a unique name. An application server consists of one or more daemon processes. Application code is running within these application server daemon processes, using the Maxscape Server API. Server and application software is executed by a content generation main loop, Application functions are plugged in via the related module files or stored in the content database. Each application server has it's own:

  • Unique Name
  • Content Management Interfaces
  • Standardized Directory Structure
  • Server Configuration
  • Application Server Daemon
  • Content Database
  • Application Software

You can create as many Application Server as you like. So far, the creation isn't fully automated, but there are some helpful scripts.

Application Server Processes (Daemons) Main Script

An application lives in an application process that communicates with the HTTP daemon via the chosen CGI interfaces, whereas the actual CGI interface is hidden, so that programming is transparent. You only need to change the main process script.

Example Main FCGI Script of an Application Process

$Process->initialise();

my $Request;
my $Response;
my $FCGI_Request = FCGI::Request();

while ($FCGI_Request->Accept >= 0)
{
  $Request = Maxscape::HTTP::Request->new;

  $Response = $Process->execute ($Request);

  print $Response->HeaderAsString, $Response->Content;

  $Process->postProcess;
  $Process->cleanup;
}

An application server can be configured with the Apache HTTPD, using the FCGI protocol. Each FCGI main script is located in an own directory under the server's document root (/maxscape/server/'application server name'/docs) and is named www.fcg and www.cgi, where www.cg is a symbolic link to the www.fcg script. The www.fcg scripts must be configured in the related httpd.conf files (/maxscape/server/'application server name'/etc/httpd.conf) via the AppClass directive.

Using an Apache with FastCGI module, application processes of the following, exemplary form can be defined:

Example Main FCGI Script of an Application Process

#!/maxscape/bin/perl

$Request;
$Process;
$Response;

while($Request->accept)
{
  $Response = $Process->execute($Request);
  $Response->answerRequest;
}

In other words, a browser can send requests, which in turn are answered by server daemons, 'running forever'. The application content and software can more or less be encapsulated within the $Process object and the $Request and the $Response objects can handle the generic parts of page generation and the communication between browser and server. Also the $Process object has many parts that can be generalized by generic server functions.

Runtime System Objects

The runtime system of an application server creates several objects to provide a server programming interface for dynamic content generation. These objects could be used in elements, templates and other data stored in the content database or in application modules, plugged in via the application plugin mechanism. Server and application function calls and variables could be embedded in the database content or used in application packages.

Web Page Generation Types

The content of web pages can be generated with methods that are mainly dependent on the browser requests and the server response content and its storage type.

Static Content Generation
The simplest type of content generation is provided by the HTTPD itself. The delivery of static content, stored in files within a hierarchically directory structure.
Dynamic Generation of Content Stored in Files
There are two ways to generate dynamic content from files. Either you have (HTML) documents with embedded programming scripts or scripts with embedded application content. The last point sucks in respect to content management aspects and the first makes it expensive to manage the document specific application software. Anyway, it enables to deliver personalized content based on browser requests.
Dynamic Generation of Content Stored in a Database
Storing both, content and application software in a 'Content Database' has many advantages in comparison to a file based approach, especially when it comes to really big and complex projects.

Configuration

An application server configuration file are located under the server's etc directory: 

/maxscape/server/'application server name'/etc
      maxscape.cnf                 application server configuration
      httpd.conf                       apache configuration

Application Modules Plugin

Application functions, callbacks and modules can be plugged into the system at several stages of the content generation process. The code may be stored in in one of the following files (the process local files are placed in the corresponding /maxscape/lib/perl/Maxscape directory of the process):

ProcessApplication.pm (process application modules)
This is the file where the process application functions are defined or included.
ServerConfiguration.pm (process local configuration)
Server configuration could be made in this file.
ServerApplication.pm (application server global modules)
If you plan to run your applications within more then one main process, it is wise to place application server global applications in the ServerApplication.pm file.

Naturaly you can make your own module structure via the PERL 'use' or 'require' statements. A good place for server global applications is for example:

/maxscape/server/'your application server'/lib/perl/'yourPrefix'/yourModule.pm

So, you can say: use 'yourPrefix'::yourModule

Default Include Directories

Each process includes modules from the following library directories in descendant order (PERL @INC list). 

/maxscape/var/project/lib/WebServer,
/maxscape/lib/perl,
/maxscape/server/'application server id'/lib/perl,

Depending on your global configuration, perl modules are included from: 

/opt/perl/'Version'/lib/i586-linux,
/opt/perl/'Version'/lib,
/opt/perl/'Version'/lib/site_perl/i586-linux,
/opt/perl/'Version'/lib/site_perl,
/opt/mysql/'Version'/perl/'Version'/lib/i586-linux,
/opt/mysql/'Version'/perl/'Version'/lib,
.

Process Invocation

A process can be invoked via the CGI, the FCGI interface or the command line shell.

Command Line Invocation
Invocation from the command line can be used to check against compilation errors. For example:

./www.fcg -h

./www.fcg

env PROJECT_SERVER_NAME=<application server> SCRIPT_NAME=/www.fcg ./www.fcg
CGI Invocation
Invocation via the CGI interface is useful when developing an application (nasty killing of the processes is not required). CGI Invocation is enabled by requesting a page with a URL specifying www.cgi instead of the www.fcg as the process script.
FCGI Configuration and Invocation
The FCGI interface is invoked via the call of the 'www.fcg' main script (FCGI is the default).

Process Creation

A FastCGI process within Maxscape is created in the way described below.

1. create a directory that shall contain the process main script.
>  su - maxscape
> cd /maxscape/server/'application server'/docs
> mkdir 'process directory'
> cd 'process directory'
2. copy a Maxscape main script to this directory (the symbolic link to www.cgi provides accessibility via the CGI interface, for rapid development).
> cp /maxscape/server/WebServer/docs/www.fcg .
> ln -s www.fcg www.cgi
3. enable and configure the application plugin files
> cd /maxscape/lib/perl/Maxscape
> cp /maxscape/server/Maxscape/lib/perl/Maxscape/ProcessApplication.pm .
> vi ProcessApplication.pm
4. Add the required directives to the global and the 'application servers' apache configuration files, e.g.:
> vi /maxscape/etc/apache/httpd.conf
> vi /maxscape/server/'application server'/etc/httpd.conf
5. Restart the server:
> maxscape restart

Apache FCGI Process Configuration

Edit the related apache configuration file and add the required entries as described in the apache manual. Also add an include directive to the main apache configuration file: 

  vi /maxscape/etc/apache/httpd.conf
  vi /maxscape/server/'your application server'/etc/httpd.conf

To configure a process two environment variables must be defined via the AppClass directive in the server's apache configuration file (/maxscape/server/'application server'/etc/httpd.conf): 

AppClass /maxscape/server/'application server'/docs/User/www.fcg \
           -processes 3 \
           -listen-queue-depth 5 \
           -restart-delay 1 \
           -initial-env PROJECT_SERVER_NAME='application server' \
           -initial-env SCRIPT_NAME=/'process directory'/www.fcg

 <Location /maxscape/server/WebServer/docs/User/www.fcg>
    SetHandler fastcgi-script
    order deny,allow
    deny from all
    allow from all
 </Location>
PROJECT_SERVER_NAME
Unique name of a special web server. Has to be set for each process in the httpd configuration file.
SCRIPT_NAME
Must be set if the process does not reside in the server's document root directory.

Process Configuration (ProcessConfiguration.pm)

Process local variables, that must or are initialized before the database is connected are configured in the corresponding 'ProcessConfiguration.pl' script of the process. For example (see file 'ProcessConfiguration.pl'):

ContextQueryMode: '' or 'Mode' or 'Mode|queryParentCategories'
Controls the context lookup and the menu mode (default='' := only page context)

ContextQueryStyle: '' or 'CategoriesAndPages'
Controls the page lookup style (default='' := only categories)

Personalised Processes

To enable the apache servers 'Basic authentication' mechanism edit the 'application servers' apache configuration file and add the necessary entries: 

  <Directory /maxscape/server/'application server'/docs/'process directory'>
    ...
    ...
    AuthName "MaXscape Administration Server"
    AuthType Basic

    #authenticate via DBI
    PerlAuthenHandler                 Apache::AuthenDBI

    # 'application server' of the 'USERS' table
    PerlSetVar Auth_DBI_data_source   dbi:mysql:'application server':localhost

    # enables database query for groups in the 'USERS' table'
    PerlSetVar Auth_DBI_grp_field     GROUP_ID

    # set user cache expiration duration (minutes)
    PerlSetVar Auth_DBI_cache_time    600
    ...
    ...
  </Directory>

Process Logging

Logging of process actions can be enabled via the related enties in the ProcessConfiguration.pl files of the processes. The output is written to the apache error files (can be viewed via the wwwlogs shell alias).

The output of the various 'application servers' can be watched using the tcsh aliases: wwwlogs and wwwerrors.


next ∙ previous ∙ top ∙ become a member ∙ contact © Maxscape