EventManager (Mobile Information Device Profile 3.0)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

MIDP3.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.microedition.event
Class EventManager

java.lang.Object
  javax.microedition.event.EventManager

public final class EventManager
extends java.lang.Object
extends java.lang.Object

The EventManager class provides methods to post and listen for events, to determine the events supported by the device, and to register applications to be automatically launched in response to events. The system publishes some events and applications publish other events.

Each event has a name, a value, and may contain an informational message and extra information about the event. When an event is posted it is given a timestamp and the identity of the MIDlet, if any, that posted it. See the EventData class for the definition of events.

Event Naming Conventions

The EventData class defines a set of commonly available system events. Individual devices may also support unique system events in addition to those defined in EventData. Event names are limited to the characters allowed by the Java Language Specification [JLS] for identifiers. Event names are case sensitive; for example, "COM.SUN" and "com.sun" are different names. In order to avoid name collisions names defined by applications and specific implementations SHOULD use the common reverse domain notation and SHOULD contain at least one ".". For example com.YourCompanyName.SomeCustomEvent.

When registering and unregistering listeners and for application launch, events may be requested using a prefix and an optional single final asterisk "*". The prefix must be at least 1 character long. For example, the pattern "com.mot.*" will match any and all event names that begin with "com.mot.".

Security of the Event API

Some events may convey privileged information to the application and therefore the application must have the appropriate permission to access such events. Additionally, the ability to post events or to register applications to launch automatically on events must be restricted to applications with the appropriate permissions. See the EventPermission class for more details.

Application Level Access Authorization

It is possible to limit operations on the events by using the application level access restrict mechanism as described in "Application Level Access Authorization" section. The following restrictions can be done by setting the authmode to true and by using the application level access authorization:

Only authorized source post events and notify listeners
Only authorized source can launch applications
Only authorized recipient can receive an event

See more details in the next sections.

Event Posting and Notification of Listeners

All events posted MUST be delivered to all valid recipients in each runtime environment on the device that implements this specification. The recipients register themselves to receive the events with addEventListener methods. The event API is asynchronous, events are delivered via a listener and event posts MUST NOT block the application execution. Each event MUST be delivered to each listener exactly once. Each event MUST successfully launch the application only once. An event matches a recipient if all of the following are true:

The event name MUST match the event name for addEventListener or registerApplication including wildcards.
The type of the event value MUST match the type of the value requested for addEventListener or registerApplication.
The source MUST permit delivery to the recipient and the recipient MUST accept delivery from a source by fulfilling the requirements set forth:
1. The event was posted with authmode equal false or the event was posted with authmode equals true and the recipient is authorized and
2. The recipient was requested with authmode equal false or the event was posted with authmode equals true and the source is authorized.
The event value must match the conditions, if any, specified by addEventListener or registerApplication.

Events that are not matched to a recipient are silently discarded. This includes the case if authorization of the source or recipient fails.

Events are discarded after they delivered to all the valid recipients. If no valid recipients can be identified the event is discarded immediately except in the case that an event caused the launch of an application the event MUST be retained until the application returns from the MIDlet.startApp method. This insures that the application is given a chance to listen for the event before the event is discarded. Once the listener has been registered the event is retained until it can be delivered to the listener.

For system events, as soon as a listener is added or an application is registered to be launched the current value is checked. If the current value is matched, the listener MUST be immediately notified or the application is launched. Performing the match in addEventListener and registerApplication removes a race condition that could exist between those actions and the application needing to poll the current value and check the condition.

Application Launch on Events

Applications may be launched automatically in response to events. The registration is done with registerApplication methods. The application will not be launched if it is already running. The application will be launched when the event value matches the requested value and the authmode constraints are fulfilled. Otherwise the application will not be launched. An application can register to launch on a particular event either via static jar attribute or dynamically through methods in the EventManager class.

Static Registration of Launch on Event Handlers

Static registration to application launch on events is done by adding the MIDlet-Event-Launch-<n> attribute to the JAR Manifest. The attribute consists of the class name of the application to be launched followed by the authorization mode used to check the source of the events followed an optional launch condition that MUST cause the application to be launched. For boolean and String type events the launch condition may consist of just the event name in which case the application will be launched on any change to the event.

Static registration of launch on event occurs during installation of the MIDlet suite or during a re-installation (update). If the MIDlet suite is being updated (re-installed), then any pre-existing registrations, both static and dynamic, for launching the MIDlet suite MUST be removed. Multiple MIDlet-Event-Launch attributes can used to register launch on several event requests. If the implementation does not have the resources to register all of the requested launch requests the installation MUST fail with Status Code 901 (Insufficient Memory).

