EventRegistry (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 EventRegistry

    java.lang.Object
      javacardx.facilities.EventRegistry

    @TransactionType(value=NOT_SUPPORTED)
    public final class EventRegistry

extends Object

The EventRegistry class allows for applications to be notified by the Java Card runtime environment or by other applications of particular conditions. These conditions when they occur are encapsulated in objects called `Event` objects. Event producers may typically - but not necessarily - run in contexts different from those of the event-consuming applications.

Events are Shareable Interface Objects (SIO). They extend the `Event` class which implement the `SharedEvent` interface (which itself extends the `Shareable` interface). Events are uniquely identified by Event URIs.

Event-consuming applications interested in a particular event must register `EventListener` objects in the registry for the URI of that event. When the event is fired, the registered event listeners are all notified. An event-producing application may notify registered listeners of a particular event by calling the `notify` method of the event registry.

Application-defined events are named relatively to their application's event root URI. An application cannot fire an event under a URI not rooted in its own namespace. An application, if authorized, may fire an event under the standard event namespace rooted at `event:///standard/`. This namespace defines a set of event URIs for common, well-defined events - such as the application lifecycle event: `event:///standard/app/created`. Events fired by the Java Card runtime environment are rooted in the platform event namespace rooted at `event:///platform/` - such as the platform clock resynchronization event: `event:///platform/clock/resynced`.

The registry ensures that event listener 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 event listeners.

An event listener remains registered until it is removed from the registry by the application that registered it or when that application is deleted.

Event URIs passed as parameter to the registry methods may be absolute or relative. These URIs are canonicalized, that is resolved then normalized.
If an event URI is absolute, its URI scheme must be "event". For example, `event:///transit/pos/ticketbook/overdraft` is a valid absolute URI. If an event URI is relative, it is resolved against the application's event root URI (or the designated source's event root URI). For example, the relative event URI `ticketbook/overdraft` may be resolved to `event:///transit/pos/ticketbook/overdraft` in the context of the application `///transit/pos`.
Event URIs used for registration (registering and unregistering) may be exact URI patterns which designate individual events or path-prefix URI patterns ending with a "/*" which may designate collections of events. For example, `event:///transit/pos/ticketbook/overdraft` designates exactly one event type, while `event:///transit/pos/*` designates all event types identified by a URI starting with `event:///transit/pos/`. Event notification does not support the use of path prefix event URI patterns.

