AWF: Americati Web Framework

In this section we’ll explain how to develop a sample web application with AWF. This application will be deployed as a war file for a Jakarta web container, but the distribution provides samples for embedded web apps.

We’ll assume that the AWF jar is installed in the user’s local maven repository. If it is not the case, it may be installed with:

For a JEE version, use the awf-jee artifact:

An AWF screen is composed by two components: a template view (usually an HTML document) and a controlling object whose class is annotated with @AwfScreen.

We’ll create two screens for this demonstration: a "login" screen, and a "welcome" screen which will be the first (and the only) screen which the user will be able to access after a successful login.

The event handler allows the access to the screen widgets. Those widgets may be read by the screen code and written in order to update the screen view. Besides the "actionable" buttons previously described, we support a number of widgets usually associated to HTML forms.

They refer to the HTML input elements with a type of text and similar like email, etc. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input for more information.

Obvious non textual types are button and file.

Those elements are mapped to the AwfTextbox Java class in the server, and the user may change its String value.

Also, any HTML textarea element with the data-awf attribute is mapped a AwfTextbox object.

The HTML <select> elements containing the data-awf attribute are mapped in the server to a AwfSelect Java object, which allows the extraction and change of the contained options (modeled by the AwfOption class.)

There is a multiple read-only attribute (set in the HTML view) which helps determine whether the selector admits multiple selection.

The HTML <input type="checkbox"> elements are mapped to Java objects of AwfCheckbox, reflecting the "checked" state.

A number of same-named HTML <input type="radio"> elements is considered a "radio group", and is mapped to an AwfRadioGroup object.

The <img> elements marked with data-awf will be mapped into an AwfImage object, allowing the dynamic change of their source path.

The <input type="file"> element marked with data-awf and data-awf-upload-action attributes is mapped to an AwfFile object, allowing the retrieval of the file’s binary contents. The data-awf-upload-action signals the action which triggers the upload; this is necessary since there could be several buttons in a screen but only one is in charge of the submission of the files.

Multiple file selection is supported by the usual procedure of adding the multiple option to the HTML input element.

The max-upload-file-len defines the maximum bytes per uploaded file and is controlled in the client (when the file is selected.) This application parameter may be overrided by the maxUploadFileLen attribute of @AwfScreen.

Also, the total POST contains the encoded sum of the files' contents, and must be less than the maximum POST request size of the screen.

HTML elements without children nodes and marked with data-awf will be mapped to a Java AwfLabel object, which allows to dynamically change the contained text. Usual elements are span and p; dynamic "clickable" content may be generated with a elements (with href="#".)

Any remaining HTML elements containing children nodes and marked with data-awf will be mapped to a Java AwfHtml object. This is used essentially to change its attributes; for example, the display of an <div data-awf="xdiv"> element may switched with xdiv.setAttribute("style", "display: none") or xdiv.setAttribute("style", "display: block").

Any action may be programmed to request a "file download". The action may be triggered from a button or an hyperlink as previously described.

The Java handler for the action must return a "download" response with the AwfCmd.download() methods providing a disk file, a byte array or a text string.

This facility is oriented toward improving the development ergonomics: when developing a screen, in order to accelerate the testing iterations it is convenient to automate the steps needed to access the target screen, starting from the login. The automatic login mode allows the automated registry of the session and jump to the desired screen as soon as the user reloads the AWF servlet (usually just pressing [F5] in the web browser.) Two things are needed:

AWF provides a very-lightweight alternative to a full dependency injection library/framework, providing easy management of singleton bean instances. Its usage is totally optional and is activated only if the bean-package servlet initialization parameter is configured.

The "bean container" is provided using the facilities of the Reflections library (class BeanStore.) This is used to support the "screen beans" which are page controllers annotated with @AwfScreen, and arbitrary singleton beans which are classes annotated with @AwfBean, as a really lightweight alternative to a full bean container. Eventually, the bean container facility could be externalized as an independent project.

