The entire source code comes with the system and is convenient when debugging. Kiss has been designed to segregate Kiss framework code from your application code for two reasons:
Naturally, in order for this to work, it is important that you not change framework code and put all of your application code in the correct areas.
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)
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.
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.
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.
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
.
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.
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
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