Problem

How can I schedule JVM restarts, shutdowns, thread dumps, or other actions with my Java applications?

Solution!

The Java Service Wrapper provides the ability to schedule a number of actions with timers.

What if your application is suffering from a memory leak which requires the JVM to be restarted at least once per week? It needs to be restarted during a time when the system is not used, at times when system administrators are home in bed.

Or if your application needs to be taken down for 10 minutes every night to allow external backups to take place?

Or you may simply want to schedule that some more benign action takes place once every 5 minutes.

Many large applications require the ability to run scheduled tasks or perform actions at specific times or at regular intervals. The problem is that different OS platforms each provide their own way of scheduled actions. When the application needs to be able to run across all of those platorms it is often necessary to implement this functionality for each platform individually.

Solution
Technical Overview

Restarts
Thread Dumps
Pausing and Resuming
Java Tasks
User Defined Actions

Configuration Properties

Solution

The Java Service Wrapper provides a way to schedule tasks such as restarts, shutdowns, thread dumps, custom events, etc. in a cross platform way using the Wrapper's timer functionality.

Timers are defined within the Wrapper's configuration file, making it possible to reliably contain all such settings within the application themselves. This makes it easy to deploy the application to multiple servers and know that everything will work consistently.

Timers can be scheduled for specific times and days of the week, or at intervals ranging from once per week down to every second. This flexibility makes it easy to plan backups or downtimes at times which least inconvenience your users, and at the same time allows your system administrators to reduce overtime by working regular hours.

Technical Overview

The Wrapper allows you to define multiple timers, each using a pair of properties. The first, wrapper.timer.<n>.interval property is used to specify when the timer should be fired. The second, wrapper.timer.<n>.action property is used to specify which action or actions should take place.

wrapper.timer.<n>.interval property:

The wrapper.timer.<n>.interval property can be used to fire the action at specific times or intervals. Wildcards can be used to specify intervals. The following are a few examples, but please read over the full property documentation to see what all is possible.

Configuration Example: Everyday at 03:55

wrapper.timer.1.interval=hour=3; minute=55

Configuration Example: Every Monday at 03:55

wrapper.timer.1.interval=day-of-week=2; hour=3; minute=55

Configuration Example: Every 5 seconds

wrapper.timer.1.interval=second=*/5

wrapper.timer.<n>.action property:

The wrapper.timer.<n>.action property is used to specify the action, or what happens, when the timer is fired. In most cases, this is a single action, but multiple actions can be separated by a comma to perform each of them in series. The following are a few examples, but please read over the full property documentation to see what all is possible.

Configuration Example: Perform a Thread Dump

wrapper.timer.1.action=dump

Configuration Example: Perform a Thread Dump and then Restart the JVM

wrapper.timer.1.action=dump, restart

Setting multiple timers:

To declare multiple timers, simply add additional properties with unique numbers in place of the "1" above.

Configuration Example: Multiple Timers to perform Thread Dumps at 03:55, 12:55, and 21:55 each day

wrapper.timer.1.interval=hour=3; minute=55
wrapper.timer.1.action=dump
wrapper.timer.2.interval=hour=12; minute=55
wrapper.timer.2.action=dump
wrapper.timer.3.interval=hour=21; minute=55
wrapper.timer.3.action=dump

We will now cover some interesting uses of timers with your applications.

Restarts

Compatibility :	3.3.0
Editions :
Platforms :

One of the most common timer actions to register is a scheduled restart of JVM. Restarts are often needed during downtimes to work around memory or resource leaks, resynchronize with external databases, or simply reload the Wrapper's configuration.

When an application has a known memory leak, a system administrator must often work around the problem until the underlying leak can be fixed by the JVM, application, or library vendor. Even when the application is an in-house system, it can often take some time for the development team to resolve the problem. In the mean time, if a leak is left unmanaged, the JVM will often start experiencing out of memory errors during peak loads.

To avoid such problems, the Wrapper can be setup to preemptively restart the JVM at times when the number of users is known to be at a minimum. For example at 3am on Sunday mornings.

