The Wrapper will attempt to obtain a read/write lock on the file when the command file is opened. Once it is opened, all commands will be executed in order and then the file will be deleted at the completion of the commands.

External processes which create command files should always open the command file in "append" mode. This way if the file does not exist it will be created newly, but if it already exists then any new commands will be appended.

The Wrapper will try several times for up to a second to open the command file once it has been determined that it exists. This is done to avoid problems while another process is in the process of writing the file. If the file remains locked for longer than a second, a warning message will appear in the log file. This will not affect the operation of the Wrapper, but to avoid the warnings, it is important that the file be locked as briefly as possible.

The file is formatted as a text file with a single command on each line. Possible commands include:

• STOP [EXIT_CODE] - Requests that the Wrapper shut down cleanly. The optional EXIT_CODE can be used to specify the exitCode when the Wrapper actually shuts down.

• RESTART - Requests that the Wrapper restart its JVM. This can be used in combination with the wrapper.restart.reload_configuration property to cause the Wrapper to reload its configuration and then launch a new JVM reflecting the changes.

• PAUSE - Requests that the Wrapper be paused. Only supported when run as a Windows Service and the wrapper.pausable property is TRUE.

• PAUSE_LOGGER {seconds} (Since ver. 3.5.11) - Causes the Wrapper to pause the next line of log output for a number of seconds. This is useful for testing the Wrapper and JVM's ability to handle delays in logging code. seconds can be in the range of 1 to 3600, or 0 for indefinite. This command is disabled unless wrapper.commandfile.enable_tests is TRUE.

• PAUSE_THREAD {THREAD} [{TIME}] (Since ver. 3.5.8) - Causes the specified Wrapper thread to be paused for a fixed amount of time. This is useful for testing how the Wrapper behaves under high load situations which might cause one or more of the Wrapper's threads to be starved of CPU. The most common cause of long pauses is high IO wait times when doing operations like logging. This command is disabled for safety unless wrapper.commandfile.enable_tests is TRUE.

  The THREAD parameter is required, and can have one of the following values:

  • MAIN - The main Wrapper thread, including monitoring and pinging the JVM process.

  • TIMER - The timer thread which exists if the wrapper.use_system_time property is FALSE.

  • JAVAIO - The java IO thread which exists if the wrapper.use_javaio_thread property is TRUE.

  • EVENT - The thread used to process all event actions. Only available in the Professional Edition.

  The optional TIME parameter is used to specify the number of seconds which the thread will be delayed. Valid values are -1, or 0 to 3600 seconds. A value of -1 will cause the pause to wait indefinitely, 0 will have no effect, and larger values will pause for the specified number of seconds. Defaults to -1.

  While the MAIN thread is paused, the Wrapper will be unresponsive so it may be necessary to forcibly kill the Wrapper's process to recover prior to the pause time expiring.

• RESUME - Requests that the Wrapper be resumed. Only supported when run as a Windows Service and the wrapper.pausable property is TRUE.

• DUMP - Requests that the Wrapper cause the JVM to produce a thread dump. The results can be viewed in the Wrapper log file.

• GC (Since ver. 3.5.7) - Requests the JVM to perform an immediate full garbage collection sweep. Be aware that doing this frequently can affect performance of the JVM as a full sweep will often cause all threads to freeze for the duration of the GC.

• CONSOLE_LOGLEVEL {LOG_LEVEL} - Changes the console loglevel of the Wrapper.

• LOGFILE_LOGLEVEL {LOG_LEVEL} - Changes the log file loglevel of the Wrapper.

• SYSLOG_LOGLEVEL {LOG_LEVEL} - Changes the syslog or Event Log loglevel of the Wrapper.

• CLOSE_SOCKET (Since ver. 3.5.0) - Causes the backend socket with the JVM to be immediately closed. This is useful for testing the JVM's ability to reconnect with the Wrapper. This command is disabled for safety unless wrapper.commandfile.enable_tests is TRUE.