The REST Server

Introduction

The DITA Merge 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 DITA Merge distribution download. It is named using the pattern, deltaxml-dita-merge-rest-x.y.z.jar, where x, y and z are respectively the major, minor and patch version numbers of the DITA Merge 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 deltaxml-dita-merge-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.

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. deltaxml-dita-merge-rest-3.0.0.jar

java -jar deltaxml-dita-merge-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.
DITA Merge REST service started, navigate to: http://0.0.0.0:8080/api/ditamerge/v1/types
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 deltaxml-dita-merge-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 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 deltaxml-dita-merge-rest-x.y.z.jar