Your application may require to run scheduled tasks or perform actions at specific times or at regular intervals. For example:

  • It 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.
  • It needs to be taken down for 10 minutes every night to allow external backups to take place.
  • You may simply want to schedule some benign actions to take place once every 5 minutes.

Here we tell you how you can do all this with the Java Service Wrapper.

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. It also 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 property, wrapper.timer.<n>.interval is used to specify when the timer should be fired. The second property, wrapper.timer.<n>.action is used to specify which action or actions should take place.

Property: wrapper.timer.<n>.interval

The property wrapper.timer.<n>.interval 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 am 
wrapper.timer.1.interval=hour=3; minute=55
Configuration Example: Every Monday at 03:55 am 
wrapper.timer.1.interval=day-of-week=2; hour=3; minute=55
Configuration Example: Every 5 seconds 
wrapper.timer.1.interval=second=*/5

Property: wrapper.timer.<n>.action

The property wrapper.timer.<n>.action 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:

If you want 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 :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

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.

A solution 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 03:00 am on Sunday mornings.

Configuration Example: Restart Every Sunday at 03:00 am 
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 :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

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 :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

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 03:00 a.m. and then resume it again at 04:00 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 :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

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 :Professional EditionStandard Edition (Not Supported)Community Edition (Not Supported)
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

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: Property Configurations

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.