JVM Settings for 3DOrchestrate Distribution Server Configured as a Windows Service

The 3DOrchestrate Distribution Server is normally installed and run in the default TomEE CATALINA mode. However, using this mode on Windows is often not appropriate because it is fundamentally a console mode application running inside an opened user session. If the user session is closed or the Windows computers is restarted for any reason, the TomEE application server and the 3DOrchestrate Distribution Server are halted and do not restart automatically.

Registering the 3DOrchestrate Distribution Server application as a Windows Service is a solution that lets the application run independently of any user session and restarts it automatically. See Configuring the 3DOrchestrate Distribution Server as a Windows Service for details.

Configuring TomEE and the 3DOrchestrate Distribution Server as a Windows Service is a completely separate mechanism from the CATALINA mode (described in JVM Settings for 3DOrchestrate Distribution Server Configured by TomEE CATALINA Scripts), and does not use any of the same CATALINA scripts or environment variables.

It is highly recommended that you use the 3DOrchestrate Distribution Server deployment utility to set up the 3DOrchestrate Distribution Server as a Windows Service because the deployment utility handles all the necessary configuration and starts the application immediately. If you prefer to run the deployment utility from the command line instead of using the GUI, the same Server Actions can be executed as follows:

cd <server_install_dir>
.\win_b64\reffiles\SMAExeServer\deploy\smaexe-deploy.bat -v .\config\deploy.param createtomeeservice
.\win_b64\reffiles\SMAExeServer\deploy\smaexe-deploy.bat -v .\config\deploy.param removetomeeservice

Warning: You must install the 3DOrchestrate Distribution Server on a local physical disk on the computer in order for the Windows Service to work properly.

Tip: Startup of the 3DOrchestrate Distribution Server Windows Service is almost instantaneous, but the 3DOrchestrate Distribution Server application within TomEE may take three to five minutes to fully initialize itself. During that initialization period, a 3DOrchestrate Station will wait before connecting (or reconnecting).

When you execute Create TomEE Service, the deployment utility produces and runs a createservice.bat script that is temporarily stored in .\bin under CATALINA_BASE, specifically:

<server_install_dir>\exe1\tomee\bin\createservice.bat

You can see the contents of this batch file in the Deploy Log tab of the deployment utility GUI; it will be similar to this:

