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 and application.ini) 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.

application.ini

This file configures the system parameters. It sets various system parameters such as database configuration, threads, and other system parameters. See Setup and Configuration

KissInit.groovy

This file is read once upon system startup and is not hot-loaded. It loads application.ini and can be used to perform other startup tasks. 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 gets compiled into the system. Whenever code in this directory tree is changed, the application must be rebuilt.

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. Nothing in this directory tree should be modified by you because it will be overwritten when Kiss is upgraded. (See updates)

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 is controlled from the file src/main/frontend/index.html. That file carries a version number and a flag that turns cache control on or off:

<meta name="kiss-version" content="...">
<meta name="kiss-cache-control" content="false">

When cache control is on, each time the version changes every user starting the application is forced to download fresh code rather than use the browser cache; once the new version is loaded, normal browser caching resumes. A production WAR stamps a fresh version automatically, so each release force-refreshes all clients with no manual step.

During development the flag is left false, both so that edited files are seen immediately on reload and to avoid a needless duplicate load of index.html. The mechanism, and the reason index.html itself is always loaded afresh, is described further in the Front-end API chapter.

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