Configuration Example: Restart Every Sunday at 03:00

wrapper.timer.1.interval=day-of-week=1; hour=3
wrapper.timer.1.action=restart

Example Log Output:

wrapper  | 2012/06/10 03:00:00 | Timer #1.  Restarting JVM.
jvm 1    | 2012/06/10 03:00:01 | TestWrapper: stop(0)
jvm 2    | 2012/06/10 03:00:06 | WrapperManager: Initializing...
jvm 2    | 2012/06/10 03:00:06 | TestWrapper: Initializing...

Thread Dumps

Compatibility :	3.3.0
Editions :
Platforms :

Sometimes when debugging a problem, it can be useful to take thread dumps at regular intervals for later analysis. The Wrapper can easily be asked to do so at 5 minute intervals for example.

Configuration Example: Request Thread Dump Every 5 minutes

wrapper.timer.1.interval=minute=*/5
wrapper.timer.1.action=dump

WARNING

If you try this, please make sure that your log file size is large enough to hold the dumps.

Pausing and Resuming

Compatibility :	3.5.0
Editions :
Platforms :

If you have configured your application to be pausable, then it is possible to use timers to pause and resume the application at specific times. When an application is paused, the Wrapper can be configured to stop the JVM but keep the Wrapper running. This is ideal for scheduling downtimes to perform database backups or other tasks that can not take place while the application is running.

The following example configuration will stop the JVM every night at 3 a.m. and then resume it again at 4 a.m.

Configuration Example: Scheduled Pause and Resume

wrapper.timer.1.interval=hour=3
wrapper.timer.1.action=pause
wrapper.timer.2.interval=hour=4
wrapper.timer.2.action=resume

This is great, but the application will always be down for 1 hour. What if we want to resume the application as soon as the necessary backups have completed?

This can be done by making use of the wrapper.commandfile property along with the RESUME command, issued at the end of your backup script. The timed resume should still be configured just in case there is a problem in the script. The resume action from the timer will be ignored if the application is no longer paused.

Java Tasks

Compatibility :	3.5.0
Editions :
Platforms :

Another use of the RESUME timer action is to launch short lived Java applications which need to perform a scheduled task and then exit. By combining a RESUME timer action with a wrapper.on_exit.<n> property definition, the Wrapper can be told to enter a paused state whenever the JVM exits, and then relaunch it when the timer is fired.

For example, the following configuration will not launch a JVM when the Wrapper is first launched. Rather, it will wait and then launch the JVM at 1 hour intervals, at the top of each hour. The application will perform some task and then exit. When it does so, the Wrapper will enter a paused state rather than exiting or relaunching a JVM. This process will then repeat each hour until the Wrapper is shutdown.

Configuration Example: Scheduled Pause and Resume

wrapper.pausable=TRUE
wrapper.pause-on-startup=TRUE
wrapper.timer.1.interval=minute=60
wrapper.timer.1.action=resume
wrapper.on_exit.default=PAUSE

The benefit of running the Java application only when needed rather than simply keeping the JVM idling is that you can greatly save on system resources by shutting down the JVM process when it is not needed.

User Defined Actions

Compatibility :	3.5.0
Editions :
Platforms :

The Wrapper also makes it possible to schedule the execution of external commands, or send out emails, at regular intervals. This is done by making use of user defined action events.

The following example will execute a cleanup script or batch file every 10 minutes.

Configuration Example: Scheduled Cleanup Command Execution

wrapper.event.user_100.command.argv.1=cleanup
wrapper.timer.1.interval=minute=*/10
wrapper.timer.1.action=user_100

Please see the Event Overview page for more information on to configure commands or send emails.

Reference: Configuration Properties

The Java Service Wrapper provides a full set of configuration properties that allows you to make the Wrapper meet your exact needs. Please take a look at the documentation for the individual properties to see all of the possibilities beyond the examples shown above.

Q & A Page:

Other Help Pages:

Currently logged on:

Customers