HTTPServer/docs/JETServer Concepts.tex

\documentclass[10pt]{book}
\usepackage{graphicx}
\usepackage{wrapfig}
\graphicspath{/home/barant/HTTPServer/images}
\begin{document}

\begin{titlepage}
   \begin{center}
       \vspace*{1cm}
 
       \textbf{JETServer Concepts}
 
       \vspace{1.5cm}
 
       \textbf{Bradford M. Arant Sr.}
 
       \vfill
 
       A whitepaper on an advanced microservices development environment\\
       for the cloud
 
       \vspace{0.8cm}
  
   \end{center}
\end{titlepage}

\tableofcontents

\chapter{Overview}

JETServer provides a complete environment for developing very powerful and feature rich web content using standard browsers. It is intended to compete and replace the aging WordPress environments that comprise a huge number of websites. JETServer is designed with high performance in mind utilizing a combination of HTML5, CSS3 and Javascript. 

JETServer is designed to support a plugin environment, known as libraries,  for extensibility of capabilities including frameworks, work flows, styles, databases, etc.

\chapter{Basic Concepts}

In this chapter we will cover the components that make up the JETServer environment. 

\chapter{Sessions}

Sessions provide a congruent and flowing state management for a connected browser. The states of various elements are stored and kept as a part of the session information so a browser refresh will not disrupt the work flow intended by the application logic.

The Session Id is maintained on the browser as a cookie. The cookie is issued to the browser on the very first response from the first request to the server. 

All API interactions are identified as being part of a session. A browser can only have one session per domain. Sessions can support multiple window instances and is basically the authorization token. The server can issue a new Session Id in a response to the browser at any time which will reset the cookie being created to maintin the Session Id.  

The session mechanism will attempt to maintain a \emph{state} of the interaction of the request objects present in the view port of the browser. Session variables also maintain a server based data environment for the session. Session variables are available to the views and microservice methods using the \$[:\emph{variable-name}] syntax.

As requests are placed the request URI is saved to the http session. If needed, perhaps because of a refresh, the page state can be recreated from the saved URI list. Other data and state information can be stored to the session as well. 

\chapter{Views}

Views are document sections that can be placed into the page. Views can be static or can contain dynamic data elements. Views can also contain other views in a nested fashion.

Views are implemented as <DIV> elements within the HTML document structure. 

Views can be used to define overall page layouts by putting other Requests into a view. 

Other more advanced graphical elements can be created by combining views into a 'view group'. 

Views have layout style specifications for the elements contained within them. Absolute layout allows a WYSIWYG layout with precise pixel location. Linear layouts line things up either vertically or horizontally. Proportional layouts use percentages so that they scale and constraint layouts are similar but offer greater flexibility in controlling the expansion/compression of the elements in the display area.

Views that have URIs attached to them are considered document level views and will be triggered when the browser makes a get request to the URI. 

TABLE elements can also be specified in a view.

\includegraphics[width=\textwidth]{images/graphical_concept.png} 

Javascript code can be attached to components within the view or to the view itself. Custom components can be built that plug into the layout tool environment and can be designed into the application environment with prebuilt behaviors. Complex display control can be constructed using these tools. 

Views can optionally contain a \emph{request} element that can be used to provide a placeholder for subsequent view requests. When these are provided inside a view the view will act as a template that can encapsulate the subview. Request viewholders are usually tied to a URL component so that as a session presentation is being created it may use conponents in the URL to determine the content to display. Hidden requests are requests that use private session data to determine the content to display. 

\section{View Components}

View Components are packaged HTML5, CSS and Javascript elements that are defined to be used together as a component within another view (usually and layout view). 

Views may utilize HTML constructs to assemble part of its implementation. The use of <IMG>, <FORM>, <INPUT>, <TEXTAREA> and a significant list of other items can be contained within a view. 

The view can contain javascript that is used to interact with these components.

\includegraphics[width=\textwidth]{images/view_component_structure.png} 


\chapter{Variables and View Data Sources}

Data is available to be displayed and represented that is only available when the views are rendered. Sources of this data are as follows:

Standard variable syntax of just using variable-name will perform a search for a variable regardless of its type but prioritized by the following order:

\begin{enumerate}

\item  a variable set using the <set> tag. These variable persist for the life of the current transaction only.

\item data retrieved from a POST within a request and are defined as visible TEXT, BUTTON and TEXTAREA and hidden <INPUT> fields