The managed beans' constructors may be without parameters or with ServletConfig and ServletContext typed ones. The beans package location must be configured with the bean-package servlet initialization parameter.

These beans may have other beans as dependent fields by signaling them with the same @AwfBean annotation (but at field level.) The screen controllers (@AwfScreen annotated classes) may also have @AwfBean dependent fields. Note that the screen instances are no singletons, unlike the injected beans.

The @AwfBean annotation allows an explicit naming of the bean with the name attribute; else, it is assumed that only a single bean exists for its class type (a fictional name is derived from the class name.) Such beans here are known as "one in its class".

It is possible to inject bean implementations through interface typed fields as in most DI frameworks. This is a rather slow process as compared with field injection by a named bean, specially on screen controller classes. Currently, AWF does not check if more than one bean implements the specified interface, so which concrete bean is injected is undefined when multiple beans implement it.

Inside any @AwfBean marked bean class, a number of static or instance level methods may also be annotated with @AwfBean, which makes them "factory" methods. Such methods will be executed by AWF exactly once in order to create additional singleton beans. This is useful when we do not have access to the source code of a class (i.e. not able to annotate its type) from which a bean instance needs to be created.

After all the beans are instanciated, the field injections proceed, and the initializer methods are called if defined. The initializer methods are designated by the @AwfInit annotation; these may have the same parameters as the constructor and also the defined beans which are "one in its class". Unlike the constructor, several initializer methods may be defined and all will be executed (though it is a dubious programming pattern.)

The screen controllers also may have initialization methods which will be called only once after instance construction, with the same semantics as singleton beans. In this case, the methods may have the associated ScreenSession as a parameter.

Below there is a "login" screen employing a fictitious LoginScreenAuthenticator bean:

AWF provides an optional facility to streamline the validation of widgets' input. Any non-login screen may define per-action static methods which fill a ActionValidations parameter. In the following example, three validators are defined for the execution of the act-calc action; in this case, the three mentioned widgets have each one validator, but zero o more validators are acceptable per widget:

Such object is used to declare a number of validators to be applied to the textbox, select and radiogroup widgets in the client (for best performance) and optionally also in the server (for best security.) Each validation consists of the widget identifier, a regular expression, and a report message to be shown on action trigger when the widget value is not acceptable. There are several signatures of add() in ActionValidations for further control of the regular expression matching.

In the client side there is a "default" validation error handler which just alerts on the first validation failure:

The developer may develop an overriding function named awfValidationFunct which implements a similar logic: returning true does mean that the request may be carried on, else some other action should be taken (like showing an alert), and the request is cancelled. This function receives an array of objects containing the following fields:

It is up to the developer how to handle the validation failures; for example, some applications will present a dialog with the list of the failures; in other cases the web page gets warning annotations besides each failed widget, and so on.

When a screen is loaded (the HTML document is fetched) the AWF Javascript engine is executed as a DOMContentLoaded event handler. If the developer defines a function named awfPostReadyFunct(), it is executed at the end of the mentioned event handler. It may be leveraged to extend the AWF behavior in a consistent way.

When a screen is loaded the AWF Javascript engine notifies the server and potentially fetches the initial state of some widgets. This time lapse has an arguably awkward behavior since the browser already displayed the HTML contents but a "final version" is yet waiting for the server response.

A solution is to hide the screen and wait for the initial request to be answered. The following examples were adapted from https://stackoverflow.com/questions/9550760 :

This solution hides the document via CSS and provides a function to show it later:

The Java controller provides the needed call to be triggered when the document is shown:

This solution adds a div element covering the screen which is later removed using the same Java code as in the previous case. The example div shows a black background with a centered image (for better results, replace with a "clock" animation):

Cases upon HttpServletRequest.getServletPath():

When the path is /awf or "empty", the "login" WebPage is built and sent to the browser without the "initial server call" instruction.

When the path is /awfres, the corresponding resource is loaded from the classpath; currently we define the resources:

