javacardx.facilities
Class TaskRegistry

java.lang.Object
  extended by javacardx.facilities.TaskRegistry

@TransactionType(value=NOT_SUPPORTED)
public final class TaskRegistry
extends Object

The TaskRegistry class allows for applications to register tasks which will be executed in their own separate thread and which will be automatically restarted in a new thread when the platform is reset.

Tasks are Runnable objects created by an application. These objects remains bound to the application's context while registered.

The registry ensures that task objects are persistent across card session. Therefore applications do not have to hold on to references on these objects to ensure their persistence. Additionally, the registry provides facilities to retrieve and manage registered tasks.

Tasks are automatically restarted in a new thread at each platform reset until the task is removed from the registry by the application that registered it or when that application is deleted.

Tasks are restarted after the application containers have been restarted but before any request or command get dispatched to applications.

The task registry operates in the Java Card runtime environment context: it is a permanent Java Card runtime environment Entry Point Object.

Task registry operations are subject to permission checks.

See Runtime Environment Specification for the Java Card Platform, Connected Edition , chapter 2 for details regarding the task registry.

Since:
Java Card 3.0
See Also:
TaskRegistryPermission

Method Summary
static TaskRegistry getTaskRegistry()
          Retrieves the restartable task registry.
 Enumeration<Runnable> list()
          Lists all the tasks registered by the current application.
 void register(Runnable task)
          Registers the given task for restartable execution.
 void register(Runnable task, boolean eager)
          Registers the given task for restartable execution.
 void unregister(Runnable task)
          Unregisters the given task previously registered by the current application, without interrupting the task's thread if the task is currently being executed.
 void unregister(Runnable task, boolean eager)
          Unregisters the given task previously registered by the current application.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getTaskRegistry

public static final TaskRegistry getTaskRegistry()
Retrieves the restartable task registry.

Returns:
the Java Card RE-owned TaskRegistry singleton instance.

register

public void register(Runnable task)
Registers the given task for restartable execution. The task will start after the next platform reset.

The task will be restarted after each platform reset.

If the same task object is already registered, this results in the currently executing task's thread (if any) to be interrupted.

Calling this method is equivalent to calling register(Runnable, boolean) with the eager parameter set to false.

Parameters:
task - the task to register.
Throws:
SecurityException -
  • if registration is not granted
  • or, if the task is not owned by the current application (or its group context),
  • or, if the same task has already been registered by another application (from the same group context).
NullPointerException - if task is null.

register

public void register(Runnable task,
                     boolean eager)
Registers the given task for restartable execution. If eager equals true, the task will be started immediately.

The task will be restarted after each platform reset.

If the same task object is already registered, this results in the currently executing task's thread (if any) to be interrupted if the task is only to be started after the next platform reset, that is if the eager parameter equals false.

Parameters:
task - the task to register.
eager - indicates that the task is to be started immediately.
Throws:
SecurityException -
  • if registration is not granted
  • or, if the task is not owned by the current application (or its group context),
  • or, if the same task has already been registered by another application (from the same group context).
NullPointerException - if task is null.

list

public Enumeration<Runnable> list()
Lists all the tasks registered by the current application.


unregister

public void unregister(Runnable task)
Unregisters the given task previously registered by the current application, without interrupting the task's thread if the task is currently being executed.

Calling this method is equivalent to calling unregister(Runnable, boolean) with the eager parameter set to false.

Parameters:
task - the task to be unregistered.
Throws:
SecurityException -
  • if unregistration is not granted,
  • or, if the task is not owned by the current application (or its group context),
  • or, if the provided task is registered, but it has not been registered by the current application.
NullPointerException - if task is null.

unregister

public void unregister(Runnable task,
                       boolean eager)
Unregisters the given task previously registered by the current application. If eager equals true and if the task is currently being executed, the thread's interrupt method is first called.

Parameters:
task - the task to be unregistered.
eager - indicates that the task is to be interrupted first.
Throws:
SecurityException -
  • if unregistration is not granted,
  • or, if the task is not owned by the current application (or its group context),
  • or, if the provided task is registered, but it has not been registered by the current application.
NullPointerException - if task is null.


Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.