RadixWare Administrator Guide/RadixWare Starter
- 1 Revision History
- 2 Conventions and Abbreviations
- 3 Introduction
- 4 Overview
- 5 Running Applications
- 6 Secure Connection with SVN Server
- 7 Replacement of Application Components
- 8 Deploying Using Java Web Start
|Date||RadixWare Version||Description of Changes|
|19.03.2019||2.1.21.х||Due to update of system core components, eliminated the facility to start applications running on Java JDK 1.7.x.
Updated section Using Configuration File
|17.09.2018||2.1.19.x||Added the following RadixWare Starter startup parameters:
Updated section Running Applications
|26.07.2018||2.1.18.x||Implemented the mechanism used to load the replacement files from zip archives.
|Supported the facility to automatically update the local starter.jar file when starting the RadixWare Desktop Explorer application.
Updated section Updating Local starter.jar
|Supported the facility to specify the file containing several certificates (to authorize the server when using the HTTPS protocol) in the –svnServerCertFile parameter of the RadixWare Starter.
Updated section Running Applications
|Added RadixWare Starter startup parameter -localSvnBackupDir.
Updated section Running Applications
|Added RadixWare Starter startup parameter –preloadThreads.
Updated section Running Applications
|17.01.2017||2.1.9.x||Added RadixWare Starter startup parameter tmpDir.
Updated section Running Applications
Conventions and Abbreviations
JVM - Java Virtual Machine
OS – Operating System
SVN - Subversion
This document describes the RadixWare Starter application and its startup procedure.
|1||RadixWare Explorer. User Guide||The document describes the RadixWare Desktop Explorer and RadixWare Web Explorer application facilities and methods of executing various operations.|
|2||RadixWare Server. Administrator Guide||The document describes the RadixWare Server application and its startup procedure.|
|3||RadixWare Web Presentation Server. Administrator Guide||The document describes the RadixWare Web Presentation Server application and its startup procedure.|
RadixWare Starter is a tool used to start up the applications based on the RadixWare technological platform. RadixWare Starter is delivered as part of the platform in the org.radixware/kernel/starter/bin/dist/starter.jar file. This file can be delivered to the workstations and servers either by means of Java WEB Start or by manual copying.
It is possible to start the application in one of the following modes: normal or test.
To receive the latest application version when working in the normal mode, RadixWare Starter accesses the SVN repository. When started, the local RadixWare Starter downloads its latest version (the updated starter.jar file) from the repository and serves as a container for the updated file within the current process. In most instances, this mechanism allows using updated starter.jar with no need of overwriting the local file. Rarely, the latest version of starter.jar can contain the changes that do not allow running the updated file in the container of the outdated one. In this instance, before starting the application it is necessary to download starter.jar from the repository using any of the available methods, and replace the local file with it. For details, refer to Updating Local starter.jar.
To reduce the SVN server load and the response time, the local cache is used. It contains the copy of the current application version. To control the local cache integrity, when loading a file from cache the file hash is checked for compliance with the digest field value in the directory.xml file. In case of non-conformity, the file is re-loaded from the SVN repository. To disable the integrity control mechanism, the disableDigestCheck parameter is used.
The SVN repository being used can be a replica.
When working in a test mode, the work directory is used. It contains the application work copy. In case the kernel (the Kernel segment) version is outdated, RadixWare Starter restarts the application that is already running.
To run the application, execute the following command from the directory containing the starter.jar file:
java [ JVM parameters] -jar starter.jar [startup parameters]
The JVM parameters can define the allowed memory size for the application, or the used virtual machine, or other JVM settings. For details on the JVM startup parameters, refer to the JVM documentation. The startup parameters define the application to start and the startup mode for it. The table below provides the used startup parameters:
|-configFile FILE||Configuration file containing the parameters of RadixWare Starter startup and of the application being started (for details, refer to Using Configuration File).|
|-svnHomeUrl=URL||Address of the application SVN repository and the branch in it. If this parameter is set, the application will be started in the normal mode.
|-additionalSvnUrls=URL1, URL2...||The list of addresses (separated by comma) of the SVN repositories from which to download the latest versions of the applications. When started, RadixWare Starter addresses the first available repository in the list if the repository specified in the -svnHomeUrl parameter is not available. In case of the repository denial, the application will address the next one. The specified repositories must have similar structures.
|-workDir=DIRECTORY||Work directory containing the work copy of the application repository. The specified directory must contain the branch.xml file. If this parameter is set, the application will be started in the test mode.
|-topLayerUri=URI||URI of the product top layer. It can be a platform layer, customer modifications layer or customer programming layer. This parameter is mandatory.
|Before starting the application, download all the files related to RadixWare Server, RadixWare Explorer or RadixWare Web Presentation Server respectively, from the SVN repository to the local cache.|
|-authPassword=PASSWORD||Authentication parameters for the access to the SVN repository.
Example: -authUser=CLERK -authPassword=123
|-authPasswordInteractive||Requests the password to access the SVN repository online.|
|-krbKdc=ADDRESS||Kerberos controller address.
|-krbParams=PARAMS||Kerberos authentication parameters.
|-sshKeyFile=FILE||Path to the SSH private key used for authentication on the SVN server.
|-sshKeyPassword=PASSWORD||Password for the SSH private key.
|-sshKeyPasswordInteractive||Requests the password for the SSH private key online.|
|-svnServerCertFile=FILE||Path to the certificate file used to authorize server when using the HTTPS protocol.
The specified file can contain several certificates (certificate storage). In this case, the first suitable file is used for authorization.
|-localFileCacheDir=PATH||Directory where the local file cache must be stored when starting the application from SVN.
|-dedicatedCacheDir||Directory containing the local cache of files from the SVN repository (specified in –localFileCacheDir parameter) will be used in the dedicated mode. In this mode, the cache files will be located in the specified directory, the subdirectories of 0, 1, 2.., type that are usually created when several parallel processes are started, will not be created. Thus, the directory for cache can be used by one process only (for example, only one started RadixWare Server instance, or only one RadixWare Explorer instance).|
|-prepareCacheOnly||Only the local cache from the SVN repository will be loaded at startup, at that, the application will not be started. If this parameter is used, it is not necessary to specify the name of class used for application startup.
If one or several of -downloadServer/-downloadExplorer/-downloadWeb parameters are specified together with this parameter, the respective file groups will be loaded to the local cache. If these parameters are absent, all files will be loaded to cache from svn.
|-localReplacementDir=PATH||Directory with zip archives containing replacement files.|
|–localFileList=FILE||Path to the file containing a list of overridings.|
|–udsBuildPath||The list of jar-files where to search for classes when compiling the user-defined functions.
If the parameter is not defined in RadixWare Explorer, the value from the RadixWare Server settings is used.
Example: -udsBuildPath <jar1>:<jar2>:<jar3> -udsBuildPath org.radixware/kernel/server/lib/ojdbc6.jar
|-showSplashScreen[=TEXT]||Displays the startup screen. If a text is defined in the parameter (for example, -showSplashScreen=Server), this text will be displayed on the startup screen. Otherwise, the name of the main application class will be displayed on this screen.|
|-disableDigestCheck||Disables the local cache files integrity control.|
|-disableSwingPreload||Disables the Swing graphics library initialization.|
|export||Exports a file from the SVN repository and saves it to the specified directory. Particularly, this parameter can be used to export the latest version of the starter.jar file from the SVN repository (for details, refer to Updating Local starter.jar).
Example: java -jar starter.jar <svn connection settings> export <path to file on svn> [where-to-save-file], where:
|-tmpDir=PATH||Path to the directory with temporary starter files.|
|-localSvnBackupDir=PATH||Path to the directory with the local copy of files loaded from the SVN repository the application works with. In order to use the local copy of files instead of addressing the SVN repository directly, it is required to preliminary load the files to the <backupdir>/<R> directory, where:
If the -localSvnBackupDir parameter is specified in the application startup file, before loading a file (<file>) of the respective revision (<R>) from the SVN repository to the local cache, the system checks whether the required file (<file>) exists in the local directory (<backupdir>/<R>). If the file exists, it will be loaded to the local cache not from the SVN repository but from the local directory (<backupdir>). This parameter can be used if it is not convenient to load files directly from the repository (for example, the connection is unstable).
|–preloadThreads=N||Number of threads of parallel loading of files from the SVN repository to the local cache. It is recommended to use this parameter together with the following ones: –downloadServer (when starting RadixWare Server), –downloadExplorer (when starting RadixWare Explorer) or –downloadWeb (when starting RadixWare Web Presentation Server).
|Class||Main class of the application being started. This parameter is mandatory.
|Application parameters||Parameters used by the application being started. They must be specified after the Class parameter.|
The application being started is defined by the specified main application class (the Class parameter). The table below provides available values of this parameter:
|Application||Main Application Class|
|RadixWare KeyStore Admin||org.radixware.kernel.utils.keyStoreAdmin.KeyStoreAdmin|
|RadixWare Web Presentation Server||org.radixware.wps.WebServer|
The -svnHomeUrl and -workDir parameters are mutually exclusive. One of these parameters must be defined.
It is possible to perform authentication on the SVN server by one of the following methods:
- login and password (not recommended).
- public / private SSH key pair.
- Kerberos protocol.
If the SVN server connection is absent, the applications can be started if the local cache contains the files of the application current version.
Using Configuration File
The parameters of RadixWare Starter startup and of the application being started can be set in the configuration file specified in the RadixWare Starter startup parameter - configFile.
The configuration file is a text file containing several sections. Each section starts with the section name enclosed in brackets. The section contains a set of parameters with the names identical to the RadixWare Starter startup parameters or to the parameters of the application being started, except for the "-" start symbol. Each parameter is written as a separate string. The configuration file strings started with the "#" symbol are considered as comments and ignored. Empty strings are ignored too.
The configuration file can contain the following sections:
- [Starter]. The section contains the RadixWare Starter startup parameters.
- [Server]. The section contains the RadixWare Server startup parameters.
- [WebPresentationServer]. The section contains the RadixWare Web Presentation Server startup parameters.
- [App]. The section contains additional startup parameters used by the application on the RadixWare platform.
The application startup parameters must be defined either in the configuration file or in the command line. The system does not support the use of both methods to define the startup parameters for one and the same application. However, it is possible to specify the RadixWare Starter startup parameters in the command line, and define the RadixWare Server startup parameters in the configuration file (for details, refer to RadixWare Server. Administrator Guide).
Example of the RadixWare Starter configuration file content:
[Starter] workDir = . topLayerUri = org.radixware appClass = org.radixware.kernel.server.Server appArgs = <RadixWare Server startup parameters>
Example of the command used to start RadixWare Starter by means of the config.ini configuration file:
If RadixWare Starter is started by means of the configuration file, only one startup parameter must be used: configFile FILE. The main class of the application being started must be defined in the appClass parameter, in the [Starter] section of the configuration file. The parameters of the application being started can be defined in the appArgs parameter, in the [Starter] section of the configuration file or in the parameters of the section used by the application.
Updating Local starter.jar
In most instances, when operating in normal mode the local RadixWare Starter downloads its latest version from the repository when started, and serves as a container for it. Rarely, the latest version of starter.jar can contain the changes that do not allow running the updated starter in the container of the outdated one. In this instance, when running the application the following message is displayed: "Local starter version <local_starter_version> doesn't correspond to repository starter version <repository_starter_version>". As a result, the application may be unstable or fail to start. If this error occurs (or to prevent such errors), it is recommended to download the starter.jar file from the repository before running the application, and replace the local file with it. Perform these actions using one of the following methods:
- Using the export command:
1. Export the latest version of starter.jar from the SVN repository using the export command. The command needs to be executed from the directory of local starter.jar.
|Example of the export command:|
2. Replace the local starter.jar file with the exported one.
3. Run the application in normal mode.
- Using the standard commands of the SVN client. Add the export command to the command file of the application. This command is used to export files from the SVN repository (for details on the command parameters, refer to the documentation for the respective SVN client):
Example of the RadixWare Explorer command file containing the export command (for Windows OS):
@echo off set "JVM_OPTIONS=-Xmx1500m" set "STARTER=-jar ./starter.jar" set "STARTER_OPTIONS=-configFile explorer.cfg" @REM receiving starter.jar from SVN echo " Export Head revision for starter.jar" svn export -r head --force --username pass --password pass http://10.7.2.231/prod/org.radixware/kernel/starter/bin/dist/starter.jar./starter.jar @REM running Explorer echo " Run Explorer..." javaw %JVM_OPTIONS% %STARTER% %STARTER_OPTIONS%
The disadvantage of this method is that it is necessary to install SVN clients on the workstations where the application is run.
- The procedure for updating the local starter. jar file can be embedded in the application command file. In this instance, the procedure will be automatically executed each time the application is run. This method is more preferable as it does not require any manual actions and prevents the starter versions incompatibility error.
Example of the RadixWare Explorer startup command containing the embedded auto update procedure (for Windows OS):
@echo off set "JVM_OPTIONS=-Xmx1000m -XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC -XX:+UseOSErrorReporting" set "STARTER_JAR=./starter.jar" set "STARTER=-jar %STARTER_JAR%" set "STARTER_OPTIONS=-configFile explorer.cfg" set "AUTO_REFRESH_STARTER=1" #0 to disable, 1 to enable set "NEW_STARTER_JAR=exported_starter.jar" @REM receiving starter.jar from SVN echo " Export Head revision for starter.jar" if %AUTO_REFRESH_STARTER% EQU 1 ( echo "Re-exporting starter.jar..." java %JVM_OPTIONS% %STARTER% %STARTER_OPTIONS% export org.radixware/kernel/starter/bin/dist/starter.jar %NEW_STARTER_JAR% echo error level is %ERRORLEVEL% if %ERRORLEVEL%==0 ( echo "Downloaded %NEW_STARTER_JAR%, replacing current starter.jar with it" move /y %NEW_STARTER_JAR% %STARTER_JAR% if %ERRORLEVEL%==0 ( echo "Replacement done" ) else ( echo "Replacement failed, 'move' command exited with status %errorlevel%") ) else ( echo "Unable to re-export starter.jar" ) ) @REM running Explorer echo " Run Explorer..." java %JVM_OPTIONS% %STARTER% %STARTER_OPTIONS%
After the script is executed successfully, the RadixWare Explorer application will be started:
Secure Connection with SVN Server
To provide secure connection with the SVN server, use encrypted connection. RadixWare Starter supports the svn+ssh:// and HTTPS secure protocols. To use the svn+ssh:// protocol, perform the following actions:
- Set up the SVN server to use encryption.
- For Windows OS, set up additional software on the computer where RadixWare Starter is started (for details, refer to SVN+SSH Protocol Support for Windows OS).
- When starting RadixWare Starter, specify the -sshKeyFile and -sshKeyPasswordInteractive startup parameters, as well as the SVN repository URL, for example svn+ssh://svn.server.local/radix.
To use the HTTPS protocol, perform the following actions:
- Set up the SVN repository access by the HTTPS protocol, for example, Apache HTTP Server. For details on the setup, refer to the Apache HTTP Server documentation.
- When starting RadixWare Starter, specify the path to the certificate used for the SVN server authorization (the -svnServerCertFile startup parameter), as well as the SVN repository URL, for example https://svn.server.local/radix.
When connecting to the SVN server by the HTTPS protocol, RadixWare Starter checks whether the certificate specified in the -svnServerCertFile startup parameter is present in the chain of server certificates.
SVN+SSH Protocol Support for Windows OS
To provide the svn+ssh:// protocol support by the RadixWare Starter application for Windows OS, perform the following actions:
- Install the SSH client (for example, Putty) on the computer where RadixWare Starter is started.
- Using the installed client, generate a pair of public and private keys in the OpenSSH format.
- Deliver the generated public key to the SSH server.
- Specify the path to the generated private key in the -sshKeyFile parameter that will be used at the RadixWare Starter startup.
Replacement of Application Components
When running RadixWare Starter in the mode of connecting to SVN server, it is possible to use the files from the local file system instead of binary files received from SVN server. This facility is used to replace the application components with own or debug versions.
The application components can be replaced as follows:
1. The replacement files are structured and added to the zip archive. This archive is created by developers in RadixWare Designer (by executing the Create local replacement zip command). At creation, it is possible to specify the software product versions the replacement will be applied to.
This method is of higher priority, as versions of replacement files prevent from using the outdated replacement after the software product update, and the structure of archive with replacement files is identical to the structure in the SVN repository that simplifies the procedure of applying the replacement files.
2. The replacement files are located in the local directory. For each file, it is necessary to specify the relative path to the file being replaced in the SVN repository.
Applying Archive with Replacement Files
The zip archive contains:
- Directory with the files to be replaced after applying the replacement file. It corresponds to the structure of software product directories in the SVN repository.
- The replacement.cfg file (optional) that can contain the following parameters:
- compatibleVersions - range of versions the archive with files is applicable to;
- creationDate - file creation date and time in the YYYY-MM-dd-hh:mm format (UTC);
- comment - notes (for example, the archive purpose).
|If the replacement.cfg file is absent in the archive, or this file does not contain the compatibleVersions parameter, the replacement is considered to be applicable to any version of the software product.|
To apply the replacement files, perform the following settings:
1. Create a replacement directory (for example, C:\Replacements) that will contain the archives with the replacement files.
2. Specify the path to the created replacement directory in the localReplacementDir parameter of the starter (RadixWare Starter application). If the configuration file is used to start the application (RadixWare Server / RadixWare Explorer), add the parameter to the [Starter] section: For example,
[Starter] ... localReplacementDir=C:\Replacements [Server] ...
3. Once the zip archive with replacement files is received from the Product Support Service, add it to the directory created at step 1. To apply the replacement, restart the application (RadixWare Server / RadixWare Explorer).
After that, each time the RadixWare Server / RadixWare Explorer application is started and switched to a new version, the system checks whether the specified directory has the archives with the replacement files applicable to the current version of the software product. If these files are found, they are used instead of the application files from the SVN repository. At that, if there are replacement files from different archives for the same files from the SVN repository, the system applies the files with the earliest creationDate from the replacement.cfg file. If this file is absent in the archive, the time of the last modification of the archive file in OS is considered as creationDate.
Applying Local Replacement Files
When overriding the file, the following information is required:
- the relative path to the file to be replaced in the SVN repository (remote-file) to be replaced, e.g. org.radixware/kernel/server/bin/server.jar;
- the path to the file (local-file) to replace with, e.g. C:\server.jar.
It is also necessary to create a text file (in any place and with any name, e.g. C:\localFiles.txt) and describe overriding rules in it. One overriding rule consists of two lines:
Specify the path to the created file with a list of overridings in the starter parameter localFileList. If you use the configuration file, add this parameter to the [Starter] section, for example:
[Starter] ... localFileList=C:\localFiles.txt [Server] ...
Deploying Using Java Web Start
The following resources could be helpful while setting up deployment of RadixWare applications via Java Web Start:
Usually, to launch applications via RadixWare Starter, e.g., to launch RadixWare Explorer, a starter.jar file should be placed in every user machine, along with OS script to start Java Machine and, optionally, configuration parameters file. To simplify distribution and automate updates of starter.jar and parameters used for launching applications, Java Web Start technology can be used.
- A signed starter.jar file
- Web server to host starter.jar file and .jnlp file.
NOTE: You can sign starter.jar file exported with RadixWare Manager by yourself, given that you have some keystore with private key and JRE installation. Signing could be done by the following command:
jarsigner -keystore <keystore_file,_e.g._keystore.jks> -storetype <keystore_type,_e.g._JCEKS> starter.jar <alias_of_the_key_in_keystore,_e.g._mycompanykeyalias>
Steps to enable deployment of the starter.jar via Java Web Start:
1. Create JNLP file. The following could be used as an example to launch RadixWare Explorer:
<?xml version="1.0" encoding="utf-8"?> <!-- JNLP File for RadixWare Starter --> <jnlp spec="1.0+" href="explorer.jnlp"> <information> <title>RadixWare Explorer</title> <vendor>Compass Plus</vendor> <offline-allowed/> </information> <security> <all-permissions/> </security> <resources> <j2se version="1.6+" max-heap-size="1536M"/> <jar href="http://<deployment_url>/starter.jar"/> </resources> <application-desc main-class="org.radixware.kernel.starter.Starter"> <argument>-svnHomeUrl=<svn url with deployed radixware application></argument> <argument>-topLayerUri=<top layer uri, e.g. org.radixware></argument> <argument>-authUser=<svn user></argument> <argument>-showSplashScreen=Explorer</argument> <argument>org.radixware.kernel.explorer.Explorer</argument> </application-desc> </jnlp>
Exact arguments list under 'application-desc' tag may vary depending on svn authentication scheme, etc.
2. Deploy .jnlp file (for example, explorer.jnlp) and starter.jar at some url (lets call it deployment_url). Make sure that correct url for deployed starter.jar is written at this line in above jnlp file:
There should be a link to jnlp file at the html page (see p.6 from https://docs.oracle.com/javase/tutorial/deployment/webstart/deploying.html)
3. Configure appropriate security settings on each machine where application is supposed to be launched:
- launch 'jcontrol' utility (it is included in both JRE and JDK)
- open 'Security' tab
- click 'Manage Certificates' button, choose 'Signer CA' certificates section and import certificate of the key used to sign starter.jar
Security problems, if any, could be temporarily solved by adding deployment_url to exception site list (https://www.java.com/en/download/faq/exception_sitelist.xml)
4. Additional configuration of the web server may be required: https://docs.oracle.com/javase/tutorial/deployment/webstart/settingUpWebServerMimeType.html
5. Open html page with link to jnlp file from user machine and click on the link. Either application will be launched, or jnlp file will be downloaded to user machine. Downloaded file may be launched by double-clicking on it (if file associations were set up correctly), or directly using 'javaws' utility from JRE (ex.: javaws explorer.jnlp)