The last two may be configured with the initialization parameters timeout-path and internal-error-path.

Other path requests are considered errors. Any other interaction is carried on with the POST method.

There are two kinds of POST requests: an XDR fetch when the client provides a user request and widget updated information. When the client gets the response, it may be instructed to update the widgets and do nothing (the user got its results), or do a "page jump"; in this last case the client will issue a plain text/html POST request (from a form created on the fly) with the minimal authentication information. It could have been a GET, but we opted for a POST to avoid url parameters in the browser tab. The following explanation begins with the later case:

a) If the HTTP Accept header contains text/html, then it is assumed an HTML page is requested. On error the request is redirected to the internal error page.

The AWF_SESSION cookie must exist and is used to extract a mandatory existing session. Also, the POST parameters awfcrsf (CRSF protection) and awfseqcode (current page sequence code) are captured and validated with the current session.

Note that if awfseqcode is invalid, if usually means a browser refresh attempt, so it is handled according to the usr-nav-path initialization parameter.

Then the handleFormPost() method is executed. This method does create a new page sequence code and set into the session. If the screen is shown for first time, then the "need initial call" boolean flag is set, which instructs the awf.js script to make it.

b) Otherwise the request is assumed to be Json text from an Ajax request. On error, an "Exit redirect" order is sent to the awf.js script in order to go to the internal error page.

The Json text is parsed with Jackson as a Java Map<String,Object>; this map is used to identify the browser provided widgets, a Java Map<String,ScreenWidget> is produced by the ScreenExtractor.extract() method.

As in the previous case, the awfcrsf and awfseqcode Json attributes are extracted and used to get the associated session (if any.) Also, the AWF_ACTION Json attribute is captured for special processing:

If contains u-logout, then a redirection to the logout page is in order.

If contains u-login, then the login screen controller is called.

Else, the awfcrsf and awfseqcode attributes are processed (like in the previous case.)

If all right, the controller object is extracted from the session and the doScreenFunction() is executed, which calls the user screen controller method, and acts upon the response.

Again: the user screen method is called only for doPost when an Ajax Json request is sent from the browser.

a) The screenData widget map is iterated and the contained widgets are marked as "unmodified" (ScreenWidget.markUnmodified() method.) This is used to avoid re-sending unmodified widgets to the browser in the response, to reduce network traffic usage and re-draw time in the browser.

b) The injectWidgets() method is in charge of injecting the declared widgets of the user provided screen. This is made with the help of a map containing the java.lang.reflect.Field objects which are captured via reflection while scanning the widgets in the WebPage.scanPages() method.

The AwfTable pseudo widgets are "heavy", since they need to search in all the widgets sent by the browser looking for the prefix name#.

The rest of the widgets are updated only if they come from the browser.

c) Next comes the call to the screen controller method using the current session, or the "null session" for the login page. The return value must be not null or a NPE is thrown.

Any exception is catched and logged. The action taken depends on the onException attribute of the AwfScreen annotation (defaults to the error page.)

The following is the processing of the user code response (ScreenAction interface.)

d) If the response is a ScreenActionExit object, then call the sendExitRedirect() method which drops the session and sends an AWF_EXIT command to the browser which in turn, forces a redirection to the logout page (defaults to awf.)

e) Else, we assume the response will contain new values for the widgets in the browser, so we prepare a map containing the currently "modified" widgets

f) Process ScreenActionUpdate by sending the widgets; optionally add the function calls if the addCall() method was used, together with the AWF_CALLER command.

g) Process ScreenActionAuthenticated; this object already was created by user code, which is in charge of validating the remote user credentials.

A new session is created, storing the principal attribute.

The ScreenActionAuthenticated is converted into a ScreenActionGoto for further processing.

i ) In this point we check that a session is active, else do a sendExitRedirect(). All the previous actions could happen for a session-less request (i.e. the login request.) For example, an implementation may provide a feedback message for a bad login attempt.