@ECHO OFF
SETLOCAL
IF NOT "AMD64"=="%PROCESSOR_ARCHITECTURE%" ECHO "CPU and/or OS NOT SUPPORTED" && EXIT /B 1
REM ***
REM *** WARN *** UNSET ANY 'JAVA_HOME' VARIABLE THAT COULD INTERFERE WITH THIS TomEE's SCRIPT
IF DEFINED JAVA_HOME SET JAVA_HOME=
REM ***
SET JRE_HOME=<3DOrchserver_install_dir>\win_b64\code\jre
SET CATALINA_HOME=<3DOrchserver_install_dir>\win_b64\code\tomee172\bin
SET CATALINA_BASE=<3DOrchserver_install_dir>\exe1\tomee
SET SERVICE_NAME=TomEE_EED_Service
SET SERVICE_VERSION=2017x
REM ***
REM *** INFO *** 'NET.EXE' AND 'SC.EXE' CAN START/STOP A SERVICE USING THE SAME SYNTAX
REM *** INFO *** { NET | SC }.EXE { START | STOP } [ SERVICE NAME ]
REM *** INFO *** 'NET.EXE' SHOULD BE PREFERRED BECAUSE IT IS A BLOCKING/SYNCHRONOUS COMMAND
REM *** INFO *** TomEE COMMAND ALSO OFFERS SIMILAR CAPABILITY
REM ***
REM *** INFO *** THE COMMANDS BELOW ARE USED TO SYNCHRONOUSLY STOP THE SERVICE
REM NET.EXE STOP %SERVICE_NAME%_%SERVICE_VERSION%
"%CATALINA_HOME%/bin/TomEE.amd64.exe" //SS//%SERVICE_NAME%_%SERVICE_VERSION%
REM ***
CALL "%CATALINA_HOME%/bin/service.bat" REMOVE  %SERVICE_NAME%_%SERVICE_VERSION%
CALL "%CATALINA_HOME%/bin/service.bat" INSTALL %SERVICE_NAME%_%SERVICE_VERSION%
REM ***
REM *** INFO *** DOCUMENTATION FOR COMMANDS BELOW:
REM *** INFO *** https://commons.apache.org/proper/commons-daemon/procrun.html
REM ***
REM *** WARN *** BEGIN
REM *** WARN *** DO NOT REMOVE THE ^ AT THE END OF THE LINES BELOW
"%CATALINA_HOME%/bin/TomEE.amd64.exe" ^
//US//%SERVICE_NAME%_%SERVICE_VERSION% ^
--DisplayName "3DEXPERIENCE %SERVICE_VERSION% %SERVICE_NAME%" ^
--Description "3DEXPERIENCE %SERVICE_VERSION% %SERVICE_NAME% (Apache TomEE)" ^
--LibraryPath "<3DOrchserver_install_dir>\exe1\tomee\bin;<3DOrchserver_install_dir>/win_b64/code/bin" ^
--JvmMs 1024 ^
--JvmMx 4096 ^
--JvmSs 2048 ^
++JvmOptions "-Dfile.encoding=UTF-8" ^
++JvmOptions "-Dorg.apache.activemq.default.directory.prefix=<3DOrchserver_install_dir>\exe1\temp" ^
++JvmOptions "-Dfiper.system.configpath=<3DOrchserver_install_dir>\config" ^
++JvmOptions "-Dfiper.system.configfile=<3DOrchserver_install_dir>\config/SMAExeServer-exe1.properties" ^
++JvmOptions "-Dfiper.system.filemgr.rootFilePath=<3DOrchserver_install_dir>\exe1\filemgr" ^
++JvmOptions "-Dfiper.system.temp=<3DOrchserver_install_dir>\exe1\acstemp"
REM ***
REM *** WARN *** THE OPTION BELOW MUST BE SET SEPARATLY AS IT SEEMS THERE IS A BUG
REM *** WARN *** THAT WILL IGNORE ANY JVM OPTIONS SET AFTER THIS ONE
REM *** WARN *** ALSO PAY EXTRA ATTENTION TO THE SINGLE QUOTE SURROUNDING THE VALUE
"%CATALINA_HOME%/bin/TomEE.amd64.exe" ^
//US//%SERVICE_NAME%_%SERVICE_VERSION% ^
++JvmOptions "-Dfiper.system.installpath='<3DOrchserver_install_dir>'"
REM ***
REM *** INFO *** THE COMMAND BELOW CAN BE USED TO DISPLAY THE CONFIGURED SERVICE USING THE GUI
REM *** INFO *** "%CATALINA_HOME%/bin/TomEE.exe" //ES//%SERVICE_NAME%_%SERVICE_VERSION%
REM ***
REM *** INFO *** THE COMMAND BELOW CAN BE USED TO START THE SERVICE IN TEXT CONSOLE MODE
REM *** INFO *** "%CATALINA_HOME%/bin/TomEE.amd64.exe" //TS//%SERVICE_NAME%_%SERVICE_VERSION%
REM ***
REM *** INFO *** THE COMMANDS BELOW ARE USED TO SYNCHRONOUSLY START THE SERVICE
REM *** INFO *** EVEN IF THE SERVICE IS STARTED IN WINDOWS SERVICE CONSOLE
REM *** INFO *** THE EED APPLICATION WITHIN TomEE MAY TAKE UP TO 2-3 MINUTES TO COMPLETE INITIALIZATION
REM NET.EXE START %SERVICE_NAME%_%SERVICE_VERSION%
"%CATALINA_HOME%/bin/TomEE.amd64.exe" //ES//%SERVICE_NAME%_%SERVICE_VERSION%
EXIT /B %ERRORLEVEL%

