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. Ignored if the JVM is not running.

• PAUSE :
  

  Requests that the Wrapper be paused. Only supported when the wrapper.pausable property is TRUE.

• RESUME :
  

  Requests that the Wrapper be resumed. Only supported when the wrapper.pausable property is TRUE.

• SUSPEND_TIMEOUTS {TIME} (Since version 3.5.40) (Standard / Professional Edition) :
  

  Tells the Wrapper to suspend all timeouts used when the JVM is not responding. {TIME} specifies the number of seconds to suspend timeouts, and should be in the range 1-3600 (1h). This could be used if the Java application needs to perform a long blocking task and avoid having the Wrapper considering the application as unresponsive.

  Timeouts can also be suspended via action properties or the Java WrapperManager.suspendTimeouts() method.

  If several requests to suspend timeouts are made, the number of seconds specified by each request will not be summed. Instead, the newly specified time will replace the remaining suspension time if it is longer, and will be ignored otherwise.

• RESUME_TIMEOUTS (Since version 3.5.40) (Standard / Professional Edition) :
  

  Tells the Wrapper to resume all timeouts previously suspended.

  Timeouts can also be resumed via other action properties or the Java WrapperManager.resumeTimeouts() method.

• USER_{n} (Since version 3.5.57) (Professional Edition) :
  

  Tells the Wrapper to trigger a user event.

  The '{n}' component of the event name is any integer in the range 1-32767.

• DUMP :
  

  Requests that the Wrapper cause the JVM to produce a thread dump. The results can be viewed in the Wrapper log file. Ignored if the JVM is not running.

• GC (Since version 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. Ignored if the JVM is not running.

• 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.

Additional testing commands are also available if and only if the wrapper.commandfile.enable_tests property is TRUE. These commands are disabled by default for safety as some of them could cause security or stability problems for the Wrapper and your application.

Possible testing commands include:

• ACCESS_VIOLATION (Since version 3.5.2) :
  

  Causes the Wrapper process itself to crash and thus fail to shutdown cleanly. When this happens, the JVM should immediately detect that the Wrapper is gone and shut itself down cleanly. Nothing after the access violation will be retained in the Wrapper log file. This is useful for testing how the Wrapper, JVM, and external systems behave if the Wrapper were to crash.

• CLOSE_BACKEND (Since version 3.5.26) :
  

  Causes the backend connection with the JVM to be immediately closed. This is useful for testing the JVM's ability to reconnect with the Wrapper. Ignored if the JVM is not running.

• CLOSE_SOCKET (Since version 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. Ignored if the JVM is not running.

  Since version 3.5.26, this is an alias to "CLOSE_BACKEND".

• PAUSE_LOGGER {seconds} (Since version 3.5.11) :
  

  Causes the Wrapper to pause the next line of log output for the number of seconds specified. This is useful for testing the Wrapper and JVM's ability to handle delays in logging code. The {seconds} parameter can be in the range of "1" to "3600", or "0" (zero) for indefinite. This command is disabled for safety unless wrapper.commandfile.enable_tests is TRUE.

• PAUSE_THREAD {THREAD} {TIME} (Since version 3.5.8) :
  

  Causes the specified Wrapper thread with the following parameter 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.

  Mandatory {THREAD} parameter:

  The {THREAD} parameter is required for the property value PAUSE_THREAD, 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.javaio.use_thread property is TRUE.

  • EVENT :
    

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

  Optional {TIME} parameter:

  The optional {TIME} parameter for the property value PAUSE_THREAD is used to specify the number of seconds which the thread will be delayed. Valid values are "-1", or "0" (zero) to "3600" seconds.. A value of "-1" will cause the pause to wait indefinitely. A value of "0" (zero) will have no effect, and larger values will pause for the specified number of seconds. The default value is "-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.