If the application does not have EventPermission with the name equal to the event name and action equal to "register", the installation MUST fail with Status Code 910 (Application authorization failure).

If an attempt is made to register an application for an event that is not supported by the device, or if an invalid value is requested, or if an inappropriate launch condition format is specified, then the installation MUST proceed without registering the application for the event.

The Jar Manifest attribute is defined as follows:

MIDlet-Event-Launch-<n>:<Classname>;<AuthorizationMode>;<Launch-Condition>

Where:

MIDlet-Event-Launch-<n> = The application launch registration attribute name. The value of <n> starts at 1 and MUST use consecutive ordinal numbers for additional application launch registrations. The first missing entry terminates the list. Any additional entries are ignored.
Classname = The fully-qualified name of the class to launch; must refer to a valid application for the current profile. For MIDP, the class must implement MIDlet found in the current MIDlet suite.
AuthorizationMode = The Authorization mode specified using authmode = true|false. If authmode is true, only events from source applications that are authenticated using the access authorization mechanism are allowed to launch this application. If authmode is false, any source application that generates an event that satisfies the Launch-Condition is allowed to launch this application.

Launch-Condition = The condition that should cause the application to be launched. Each MIDlet-Event-Launch-<n> attribute may include zero or one launch conditions. If one or more of the launch events is matched, then the application MUST be launched. Each launch condition MUST be of one of the following forms :

Event Type	Launch-Condition Format
`boolean`	`<Event-Name>[=”true”\|”false” ]`
`string`	`<Event-Name>[= ‘"’<String-Event-Value>‘"’ [ , ‘"’<String-Event-Value>‘"’ ]*`
`integer or long`	`<Event-Name>=<Long-Event-Value>,<Long-Event-Value>`
`float or double`	`<Event-Name>=<Double-Event-Value>,<Double-Event-Value>`

Where:

Whitespace is ignored before and after the delimiters quote "=", semi-colon ";", and comma ",".
Event-Name = The name of the event on which to launch the application.
String-Event-Value = The optional event value of interest. The application will be launched if the event value is equal to this value. The event value is quoted and can not contain a quote.
Long-Event-Value = The application will be launched if the event value falls within the range between the low and high values (inclusive). The value must contain only characters valid for Long Literals as defined by the Java Language Specification [JLS] and are accepted by the java.lang.Long.valueOf method.
Double-Event-Value = The application will be launched if the event value falls within the range between the low and high values (inclusive). The value must contain only characters valid for Floating Point Literals as defined by the Java Language Specification [JLS] and are accepted by the java.lang.Double.valueOf method.

Note: Care should be taken when registering applications to launch on events that change often as frequent attempts to launch the application may negatively impact performance. The implementation may limit the launch frequency to avoid degrading device performance or battery lifetime.

Example

  MIDlet-Name: SystemUtilities
  MIDlet-Version: 1.0.1
  MIDlet-Vendor: FictionalCo
  MIDlet-1: UsageMonitor, /usemnt.png, com.fictionalco.UsageMonitor
  MIDlet-2: PowerManager, /pwrmgt.png, com.fictionalco.PowerMgr
  MIDlet-Event-Launch-1: com.fictionalco.UsageMonitor;authmode=false;SYSTEM_STATE="STARTUP"
  MIDlet-Event-Launch-2: com.fictionalco.PowerMgr;authmode=false;BATTERY_LEVEL=5,100
  MicroEdition-Profile: MIDP-3.0
  MicroEdition-Configuration: CLDC-1.1
  MIDlet-Description: Useful system utilities
  MIDlet-Jar-URL: http://www.fictionalco.com/SysUtils.jar

Dynamic Registration of Launch on Event Handlers

In addition to statically registering an application to launch in response to events through appropriate entries in the Jar Manifest, an application can dynamically register applications using the registerApplication methods.

The implementation MUST support at least five (5) launch registrations whether registered via MIDlet-Event-Launch-<n> attributes or the API.

Code Examples

Querying a System Event Value

The application must first get an instance of EventManager. The EventManager.getCurrent method is then called to get an EventData object for the desired system event. The application must have the required permission to query the requested system event or a SecurityException will be thrown. The appropriate getXXX method may then be called to get the current event.

       EventManager ssm = EventManager.getInstance(this);
       try {
           battery = ssm.getCurrent(BATTERY_LEVEL);
       } catch (SecurityException e) {
           ...
       }
       batteryLevel = battery.getInt();

