javacardx.facilities
Class Event

java.lang.Object
  extended by java.util.EventObject
      extended by javacardx.facilities.Event
All Implemented Interfaces:
Shareable, SharedEvent

@TransactionType(value=NOT_SUPPORTED)
public class Event
extends EventObject
implements SharedEvent

The Event class is the base class for all events notified through the EventRegistry.

Each event is identified by an Event URI. Each event is also constructed with a reference to the application or application resource, the "source", which initially created and fired it. The source is identified with its URI: the source URI. A source URI can therefore be one of the followings:

Note that security restrictions apply when creating an Event object to prevent impersonation of other applications or of the platform. See Event(String, String, Object).

Note also that the source field of the superclass EventObject as can be retrieved using the EventObject.getSource() is not used to store the source URI. This field is always set at instantiation time with a reference to the EventRegistry singleton instance.

This class may be subclassed to encapsulate state specific to the occurring conditions. Direct instances of this class can be used to notify of events that do not encapsulate domain-specific information and behavior. When an event object must encapsulate domain-specific information and behavior a new event object class must be defined by extending this Event base class.

Note though that this class provides a generic means for some auxiliary (e.g., The actual semantics of the data bound to the event (if any) may be specific to the event and should be documented on a per-event type basis.

Only the methods defined in the SharedEvent interface this class implements and in Shareable interfaces implemented by its subclasses are accessible to event-consuming applications running in other contexts than the context from which an Event object was created and fired.

The String instances returned by the methods getURI() and getSourceURI() are bound to the same owner context as that of the calling object.

Platform Events

Platform events are events fired by the Java Card runtime environment to notify applications of specific platform conditions. Platform event URIs are rooted at event:///platform/. This platform event namespace defines a set of platform events that encapsulate specific Java Card RE conditions. This includes a card lifecycle event such as a real-time clock resynchronization.

A platform event URI designates one of the followings:

Creation and firing of platform events is restricted to the Java Card runtime environment.

Standard Events

Standard events are events fired by an application or by the Java Card runtime environment on behalf of an application to notify other applications of specific application and resource conditions. Standard event URIs are rooted at event:///standard/. This standard event namespace defines a set of event URIs for common, well-defined conditions. This includes standard application lifecycle events and standard resource lifecycle events.

Standard events may be fired by applications or application resources to notify other applications of specific application and resource lifecycle conditions such as an application or resource being created or deleted. For example, an application may fire a resource update event when a resource exposed through an SIO has been updated.

The Java Card runtime environment may fire standard events on behalf of an application or a resource; in which case the source of the event is not the platform but the application or the resource. For example, the Java Card runtime environment may fire an application creation event when an application has been created and has been assigned an application URI.

Standard application lifecycle event URIs are rooted at event:///standard/app/. A standard application lifecycle event URI designates one of the followings:

Firing such standard application lifecycle events may be restricted to the Java Card runtime environment and privileged applications such as card management applications.

Standard resource lifecycle event URIs are rooted at event:///standard/rsrc/. A standard resource lifecycle event URI designates one of the followings:

See Runtime Environment Specification for the Java Card Platform, Connected Edition , chapter 8 for details regarding card management and application lifecycle events.

Application-defined Events

An application may define events in its own event namespace. Application-defined events are named relatively to their application's root event URI. For example, if an application URI is ///transit/pos, the application’s event root URI is event:///transit/pos and a well-formed event URI could be event:///transit/pos/ticketbook/overdraft.

Since:
Java Card 3.0
See Also:
SharedEvent, EventNotificationListener

Field Summary
static String EVENT_CLOCK_RESYNCED_URI
          The canonical clock resynchronization event URI (platform event).
static String EVENT_STANDARD_APP_CREATED_URI
          The canonical standard application creation event URI.
static String EVENT_STANDARD_APP_DELETED_URI
          The canonical standard application deletion completion event URI.
static String EVENT_STANDARD_APP_DELETING_URI
          The canonical standard application deletion start event URI.
static String EVENT_STANDARD_RSRC_CREATED_URI
          The canonical standard resource creation event URI.
static String EVENT_STANDARD_RSRC_DELETED_URI
          The canonical standard resource deletion event URI.
static String EVENT_STANDARD_RSRC_UPDATED_URI
          The canonical standard resource update event URI.
 
Fields inherited from class java.util.EventObject
source
 
Constructor Summary
Event(String eventURI)
          Creates an Event object identified by the provided URI.
Event(String eventURI, Object data)
          Creates an Event object identified by the provided URI.
Event(String sourceURI, String eventURI, Object data)
          Creates an Event object identified by the provided event URI and whose source will be set to the provided application-rooted source URI (an application URI or an application's resource URI).
 
Method Summary
 Object getData()
          Returns the auxiliary (e.g., application-defined) data.
 String getSourceURI()
          Returns the (canonical) URI of the application or resource which fired this event.
 String getURI()
          Returns this event's (canonical) URI.
 
Methods inherited from class java.util.EventObject
getSource, toString
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

EVENT_CLOCK_RESYNCED_URI

public static final String EVENT_CLOCK_RESYNCED_URI
The canonical clock resynchronization event URI (platform event).

See Also:
Constant Field Values

EVENT_STANDARD_APP_CREATED_URI

public static final String EVENT_STANDARD_APP_CREATED_URI
The canonical standard application creation event URI.

See Also:
Constant Field Values

EVENT_STANDARD_APP_DELETED_URI

public static final String EVENT_STANDARD_APP_DELETED_URI
The canonical standard application deletion completion event URI.

See Also:
Constant Field Values

EVENT_STANDARD_APP_DELETING_URI

public static final String EVENT_STANDARD_APP_DELETING_URI
The canonical standard application deletion start event URI.

See Also:
Constant Field Values

EVENT_STANDARD_RSRC_CREATED_URI

public static final String EVENT_STANDARD_RSRC_CREATED_URI
The canonical standard resource creation event URI.

See Also:
Constant Field Values

EVENT_STANDARD_RSRC_UPDATED_URI

public static final String EVENT_STANDARD_RSRC_UPDATED_URI
The canonical standard resource update event URI.

See Also:
Constant Field Values

EVENT_STANDARD_RSRC_DELETED_URI

public static final String EVENT_STANDARD_RSRC_DELETED_URI
The canonical standard resource deletion event URI.

See Also:
Constant Field Values
Constructor Detail

Event

public Event(String eventURI)
Creates an Event object identified by the provided URI. The provided event URI is canonicalized (resolved against the current application's event root URI then normalized).

Parameters:
eventURI - the URI of this event.
Throws:
NullPointerException - if eventURI is null.
SecurityException -
  • if eventURI is not in the current application's event namespace or in the standard event namespace (especially, if eventURI is in the platform event namespace),
  • if eventURI is not accessible in the caller's context.
IllegalStateException - if the source URI cannot be determined such as when its's an applet and the Applet.register() method has not yet been invoked.
IllegalArgumentException -
  • if eventURI is not a well-formed event URI,
  • or, if eventURI is in the standard application or resource event namespace but is not one of the standard event URIs defined above.

Event

public Event(String eventURI,
             Object data)
Creates an Event object identified by the provided URI. The provided event URI is canonicalized (resolved against the current application's event root URI then normalized). The provided data is set in this event state. Developers must account for context isolation and should typically provide data in the form of an SIO or an "implicitly transferable" object.

Parameters:
eventURI - the URI of this event.
data - the auxiliary data (may be null).
Throws:
NullPointerException - if eventURI is null.
SecurityException -
  • if eventURI is not in the current application's event namespace or in the standard event namespace (especially, if eventURI is in the platform event namespace),
  • if eventURI is not accessible in the caller's context.
IllegalStateException - if the source URI cannot be determined such as when its's an applet and the Applet.register() method has not yet been invoked.
IllegalArgumentException -
  • if eventURI is not a well-formed event URI,
  • or, if eventURI is in the standard application or resource event namespace but is not one of the standard event URIs defined above.

Event

public Event(String sourceURI,
             String eventURI,
             Object data)
Creates an Event object identified by the provided event URI and whose source will be set to the provided application-rooted source URI (an application URI or an application's resource URI). The provided source and event URIs are canonicalized (resolved against the current application's root URI and application's event root URI, respectively, then normalized). The provided data is set in this event state. Developers must account for context isolation and should typically provide data in the form of an SIO or an "implicitly transferable" object.

Note that the source URI should typically be either the current application's URI or an absolute resource URI rooted in the current application's namespace. If a relative URI other than the current application's URI is provided, it will be resolved to an other application URI which will be illegal.

Parameters:
sourceURI - the URI of this event's source
eventURI - the URI of this event.
data - the auxiliary data (may be null).
Throws:
SecurityException -
  • if sourceURI is not in the current application's namespace (such as if sourceURI is not the current application's URI or an absolute resource URI rooted in the current application's namespace),
  • or, if eventURI is not in the current application's event namespace or in the standard event namespace (especially, if eventURI is in the platform event namespace),
  • if sourceURI or eventURI is not accessible in the caller's context.
NullPointerException - if sourceURI or eventURI is null.
IllegalArgumentException -
  • if sourceURI is not a well-formed application URI or application's resource URI,
  • or, if eventURI is not a well-formed event URI,
  • or, if eventURI is in the standard application or resource event namespace but is not one of the standard event URIs defined above.
Method Detail

getSourceURI

public final String getSourceURI()
Returns the (canonical) URI of the application or resource which fired this event.

Specified by:
getSourceURI in interface SharedEvent
Returns:
the source application or resource's URI or EventRegistry.SOURCE_PLATFORM if the event is a platform event.

getURI

public final String getURI()
Returns this event's (canonical) URI.

Specified by:
getURI in interface SharedEvent
Returns:
this event's URI

getData

public final Object getData()
Returns the auxiliary (e.g., application-defined) data. Developers must account for context isolation and should typically provide data in the form of an SIO or an "implicitly transferable" object.

Specified by:
getData in interface SharedEvent
Returns:
the auxiliary data, or null if no auxiliary data was set.


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