Compatibility :	3.5.28
Editions :
Platforms :

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.

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 canceled by calling setAlwaysOnTop(false).

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
    }
}

Compatibility :	3.5.28
Editions :
Platforms :

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 preferred 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.

Compatibility :	3.5.28
Editions :
Platforms :

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.

Compatibility :	3.5.28
Editions :
Platforms :

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.