Adding an Event Listener

The application must first get an instance of EventManager. The EventManager.addListener method is called to add the listener using system event or the application event name. The application must have the required permission to query the requested event or a SecurityException will be thrown.

       EventData battery;
       boolean authmode = false;
       EventManager ssm = EventManager.getInstance(this);

       // Receive events at 10% and 20% battery level
       ssm.addEventListener(BATTERY_LEVEL, this, authmode, 10, 20);

       // Also receive events at 90% and 100% battery level
       ssm.addEventListener(BATTERY_LEVEL, this, authmode, 90, 100);

       // Listen for login/logout application events
       ssm.addEventListener("com.foo.UserLogin", this, authmode);
       ssm.addEventListener("com.foo.UserLogout, this, authmode);

Handling an Event

The application had previously registered this object as a listener for multiple events and has implemented the EventDataListener.handleEvent method as follows.

      handleEvent(EventData event) {
          String  eventName = event.getName();
          int     batteryLevel;
          boolean bodyOpen;

          if (eventName.equals(BATTERY_LEVEL)) {
              batteryLevel = event.getInt();
          } else if (eventName.equals(BODY_OPEN)) {
              bodyOpen = event.getBoolean();
          } else if (eventName.equals("com.foo.Login")) {
              String user = event.getString();
              MIDletIdentity source = event.getSourceInfo();
               // check if the source is access authorized 
              boolean authmode = source.isAuthorized();
              ...
          }
      }

Posting an Event

The application must first get an instance of EventManager. An EventData object must then be created using the appropriate constructor. The EventManager.post method is called to send the event.The application must have the appropriate permission to post the event or a SecurityException will be thrown.

      String username = "user1";
      EventManager ssm = EventManager.getInstance(this);

      EventData login = new EventData("com.foo.UserLogin", "User Login",
          username, null);
      EventData appState = new EventData("APPLICATION_STATUS", "IDLE",
          "The app is idle", null);
      try {
          ssm.post(login);
          ssm.post(appState);
      } catch (SecurityException e) {
          ...
      }

Registering an Application to Launch on Events

The application must first get an instance of EventManager. The appropriate registerApplication method is then called to register to be launched on the event.

       EventData battery;
       boolean authmode = false;
       EventManager ssm = EventManager.getInstance(this);

       try {
           // Launch the application if the battery level drops below 10%
           ssm.registerApplication(BATTERY_LEVEL, "com.fictionalco.PowerMgr", authmode, 0, 10);
       } catch (SecurityException e) {
           ...
       }

Since:: MIDP 3.0

Method Summary
`void`	`addEventListener(java.lang.String event, EventDataListener listener, boolean authmode)` Add an `EventListener` to be notified.
`void`	`addEventListener(java.lang.String event, EventDataListener listener, boolean authmode, boolean value)` Add an event listener to be notified of events with `boolean` values.
`void`	`addEventListener(java.lang.String event, EventDataListener listener, boolean authmode, double low, double high)` Add an event listener to be notified of an event represented by `double` values.
`void`	`addEventListener(java.lang.String event, EventDataListener listener, boolean authmode, long low, long high)` Add an event listener to be notified of an event represented by `int` or `long` values.
`void`	`addEventListener(java.lang.String event, EventDataListener listener, boolean authmode, java.lang.String[] values)` Add an event listener to be notified of an event represented by `String` values.
`EventData`	`getCurrent(java.lang.String event)` Returns an `EventData` object for the requested system event.
`static EventManager`	`getInstance()` Returns the instance of `EventManager`.
`java.lang.String[]`	`getSystemEvents()` Returns a `String` array containing the names of all the system events available on the device.
`void`	`post(EventData event, boolean authmode)` Post an event.
`void`	`registerApplication(java.lang.String event, java.lang.String application, boolean authmode)` Register an application to be launched on an event.
`void`	`registerApplication(java.lang.String event, java.lang.String application, boolean authmode, boolean value)` Register an application to be launched in response to an event represented by a `boolean` values.
`void`	`registerApplication(java.lang.String event, java.lang.String application, boolean authmode, double low, double high)` Register an application to be launched in response to an event represented by a `double` value.
`void`	`registerApplication(java.lang.String event, java.lang.String application, boolean authmode, long low, long high)` Register an application to be launched in response to an event represented by an `int` or `long` value.
`void`	`registerApplication(java.lang.String event, java.lang.String application, boolean authmode, java.lang.String[] values)` Register an application to be launched in response to a event represented by a `String` value.
`void`	`removeEventListener(java.lang.String event, EventDataListener listener)` Removes an event listener for the named event(s) including wildcards.
`void`	`unregisterApplication(java.lang.String event, java.lang.String application)` Unregister an application from launching in response to an event.

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

Method Detail

getInstance

public static EventManager getInstance()

Returns the instance of EventManager.

Returns:: The instance of EventManager.

getSystemEvents

public java.lang.String[] getSystemEvents()

Returns a String array containing the names of all the system events available on the device. Application specific event names are not listed.

Returns:: A String array containing the names of all the system events available.
See Also:: EventData, getCurrent(String)

getCurrent

public EventData getCurrent(java.lang.String event)

Returns an EventData object for the requested system event.

Parameters:: event - The name for the event.
Returns:: An EventData object for the requested system event; or null if there the requested name is not a known system event as returned from getSystemEvents().
Throws:: java.lang.SecurityException - If the application does not have EventPermission with the name equal the event name and action equals "read".; java.lang.NullPointerException - If event is null.
See Also:: EventData, EventPermission, getSystemEvents()

post

public void post(EventData event,
                 boolean authmode)
          throws java.io.IOException

Post an event. The event is posted and the method MUST NOT wait for the event to be delivered. The event MUST be delivered to any recipient that matches the event.

If the name of the event is recognized by the system the value provided MUST match the value type for the event. The time from java.lang.System.currentTimeMillis initializes the value of the EventData.getTimestamp method. The implementation sets the event source to be the calling MIDlet.

Parameters:: event - The event to post. The contents of the EventData object are the value for the event.; authmode - If true, the event MUST only be delivered to authorized recipients. If false, the events MUST be delivered to any matching recipient.
Throws:: java.lang.NullPointerException - If event is null.; java.lang.IllegalArgumentException - If event names an event for which the type is known to the system and the value provided does not match.; java.lang.SecurityException - If the application does not have the EventPermission with the name equal the event name and action equals "post"; or if the event name is one of those returned by getSystemEvents() and the application does not have the EventPermission with the name equal the event name and action equals "postsystem".; java.io.IOException - If there are insufficient resources to retain the EventData until it can be delivered to all listeners. Refer to EventData for the minimum size the MUST be supported.
See Also:: EventData, EventPermission

addEventListener

public void addEventListener(java.lang.String event,
                             EventDataListener listener,
                             boolean authmode)

Add an EventListener to be notified. The listener will be notified for changes in every known event that matches the requested name and authorization mode.

If the listener is removed using removeEventListener then it will no longer be notified.

Parameters:: event - The event(s) for which the listener will be added; if event contains a final "*", the listener will match any event name with identical prefix (without the "*").; listener - The listener to add.; authmode - If true, check if the source of event is authorized as specified by the MIDlet's access authorization attributes. Authorized sources are allowed to notify the listener. If false, events irrespective of source are allowed to notify the listener.
Throws:: java.lang.NullPointerException - If listener or event is null; java.lang.SecurityException - If the application does not have EventPermission with the name equal the event name and action equals "read".
See Also:: EventData, removeEventListener(String, EventDataListener)

addEventListener

public void addEventListener(java.lang.String event,
                             EventDataListener listener,
                             boolean authmode,
                             boolean value)

Add an event listener to be notified of events with boolean values. The listener will be called when the value changes to the requested value. The listener will be called immediately for every known event that matches the requested name, value, and authorization mode.

If the listener is removed using removeEventListener then it will no longer be notified.

Parameters:: event - The event(s) for which the listener will be added; if event contains a final "*", the listener will match any event name with identical prefix (without the "*").; listener - The listener to add.; authmode - If true, check if the source of event is authorized as specified by the MIDlet's access authorization attributes. Authorized sources are allowed to notify the listener. If false, events irrespective of source are allowed to notify the listener.; value - The event value for which the listener should be notified.
Throws:: java.lang.NullPointerException - If listener or event is null; java.lang.IllegalArgumentException - If the named event is a system event and is known not to be a boolean event.; java.lang.SecurityException - If the application does not have EventPermission with the name equal the event name and action equals "read".
See Also:: EventData, addEventListener(String, EventDataListener, boolean)

addEventListener

public void addEventListener(java.lang.String event,
                             EventDataListener listener,
                             boolean authmode,
                             java.lang.String[] values)

Add an event listener to be notified of an event represented by String values. The listener will be notified if the event contains one of the requested values. The listener will be called immediately for every known value that matches the requested name, value, and authorization mode.

If the listener is removed using removeEventListener then it will be removed for all values and will no longer be notified.

Parameters:: event - The event(s) for which the listener will be added; if event contains a final "*", the listener will match any event name with identical prefix (without the "*").; listener - The listener to add.; authmode - If true, check if the source of event is authorized as specified by the MIDlet's access authorization attributes. Authorized sources are allowed to notify the listener. If false, events irrespective of source are allowed to notify the listener.; values - The event values for which the listener should be notified.
Throws:: java.lang.NullPointerException - If listener or events is null.; java.lang.IllegalArgumentException - If values contain strings that are not valid for the event or if the named event is a system event and is known not to be a String event.; java.lang.SecurityException - If the application does not have EventPermission with the name equal the event name and action equals "read".
See Also:: EventData, removeEventListener(String, EventDataListener)

addEventListener

public void addEventListener(java.lang.String event,
                             EventDataListener listener,
                             boolean authmode,
                             double low,
                             double high)

Add an event listener to be notified of an event represented by double values. The listener will be notified when the value falls within the range between the low and high values (inclusive). A listener may be added repeatedly using different ranges of values but will be notified only once for any single change. The listener will be called immediately for every known event that matches the requested name, value, and authorization mode.

If the listener is removed using removeEventListener then it will be removed for all ranges and will no longer be notified.

Parameters:: event - The event(s) for which the listener will be added; if event contains a final "*", the listener will match any event name with identical prefix (without the "*").; listener - The listener to add.; authmode - If true, check if the source of event is authorized as specified by the MIDlet's access authorization attributes. Authorized sources are allowed to notify the listener. If false, events irrespective of source are allowed to notify the listener.; low - The low end of the range of interest.; high - The high end of the range of interest.
Throws:: java.lang.NullPointerException - If listener or event is null.; java.lang.IllegalArgumentException - If high is less than low or if either low or high is NaN or outside the valid range for the event or if the named event is a system event and is known not to be a double event.; java.lang.SecurityException - If the application does not have EventPermission with the name equal the event name and action equals "read".
See Also:: EventData, removeEventListener(String, EventDataListener)

addEventListener

public void addEventListener(java.lang.String event,
                             EventDataListener listener,
                             boolean authmode,
                             long low,
                             long high)

Add an event listener to be notified of an event represented by int or long values. The listener will be notified when the value falls within the range between the low and high values (inclusive). A listener may be added repeatedly using different ranges of values but will be notified only once for any single event change. The listener will be called immediately for every known event that matches the requested name, value, and authorization mode.

If the listener is removed using removeEventListener then it will be removed for all ranges and will no longer be notified.

Parameters:: event - The event(s) for which the listener will be added; if event contains a final "*", the listener will match any event name with identical prefix (without the "*").; listener - The listener to add.; authmode - If true, check if the source of event is authorized as specified by the MIDlet's access authorization attributes. Authorized sources are allowed to notify the listener. If false, events irrespective of source are allowed to notify the listener.; low - The low end of the range of interest.; high - The high end of the range of interest.
Throws:: java.lang.NullPointerException - If listener or event is null.; java.lang.IllegalArgumentException - If high is less than low or if either low or high is outside the valid range of values for the event or if the named event is a system event and is known not to be an int event.; java.lang.SecurityException - If the application does not have EventPermission with the name equal the event name and action equals "read".
See Also:: EventData, removeEventListener(String, EventDataListener)

removeEventListener

public void removeEventListener(java.lang.String event,
                                EventDataListener listener)

Removes an event listener for the named event(s) including wildcards. For example, to remove notifications to the listener for all events call removeEventListener("*", listener). The listener will no longer be notified of any matching event. If the listener was added for multiple conditions then all of the conditions will be removed for the event and listener. If listener had not previously been added as a listener to the event then the request is ignored.

Parameters:: event - The event(s) for which the listener will be removed; if event contains a final "*", the listener will match any event name with identical prefix (without the "*").; listener - The listener to remove.
Throws:: java.lang.NullPointerException - If listener or event is null.
See Also:: EventData, addEventListener(String, EventDataListener, boolean)

registerApplication

public void registerApplication(java.lang.String event,
                                java.lang.String application,
                                boolean authmode)
                         throws java.lang.ClassNotFoundException,
                                java.io.IOException

Register an application to be launched on an event. An application can register multiple times with different events and values with each registration accumulating; duplicate registrations with the same input parameters will have no effect. The application MUST NOT be launched if it is already running.

If the application is unregistered using unregisterApplication then it will no longer be launched in response to the event.