Conversely, executing Remove TomEE Service stops the application if it is running and then unregisters it with the following transient batch script:

<server_install_dir>\exe1\tomee\bin\removeservice.bat

As opposed to the default CATALINA mode of the 3DOrchestrate Distribution Server, running the application as a Windows Services requires explicit settings for the minumum and maximum heap size (as highlighted in the createservice.bat script above). Consequently, the resulting performance settings are:

• Hardcoded minimum heap size of 1 GB of memory
• Hardcoded maximum heap size of 4 GB
• Hardcoded Parallel Stop The World (STW) garbage collection (GC) algorithm for both young (-XX:+UseParallelGC) and old (-XX:+UseOldParallelGC) generation objects

If this configuration is not appropriate for your target execution environment, you can change the default settings by using the TomEE service console utility as explained in the createservice.bat script:

...
REM *** INFO *** THE COMMAND BELOW CAN BE USED TO DISPLAY THE CONFIGURED SERVICE USING THE GUI
REM *** INFO *** "%CATALINA_HOME%/bin/TomEE.exe" //ES//%SERVICE_NAME%_%SERVICE_VERSION%
...

For example, entering the following command

cd <server_install_dir>
.\win_b64\code\tomee172\bin\TomEE.exe //ES//TomEE_EED_Service_2017x

displays the following properties panel:

This panel is similar to the default Windows Service properties panel, as it lets you start/stop the service and change the Startup type.

There are additional tabs, however, that give you access to settings for the TomEE application server (when the service is configured by the 3DOrchestrate deployment utility). For example, the Logging tab lets you change various TomEE log file settings.

The most important configuration settings are under the Java tab:

The full set of Java Options are editable here—these include many settings specific to TomEE and the 3DOrchestrate Distribution Server application. These settings are:

-javaagent:<3DOrchserver_install_dir>\win_b64\code\tomee172\lib\openejb-javaagent.jar
-Dcatalina.base=<3DOrchserver_install_dir>\exe1\tomee
-Dcatalina.home=<3DOrchserver_install_dir>\win_b64\code\tomee172
-Djava.endorsed.dirs=<3DOrchserver_install_dir>\win_b64\code\tomee172\endorsed
-Djava.io.tmpdir=<3DOrchserver_install_dir>\exe1\tomee\temp
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
-Djava.util.logging.config.file=<3DOrchserver_install_dir>\exe1\tomee\conf\logging.properties
-Djava.awt.headless=true
-XX:+UseParallelGC
-XX:MaxPermSize=256M
-Dfile.encoding=UTF-8
-Dorg.apache.activemq.default.directory.prefix=<3DOrchserver_install_dir>\exe1\temp
-Dfiper.system.configpath=<3DOrchserver_install_dir>\config
-Dfiper.system.configfile=<3DOrchserver_install_dir>\config/SMAExeServer-exe1.properties
-Dfiper.system.filemgr.rootFilePath=<3DOrchserver_install_dir>\exe1\filemgr
-Dfiper.system.temp=<3DOrchserver_install_dir>\exe1\acstemp
-Dfiper.system.installpath=<3DOrchserver_install_dir>

In this list, the explicit setting -XX:+UseParallelGC forces the STW garbage collector which is the same choice as that made by the default Java ergonomics. You can change the garbage collection algorithm by changing this line to -XX:+UseG1GC, for example.

The Java heap size options are displayed in separate fields near the bottom of the panel:

Initial memory pool	1024 MB
Maximum memory pool	4096 MB

Note that these values are in megabytes (MB), not gigabytes (GB), and

1024 MB = 1 GB

4096 MB = 4 GB

To change the Maximum memory pool to 6 GB, enter 6 x 1024 = 6144 MB.