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

    java.lang.Object
      java.util.EventObject
          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:

- An application URI.
- An application's resource URI, a URI which designates a resource inside the namespace of the application's that fires it, such as a file resource URI. There is no constraint on the URI scheme.
- The reserved `/platform` or `///platform` URI that identifies the platform in the case of platform events.

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:

- a clock resynchronization event: `event:///platform/clock/resynced` (see `EVENT_CLOCK_RESYNCED_URI`).
  This event may be fired subsequently to a call to `JCSystem.synchronizeTime()`. The time delta associated to the clock resynchronization event may be set and retrieved from the auxiliary event data as a `Long` object.
- Definition of additional platform event URIs is reserved to the Java Card specifications.

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:

- an application creation event: `event:///standard/app/created` (see `EVENT_STANDARD_APP_CREATED_URI`)
- an application deletion completion event: `event:///standard/app/deleted` (see `EVENT_STANDARD_APP_DELETED_URI`)
- an application deletion start event: `event:///standard/app/deleting` (see `EVENT_STANDARD_APP_DELETING_URI`)
- Definition of additional standard application event URIs is reserved to the Java Card specifications.

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:

- a resource creation event: `event:///standard/rsrc/created` (see `EVENT_STANDARD_RSRC_CREATED_URI`)
- a resource update event: `event:///standard/rsrc/updated` (see `EVENT_STANDARD_RSRC_UPDATED_URI`)
- a resource deletion event: `event:///standard/rsrc/deleted` (see `EVENT_STANDARD_RSRC_DELETED_URI`)
- Definition of additional standard resource event URIs is reserved to the Java Card specifications.

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.

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.