\item a session variable set using the <setsession> tag. These varables persist fo the entire session.

\item an environment variable from the JETServer runtime environment. These variables are set when the server is started and do not change for the life of the server runtime. 

\item a mySQL server result table created in the last SELECT statement. The persistence of these variables is only for the life of the open data path or until another operation is performed within the same access path to the database. Each open data path can return results without qualification and the order of the database specification will determine search order. When databases are opened for use in content an associated session name that is used to differentiate multiple open access paths simultaneously.

\end{enumerate}

\chapter{Forms}

Using the INPUT tag within a FORM tag allows the submission of the related form data to the server to be processed as a POST request. A BUTTON can perform this activity and request a microservices method and pass the form data along as a parameter to the request.

BUTTONs are attached to server side microservice methods. 

\chapter{Image Library}

Significant content can be provided in the form of images and are used as part of a design. The image library is not intended to be a photo cataloguing function but is designed to provide image support to the view elements such as logos. The View Layout Editor is used to access the image library for inclusion into a view. Images can be placed in views and resized or rotated. 

Imagemagick is used internally to create a scaled and rotated version of the image for network optimization resulting in improved performance. These scaled and rotated images exist in the permanent cache and are always checked first when rendering images to the browser.

Images create a corresponding IMG tag that the browser consumes to request the selected images.   

\chapter{Work Flow Networks}

JETServer is a complete work flow engine capable of delivering extremely sophisticated work flow requirements on various business data sets. Performing various activities on business entities creates needs for scheduling follow-ups and other automatic processed based upon very long time delays or other triggers that cause the need for more immediate action.  

Work flow processes are initiated on a particular business entity and stick to the entity throughout the definition of the work flow process. At any one time there could be many work flow tags running on any one piece of data at a time. As well, work flow processes may initiate another work fow procedure on the same business entity or a different one that is related. 

Work flow processes can be initiated on a button press using the initiateWorkFlow API call. They are attached to a business entity and they may trigger other work flow processe on other entities related to various activities. Work flow process are very powerful trackers where things otherwise may slip through the cracks. Watch dog work flows can be ceated to ensure all activities are being handled and performed to avoid stale data situations. 

Work Flow Networks are developed using a graphical flow chart style workbench that allows the business process analyst to snap together activities that are to be performed by automated process and/or user interaction. Work Queue objects are available to design work lists for users to interact with items requiring intervention. Users can review various work queues and perform the requested activities to complete the work flow requirements. 

\section {Work Flow Units}

Work flow units are created when a work flow process is initiated on a business entity. A work flow unit (WFU) contains the business entity and a work flow identifier and a queue identifier. As the WFU moves through the work flow patterns the queue identifier is updated to represent its 'state'. 

\section{Work Flow Queues}

As work flow units move through the process they move from queue to queue. The various queue types perform perscribed operations on the work flow unit moving through the procedure. The queue types are as follows:

\begin{enumerate}

\item Action Queues - as work flows are constructed they are placed into a container called an action queue. 

 \item External Queues - provides a visual access point to the data entity referenced by the WFU. External queues reference views that are sent to the client as output to the work flow and the work flow is suspended until an appropriate POST operation is sent to the server in response to the work flow requirements.

\item Decision Queues - provides a method to perform tests upon the reference business entity and branch the work flow based upon the test outcome.

\item Wait Queues - these queues provide a place for the WFU to wait indefinetly or for perscribed periods of time before the WFU is passed to the next queue. The wait queue can return a list of WFUs that are currently contained so that work lists and other lists can be analyzed and worked with externally to satisfy work flow requirements.

\item Process Queues - these queues can perform a system call to perform advanced operations and can control the flow of the WFU based upon the operation's outcome. 

\end{enumerate}

\subsection{Action Queues}
\subsection{External Queues}
\subsection{Decision Queues}
\subsection{Wait Queues}
\subsection{Process Queues}

\section{Permanent Work Flow Procedures}

\subsection{Administration Work Flow Procedures}

Special procedures designed to maintain the basic operations of the website are contained in an internal area compiled with the executable so they remain unchangeable without version upgrades. 

Upon initial installation and startup of the server a welcome page is presented with a button the setup the administrative access options. Once this is accomplished then the administractive mode of the server is entered and the user is entered into the administration menu functions for the server.

