Gilhari Microservice Framework
for JSON Persistence

Gilhari Microservice Framework

Gilhari Usage Tips

Syntax and semantics of the RESTful APIs provided by the Gilhari microservice framework:

The file Gilhari_APIs.pdf (located in the docs directory of the Gilhari SDK) provides details on the syntax and semantics of various APIs exposed by the Gilhari RESTful JSON Persistence Service microservice framework. It also has some sample APIs for an app-specific Gilhari microservice that deals with Employee objects.

Please note that, in response to a POST request, only the mapped attributes specified for a class in the ORM specification are saved in the database. So, if an original JSON object in the body of a POST request has more attributes, they will be ignored - the object will essentially be trimmed when saved.

You may also find the Gilhari API details in the POSTMAN documentation by importing the "Gilhari REST API" collection in POSTMAN from the following link (File -> Import -> Import from Link): https://www.postman.com/dperiwalst/workspace/gilhari-workspace/collection/36957822-96723d13-25ea-4e3c-8150-407034561a45?action=share&creator=36957822

Database and JDBC Driver considerations:

Gilhari microservice framework integrates with a database using a JDBC driver. For an app-specific Gilhari microservice running in a container, the JDBC driver will reside in the container image and the database will typically be running outside the container.

For quick prototyping purposes, you may also use a SQLite database that can reside and run in the file system of the container. A SQLite JDBC driver is already packaged in the Docker image of the Gilhari framework and has been added as a default JDBC driver in the classpath. Please note that the SQLite database and its JDBC driver are not appropriate for serious work or testing as the error handling and multi-threading support in them are not very robust.

Database Specification:

The database URL is specified using the JDX_DATABASE tag in the ORM specification (.jdx) file. Please make sure that you are using the correct URI for your target database. Sometimes, the "localhost" specification would not work from inside a container as the database is running outside the container “host”; you have to specify the IP address of the system where your database is running. If any firewall or remote connection issues are indicated in an error message, please configure your systems to take care of that.

Also, please make sure that the correct JDBC driver name corresponding to your database has been specified in the JDBC_DRIVER tag in the ORM specification (.jdx) file.

The JDX_DATABASE tag in the ORM specification (.jdx) file also contains the login credentials (name/password) for the database. You should change them as per your setup in the ORM specification file itself or you may override those credentials in the Gilhari microservice configuration (e.g. gilhari_service.config) file. See Note 5 above.

Please make sure that the appropriate JDX_DBTYPE is specified in the JDX_DATABASE tag. For example, JDX_DBTYPE=MYSQL or JDX_DBTYPE=POSTGRES, etc.

JDBC Driver:

The Gilhari framework ships with the following three commonly used JDBC drivers in the directory /node/node_modules/jdxnode/external_libs:

    mysql-connector-java-5.1.39-bin.jar (for MySQL)
    postgresql-42.2.2.jre6.jar (for Postgres)
    sqlite-jdbc-3.8.11.2.jar (for SQLite)

So, if any of these pre-packaged JDBC drivers is suitable for your target database, you may specify the appropriate JDBC driver in the configuration file (e.g., gilhari_service.config) for your app-specific Gilhari microservice.

For example, if you want to use the MySQL JDBC driver, you may specify:

"jdbc_driver_path": "/node/node_modules/jdxnode/external_libs/mysql-connector-java-5.1.39-bin.jar",

However, if you want to use a different JDBC driver, you should package the corresponding .jar file in your app-specific Gilhari image (e.g., in the config directory of your app) and then specify that location for the JDBC driver in the configuration file (e.g., gilhari_service.config). For example,

 "jdbc_driver_path": "config/myDatabaseJDBCDriver.jar",

Database Connection Errors:

If you encounter database connection errors even after making the suggested changes for the Database Specification and JDBC Driver described above, the following might help:

  • IMPORTANT: Don't forget to update the Docker image of your app by rebuilding the image after making the suggested changes. Then deploy and run the new image.
  • Start (or restart) the database server (service) if it is not running.
  • Before running the updated image of your app-specific Gilhari microservice, remove the old containers with the earlier images as they may be blocking some communication ports.
  • Sometimes, running Gilhari with jdx_debug_level of 3 can be very helpful in diagnosing many problems as that would emit all the SQL statements generated and used by Gilhari. See Note 5.
  • Any error messages emitted by the Gilhari microservice may point to a specific area to investigate further.

Using Legacy Data in an Existing Database:

You may use Gilhari with existing data in a legacy relational database where the schema (tables) is already created and the tables might contain useful data.

Normally, when JDX, the underlying ORM for Gilhari, does not find a JDXMetadata table during the first connection to the database, it assumes that it needs to create the schema (tables) for the mapped classes in the mapping specification and, as part of that process, it drops the old tables, if any, and creates them fresh again. This behavior may be reasonable if JDX is being used for a brand new database schema or when the existing data is not important enough to be retained.

However, if the legacy tables and data should be retained and be used by Gilhari through JDX, you should just pre-create (only once) the JDXMetadata table in the database using the following SQL command:

CREATE TABLE IF NOT EXISTS JDXMetadata (jdxORMId TEXT, jdxTimestamp TEXT, jdxMetaVersionId TEXT, jdxMetaFileName TEXT, jdxMetaInfo TEXT)

The existence of the JDXMetadata table in the database will prevent JDX from creating a new schema for the mapped classes. However, beware that if you use a “true” value for the jdx_force_create_schema property ("jdx_force_create_schema": "true") in the Gilahri microservice configuration file (e.g., gilhari_service.config), any existing tables for the mapped classes will be dropped and recreated.