The REST Server

Introduction

The DeltaJSON REST server is a Java ARchive (JAR) that runs as a service on a host machine. This multithreaded application provides a REST API and listens for HTTP requests from client applications on (by default) the 8080 port.

Setup

Java 8 or later should be installed on the machine hosting the REST server. 

The REST server JAR is included with the DeltaJSON distribution download. It is named using the pattern, deltajson-rest-x.y.z.jar, where x, y and z are respectively the major, minor and patch version numbers of the DeltaJSON release.

Supporting resource files are also included in the download. The REST server JAR file and supporting files should be copied to a directory on the host machine.

License File

The REST server license file named deltajson-rest.lic should be copied to the installation directory. This license file controls the HTTP port that the server listens on and also the maximum number of threads that can be exploited by the REST server.

License Server

If using a license server, or multiple license servers for redundancy, these can be specified using the license-servers command-line option. For example:

java -jar deltajson-rest-x.y.z.jar license-servers="10.1.10.1, 10.1.10.2, 10.1.10.3"

Starting and Stopping the Service

To start the REST service use the following command (adjust heap and stack sizes as needed or to suit the target system) from the install directory. If all is well some lines of debug and information messages will appear as indicated below.

Note: To use the following command-line samples, replace x.y.z with the major.minor.patch version number of your release e.g. deltajson-rest-1.0.0.jar

java -jar deltajson-rest-x.y.z.jar

Apr 12, 2019 8:51:02 AM org.glassfish.grizzly.http.server.NetworkListener start
INFO: Started listener bound to [0.0.0.0:8080]
Apr 12, 2019 8:51:02 AM org.glassfish.grizzly.http.server.HttpServer start
INFO: [HttpServer] Started.
DeltaJSON REST service started, navigate to: http://0.0.0.0:8080/api/json/v1/
Press Control-C to stop it...

When using JDK 9.0 or 10.0 an additional add-modules argument is required when starting the server:

java --add-modules java.xml.bind -jar deltajson-rest-x.y.z.jar

To stop the service use Control-C as indicated or an appropriate operating system command/tool such as 'kill'.

Logging

Logging for the REST server is controlled through slf4j, which allows a variety of methods such as java.util.logging and logback.

For example with java.util.logging, a logging.properties file that can be placed in the installation directory. Alternatively the Java property java.util.logging.config.file can be used when starting the service, i.e.:

java -Djava.util.logging.config.file=/path/to/logging.properties -jar deltajson-rest-x.y.z.jar

For example:

handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler
.level = OFF
com.deltaxml.json.rest.level = FINER
java.util.logging.FileHandler.level     = FINER
java.util.logging.FileHandler.pattern   = deltajson.log

java.util.logging.ConsoleHandler.level     = FINE

Using the FINER level will enable logging of every successful request in addition to errors, etc. Use a less granular level such as FINE if you do not want these to be logged.

For logback, you will need to add your configuration file onto the classpath. You may need to start the REST service differently, for example:

java -cp deltajson-rest-x.y.z.jar:/path/to/dir-containing-logback-xml com.deltaxml.json.rest.Main

File IO

The File IO type can be disabled, for example for security reasons, by using the Java property disableFileIO:

java -DdisableFileIO=true -jar deltajson-rest-x.y.z.jar