TaskRegistry (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacardx.facilities
Class TaskRegistry

    java.lang.Object
      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 then the current execution state of the task may get affected depending on the value of the `eager` parameter:

  - if the `eager` parameter equals false (the task is only to be started after the next platform reset) and if the task is currently being executed then the task's thread is interrupted (by a call to `Thread.interrupt()`),
  - if the `eager` parameter equals true (the task is to be started immediately) and if the task is not currently being executed then the task is started,
  - in all other cases, re-registration of the same task object will have no additional effect on the current execution state of the task.

  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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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