5.5.2.3.3. Timer
API DOCS

Timer is a non-visual component allowing certain screen controller code to be run at specified time intervals. The timer works in a thread that handles user interface events, therefore it can update screen components. Timer stops working when a screen it was created for gets closed.

The component is implemented for the Web Client and the Desktop Client. For the web client, timer implementation is based on polling from web-browser, for the desktop client it is based on javax.swing.Timer.

The main approach for creating timers is by declaring them in a screen XML-descriptor – in the timers element which is located between dsContext and layout elements.

Timers are described using the timer element.

  • delay is a required attribute; it defines timer interval in milliseconds.

  • autostart – an optional attribute; when it is set to true, timer starts immediately after the screen gets opened. By default the value is false, which means that the timer will be started by invoking its start() method.

  • repeating – an optional attribute, turns on repeating executions of the timer. If the attribute is set to true, the timer runs in cycles at equal intervals defined in the delay attribute. Otherwise, the timer runs only once – delay milliseconds after the timer start.

  • onTimer – optional attribute containing a name of a method called when the timer fires. The handling method should be defined in a screen controller with the public modifier and have one parameter of type com.haulmont.cuba.gui.components.Timer.

An example of using a timer to refresh table content periodically:

<window ...
  <dsContext>
      <collectionDatasource id="bookInstanceDs" ...
  </dsContext>
  <timers>
      <timer delay="3000" autostart="true" repeating="true" onTimer="refreshData"/>
  </timers>
  <layout ...
@Inject
private CollectionDatasource bookInstanceDs;

public void refreshData(Timer timer) {
    bookInstanceDs.refresh();
}

A timer can be injected into a controller field, or acquired using the Window.getTimer() method. Timer execution can be controlled using the timer’s start() and stop() methods. For an already active timer, start() invocation will be ignored. After stopping the timer using stop() method, it can be started again with start().

Example of defining a timer in an XML descriptor and using timer listeners in a controller:

<timers>
    <timer id="helloTimer" delay="5000"/>
</timers>
@Inject
private Timer helloTimer;

@Override
public void init(Map<String, Object> params) {
    // add execution handler
    helloTimer.addActionListener(timer -> {
        showNotification("Hello", NotificationType.HUMANIZED);
    });
    // add stop listener
    helloTimer.addStopListener(timer -> {
        showNotification("Timer is stopped", NotificationType.HUMANIZED);
    });
    // start the timer
    helloTimer.start();
}

A timer can be created in a controller, in this case it should be added to the screen implicitly using the addTimer() method, for example:

@Inject
private ComponentsFactory componentsFactory;

@Override
public void init(Map<String, Object> params) {
    // create timer
    Timer helloTimer = componentsFactory.createTimer();
    // add timer to the screen
    addTimer(helloTimer);
    // set timer parameters
    helloTimer.setDelay(5000);
    helloTimer.setRepeating(true);
    // add execution handler
    helloTimer.addActionListener(timer -> {
        showNotification("Hello", NotificationType.HUMANIZED);
    });
    // add stop listener
    helloTimer.addStopListener(timer -> {
        showNotification("Timer is stopped", NotificationType.HUMANIZED);
    });
    // start the timer
    helloTimer.start();
}