3.1 Back-end Application Files ¶

Some back-end code is normal code that gets pre-compiled at build time, as most systems do — as the Kiss core framework code is. However, some Kiss code (the majority of the application code) is hot-loaded at runtime. What this means is that code that is hot-loaded can be added, changed, or deleted on a running system. There is no need to bring the system down or rebuild anything. In a development environment, development and debugging occur while the system is running continuously. There is no need to bring the system down or rebuild anything. A production system can be updated while the system is running without the need to reboot the server or upset normal user use of the system.

All back-end code resides in the following directories:

src/main/backend

The vast majority of your application-specific code goes in this directory tree. All files in this directory tree (except KissInit.groovy) are hot-loaded.

This directory contains the following:

services

This is where all of your web services will be located. You can structure sub-directories to it as needed. Web services can call any core Kiss code, jar files, or precompiled code directly. However, although web services can call other hot-loaded files located in the backend tree, a special syntax is required. There is an example of this in services/MyGroovyService.groovy.

Unlike other coding philosophies that prefer thin web services that call core code, Kiss strongly prefers thick web services that contain the bulk of your application code. This maximizes the use and value of the hot-load facility.

scripts

This directory contains code that is not web services but common application code that is to be hot-loaded. However, there is a big negative associated with this code. While hot-loaded web services can directly call Kiss core code, jar files, and precompiled code, they can’t call methods in the scripts directory directly. They must use a convoluted syntax enabling the hot-loading of those methods. An example of this exists in the services/MyGroovyService.groovy.

KissInit.groovy

This file is used to configure the system. It is read once upon system startup and is not hot-loaded. See Setup and Configuration

Login.groovy

This is the code that validates a user’s login. It is kept here because it is common for application customization of the login process.

CronTasks

Files in this directory support the ability to auto-start processes at scheduled and recurring dates and times ala Unix cron. See the files in that directory for documentation.

src/main/precompiled

Code in this directory tree is compiled at build time and not hot-loaded. This directory tree is used to store common application-specific code that doesn’t change particularly often.

src/main/core

Kiss core back-end framework code resides in this directory tree. Nothing in this directory tree should be modified by you because it will be overwritten when Kiss is upgraded. (See updates)

3.2 Front-end Application Files ¶

Files under the src/main/frontend directory represent the front-end of the application.

All files under the src/main/frontend/kiss directory are part of the Kiss system and should not be modified.

index.html and index.js are also part of the Kiss system and aren’t normally modified. They contain code that ensures that browsers load updated code.

index.html contains three important variables that assure that users correctly load front-end code that has been changed rather than using their cached version. These variables are as follows:

SystemInfo.softwareVersion

This can be set to any unique string. When the system is in production use, if this string changes, the browser will load new copies of all front-end files (which it will cache for future use). If any front-end files are changed, this variable should be changed. The users will get the new screens after they log out and back into the system.

SystemInfo.controlCache

Setting this variable to true tells the system to observe the value in SystemInfo.softwareVersion and re-load the front-end screens if its value changes.

The value of this variable is often set to false during the development process to avoid double-loading of certain files. When debugging the front-end, be sure to disable the browser cache.

SystemInfo.releaseDate

This variable is used to track the release date of a given front-end. It is used for display purposes only.

In addition to differentiating between development and production environments, index.js is also used to detect the user’s device type (e.g., desktop, tablet, mobile) and, if desired, load different application screens.

login.html and login.js represent the user login page and should be modified to suit your needs.

Other directories such as page1 represent other user pages and would be the application-specific screens you create. The included page1 directory is only an example page.

3.3 Database ¶

Kiss supports Microsoft SQL Server, Oracle, PostgreSQL, MySQL, and SQLite.

As shipped, Kiss comes configured with an embedded SQLite server and database. While this is fine for a demo or small application, a real database should be configured for real use. The included database is located in the backend directory and is named DB.sqlite

Although Kiss has no preferred database, PostgreSQL is strongly recommended because it is free, full-featured, fast, rock solid, and portable on all major platforms.

See Setup and Configuration

3.4 Single Page Application ¶

Kiss applications are single-page applications in the sense that there is a single <body> tag and all other pages essentially get placed into that tag on a single page. However, Kiss is not a single-page application in the sense that the entire application gets loaded with a single GET request. This doesn’t make sense for a large business application in which many hundreds of pages may exist. Kiss lazy-loads pages as they are used, and except for browser cache, eliminates them once another page is loaded.

3.5 Controlling Browser Cache ¶

As discussed previously, the user’s browser cache can be controlled from the file src/main/frontend/index.html. In that file, you will see two lines that look as follows:

SystemInfo.softwareVersion = "1";  // version of the entire system
SystemInfo.controlCache = false;   // normally true but use false during
                            // debugging

If SystemInfo.controlCache is set to true, each time SystemInfo.softwareVersion is incremented, all users starting the application will be forced to load new code from the server and not use their browser’s cache. Once they download the new version, normal browser cache activity will occur.

Users using the system when front-end files are changed will not get the updated files until they log out and back into the system. In a development environment with browser cache disabled, the developer will see all screen changes upon reload, regardless of the variable settings. In fact, it is better to set SystemInfo.controlCache to false in a development environment to avoid a needless duplicate load of index.html.

3.6 Creating JavaDocs ¶

JavaDocs for the Kiss system will need to be created. They are created from the command line by issuing the following command:

./bld javadoc              [Linux, macOS, BSD, etc.]
    -or-
bld javadoc                [Windows]

The JavaDoc files end up in the work/javadoc directory.

3.7 Deploying A Kiss Application ¶

The only file needed to deploy the application is Kiss.war It can be built by typing ./bld war at a command prompt. Kiss.war ends up in the work directory. If you have your IDE create the Kiss.war file, it will likely not work. The Kiss system requires a special build process because application files are distributed in source form. Therefore, bld should be used to create the production WAR file.

If using Tomcat, Kiss.war should be placed in the webapps directory. When Tomcat starts, it will see the file, unpack it, and run it. The application will be available at [HOST]/Kiss

Renaming Kiss.war to ABC.war, for example, will cause the application path to change to [HOST]/ABC

3.8 Learning The System ¶

In order to start getting a feel for how Kiss applications function, in terms of the back-end, look at files in the src/main/backend/services directory. With Kiss you can develop applications in several different languages. The services example shows the same code in all of the supported languages.

In terms of the front-end, see the example files under src/main/frontend/page1