In addition to the full API provided by the Java system, and any additional JAR files you add, Kiss comes with an API that assists with the development of business application with Kiss. These API’s may be broadly grouped as follows:
An overview of these API’s is contained in this chapter. Detailed documentation is contained in the JavaDocs. See Creating JavaDocs.
Kiss comes with a powerful library for accessing SQL databases.
Code for this is located under org.kissweb.database
It is
currently being used in production environments. This API provides
the following benefits:
As shipped, this library supports PostgreSQL, Microsoft Server, Oracle, MySQL, and SQLite.
The detailed documentation for the database utilities are in the JavaDocs which you must generate. (See Creating JavaDocs.) This section provides an overview.
The Kiss database routines revolve around four main classes as follows:
Connection
This represents a connection to an SQL database.
Command
This represents a single action or command against the database.
Cursor
If the action is a select
, the Cursor
represents a
pointer into the result set.
Record
This class represents a single row within a table or result set.
The Connection
class contains several convenience methods that
are used in simple cases where only a single action is being
performed. These methods should not be used when multiple
simultaneous actions are taking place at once (by that single thread).
This issue is not a problem in multi-user or multi-threaded
situations. It is only a problem when a single thread is doing one
action while another action is still open.
You will notice that your REST services are passed a Connection argument. Kiss automatically forms a unique connection for each REST service call and closes it when the call is done. Therefore, you will not normally need to create your own connection. Additionally, Kiss automatically starts a new transaction with each REST service and commits it when the service is done. However, if the service throws any exception, the transaction is rolled back instead.
You would not normally write SQL for single record adds, updates, and
deletes. Using the Record API, Kiss
automatically
generates these statements for you.
In addition to the above, these utilities provide full support for transactions and parameters.
Microservices are classes that may be added, changed, or deleted while the system is running. In spite of this, however, all microservices are fully compiled and run at full speed. This has two major advantages.
First, in a development environment, all development may be done without the need to bring the development server down, rebuild, re-deploy, and reboot the development server. This means development time is significantly reduced. Additionally, IDE debuggers function in an environment such as this so the debugging process may proceed normally.
Second, in a production environment, the system may be upgraded without disrupting existing users on the system. Of course users actively using the exact features you have just changed could be affected (if their front-end and back-ends do not agree). A simple re-try would put everything back in sync.
Kiss microservices are on a class basis. What that means is that a microservice is always a single and whole class. You cannot have more than one class in a microservice. Microservices can call core components of the system just as regular methods can. However, if one wishes to have one microservice call another microservice, the calling mechanism is a little more clunky. However, using this clunkier mechanism retains all of the dynamic features of the system.
Defining microservices in Kiss involves defining a normal class just as you would write a class in any circumstance. No special configuration, wiring, declarations, or additional steps are required. Microservice additions, changes, and deletions take affect as soon as you save the source file. All microservices are compiled at runtime by the system automatically. So there is no compilation step that you need to perform.
The only caveat to the above is that remote microservices (described below) expect a certain method signature (standard arguments). This is only to assure that the front-end and back-end can communicate as expected. Local microservices do not have this requirement.
In Kiss, microservices can be written in Java, Groovy, or Common Lisp. However, Groovy microservices have been used exclusively in all current environments that we are aware of. Therefore, Groovy microservices are best tested.
The reasons Groovy was used are as follows:
Having said all this, however, all three languages are fully supported and there are no known bugs in any of the languages supported.
There are two types of microservices as follows:
Remote services are generally called by a (likely JavaScript) front-end or a remote client typically over HTTP or HTTPS. Local services are services that are called locally, from within the system as, for example, one microservice calling a method in a different microservice.
In Kiss, remote microservices appear to the outside world as typical REST services. They may be called by a JavaScript front-end, web service client, or any other facility that can talk to REST services.
Kiss REST services are asynchronous HTTP or
HTTPS services. Internally they are processed utilizing a
thread pool to assure optimal CPU utilization. The number of threads
in the thread pool is controlled by a configuration parameter given in
the KissInit.groovy
file.
Kiss comes with JavaScript code so that Kiss
REST
services can be easily accessed from a typical front-end.
This code resides in a single file and can and has been used by
alternative front-ends such as Angular and React
.
There is no need to handle authentication. Kiss handles that automatically. So, when your web method is called, you know who they are and that they have been authenticated.
Remote REST microservices typically reside under the
backend/services
directory. You can organize them any way you
like. A microservice is equivalent to a class. The class name is the
microservice name. The methods in that class that have a certain
signature (particular set of arguments) are the web methods.
A REST web microservice has the following signature:
void myMethod(JSONObject injson, JSONObject outjson, Connection db, ProcessServlet servlet) { ... }
This is a JSON
object that contains all of the arguments passed
in from the front-end.
This is a JSON
object which will contain all of the results
sent back to the front-end. Whatever is put in this object gets sent back to the front-end.
This is a database connection that can be used to access the SQL database. The connection is unique and independent of all other services.
This object provides access to various system facilities uniquely related to this call.
See JSON and the JavaDoc
for additional information.
Local microservices are simply regular classes. They typically reside
in the backend/services
directory organized anyway you like.
Although methods within a particular microservice/class can call each
other in the normal way, there is an extra step required for one
microservice to call method in a different microservice. One of the
reasons for this is so the system can be certain the latest version of
the service is loaded and that it is fully compiled before you attempt
to use it.
In Groovy, a method in one class/microservice can call a method in a different class/microservice via the following methods.
See the Javadoc.
The first two arguments to all REST methods is injson
and
outjson
. injson
is a JSONObject
that contains
the data passed in from the front-end. outjson
is a
pre-initialized, empty JSONObject
that will be returned
to the front-end. The rest service should read the data passed in
from injson
, perform any needed processes, and put the result
into outjson
to be returned to the front-end.
A modified version of a publicly available JSON Java package is included and used to access JSON from the front-end and create JSON to return to the front-end. This package has many methods but only a few are commonly used.
There are two main data type of interest. They are JSONObject
and
JSONArray
. They hold the JSON types indicated by their names.
Command useful for getting data out of injson
:
Again, outjson
is supplied as a pre-initialized, but empty,
JSONObject
. It is up to the REST service code to populate it
with the return data. Useful JSON utilities include the following:
Kiss includes an ever-growing set of utilities to help deal with common tasks.
These utilities are located under the src/main/core/org/kissweb
directory and have names such as
DateTime.java
, NumberFormat
, etc. These utilities
are documented in the JavaDocs.