Events Overview

Compatibility :3.3.0
Editions :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/OSIBM z/Linux

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

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:

Event Email Properties:

Event Command Properties:

Event Types

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.

Event Mails

NOTE

This function requires the Professional Edition of the Java Service Wrapper.

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.

Example (send email in response to JVM restarts):
# 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.

Event Commands

NOTE

This function requires the Professional Edition of the Java Service Wrapper.

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.

Example (execute 'mycleanup' before JVM launch, no wait):
wrapper.event.jvm_prelaunch.command.argv.1=/usr/bin/mycleanup
wrapper.event.jvm_prelaunch.command.argv.2=parameter1
Example (execute 'mycleanup' before JVM launch, indefinite wait):
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
Example (execute 'mycleanup' before JVM launch, 5 second wait):
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.