User:Robertwenzel/LongOperations

Author
Robert Wenzel, Engineer, Potix Corporation

Date
January XX, 2015

Version
ZK 7.0.4

Introduction

Long operations are useful - bla - leverage Java Threads - bla - here how to hide and reuse the technical details. support MVVM and MVC programming model

Long Operations de-mystified

A very Simple Example

This simple example shows a very simple use case of the LongOperation class. The operation creates a simple result which is added to the resultModel when it finishes. During the 3 seconds the default busy overlay is displayed, asking the user to wait.

public class SimpleLongOperationViewModel {
	private ListModelList<String> resultModel = new ListModelList<String>();

	@Command
	public void startLongOperation() {
		LongOperation longOperation = new LongOperation() {
			private List<String> result;

			@Override
			protected void execute() throws InterruptedException {
				Thread.sleep(3000); //simulate a long backend operation
				result = Arrays.asList("aaa", "bbb", "ccc");
			}

			protected void onFinish() {
				resultModel.addAll(result);
			};

			@Override
			protected void onCleanup() {
				Clients.clearBusy();
			}
		};

		Clients.showBusy("Result coming in 3 seconds, please wait!");
		longOperation.start();
	}

	public ListModelList<String> getResultModel() {
		return resultModel;
	}
}

• Line 10: Implement the execute callback to collecting the result asynchrously
• Line 15: Implement the onFinish callback to update the UI once the operation has finished successfully
• Line 26: Launch the operation

In the 'startLongOperation'-command handler the "busy"-overlay is shown. In onCancel it is cleared, however the long operation terminates (successful or not).

Here the straight forward zul code using this SimpleLongOperationViewModel and posting the startLongOperation-command

    <div apply="org.zkoss.bind.BindComposer" 
    	 viewModel="@id('vm') @init('zk.example.longoperations.example.SimpleLongOperationViewModel')">
        <button onClick="@command('startLongOperation')" label="start"/>
        <grid model="@load(vm.resultModel)" height="300px"/>
    </div>

Updating the UI during the Operation

To update the UI during a long operation the desktop needs to be activated for UI updates. For this the methods activate() and deactivate() can be used as in the example below. It is advisable to activate the UI as short as possible for the UI to remain responsive. Any kind of UI updates can be performed between those 2 methods e.g.

• change the busy message
• adding/removing in a ListModelList
• set any component properties (or notify change VM properties)
  • e.g. update the value of a status-<label> OR <progressmeter>
• show/hide/enable/disable UI elements dynamically
• ...

	private static final String IDLE = "idle";
	private String status = IDLE;

...

	@Command
	public void startLongOperation() {
		LongOperation longOperation = new LongOperation() {
			private List<String> result;

			@Override
			protected void execute() throws InterruptedException {
				step("Validating Parameters...", 10, 500);
				step("Fetching Data ...", 40, 1500);
				step("Filtering Data...", 60, 1750);
				step("Updating Model...", 90, 750);
				result = Arrays.asList("aaa", "bbb", "ccc");
			}

			private void step(String message, int progress, int duration) throws InterruptedException {
				activate();
				updateStatus(progress+ "% - " + message);
				deactivate();
				Thread.sleep(duration); //simulate processing time for the current step
			}

			@Override
			protected void onFinish() {
				resultModel.addAll(result);
				updateStatus(IDLE);
			}
		};
		longOperation.start();
	}

	private void updateStatus(String update) {
		status = update;
		BindUtils.postNotifyChange(null, null, UpdatingStatusLongOperationViewModel.this, "status");
	}

• Line 21: activate the Thread for UI updates
• Line 23: deactivate the Thread to send the updates back to the browser
• Line 38: notify the change to update the UI

    <div apply="org.zkoss.bind.BindComposer"
    	 viewModel="@id('vm') @init('zk.example.longoperations.example.UpdatingStatusLongOperationViewModel')">
    	<button onClick="@command('startLongOperation')" label="start" 
    	        disabled="@load(vm.status ne 'idle')" autodisable="self" />
    	<label value="@load(vm.status)" />
    	<grid model="@load(vm.resultModel)" height="300px" />
    </div>

• Line 3: The status label to update during the operation

Aborting a Long Operation

Referring to zk.example.longoperations.example.CancellableLongOperationViewModel you can cancel a long operation and give user feedback accordingly. The Long Operation will naturally terminate (calling onCancel) when the thread was interrupted, or by checking explicitly for cancellation between steps, in case the Long Operation was cancelled during a blocking method call.

Of course this requires you break down your task into separate steps, or use non blocking method calls that throw InterruptedExceptions themselves - the LongOperation class will handle them for you.

IMPORTANT don't swallow InterruptedExceptions (they are very helpful)

	private LongOperation currentOperation;

	@Command
	public void startLongOperation() {
		currentOperation = new LongOperation() {

			@Override
			protected void execute() throws InterruptedException {
				step("Starting query (WHAT is the 'ANSWER';). This might take a about 7.5 million Years ...", 2000);
				step("Executing your query (1 million years passed) please wait...", 500);
				step("Executing your query (2 million years passed) please wait...", 500);
				step("Executing your query (3 million years passed) please wait...", 500);
...
				result = "The answer is 42";
			}

			private void step(String message, int duration) throws InterruptedException {
				//check explicitly if the task was cancelled 
				// if cancelled it will thow an InterruptedException to stop the task
				checkCancelled(); 
				activate(); //would throw an InterruptedException if cancelled
				updateStatus(message);
				deactivate();
				Thread.sleep(duration); //will throw an InterruptedException if cancelled during sleep
			}

...
			@Override
			protected void onCancel() {
				Clients.showNotification("Now you'll never know... be more patient next time");
			}

			@Override
			protected void onFinish() {
				Clients.showNotification(result);
			}
...
		}
	}

	@Command
	public void cancelOperation() {
		currentOperation.cancel();
	}

• Line 20: before performing a longer step call checkCancel()
• Line 21: activation will interrupt automatically if the Operation was cancelled
• Line 24: non blocking method calls such as sleep(), wait(), nio calls will interrupt automatically
• Line 30: UI callback for a cancelled Long Operation
• Line 43: cancel a task from a UI Command (MVVM or Event MVC)

Parallel Tasks

The LongOperation class also supports parallel tasks which can be visualized separately e.g. using a <grid> with a ListModelList of TaskInfo objects

check out the example in zk.example.longoperations.example.ParallelLongOperationViewModel / src/main/webapp/longop-parallel.zul

Customizing LongOperation

It is easy to extend the LongOperation class to provide additional reusable functions for more compact code in your Composer/ViewModel classes.

Resulting Demo

The video below demonstrates the results of the two advanced usages described above. For ease of demonstration here we use a PDF printer so the resulting screen is a PDF file, but you can definitely specify a real printer to print out the desired results on papers. ERROR: Link hasn't been found

Summary

The LongOperation class is a reusable/extensible base class for your long operations. It integrates with MVC/MVVM and helps to separate UI updates from Background processing still allowing intermediate UI updates.

Refer to download .

Download

• The source code for this article can be found in github.
• Download the packed jar file from github.

Comments

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.