World Map
Java Service Wrapper is the easiest way to make your product more reliable.
  • Free Trial
  • Buy Now
wrapper.single_invocation.notify Properties

Overview: wrapper.single_invocation.notify Properties

When single invocation is enabled, the Wrapper will check that there is no other instance running with the same value of the wrapper.ntservice.name property. If another instance exists, it will show an error message by default.

Starting from version 3.5.28, it is possible to give the focus to a window of the running application instead of showing the error message. This will work out of the box without any additional coding.

Another solution offers more flexibility by allowing you to execute custom actions in response to the second invocation. If your application has several windows, you will be able to select exactly which one to show up. You may also want to trigger completely different actions like showing a custom message or sending a notification by email. This solution is based on event handling and requires some coding.

NOTE

These new features require that the second instance of the Wrapper be launched from the same user as (or a user with higher privileges than) the first instance.

If the first instance is running as a service, unless it is interactive, it is not able to display a GUI. It is thus not possible to give the focus to any window, but a second instance with enough privileges will still be able to trigger different actions as long as they don't involve the GUI.

Starting with Windows Vista and Server 2008, a service is not allowed to interact with the user's desktop. In this case, the service will not be able to give focus to a desktop application.

wrapper.single_invocation.notify

Compatibility :3.5.28
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

When set to TRUE, this property specifies that the Wrapper monitoring the running application will be notified for any attempt made to launch another instance. By default, this will focus the first visible window (in the z-order) of the Java application. However, this feature can be turned off using wrapper.single_invocation.notify.focus_window.

The Wrapper will also send a notification to the JVM which will in turn trigger an event called 'WrapperSecondInvocationEvent'. This event can be consumed by your Java application to execute custom tasks. The default value for this property is FALSE meaning that no notification will be sent and a simple error message will be shown if an instance is already running.

To handle the event, a few changes will be needed in your application:

  • First, add a dependency to wrapper.jar.
  • Then, implement the interface org.tanukisoftware.wrapper.event.WrapperEventListener in one of your classes. This requires to only add one method in your class. It is the method that will be called when the event is triggered.
  • Finally, add the class as a listener to the event.
Example: How to implement WrapperEventListener and listen to WrapperSecondInvocationEvent
import org.tanukisoftware.wrapper.WrapperManager;
import org.tanukisoftware.wrapper.event.WrapperEvent;
import org.tanukisoftware.wrapper.event.WrapperSecondInvocationEvent;
import org.tanukisoftware.wrapper.event.WrapperEventListener;

// Implement WrapperEventListener
public class Main implements WrapperEventListener {
    
    /**
    * Create the application.
    */
    public Main() {
        ...
        // Adds itself as a listener for WrapperSecondInvocationEvent
        WrapperManager.addWrapperEventListener( this, 
            WrapperEventListener.EVENT_FLAG_REMOTE_CONTROL );
    }
        
    public void fired( WrapperEvent event ) {
        if (event instanceof WrapperSecondInvocationEvent ) {
            // Write here the code to be executed 
            // in response to WrapperSecondInvocationEvent
            ...
        }
    }
}

Any custom action can be coded inside the fired() method. A common practice is to bring a specific window of the running application to the top whenever the user tries to launch it a second time. The following example uses setAlwaysOnTop(true) to bring a window to the front. This however will cause the window to be 'topmost' which means it will overlap all other windows of the desktop even if the user would click on the background. This behaviour can be cancelled by calling setAlwaysOnTop(false).

Example:
public void fired( WrapperEvent event )
{
    if (event instanceof WrapperSecondInvocationEvent )
    {
        // requires java 1.5 or later
        frame.setAlwaysOnTop(true); // bring the window to the top
        frame.setAlwaysOnTop(false);  // remove the topmost feature
    }
}

WARNING

By enabling this property, a named pipe will be opened to allow communication between the two Wrapper instances. Be aware that any application running on the same user or a user with higher privilege is potentially able to communicate through the pipe and thus trigger the event. This may cause a security issue and it is the responsibility of the Java application to execute code that is safe regarding this aspect.

wrapper.single_invocation.notify.focus_window

Compatibility :3.5.28
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

This property is set to TRUE by default and will focus the first visible window (in the z-order) of the Java application whenever the user tries to launch it a second time. If there is no such window, an attempt will be made to give the focus to a window of the Wrapper monitoring the running application. This feature is only available if wrapper.single_invocation.notify is set to TRUE.

Technically, the Java application cannot activate its own windows because it is not the active application at the time the user tries to launch a second instance. When the Wrapper monitoring the Java application receives a notification from another instance, it will communicate back the required information so that the instance launched by the user can activate the appropriate window. In any case, this will be done after triggering the event giving the Java application a chance to set its prefered window at the top of the z-order position.

Unless you want to execute some custom actions that don't involve any window, you should always keep this property set to TRUE because it can be confusing to bring a window to the foreground while the focus is still set to a background window.

wrapper.single_invocation.timeout

Compatibility :3.5.28
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

This property specifies the maximum amount of time (in seconds) that the Wrapper will wait until it gets a reply from the running instance. Failing that, it will show an error message and stop. The default value is set to 15 seconds. Unless the actions triggered by the event take too long to execute, the reply should come with no latency.

wrapper.single_invocation.notify.show_splashscreen

Compatibility :3.5.28
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

With single invocation mode, the default behaviour is to not show the splash screen when the Wrapper is launched a second time. If the actions triggered by the event take too long to execute, it may be useful to show the splashscreen. This can be done by setting this property to TRUE.