\subsection{Initial Transaction Work Flow Procedure}

Initial work flow begins with the init work flow procedure aptly named 'init' in the root folder of the 'worflow' directory. The init procedure defines the nature and lifespan of the transaction received from the browser.

If the init procedure is absent in the folder then a default procedure is used. The default procedure offers the full functionality of the JETServer. It will receive the user request and do the session lookups and perform the view hierarchy operations.  

Libraries will be searched in the order defined by library list contained withing the libraries subfolder. First match will proide that resource to the rendering of the current page cycle. 

\chapter{Requests}

Requests are view 'placeholders' that can be used to make a request to the server and have the response be displayed in the viewport of the request. Requests are the fundamental building block to creating extended content pages.

When specifying a request in a view the URI must be specified. As the view is rendered to the response buffer on the server it will submit the request to the specified URI and when the response is received the placeholder will be replaced with the response data. 

The requests made to the server are microservices method calls. They are not the URIs mentioned in other parts of this document and are intended to address the microservice method's address space. Since JETServer uses a technique of providing the URI to the microservice method it can provide a unique link designed for that session only with a timestamp embedded resulting in a secure interaction environment that eliminates stale access to API calls.

Requests are implemented as <DIV> elements with an id tag that provides the name of the request. 

A request response will contain HTML document data that will be replaced as the innerHTML of the request 'placeholder'. Variables specified in the view will be rendered and the HTML is attached to the document structure where the request exists.

The document content of the response may contain a script tag which contains javascript that executes immediately after the HTML is attached to the document. 

\section{Microservice Methods}

JETServer uses a microservices style architecture and provides access to backend services through an API set that is designed to interact with the various view components of the application.  In essence the work flow engine will create microservice functions available only to the session providing a highly secure API system as all other sessions or attempts at accessing functions will be rejected if the work flow does not permit the operation.

Microservice methods are oriented around the business entity structure and are used to provide information query handling as well as the add, update and delete functionality of new business entity instances.

Microservice methods can also be used to provide lists of objects that can be further used in modifying or removing instances.

Applications can be designed that employ various business logic entities. Views that define forms for adding new customers or information on books or some other data entity can be specified and attached to the business entity. Common lists of objects that have filters applied can be retrieved and views selected for presentation of the data.  

\chapter{Defining URL, Links and Deep Links}

Because the session manages the states for presentation the contents of the page are directly linked to a URL which can be used to recreate the  contents in the event of an interruption. Also, a link is an entry point to the website that contains a complete structure to recreate the contents. Pages will usually consist of various viewpoints which make requests upon the server to fulfill the content requirements specified by a URL. 

A URI provides an external access string to be mapped to a site view. When a browser submits a GET request to a URI that is mapped to the server then it will return the resulting site marker forcing the session to check its current state and send the appropriate information. 

The URI may be specified as \emph{complete} or \emph{partial}. Partial URI specification will match the pattern check but will also pass additional parameters not specified into the view so that it may parse the content and provide the appropriate display result. 

\chapter{Business Entities}

Business entities provide the framework in which to hang all thiese views and logic. Business entities allow for the description of account, customers, products, inventories and any other associated data elements that may be used in business logic consideration. 

Instances of business entities are considered entity objects or entity instances. Interaction with business entities is performed using an object style interface and JETServer uses mySQL underneath to perform the persistent storage operations. 

Views are associated with a business entity combined with a microservice method to create functionality. 

\chapter{Libraries}

Libraries provide extensibility to the JETServer environment by allowing custom tools, applications, themes, templates, entities and components to be added to the server and utilized in the presentation. Installed packages are provided a root namespace and all related content must be contained and extended by the 'library' root path namespace.

The 'libraries' subfolder must contain a library list file that contains a simple list of the order in which the libraries contained herein are to be search for resolving resouce names.  Updates to the library list file will immediately be applied to the next transaction. Transactions still in process will not be changed.

Libraries can contain many things including full application request flows that can be integrated into other work flows or used as is. 

Local code is setup automatically in a default package named 'local'. The local package is always searched first when resolving names to finding objects. 

The system itself maintains a package space which is where the tools and control logic are kept. This space is static within the JETServer executable and is not modifiable. 

You can create an empty package and give it a namespace and write custom items into that package space. This package space can then be saved and distributed on the JETStore if it provides useful utility to others. 

