Cosmos WebServer

Cosmos WebServer (CWS) is an utility that allows you to use Cosmos as a web services provider, allowing you to create REST services.

Cosmos WebServer can be started in command line or as a Windows service.

Once started, the server handles the HTTP requests on the defined port (default 8081). A request can become invocation to a method of a configured Cosmos application.

This operation is detailed below.

This utility is available as of version 6.0 of Cosmos, except for the Log file: Cwslog.log, which has been incorporated since version 7.2.

Starting with Cosmos version 7.4, Cosmos WebServer also supports HTTPS connections.

Cosmos WebServer does not work with Cosmos SQL Desktop or Cosmos SQL Workgroup licenses.

The basic scheme of Cosmos WebServer (CWS) is shown in the following figure:

A Cosmos WebServer installation will consist of:

• Web server (coswebserver.exe + cosmoswebserver.jar).
• Cosmos runtime embedded in a DLL (cosjnidll.dll).
• The Cosmos application where you will define the modules that implement the REST services.

Cosmos WebServer uses the “JVM.dll” dll of the Java virtual machine. Therefore, to run CWS it is necessary to have a 32-bit Java virtual machine (version 1.8 or higher) installed on the same machine as Cosmos WebServer.

The Cosmoswebserver.exe application allows you to start the CWS server by command line or as Windows service.

Cosmos WebServer configuration file

The configuration file received as a parameter by the Cosmoswebserver.exe application will indicate, among other things, the port where the server will listen, the configuration file path of the Cosmos REST services, the parameters of the Java virtual machine (cosmosrestserver.jar file path, memory parameters) and, optionally, the server’s HTML resource path.

Environment variables

To configure an HTTPS connection it will be necessary to define the following variables:

REST’s server configuration file

This configuration file specifies, in XML format, the name of the Cosmos application, the name of the modules and the methods that will be in charge of implementing the REST services, as well as the path (URL) and HTTP verb (GET , POST, PUT, DELETE, etc.) that must be used to access each of these methods. Each REST service in Cosmos will correspond to a method defined in the «method» sections, which will be accessed through its path and that of the module («module») and the project («Project») to which they belong (path property of «Project», «Module» and «method»). Each corresponding Cosmos method with a REST service must return a string with the result of executing the REST service.

Configuration file sections

• The «project» section. In this section the following properties are defined:
  • Project identifier on the web server.
  • Path of the Cosmos project file into the server’s file system.
  • Path from which the project methods are accessed in the server URL.
• The «module» section. For each module of the Cosmos project that defines a REST service, a «module» section must be defined. The «module» sections should be defined as child sections of the «project» section, one for each module.
• The «method» section. For each of the REST server methods defined in a module, a section called «method» is defined as the child section of the corresponding «module» section. A «method» section must be defined for each module method that implements a web service.
  If the method receives parameters, it will indicate the name and, optionally, the default value of each parameter, as well as the way the parameter reaches the method. A parameter can be defined through the URL or through the BODY section of the HTTP request.
  Depending on the type of parameter that the method receives, the following sections must be defined within the «method» section:
  • «queryParameter» section
  • «urlParameter» section
  • «bodyParameter» section
  • «headerParameter» section

Creating a REST service in Cosmos

A REST service in Cosmos is defined as a function or method defined in a module of a project in Cosmos, which receives some parameters from the URL or from the body of an HTTP request, and returns a string with the result of its execution, and a status code indicating whether the execution has been successful, failed, etc.

This code must be a standard HTTP status code (200 – ok, 201 – created, 405 – method not allowed, etc.).

This status code will be set by the Cosmos method or function corresponding to the REST service by executing the SetExecStatus method of the Module class at the end of the function body.

Log4j file

The Cosmos WebServer server allows the generation of a log file in which information about the operations of Cosmos WebServer will be stored.

Cosmos WebServer uses the Log4j2 tool to generate the log file.

By default, CosmosWeb Server does not generate any log files. If you want the application to store log information, it should be indicated in the configuration file of Cosmos WebServer (see the section: Cosmos WebServer configuration file).

CosmosWebServer.log file

This file is created in the c:\tmp directory, and in it Cosmos WebServer will write the information generated in the installation, start-up, stop and removal of the Windows service or in the startup process of Cosmos Web-Server as an application.

Cwslog.log File

The output of the errors generated by the Cosmos WebServer runtime during the processes can be to a file if a file with the name CWSLog.log is created in the temporary directory.