|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavacardx.facilities.EventRegistry
@TransactionType(value=NOT_SUPPORTED) public final class EventRegistry
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.
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 |
---|
public static final String SOURCE_PLATFORM
Method Detail |
---|
public static final EventRegistry getEventRegistry()
public void register(String sourceURI, String eventURI, EventNotificationListener listener)
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):
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
.
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.
SecurityException
- NullPointerException
- if eventURI
or listener
is null.
IllegalArgumentException
- sourceURI
is not null and is not a
well-formed application, application's resource URI, or
the platform URI,eventURI
is not a well-formed event URI,eventURI
is absolute and rooted in an
event namespace that is not legal for the source
designated by sourceURI
, eventURI
is relative and sourceURI
is not null but the source's event root URI can not be determined.public void register(String eventURI, EventNotificationListener listener)
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
.
eventURI
- an exact or path-prefix event URI pattern designating a set of
events.listener
- the event listener.
SecurityException
- NullPointerException
- if eventURI
or listener
is null.
IllegalArgumentException
- if eventURI
is not a well-formed event URI.public Enumeration<EventNotificationListener> list()
public void notifyListeners(Event event)
This method will returns only after all listeners have been notified.
event
- the event.
SecurityException
- NullPointerException
- if event
is null.public void notifyListeners(Event event, boolean noWait)
event
- the event.noWait
- true if this method must not block until all listeners have
been notified, false otherwise
SecurityException
- NullPointerException
- if event
is null.public void notifyListenersInRole(Event event, String role)
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.
event
- the event.role
- the role name or null (e.g., any role) if all registered
listeners are to be notified.
SecurityException
- NullPointerException
- if event
is null.public void notifyListenersInRole(Event event, String role, boolean noWait)
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.
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
SecurityException
- NullPointerException
- if event
is null.public void unregister(String sourceURI, String eventURI, EventNotificationListener listener)
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 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.
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).
SecurityException
- NullPointerException
- if eventURI
is null.
IllegalArgumentException
- sourceURI
is not null and is not a
well-formed application, application's resource URI, or
the platform URI,eventURI
is not a well-formed event URI,eventURI
is relative and sourceURI
is not null but the source's event root URI can not be determined,eventURI
is absolute and rooted in an event namespace not
legal for the source designated by sourceURI
.public void unregister(String eventURI, EventNotificationListener listener)
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
.
eventURI
- an exact or path-prefix event URI pattern designating a set of
events.listener
- the event listener (may be null).
SecurityException
- NullPointerException
- if eventURI
is null.
IllegalArgumentException
- if eventURI
is not a well-formed event URI.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |