Compatibility :	3.3.0
Editions :
Platforms :

The Java Service Wrapper has the ability to notify a system administrator via email, as well as react to a wide range of built-in and user-defined events.

• Event Configuration Properties
• Event Types
• Event Mails
• Event Commands

This section includes a full list of properties which can be used to configure and control how the Wrapper reacts to events.

General Event Properties:

• wrapper.event.<event_name>.loglevel (3.3.6) ( Pro )

  Controls the log level of messages being logged each time a specific event takes place.

• wrapper.event.<event_name>.message (3.3.6) ( Pro )

  Controls the message which will be logged each time a specific event takes place.

• wrapper.event.<event_name>.set_environment (3.3.0, deprecated as of 3.3.6) ( Pro )

Event Email Properties:

Email Alert Setting:

• wrapper.event.<event_name>.email (3.3.0) ( Pro )

  Configures whether or not emails should be sent for a particular event.

Email System:

• wrapper.event.<event_name>.email.client.host (3.3.2) ( Pro )

  Sets the name of the machine running the Wrapper and sent to the SMTP server.

• wrapper.event.<event_name>.email.smtp.host (3.3.0) ( Pro )

  Configures the SMTP host which the Wrapper will attempt to connect to when sending emails.

• wrapper.event.<event_name>.email.smtp.port (3.3.0) ( Pro )

  Configures the SMTP port which the Wrapper will attempt to connect to when sending emails.

• wrapper.event.<event_name>.email.smtp.auth.type (3.5.3) ( Pro )

  Specifies an authentication method to use when connecting to an SMTP server.

• wrapper.event.<event_name>.email.smtp.auth.userid (3.5.3) ( Pro )

  Specifies the user Id to use for authentication when connecting to an SMTP server.

• wrapper.event.<event_name>.email.smtp.auth.password (3.5.3) ( Pro )

  Specifies the password to use for authentication when connecting to an SMTP server.

• wrapper.event.<event_name>.email.receive.timeout (3.3.2) ( Pro )

  Configures the maximum number of seconds to wait for a reply from the SMTP server after a command is sent by the Wrapper.

• wrapper.event.<event_name>.email.send.timeout (3.3.2) ( Pro )

  Configures the maximum number of seconds to wait when the Wrapper attempts to send a command to the SMTP server.

• wrapper.event.<event_name>.email.debug (3.3.0) ( Pro )

  Prints detailed information when emails are sent.

Email Body:

• wrapper.event.<event_name>.email.sender (3.3.0) ( Pro )

  Specifies the from address of the emails.

• wrapper.event.<event_name>.email.recipient (3.3.0) ( Pro )

  Specifies the recipient(s) of the emails.

• wrapper.event.<event_name>.email.subject (3.3.0) ( Pro )

  Configures the subject of the emails.

• wrapper.event.<event_name>.email.body (3.3.0) ( Pro )

  Configures the body of the emails.

• wrapper.event.<event_name>.email.attach_log (3.4.0, deprecated as of 3.5.31) ( Pro )

  Enables sending a log file in the attachments of the emails.

• wrapper.event.<event_name>.email.maillog (3.5.31) ( Pro )

  Enables sending logs as an attachment or directly in the body of the emails.

• wrapper.event.default.email.maillog.lines (3.4.0) ( Pro )

  Specifies the number of lines of the logs included in the emails.

• wrapper.event.default.email.maillog.format (3.4.0) ( Pro )

  Configures the format of the logs included in the emails.

• wrapper.event.default.email.maillog.loglevel (3.4.0) ( Pro )

  Filters messages included in the emails according to their log levels.

Event Command Properties:

• wrapper.event.<event_name>.command.argv.<n> (3.3.0) ( Pro )

  Specify a command (and its arguments) to be executed in response to a specific event.

• wrapper.event.<event_name>.command.block (3.4.1) ( Pro )

  Tells the Wrapper whether or not to wait for the command to complete before allowing the Wrapper to continue.