Note that for an event URI with a deep path component there may be multiple possible legal sources. For example, `///transit/pos/ticketbook`, `///transit/pos` and `///transit` may all be legal source URIs for the event URI `event:///transit/pos/ticketbook/overdraft` even though only one may be valid at a particular time since application URIs can not overlapp. When registering for such an event URI without explicitly specifying the source URI (see `register(java.lang.String, javacardx.facilities.EventNotificationListener)`, the source URI is determined based on the installed applications and may change accordingly.

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

Event registry operations are subject to permission checks.

See Runtime Environment Specification for the Java Card Platform, Connected Edition , chapter 7 for details regarding the event notification framework.

Since:
  Java Card 3.0
See Also:
  `Event`, `SharedEvent`, `EventNotificationListener`, `EventRegistryPermission`

Field Summary
`static String` | `SOURCE_PLATFORM` The source URI for platform events.

Method Summary
`static EventRegistry` | `getEventRegistry()` Retrieves the event registry.
`Enumeration<EventNotificationListener>` | `list()` Lists all the listeners registered by the current application.
`void` | `notifyListeners(Event event)` Notifies all the listeners registered for events of the type of the provided event.
`void` | `notifyListeners(Event event, boolean noWait)` Notifies all the listeners registered for events of the type of the provided event.
`void` | `notifyListenersInRole(Event event, String role)` Notifies the listeners registered for events of the type of the provided event.
`void` | `notifyListenersInRole(Event event, String role, boolean noWait)` Notifies the listeners registered for events of the type of the provided event.
`void` | `register(String eventURI, EventNotificationListener listener)` Registers a listener for events of the specified type(s).
`void` | `register(String sourceURI, String eventURI, EventNotificationListener listener)` Registers a listener for events of the specified type(s) fired by the specified source(s).
`void` | `unregister(String eventURI, EventNotificationListener listener)` Unregisters the specified listener previously registered by the current application for events of the specified type.
`void` | `unregister(String sourceURI, String eventURI, EventNotificationListener listener)` Unregisters the specified listener previously registered by the current application for events of the specified type fired by the specified source(s).

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### SOURCE_PLATFORM

    public static final String SOURCE_PLATFORM

  The source URI for platform events.

  See Also:
    Constant Field Values

Method Detail

### getEventRegistry

    public static final EventRegistry getEventRegistry()

  Retrieves the event registry.

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

### register

    public void register(String sourceURI,
                         String eventURI,
                         EventNotificationListener listener)

  Registers a listener for events of the specified type(s) fired by the specified source(s).

  If the provided source URI is null, then the listener is registered for any legal source of the designated event.

  Before registration, the provided source URI is first canonicalized (resolved against the current application's root URI then normalized) then the provided event URI is canonicalized (resolved against the source's event root URI then normalized):

  - If the provided event URI is relative, it is resolved against the provided source's event root URI, if any.
  - If the provided event URI is relative, but the source's event root URI can not be determined, such as because the provided source URI designates a resource URI which is not rooted in the namespace of a currently instantiated application, registration will fail.
  - If the provided event URI is relative, and the provided source URI is null, the provided event URI is resolved against the current application's event root URI.
  If the provided event URI is absolute and rooted in an event namespace other than that of the current application, the implicit source URI is determined from the event URI.

  Note that if the provided source URI is a relative path URI, it will be resolved against the current application URI to another application URI. For example, the URI `admin` would be resolved to `///transit/admin` in the context of the application's `///transit/pos`.

  Parameters:
    `sourceURI` - the URI of the producing application or resource, or of the platform (may be null).
    `eventURI` - an exact or path-prefix event URI pattern designating a set of events.
    `listener` - the event listener.
  Throws:
    `SecurityException` -
    - if registration is not granted for the canonicalized event URI,
    - or, if the listener is not owned by the current application (or its group context).
    `NullPointerException` - if `eventURI` or `listener` is null.
    `IllegalArgumentException` -
    - if `sourceURI` is not null and is not a well-formed application, application's resource URI, or the platform URI,
    - or, if `eventURI` is not a well-formed event URI,
    - or, if `eventURI` is absolute and rooted in an event namespace that is not legal for the source designated by `sourceURI`,
    - or, if `eventURI` is relative and `sourceURI` is not null but the source's event root URI can not be determined.

### register

    public void register(String eventURI,
                         EventNotificationListener listener)

  Registers a listener for events of the specified type(s).

  The listener is registered for any legal source of the designated event.

  Before registration, the provided event URI is canonicalized (resolved against the current application's event root URI then normalized).

  If the provided event URI is absolute and rooted in an event namespace other than that of the current application, the implicit source URI is determined from the event URI.

  Calling this method is equivalent to calling `register(java.lang.String, java.lang.String, javacardx.facilities.EventNotificationListener)` with the `sourceURI` parameter set to `null`.

  Parameters:
    `eventURI` - an exact or path-prefix event URI pattern designating a set of events.
    `listener` - the event listener.
  Throws:
    `SecurityException` -
    - if registration is not granted for the canonicalized event URI,
    - or, if the listener is not owned by the current application (or its group context).
    `NullPointerException` - if `eventURI` or `listener` is null.
    `IllegalArgumentException` - if `eventURI` is not a well-formed event URI.

### list

    public Enumeration<EventNotificationListener> list()

  Lists all the listeners registered by the current application.

  Returns:
    an enumeration of all the listeners registered by the current application.

### notifyListeners

    public void notifyListeners(Event event)

  Notifies all the listeners registered for events of the type of the provided event.

  This method will returns only after all listeners have been notified.

  Parameters:
    `event` - the event.
  Throws:
    `SecurityException` -
    - if notification is not granted for the provided event's URI,
    - or, if the event's source does not correspond to the current application
    - or, if the event's URI is neither in the namespace of the current application nor in the standard event namespace,
    - or, if the event is not owned by the current application (or its group context).
    `NullPointerException` - if `event` is null.

### notifyListeners

    public void notifyListeners(Event event,
                                boolean noWait)

  Notifies all the listeners registered for events of the type of the provided event.

  Parameters:
    `event` - the event.
    `noWait` - true if this method must not block until all listeners have been notified, false otherwise
  Throws:
    `SecurityException` -
    - if notification is not granted for the provided event's URI,
    - or, if the event's source does not correspond to the current application,
    - or, if the event's URI is neither in the namespace of the current application nor in the standard event namespace,
    - or, if the event is not owned by the current application (or its group context).
    `NullPointerException` - if `event` is null.

### notifyListenersInRole

    public void notifyListenersInRole(Event event,
                                      String role)

  Notifies the listeners registered for events of the type of the provided event. Only notifies the listeners which are in the specified security role as can be determined by a call to `JCSystem.isClientInRole(java.lang.String, java.lang.String)`. This also includes the listeners of the current application and the other applications within the same group context (the current group context).

  This method will returns only after all listeners have been notified.

  Parameters:
    `event` - the event.
    `role` - the role name or null (e.g., any role) if all registered listeners are to be notified.
  Throws:
    `SecurityException` -
    - if notification is not granted for the provided event's URI,
    - or, if the event's source does not correspond to the current application,
    - or, if the event's URI is neither in the namespace of the current application nor in the standard event namespace,
    - or, if the event is not owned by the current application (or its group context).
    `NullPointerException` - if `event` is null.

### notifyListenersInRole

    public void notifyListenersInRole(Event event,
                                      String role,
                                      boolean noWait)

  Notifies the listeners registered for events of the type of the provided event. Only notifies the listeners which are in the specified security role as can be determined by a call to `JCSystem.isClientInRole(java.lang.String, java.lang.String)`. This also includes the listeners of the current application and the other applications within the same group context (the current group context).

  The role definition that applies is that of the current application.

  Roles and role membership can be defined using application descriptors.

  Parameters:
    `event` - the event.
    `role` - the role name or null (e.g., any role) if all registered listeners are to be notified.
    `noWait` - true if this method must not block until all listeners have been notified, false otherwise
  Throws:
    `SecurityException` -
    - if notification is not granted for the provided event's URI,
    - or, if the event's source does not correspond to the current application,
    - or, if the event's URI is neither in the namespace of the current application nor in the standard event namespace,
    - or, if the event is not owned by the current application (or its group context).
    `NullPointerException` - if `event` is null.

### unregister

    public void unregister(String sourceURI,
                           String eventURI,
                           EventNotificationListener listener)

  Unregisters the specified listener previously registered by the current application for events of the specified type fired by the specified source(s).

  Before unregistration, the provided source URI is first canonicalized (resolved against the current application's root URI then normalized) then the provided event URI is canonicalized (resolved against the source's event root URI then normalized):

  - If the provided event URI is relative, it is resolved against the provided source's event root URI, if any.
  - If the provided event URI is relative, but the source's event root URI can not be determined, such as because the provided source URI designates a resource URI which is not rooted in the namespace of a currently instantiated application, unregistration will fail.
  - If the provided event URI is relative, and the provided source URI is null, the provided event URI is resolved against the current application's event root URI.
  If the provided event URI is absolute and rooted in another application's event namespace, the implicit source URI is determined from the event URI.

  If `listener` is null, all listeners previously registered by the current application for events of the specified type fired by the specified application(s) are removed.

  Note that if the provided source URI is a relative path URI, it will be resolved against the current application URI to another application URI. For example, the URI `admin` would be resolved to `///transit/admin` in the context of the application's `///transit/pos`.

  Note also that for a particular listener to be unregistered, the source URI provided for unregistration through the `sourceURI` parameter must match exactly the explicit source URI provided at registration through the `sourceURI` parameter of the `register` method.

  Parameters:
    `sourceURI` - the URI of the producing application or resource, or of the platform (may be null).
    `eventURI` - an exact or path-prefix event URI pattern designating a set of events.
    `listener` - the event listener (may be null).
  Throws:
    `SecurityException` -
    - if unregistration is not granted for the canonicalized event URI,
    - or, if the listener is not owned by the current application (or its group context).
    `NullPointerException` - if `eventURI` is null.
    `IllegalArgumentException` -
    - if `sourceURI` is not null and is not a well-formed application, application's resource URI, or the platform URI,
    - or, if `eventURI` is not a well-formed event URI,
    - or, if `eventURI` is relative and `sourceURI` is not null but the source's event root URI can not be determined,
    - or, if `eventURI` is absolute and rooted in an event namespace not legal for the source designated by `sourceURI`.

### unregister

    public void unregister(String eventURI,
                           EventNotificationListener listener)

  Unregisters the specified listener previously registered by the current application for events of the specified type.

  Before unregistration, the provided event URI is canonicalized (resolved against the current application's event root URI then normalized).

  If the provided event URI is absolute and rooted in another application's event namespace, the implicit source URI is determined from the event URI.

  If `listener` is null, all listeners previously registered by the current application for events of the specified type are removed.

  Calling this method is equivalent to calling `unregister(java.lang.String, java.lang.String, javacardx.facilities.EventNotificationListener)` with the `sourceURI` parameter set to `null`.

  Parameters:
    `eventURI` - an exact or path-prefix event URI pattern designating a set of events.
    `listener` - the event listener (may be null).
  Throws:
    `SecurityException` -
    - if unregistration is not granted for the canonicalized event URI,
    - or, if the listener is not owned by the current application (or its group context).
    `NullPointerException` - if `eventURI` is null.
    `IllegalArgumentException` - if `eventURI` is not a well-formed event URI.

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.