Cosmos WebServer does not work with Cosmos SQL Desktop or Cosmos SQL Workgroup licenses.
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.
The basic scheme of Cosmos WebServer (CWS) is shown in the following figure:
A Cosmos WebServer installation will consist of:
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.
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.
This variable indicates the path of the configuration file of the REST services of the server (the configuration of this file is explained in the section "REST’s server configuration file").
Indicates the server port where CWS will listen for HTTP requests.
This environment variable indicates the directory path where CWS will store resources that will be accessible via the server URL. These resources may be HTML pages, image files, etc.
It will be necessary to define this variable so that the execution of Cosmos WebServer is multi-threaded, that is, that allows processing more than one REST request at the same time without having to wait for one to finish to process the next one.
To configure an HTTPS connection it will be necessary to define the following variables:
This variable sets the server port where CWS will listen to HTTPS requests.
This variable defines the absolute path of the certificate store file.
This variable indicates the certificate store password.
This variable indicates the alias of the certificate that you want to use. If this variable is not defined, it will use the first certificate of the store.
This variable indicates the alias password defined in SSL_KEYSTORE_ALIAS. If not specified, it will use the password entered in SSL_KEYSTORE_PWD.
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.
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:
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.
The Cosmos WebServer utility can be started from the command line or as a Windows service.
To start it from the command line we will have to use the following syntax:
Cosmoswebserver.exe –ini c:\cosmos\etc\stockserver.ini
The problem of starting Cosmos WebServer from the command line is that, when the server where it is installed is restarted, it is necessary to manually restart Cosmos WebServer.
This problem is solved by installing Cosmos WebServer as a Windows service.
To install Cosmos WebServer as a service it will be necessary to run Cosmos WebServer with the parameter "-install <service_name>".
Cosmoswebserver.exe –install ServiceWeb –user .\user –passwd passwd
The parameter "service_name" will indicate a non-existent Windows service name, which will be the one that will identify the Cosmos WebServer service.
The parameters "-user" and "-passwd" indicate respectively the user who starts the service and its password. These parameters are optional. If not indicated, the service will boot with a local system account.
The service will be installed by default as "AUTOMATIC", ie when the server is restarted the service will start automatically.
To start the Cosmos WebServer service installed with "-install" you must run CosmoswebServer with the parameter "-start <service_name>".
Cosmoswebserver.exe –start ServicieWeb
As we saw in section Cosmos WebServer configuration file, CosmosWebServer needs the name of a config file. This name will be obtained by CosmosWebServer from the cosmoswebserver.ini file, which should be located in "COSMOSDIR\etc". For each service that we want to install, we must define a section with the name of the service and a variable, called INIFILE, with the absolute path of the configuration file for that service.
To stop the Cosmos WebServer service installed with "-install" you must run CosmosWebServer with the parameter "-stop <service_name>".
Cosmoswebserver.exe –stop ServiceWeb
From that moment the service will be installed, but not available to accept new connections, until it is not rebooted with "-start".
To uninstall the CosmosWebServer service installed with "-install", you must run CosmosWebServer with the parameter "-remove <service_name>".
Cosmoswebserver.exe –remove ServiceWeb
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).
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.
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.
Cosmos WebServer as service
If an error occurs during the execution of a Cosmos service and the ErrorLevel is greater than 0, information about the error will be stored in the log file, as well as the method and module where the error occurred, and the call stack from the application.
If an error occurs during execution and the ErrorLevel equals 0, the error information will not be written to the log file.
If the Trace method is executed in the source code of the Cosmos service, the text associated with the Trace method will be written to the log file.
Cosmos WebServer as application
If an error occurs during the execution of a Cosmos service and the ErrorLevel is greater than 0, information about the error will be stored in the log file, as well as the method and module where the error occurred, and the call stack of the application. This same information will be displayed on the screen through a MessageBox.