• wrapper.event.<event_name>.command.block.action (3.4.1) ( Pro )

  Configures the action to take place whenever a configured event command fails to complete within the specified timeout.

• wrapper.event.<event_name>.command.block.timeout (3.3.0) ( Pro )

  Configures how long the Wrapper will wait for a configured event to complete.

• wrapper.event.<event_name>.command.loglevel (3.3.0) ( Pro )

  Controls the log level of messages related to the event commands being executed.

• wrapper.event.<event_name>.command.new_process_group (3.5.47) ( Pro )

  Specifies if the event command should be started in a new process group.

• wrapper.event.<event_name>.command.on_exit.<n> (3.3.0) ( Pro )

  Control what the Wrapper will do in response to specific exit codes of event commands.

• wrapper.event.<event_name>.command.privileges.disable (3.5.57) ( Pro )

  Disables privileges for event commands.

• wrapper.event.<event_name>.command.privileges.enable (3.5.57) ( Pro )

  Enables privileges for event commands.

• wrapper.event.<event_name>.command.privileges.remove (3.5.57) ( Pro )

  Removes privileges from the access tokens of event commands.

The Wrapper is able to send emails and/or execute external commands in response to a number of events. The following list describes each of the defined events:

• wrapper_start :

  Fired when the Wrapper process first starts. This event can be used to do any initialization that must be done before the first JVM is launched.

  In the case of emails, it can be used to indicate that the system has just been rebooted, for example.

• jvm_prelaunch :

  Fired whenever a new JVM is about to be launched. This event can be used to do any initialization that must be done before each JVM is launched.

• jvm_start :

  Fired immediately after a new JVM has been launched, but before its application is started.

• jvm_started :

  Fired once the Wrapper code in the JVM has notified the Wrapper process that the new application is up and running.

  Note that unless Integration Method 3 (WrapperListener) is being used, this may be fired before the user application is actually fully up. Depending on the user application, both Method 1 (WrapperSimpleApp) and Method 2 (WrapperStartStopApp) can also be configured to wait until the application is fully started before reporting that it is up. See the "Advanced" section of each Integration Method for details.

• jvm_deadlock (Since ver. 3.5.0) :

  Fired whenever a thread deadlock is detected within the JVM with the Check Deadlock feature.

• jvm_ping_slow :

  Fired when a ping is first determined to be slower than the number of seconds specified by wrapper.ping.alert.threshold. The event will be fired before the ping has been responded.

• jvm_ping_response_slow :

  Fired when a ping is determined to be slower than the number of seconds specified by wrapper.ping.alert.threshold. The event will be fired after the ping has been responded.

• jvm_ping_timeout :

  Fired when the time between two ping responses took longer than the number of seconds specified by wrapper.ping.timeout.

• jvm_stop :

  Fired whenever a JVM is about to be shutdown. The event will be fired if the JVM crashes but it will happen after the JVM process is gone. If the system crashes or loses power for any reason, the event will never be fired.

• jvm_stopped :

  Fired after a JVM is shutdown for any reason. This event can be used to do any cleanup. If the system crashes or loses power for any reason, the event will never be fired.

• jvm_restart :

  Fired when the Wrapper is about to restart a JVM.

• jvm_failed_invocation :

  Fired when the JVM has exited in a state which results in a restart, but the total time that the JVM was running was less than the configured wrapper.successful_invocation_time property.

• jvm_max_failed_invocations :

  Fired when the JVM has exited in a state which results in a restart, but the failed invocations (jvm_failed_invocation event) is counted up, the total number of consecutive failed invocations is more than the configured wrapper.max_failed_invocations property.

• jvm_kill :

  Fired when the Wrapper has decided that a JVM which it believed to be frozen needs to be killed. This happens before the JVM process is killed. This event will always be preceded by the jvm_stop event then followed by the jvm_killed and jvm_stopped events. See the wrapper.jvm_kill.delay property if a delay is needed when executing commands for this event.

• jvm_killed :

  Fired when the Wrapper has killed a JVM which it believed to be frozen. This event will always be followed by the jvm_stopped event.

