Smart Card Shell

Task - Reference Documentation

The Task host class allows to define and control background tasks in the Smart Card Shell.

A background task consists of a user object that implements a run() method and an actionListener() method to receive user notification. A Task object provides for visualization in the task tab of the Smart Card Shell and controls to start and stop the task. It also implements a message queue for asynchronously passing messages from other tasks or scripts.

Index of Methods

Properties

Type Name Description
String icon Name of icon selected with setIcon()
String tooltip Tooltip set with setToolTip()
String[] contextMenu Context menu set with setContextMenu()
Object userObject Object registered as user object in constructor
String status Task status, one of created, running, failed, passed

Constructor

Prototype

Task(Object userObject)

Description

Create a Task object with associated user object. Add task entry in tasks tab.

A newly created task object can be started using the start() method. It can be stopped with stop() method.

A call to dispose() will stop the task, clear the queue and remove the task entry from the task list.

Arguments

Type Name Description
Object userObject The user object

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments given
GPError GPError.INVALID_TYPE On or more arguments are not of the expected type

Example


function TaskTest() {
	this.name = "Task#" + TaskTest.CNT++;
	this.task = new Task(this);
	this.task.setContextMenu([ "Start", "Stop", "Trace", "Post", "Dispose" ]);
	this.task.setToolTip("Tooltip");
}

TaskTest.CNT = 1;


TaskTest.prototype.start = function() {
	this.task.start();
}



TaskTest.prototype.run = function() {
	var i = 10;
	do	{
		print("Hello");
		GPSystem.trace("Trace");
		this.task.setMessage("Running " + i);
		var o = this.task.poll(1000);

		if (o) {
			print("Received " + o);
		}
	} while (i-- > 0);
}


TaskTest.prototype.actionListener = function(source, action) {
	print("Source / Action: " + source + "/" + action);

	switch(action) {
		case "Start":
			this.task.start();
			break;
		case "Stop":
			this.task.stop();
			break;
		case "Trace":
			print(GPSystem.copyTrace());
			break;
		case "Post":
			this.task.post("Message");
			break;
		case "Dispose":
			this.task.dispose();
			break;
	}
}



TaskTest.prototype.toString = function() {
	return this.name;
}


for (var i = 0; i < 20; i++) {
	new TaskTest();
}

start()

Prototype

start()

Description

Start the task by creating a dynamic scope and calling the run() method of the user object.

Start can be called multiple time, creating subsequent synchronous executions of run().

Return

Void The method does not return a value

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


task.start();

stop()

Prototype

stop()

Description

Stop the task by sending an interupt signal to the running task and clear the queue.

Return

Void The method does not return a value

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


task.stop();

post()

Prototype

post(Object object)

Description

Post an object to the queue maintained for this task.

Arguments

Type Name Description
Object object Object to be added to queue.

Return

Void The method does not return a value

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for method invocation

Example


task.post("Message");

poll()

Prototype

Object poll(Number timeout)

Description

Poll for an object from the queue maintained for this task.

Arguments

Type Name Description
Number timeout Number of milliseconds to wait for object.

Return

Object The object retrieved from the queue or null, if no object available within specified time.

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for method invocation

Example


var o = task.poll(1);
print(o);

setContextMenu()

Prototype

setContextMenu(String[] entries)

Description

Set content of context menu.

Selected actions trigger an actionLister() method call on the user object.

A separator can be defined using "---" as entry.

Arguments

Type Name Description
String[] entries Array of context menu entries

Return

Void The method does not return a value

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for method invocation

Example


task.setContextMenu(["add"]);

setToolTip()

Prototype

setToolTip(String toolTipText)

setToolTip()

Description

Set a text to display as tool tip, which is displayed when the mouse is held over the node.

If no text is defined, the tool tip is removed.

Arguments

Type Name Description
String toolTipText Text to display

Return

Void The method does not return a value

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for method invocation

Example


task.setToolTip("Press the right mouse button to see context menu");

setIcon()

Prototype

setIcon(String iconName)

setIcon()

Description

Change the icon of the node to the named icon or reset to the default.

The name of the icon is mapped to the file name <iconName>.png and located in the icons directory directly underneath the installation directory.

Arguments

Type Name Description
String iconName Name of icon

Return

Void The method does not return a value

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for method invocation

Example


task.setIcon("selected");

setMessage()

Prototype

setMessage(String message)

Description

Change the message of the node to the given string.

Arguments

Type Name Description
String message Message for node

Return

Void The method does not return a value

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for method invocation

Example


task.setMessage("Changed label");

getTaskList()

Prototype

Task[] Task.getTaskList()

Description

Return the list of currently defined tasks

Return

Task[] The list of tasks.

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


dispose()

Prototype

dispose()

Description

Stop task, clear queue and remove from task list.

Return

Void The method does not return a value

Exceptions

Name Value Description
GPError GPError.INVALID_ARGUMENTS Too many arguments in call

Example


GPSystem.wait(1000);
task.dispose();