j) The ScreenActionGoto, ScreenActionGosub, ScreenActionReturn and ScreenActionDownload responses are processed, dealing with the session stack. These methods use the sendJump() method which provides the jump command (AWF_JUMP command), the current CRSF token, and the current sequence to the browser.

The buildHtml() method is in charge of producing an actual HTML page response. It consists of:

Each screen (controller + template view) is stored internally in a WebPage instance. The servlet has a map containing these WebPage instances indexed by the screen logical name.

In the server, the widgets are objects implementing ScreenWidget (from the user framework point of view), but also extending from the abstract class BaseScreenWidget in order to support more features while not complicating the user API: this later class only has package-level access methods which are called by the AwfServlet code.

Those widgets are collected in a Map<String,ScreenWidget>, and it is provided to the browser as a Json string (together with the CRSF token and synchronization sequence.)

Note that this transfer only happens as a response of a browser initiated HTTP request, so we are dealing here with the "response to the browser".

Now we’ll see the browser point of view.

The login page is loaded by a GET request into the AWF servlet. At first, the login page must provide HTML elements which correspond to the widgets user for authentication (like username and password fields.) In the server there is no session, and the browser (with the awf.js code) builds a Json request upon user authentication request (i.e. click on sign-in button.)

The data-awf marked elements are sent in this Json string to the server to be converted into ScreenWidget objects using code inside the ScreenExtractor class. Those objects are injected into the corresponding @AwfScreen user-provided object before the screen controller method execution, in order to make available the widget contents.

The BaseScreenWiget has a flag for registering which widgets are modified by user code (from the screen controller method), and those "touched" widgets are sent to the browser for the corresponding redraw.

Instead, if the authentication is successful, a "page jump" command is expected to be returned to the browser (without further widget information.) On "page jump" command, the browser will execute a POST request to the servlet, for obtaining the new HTML document (the target page is already set in the associated server session, so the browser does not specify the destination page.)

Except from the login screen, the screens are loaded by POST requests. The first time the screen is invoked, a new @AwfScreen object instance is constructed and is associated to the server session. The response correspond to a HTML document built from the associated screen template. At this time, no ScreenWidget objects exist.

When the document is loaded in the browser, the awf.js script issues a "initial request" containing the data-awf marked elements as a Json string, so the servlet has the opportunity of extracting the corresponding widgets and issue a first call to the screen controller method. On return, the screen is marked as "initialized".

Note that the browser here issues the request with the pseudo-action awf-initial-call, which is converted into the real programmed action stored in the server session.

As in the previous case, only the "touched" widgets are returned to the browser for redraw.

The user may jump from a screen but return later (after a ScreenActionReturn response.) In this case, the screen widgets are already loaded in the server (thru the screen instance in the screen stack of the session.)

Now, the "touched" widget contents will be included in the HTML document as a Json string, and a flag will be set to avoid the previously described "initial request". This is made in order to save an extra unneeded browser request and improve the application responsiveness.

awf.js drives the browser interactions. On load, it scans the widgets using document.querySelectorAll("[data-awf]"). All the interesting HTML elements are stored in the awfElementList array, some as plain DOM objects, others (like a radio group) as a new "internal widget" object.

Those elements are repainted using awfRepaint(), employing the initial values if provided in the awfIniScr object (coming from the servlet.) That routine is called later for each user interaction.

The buttons have their "click" event pointing to the awfFireAction() function, which builds a new object containing the associated widgets which were changed by the browser’s user. Those are sent to the server as a Json request.

The HtmlUnitTest is the main test to execute and prove the widgets using the HtmlUnit Javascript engine. Uses the HtmlUnitUnit to streamline the coding. The BeanTracker is used to count the registered bean method calls.

The ManualTest just executes the test application using embedded Tomcat and the client user must employ a web browser. Uses the "EmbeddedTomcat" class. The DelegateToSlf4jLogger is used to reconfigure Tomcat logging to Slf4j.