It is intended to provide a JETStore for the user to browse for registered packages of all kinds from themes to full application work flows. It is hopeful that someday there will be a rich environment for providing tools and applications for the JETServer system.

\chapter{Server Directory Structure}

JETServer depends upon a hierarchical file system to provide the system functions. Libraries are stored as copies of the basic hierarchical structure that act as a qualified namespace. 

\chapter{ServerCore Network Platform}

JETServer is utilizing the ServerCore library to implement the TCP networking requirements. Using the Linux operating system and the epoll system architecture JETServer delivers high performance networking with extreme control.

Written in C++ JETServer is designed for performance at all levels of the technical implementation. Using the core namespace along with the http namespace to create the basic core functionality JETServer provides a framework in which to create complete work flow patterns required to build complex applications.

\includegraphics[width=10cm]{images/classcore_1_1_socket__inherit__graph.png} 

\section{Transaction Life Cycle}

JETServer is a complete HTTP request server in full compliance with the latest standards. Internally it can also mesh itself into a network of JETServers and will automatically adjust and load balance traffic requests coming through the server. 

Being an HTTP request server JETServer must conform to CGI specifications that are used to interact with the browser. 

\begin{wrapfigure}{R}{0.3\textwidth}
\includegraphics[width=0.25\textwidth]{images/transaction_lifecycle.png} 
\end{wrapfigure}

For e	ach received request JETServer will generate appropriate code sections and output them through the CGI gateway process for rendering by the browser. 

Form Field Data Cache provides access to the form variables received in the request.When the CGI data is parsed from the request it is placed in this cache for access by processes that may require it during the transaction life cycle. 


\chapter{User Interfaces and Tools}

\section{View Layout Editor}

The View Layout Editor provides a WYSIWYG interface for combining HTML elements to formulate the presentation. Style sheet activities and parameters are automatically maintained as elements are manipulated in a graphical environment. Previews provided by various automatic layout objects including absolute mode which allows WYSIWYG placement of elements. 

Development of a theme editor provides ability to allow user to set various themes for the graphical elements of the design. Ability to view the layouts using various theme data configurations provides a useful thematic testing environment.

The designed view layouts can be saved to create a view library and are usually associated to an entity and placed into the workflow storyboard.

In order to create a subfunctionlity within a view you can add the request object into the view layouts. As these layouts are rendered to the browser they will make their subsequent requests to the server keeping the event chain alive for the initiating or root request object. 

\section{Business Entity Editor}

The Business Entity Editor provides a work management area to create and maintain business entity related data and the relationship between them. A repository provides for linking together data description elements with views and work flow elements to create a feature rich base to construct highly capable work flows for business and function.

Business Entities can have work flow processes attached to them. Processes can be developed to interact with other entity work flows using an advanced event management system. 

\section{Storyboard Editor}

The Storyboard Editor provides the designer the ability to layout the pages and their components and design the flow relationships between the elements. As designs require extending the control elements of various views the storyboard editor keeps track of the request branching and allows the designer to maintain control over the hierarchical flow elements of the UI design. 

The design approach provides the ability to layout \emph{request} objects and associate various URI elements to these internal request objects to generate a complete presentation of the elements.

Various views can be layed out in the storyboard. Storyboards are based around the request object as each request object will perform a request activity which may result in a chain of further request events. 

\chapter{Views and User Interface Components}

JETServer enables a simple architecture for presenting and controlling the presentation. Interaction with the user is accomplished with various standard components that interact with workflows generated from the events which the component may produce. 

\section{View Hierarchy}
Views are managed as a hierarchy of nested references to view components defined in the 'view' subfolder. The determination of which view to deliver to the requester is made through the parsing of the requested URL being passed from the requester. The tree hierarchy is maintained as views are added, changed and removed from visibility through event processing. If a refresh (F5) is performed on the URL the engine will render the identical page before the refresh was requested. 

\chapter{JET Tag Reference}

JET tags can be used within views as well as microservice methods to build business logic. 

\section{CALL}
\section{COMMENT}
\section{DATABASE}
\section{EXCLUDE}
\section{EXTRACT}
\section{FOR}
\section{IF.. ELSE}
\section{IFNOROW... ELSE}
\section{IFROW... ELSE}
\section{INCLUDE}
\section{SYSTEM}
\section{TAG}
\section{WHILE}
\section{WHILEROW}

\end{document}