ULib Servlet Pages

ULib Servlet Page (dynamic pages)

A USP page is basicly a request handler that will be called by userver when the relevant usp alias is requested. The document consists of overloaded html comment tags that contain usp macros or c++ codeblocks which after being compiled into a shared object library can generate a dynamic html response.

Tags

Have a look at the examples in the ulib source directory ULib/src/ulib/net/server/plugin/usp for usage but in very simple terms.

HTML

Anything that is not enclosed in <!-- ... --> tags is understood to be HTML

Comments

<!--# (comment) -->

header

<!--#header
Content-Type: application/json
-->

Set the response html header variables

args tag

Declare page variables for interacting with the html document.

<!--#args
name;
-->
<h1>Hello <!--#xmlputs name --></h1>

A number of usp macros interact with args

<!--#number --> 
<!--#cout -->
<!--#puts -->
<!--#xmlputs -->
<!--#print -->
<!--#printfor -->

other helpful functions include :

UHTTP::isGETorPOST()
UHTTP::processForm()
UHTTP::getUserAuthentication()

form example

Declaration tag

#includes, classes, functions etc

<!--#declaration 
#include "some_header.h"
-->

calculator usp

Additionally userver will call certain functions at defined execution points if they are declared (think implimenting virtual functions):
- "static void usp_init_NAMEOFYOURFILE" // usp_init
- "static void usp_end_NAMEOFYOURFILE" // usp_end
- "static void usp_sighup_NAMEOFYOURFILE" // usp_sighup
- "static void usp_fork_NAMEOFYOURFILE" // usp_fork

Example usp

Session Tag

<!--#session
UVector<UString> strings;
-->

Allows the declaration of session persistent variables

Note re-declaring an existing session variable (without initialization) on additional usp pages references the same data value.

Storage Tag

<!--#storage -->

Interact with client local storage refer to:

UHTTP::getDataStorage()
UHTTP::putDataStorage()
USP_STORAGE_VAR_GET(%u,%.*s)
USP_STORAGE_VAR_PUT(%u,%.*s)

chat usp example

Code Tags

<!--#code --> 
<!--#vcode --> // validation code must be unique and before all other <--#?code--> tags 
<!--#pcode --> // paralleling code (background long running task)
<!--#lcode --> // load balancer aware codeblock

Generic c++ codeblock instruction flow begins once the service is booted by an incoming request

The incoming request is available as a string in the UHTTP::body variable.

The output response string is constructed in the UClientImage_Base::wbuffer which can be manipulated manually or through a number of macros /include/ulib/net/server/usp_macro.h.

Preprocessor

USP pages support c/c++ like preprocessor directives:

<!--#define $GREETING <h1>Hello World</h1>-->
<!--#include MainWindow.usph -->

The preprocessor is executed in two steps.

Firstly the contents of any include file is substituted (recursively if the included file itself had includes)
Secondly the translator substitutes the defined terms with their definitions. The whole result is then translated into a cpp file ready to be compiled.

These are very useful for reusing usp code as templates/macro. common examples may include:

Page headers/footers
Copyright notices

Ensure your build system is configured to react to changes to your template/header files.

Compiling

Once you have written your .usp file it needs to be compiled.

Manually compile

Navigate to the folder where the file.usp was saved and execute the compilation in a shell for

example:

cd /srv/http/servlet
usp_compile.sh test

The shell script will call the relevant programs to generate c++ code from the usp file and finally call gcc and libtool to create a shared library. Any compilation errors will be output to console and no .so file will be generated.

Automatic

UServer will also try to compile any .usp files it finds in the docroot that do not have their associated objects. Simply paste your usp files in the docroot as you would html and restart userver. On linux UServer can be also be built with inotify support so that the server need not be restarted.

IDE integration

For virtually all IDEs it is trivial to integrate a custom compile step such that usp_compile is called on relevant .usp files, recent versions of usp_compile even support local include directories and external build directories.