javacardx.facilities
Class EventRegistry

java.lang.Object
  extended by 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.

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 application(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 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 (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 or application's resource 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 application(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 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.

Parameters:
sourceURI - the URI of the producing application or resource (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 or application's resource 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.

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.


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