• jvm_unexpected_exit :

  Fired when the JVM process disappears for an unexpected reason. For example when it crashes. This event will always be followed by the jvm_stop and jvm_stopped events.

• wrapper_stop :

  Fired last when the Wrapper process is shutting down. This event can be used to do any cleanup that must be done after the last JVM is shut down.

  Note that this event will only be fired if the Wrapper is shutdown normally. If the system crashes or loses power for any reason, the event will never be fired.

• wrapper_pause (Since ver. 3.5.0) :

  Fired whenever the Wrapper is paused. Depending on the configuration of how the Wrapper behaves when paused, events about the JVM being stopped will also be fired.

  See the wrapper.pausable and wrapper.pausable.stop_jvm properties for more details.

• wrapper_resume (Since ver. 3.5.0) :

  Fired whenever the Wrapper is resumed. Depending on the configuration of how the Wrapper behaves when paused, events about the JVM being started will also be fired.

  See the wrapper.pausable and wrapper.pausable.stop_jvm properties for more details.

• user_<n> (Since ver. 3.5.0) :

  User event which is fired in response to an Action. The '<n>' component of the event name is any integer in the range 1 to 32767.

  Actions which can be configured to fire a user event include: wrapper.filter.action.<n>, wrapper.timer.<n>.action, wrapper.check.deadlock.action, and wrapper.event.<event_name>.command.block.action.

The Wrapper is able to send out alert emails to in response to certain events. Emails can be sent out with a customized message, along with a fragment of the Wrapper's log file. This makes it possible for a system administrator to decide whether or not it is necessary to take further action. See the documentation of individual properties for details on their use.

# Common Event Email settings.
#wrapper.event.default.email.debug=TRUE
wrapper.event.default.email.smtp.host=smtp.mycompany.com
wrapper.event.default.email.smtp.port=25
wrapper.event.default.email.subject=[%WRAPPER_HOSTNAME%:%WRAPPER_NAME%:%WRAPPER_EVENT_NAME%] Event Notification
wrapper.event.default.email.sender=myapp-noreply@mycompany.com
wrapper.event.default.email.recipient=myapp-admin@mycompany.com

# Event specific settings.
wrapper.event.jvm_restart.email=TRUE
wrapper.event.jvm_restart.email.body=The JVM was restarted.\n\nPlease check on its status.\n

The properties are all of the form wrapper.event.<x>.email* where <x> component is either the keyword default, or one of the Event Types defined above.

Whenever a property is not specifically defined for any of the event names, the default value wrapper.event.default.email* will be used. This is useful for setting values which will be common to all event emails.

The Wrapper is able to execute external commands in response to certain events. These can be useful for doing system cleanup, sending out notifications, or taking actions which can only be handled natively. See the documentation of individual properties for details on their use.

It is possible to instruct the Java Service Wrapper to launch the command and forget about it, block until the command has completed, or wait a maximum time for the command to complete. If the wait times out, the command will be left running.

The Wrapper does not currently provide for a way to log the output of the external commands.

wrapper.event.jvm_prelaunch.command.argv.1=/usr/bin/mycleanup
wrapper.event.jvm_prelaunch.command.argv.2=parameter1

wrapper.event.jvm_prelaunch.command.argv.1=/usr/bin/mycleanup
wrapper.event.jvm_prelaunch.command.argv.2=parameter1
wrapper.event.jvm_prelaunch.command.block=TRUE

wrapper.event.jvm_prelaunch.command.argv.1=/usr/bin/mycleanup
wrapper.event.jvm_prelaunch.command.argv.2=parameter1
wrapper.event.jvm_prelaunch.command.block=TRUE
wrapper.event.jvm_prelaunch.command.block.timeout=5

The properties are all of the form wrapper.event.<x>.command.* where <x> component is one of the Event Types defined above.

Whenever a property is not specifically defined for any of the event names, the default value wrapper.event.default.command.* will be used. This is useful for setting values which will be common to all event commands.