Just An Application

December 11, 2009

What’s New In MIDP 3.0: Redux – Events

Filed under: Java, JME, MIDP, MIDP3, MIDP3EventAPI — Tags: , , , , — Simon Lewis @ 3:27 pm

Original Post

Changes Since Proposed Final Draft

New EventPermission Action

The class javax.microedition.event.EventPermission now supports
the

    postsystem

action.

An EventPermission with the postsystem action is required to post any event, using the EventManager.post(EventData, boolean) method, if it is a system event.

A system event is any event whose name is contained in the result returned by a call to the EventManager.getSystemEvents() method.

This makes it much easier to prevent unidentified third-party MIDlets from posting fake SYSTEM_STATE events for example.

Issues

EventData.getDouble()

If the EventData value is a String then this method is defined to return the result of calling the method

    java.lang.Double.parseDouble(String)

Both CLDC and CDC define this method in terms of the

    java.lang.Double.valueOf(String)

method.

The format supported by the CLDC version of the method is defined as


    FloatValue:

        Signopt FloatingPointLiteral

The format supported by the CDC version of the method is defined as


    FloatValue:

        Signopt NaN
        Signopt Infinity
        Signopt FloatingPointLiteral

In each case the definition of FloatingPointLiteral is that in the JLS.

Hence the EventData.getDouble() method will behave differently when running on CLDC and CDC if the value is the String Infinity or NaN.

This is a minor point but it would have been very easy to fix.

EventData.getFloat()

Analagously to the getDouble() method, this method is defined in terms of the

    java.lang.Float.parseFloat(String)

method.

The CLDC version of this method does not explicitly specify what format(s) it supports. The CDC version is defined in terms of the method

    java.lang.Float.valueOf(String)

which supports the same format as the Double version.

Depending on the format supported by the CLDC implementation the EventData.getFloat() method may or may not suffer from the same problem as EventData.getDouble().

Again, this is a minor point but it would have been very easy to fix.

In addition the documentation contradicts itself. The table clearly shows that if the value of the Event is boolean then the value 1.0 is returned if it is true, and the value 0.0 if it is false, yet the documentation states that a NumberFormatException is thrown

If the value is a boolean or can not be parsed as a float value.

At a minimum this should have been picked up during the writing of the TCK since somebody should have been writing a test for this case.

EventData.getLong()

Being very pedantic, but this is supposed to be an official specification, the documentation states that it returns

The value as an int.

which it does not.

The MIDlet-Event-Launch-<n> Attribute

Double Values

For the case where the Event value is a double, the value of this attribute is defined as

    <Event-Name>=<Double-Event-Value>,<Double-Event-Value>

The value of a Double-Event-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.[sic]

As written this excludes negative decimal values . It is not clear whether this is intentional. It would have been better to provide an explicit definition of the format.

Again this is something that the people writing the TCK would have picked up on,

Long Values

For the case where the Event value is a long, the value of this attribute is defined as

    <Event-Name>=<Long-Event-Value>,<Long-Event-Value>

The value of a Long-Event-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.

As written this excludes negative decimal values. In addition, the CLDC version of java.lang.Long does not have a valueOf method

How did the people writing the TCK know what to test ?


Copyright (c) 2009 By Simon Lewis. All Rights Reserved.

June 4, 2009

What’s New In MIDP 3.0 ? Part 3: Events

Filed under: Java, JME, MIDP, MIDP3, MIDP3API, MIDP3EventAPI — Tags: , , , , , — Simon Lewis @ 11:19 pm

1. The Event API

The event API is specified by a single interface

  • EventDataListener

and three classes

  • EventData
  • EventManager
  • EventPermission

all of which are defined in the javax.microedition.event package.

1.1 EventDataListener

The EventDataListener interface defines a single method

    void handleEvent(EventData event)

1.2 EventData

An event is represented by an instance of EventData.

1.2.1 Fields

Each event has a name, and a typed value. When received by a MIDlet an event will also have a timestamp and a source. Each event may also have an optional message and an optional information object.

1.2.1.1 Name

The name of an event is either that of a pre-defined system event, or is application specific.

In the case of an application specific name the specification suggests, but does not require, that the reverse domain name convention should be adopted, and that the name have at least two components.

For example

    com.midletsrus.event.example

The name of an event can be accessed using the method getName().

1.2.1.2 Value

The value of an event may be of one of the following types

  • boolean
  • double
  • long
  • String

The value of an event can be accessed either by using one of the following type specific methods

  • getBoolean()
  • getDouble()
  • getFloat()
  • getInt()
  • getLong()
  • getString()

each of which returns a value of the appropriate type, or the method

     getValue()

which returns an instance of the Java class corresponding to the underlying value type.

Note

If the actual value of the event is a string, each of the numeric type-specific methods will attempt to parse the string as a number of the appropriate type. This may result in a NumberFormatException.

1.2.1.3 Timestamp

When received by a MIDlet an event will have a valid timestamp equivalent to the result of calling the method System.currentTimeMillis() at the time the event was posted.

The timestamp can be accessed using the method getTimestamp().

1.1.1.4 Source

When received by a MIDlet an event will have a source which can be used to identify the originator of the event.

The source can be accessed by using the method getSourceInfo().

This method returns an instance of the class MIDletIdentity if the event was posted by a MIDlet, null otherwise.

Note

The class MIDletIdentity is a new class defined in the javax.microedition.midlet package which provides access to information about the MIDlet suite containing a given MIDlet.

1.1.1.5 Message

An event may have an optional message of type String which can be accessed using the getMessage() method.

1.1.1.6 Information Object

An event may have an optional information object which can be accessed using the getInfo() method. The instance of Object returned by this method is constrained to be of one of the following types.

  • Boolean
  • Double
  • Long
  • String
  • byte[]

or null if there is no information object.

Note

The information object can in theory be used by an application to associate additional arbitrary information with an event. However, the specification only requires that an implementation support the passing of at least 1024 bytes of data inclusive of the name, value, message, and information object, so it is not a guaranteed way of passing unlimited amounts of data.

1.1.2 Constructors

There are four constructors which enable the creation of instances of EventData with values of each of the permitted types, and a name, message, and information object.

Note

The specification states that the constructors can be used to create representations of both system and application specific events. It does not, however, require that an implementation ensure that the value supplied for a system event is legal. Nor does it specify any constraints on the use of the message and the information object in the system event case.

1.1.3 System Events

The EventData class defines a number of constants which specify the names and possible values of system events (see below). The specification does not explicitly state that all the defined system events must be supported, but it does expicitly state that additional system events may be supported by a specific implementation and/or device.

For each system event below, the constant defining the name is in parentheses, and the value type is after the colon.

1.1.3.1 Audio Mute Event (AUDIO_MUTE): boolean

true if all audio output devices are muted.

1.1.3.2 Backlight Event (BACKLIGHT): int

Legal values are defined by the constants

  • BACKLIGHT_OFF
  • BACKLIGHT_ON
  • BACKLIGHT_DIM

1.1.3.3 Battery Charging Event (BATTERY_CHARGING): boolean

true if battery is charging.

1.1.3.4 Battery Level Event (BATTERY_LEVEL): int

Legal values are 1 to 100 inclusive

1.1.3.5 Battery Low Event (BATTERY_LOW): true

true if battery is low.

1.1.3.6 Data Network Event (DATA_NETWORK): String

The value specifies the currently available data networks as a semi-colon separated list of values defined by the following constants

  • NETWORK_3GPP_CSD
  • NETWORK_3GPP_PD
  • NETWORK_3GPP_PD_EDGE
  • NETWORK_3GPP_PD_3G
  • NETWORK_3GPP_PD_HSDPA
  • NETWORK_802DOT11
  • NETWORK_802DOT16
  • NETWORK_CDMA

1.1.3.7 External Power Event (EXTERNAL_POWER): boolean

true if device is connected to an external power source.

1.1.3.8 Flight Mode Event (FLIGHT_MODE): boolean

true if device is in flight mode.

1.1.3.9 Profile Activated Event (PROFILE_ACTIVATED): String

Legal values are defined by the constants

  • PROFILE_GENERAL
  • PROFILE_SILENT
  • PROFILE_MEETING
  • PROFILE_OUTDOOR
  • PROFILE_PAGER
  • PROFILE_OFFLINE
  • PROFILE_USER1
  • PROFILE_USER2
  • PROFILE_USER3
  • PROFILE_USER4
  • PROFILE_SYSTEM1
  • PROFILE_SYSTEM2
  • PROFILE_SYSTEM3
  • PROFILE_SYSTEM4

1.1.3.10 Screensaver Mode Event (SCREENSAVER_MODE): String

Legal values are defined by the constants

  • SCREENSAVER_MODE_ACTIVATED
  • SCREENSAVER_MODE_DEACTIVATED

1.1.3.11 System State Event (SYSTEM_STATE): String

Legal values are defined by the constants

  • SYSTEM_STATE_STARTUP
  • SYSTEM_STATE_NORMAL
  • SYSTEM_STATE_SHUTDOWN
  • SYSTEM_STATE_STANDBY

1.1.3.12 Voice Call Event (VOICE_CALL): boolean

true if at least one voice call is active.

1.1.4 Application Relaunch Events

When an attempt is made to launch an already running MIDlet an application relaunch system event is generated.

The name of this event is a concatenation of the value of the constant APPLICATION_RELAUNCH_PREFIX and the vendor, name, and version of the MIDlet suite containing the relaunched MIDlet formatted as specified by the documentation of the MIDletIdentity.toString() method.

1.1.5 System Property Events

The specification states that an implementation may choose to support system events for changes to system properties, with the name of the event being the same as that of the corresponding system property.

1.2 EventManager

A MIDlet can call methods on an instance of the EventManager class to perform the following functions

  • adding and removing event listeners
  • registering and unregistering a MIDlet for launch in response to an event
  • posting an event
  • listing the supported system events
  • getting a system event

A MIDlet can obtain an EventManager instance by calling the static method getInstance().

1.2.1 Adding An Event Listener

A MIDlet can receive events by registering an object which implements the EventDataListener interface as an event listener with the event manager, using an appropriate variant of the addEventListener() method to specify the criteria an event should match.

A MIDlet must specify the name of the event to listen for, or an event name prefix which the name of the event should match, and the authorization mode, which specifies whether the source of the event must be authorized with respect to the invoking MIDlet.

Note

It is not clear whether the authorization mode applies to system events since they are not necessarily posted by a MIDlet. I currently assume that it does not.

Event names are case-sensitive.

An event name prefix is a string of at least one character with the suffix ‘*’. The name of an event matches the pattern if the specified pattern excluding the trailing ‘*’ is a prefix of the event name.

A MIDlet may also specify a constraint on the value of an event, the exact nature of the constraint depending upon the type of the event value.

A MIDlet may only register an event listener if the MIDlet suite containing it has been granted the appropriate permission. (see EventPermission)

If all the specified criteria are met when a given event occurs, then the handleEvent(EventData) method of the registered event listener is invoked with an instance of EventData representing the matching event. The instance of EventData is only guaranteed to be valid for the duration of the call.

Note

If the call to addEventListener() specifies a system event, and the current system event matches the specified criteria then the event listener will be invoked immediately with the matching system event.

It is not clear whether there is any guarantee as to when this occurs relative to the call to addEventListener().

An event listener may be added for multiple values or value ranges of the same event or events.

Note

It is not clear what the intended behaviour is if two calls of addEventListener() differing only in the value of the authorization mode are performed.

There are a total of five variants of the addEventListener() method corresponding to the four possible event value types plus the case where there is no constraint on the event value.

1.2.1.1 addEventListener(String, EventDataListener, boolean)

The first argument is the event name, or event name prefix.

The second argument is an instance of an object implementing the EventDataListener interface.

The third argument is the required authorization mode. If the value is true then the source of an event must be authorized with respect to the invoking MIDlet. If the value is false then the event source is ignored.

Code fragment

Listen for application specific example.event.public events from any MIDlet, assuming the invoker implements the EventDataListener interface.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.addEventListener("example.event.public", this, false);

...

Code fragment

Listen for application specific example.event.public events from authorized MIDlets only, assuming the invoker implements the EventDataListener interface.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.addEventListener("example.event.public", this, true);

...

1.2.1.2 addEventListener(String, EventDataListener, boolean, boolean)

The first three arguments are as above.

The fourth argument specifies the required value of the event.

It is an error if the specified event is a system event and its value is not defined to be of type boolean.

Code Fragment

Listen for application specific example.event.boolean events with the value of true from any MIDlet, assuming the invoker implements the EventDataListener interface.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.addEventListener("example.event.boolean", this, false, true);

...

1.2.1.3 addEventListener(String, EventDataListener, boolean, double, double)

The first three arguments are as above.

The fourth and fifth argument specify the inclusive lower and upper bounds of the range within which the value of the event should lie.

Neither the lower or upper bound may be NaN, and the specified lower bound must be less than or equal to the specified upper bound.

It is an error if the specified event is a system event and its value is not defined to be of type double, or if either of the specified values is not legal for that system event.

Code Fragment

Listen for application specific example.event.temperature events with a value between 0.0 and 20.0 from any MIDlet, assuming the invoker implements the EventDataListener interface.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.addEventListener("example.event.temperature", this, false, 0.0D, 20.0D);

...

1.2.1.4 addEventListener(String, EventDataListener, boolean, long, long)

The first three arguments are as above.

The fourth and fifth arguments specify the inclusive lower and upper bounds respectively of the range within which the value of the event should lie.

The specified lower bound must be less than or equal to the specified upper bound.

It is an error if the specified event is a system event and its value is not defined to be of type int or long, or if either of the specified values is not legal for that system event.

Note

The specification actually states an IllegalArgumentException should be thrown if

the named event is a system event and is known not to be an int event.

I have assumed this should actually be int or long

Code Fragment

Listen for application specific example.event.altitude events with a value between 1000 and 1500, or 2000 and 2500 from any MIDlet, assuming the invoker implements the EventDataListener interface.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.addEventListener("example.event.altitude", this, false, 1000L, 1500L);
    em.addEventListener("example.event.altitude", this, false, 2000L, 2500L);

...

1.2.1.5 addEventListener(String, EventDataListener, boolean, String[])

The first three arguments are as above.

The fourth argument specifies the set of event values of interest.

It is an error if the specified event is a system event and its value is not defined to be of type String.

Code Fragment

Listen for screensaver activated events, assuming the invoker implements the EventDataListener interface.


import javax.microedition.event.EventData;
import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.addEventListener(
           EventData.SCREENSAVER_MODE,
           this,
           false,
           new String[]
           {
               EventData.SCREENSAVER_MODE_ACTIVATED
           });
		   
...

Code Fragment

Listen for screensaver activated and deactivated events, assuming the invoker implements the EventDataListener interface.


import javax.microedition.event.EventData;
import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.addEventListener(
           EventData.SCREENSAVER_MODE,
           this,
           false,
           new String[]
           {
               EventData.SCREENSAVER_MODE_ACTIVATED,
               EventData.SCREENSAVER_MODE_DEACTIVATED
           });
		   
...

1.2.2 Removing An Event Listener

A MIDlet can remove an event listener by calling the

    removeEventListener(String event, EventDataListener listener) 

method.

The MIDlet must specify the event and the event listener to unregister.

The event can be specified as a name, as a prefix, or as a wildcard, the string “*”, which matches all events.

Note

It is not clear from the specification what the semantics of this method actually are. For example, what happens if an event listener was registered using a prefix, but is unregistered with a name which matches the prefix ? Presumably the event listener is removed for all events which match the prefix it was added with, despite the fact that it was specified for removal for a specific event ?

1.2.3 Adding An Application Launch On Event Registration

A MIDlet can register itself or another MIDlet in the same MIDlet suite to be launched when a given event occurs using an appropriate version of the registerApplication() method.

The criteria specifying the event or events to launch are are identical to those used when adding an event listener using addEventListener().

If all the specified criteria are met and the MIDlet is not already running then it will be launched.

Note

If the call to registerApplication() specifies a system event, and the current system event matches the specified criteria then the specified MIDlet will be launched immediately.

A MIDlet can only register an application for launch on event if the MIDlet suite containing it has been granted the appropriate permission. (see EventPermission)

A MIDlet can be registered for launch for multiple values or value ranges of the same event.

Note

It is not clear what the intended behaviour is if two identical registrations differing only in the value of the authorization mode are performed.

As with the addEventListener()method there are five variants of the registerApplication() method.

1.2.3.1 registerApplication(String, String, boolean)

The first argument specifies the event to launch on and must be a specific event name, or an event name prefix

The second argument specfies the MIDlet to be launched and must be the fully qualified name of a sub-class of javax.microedition.midlet.MIDlet which has been explicitly declared as a MIDlet by the MIDlet suite using a MIDlet-<n> attribute.

The third argument specifies the authorization mode. If specified as true then for the application to be launched an event must originate from an authorized MIDlet.

Code Fragment

Register the MIDlet implemented by the class example.event.EventMIDlet to launch when an application specific example.event.public event originating from any MIDlet occurs.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.registerApplication("example.event.public", "example.event.EventMIDlet", false);
		   
...

Code Fragment

Register the MIDlet implemented by the class example.event.EventMIDlet to launch when an application specific example.event.public event originating from an authorized MIDlet occurs.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.registerApplication("example.event.public", "example.event.EventMIDlet", true);
		   
...

1.2.3.2 registerApplication(String, String, boolean, boolean)

The first three arguments are as above.

The fourth argument is the boolean value the specified event should have for the MIDlet to be launched.

It is an error if the specified event is a system event and its value is not defined to be of type boolean.

Code Fragment

Register the MIDlet implemented by the class example.event.EventMIDlet to launch when an application specific example.event.boolean event with a value of true originating from any MIDlet occurs.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.registerApplication(
          "example.event.boolean", 
          "example.event.EventMIDlet", 
          false, 
          true);
		   
...

1.2.3.3 registerApplication(String, String, boolean, double, double)

The first three arguments are as above.

The fourth and fifth arguments specify the inclusive lower and upper bounds respectively within which the event value should lie for the MIDlet to be launched.

Neither specified value may be NaN, and the specified lower bound must be less than or equal to the specified upper bound.

It is an error if the specified event is a system event and its value is not defined to be of type double, or if either of the specified values are not legal for the event.

Code Fragment

Register the MIDlet implemented by the class example.event.EventMIDlet to launch when an application specific example.event.temperature event with a value between 0.0 and 20.0, originating from any MIDlet occurs.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.registerApplication(
          "example.event.temperature", 
          "example.event.EventMIDlet", 
          false, 
          0.0D, 
          20.0D);
		   
...

1.2.3.4 registerApplication(String, String, boolean, long, long)

The first three arguments are as above.

The fourth and fifth arguments specify the lower and upper bounds respectively within which the event value should lie for the MIDlet to be launched.

The specified lower bound must be less than or equal to the specified upper bound.

Note

For this variant of the registerApplication() method the specification does not explicitly state that it is an error if the caller specifies a system event whose value is not defined to be of type long, as it does for the double variant above, or the equivalent variant of addEventListener().

Code Fragment

Register the MIDlet implemented by the class example.event.EventMIDlet to launch when an application specific example.event.altitude event with a value between 1000 and 1500 or between 2000 and 2500 originating from any MIDlet occurs.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.registerApplication(
          "example.event.altitude", 
          "example.event.EventMIDlet", 
          false, 
          1000L, 
          1500L);
    em.registerApplication(
          "example.event.altitude", 
          "example.event.EventMIDlet", 
          false, 
          2000L, 
          2500L);
		   
...

1.2.3.5 registerApplication(String, String, boolean, String[])

The first three arguments are as above.

The fourth argument specifies the possible values an event should have for the MIDlet to be launched.

It is an error if the specified event is a system event and its value is not defined to be of type String, or one or more of the specified values are not defined as legal for that event.

Code fragment

Register the MIDlet implemented by the class example.event.EventMIDlet to launch when an application specific example.event.colour event with a value of, red, green, or blue, originating from any MIDlet occurs.


import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    em.registerApplication(
           "example.event.colour", 
           "example.event.EventMIDlet", 
           false, 
           new String[]
           {
               "red",
               "blue",
               "green"
           });
 	   
...

1.2.4 Removing An Application Launch On Event Registration

A MIDlet can remove a registration for an application launch on event by using the

    unregisterApplication(String event, String application)

method.

The first argument specifies the event, and must be either an event name, or an event name prefix.

The second argument specifies the MIDlet class, and must be a fully qualified class name.

It is an error if the specified class does not exist.

This method will remove registrations added using variants of the registerApplication() method and those added at installation time.

1.2.5 Posting An Event

A MIDlet can post an event by calling the method

    post(EventData event, boolean authmode). 

The first argument is an instance of EventData representing the event to be posted.

The second argument specifies whether the event should only be delivered to MIDlets which are authorized with respect to the posting
MIDlet.

This method is asynchronous, that is, it returns before the event has been delivered.

A MIDlet may only post an event if the MIDlet suite containing it has been granted the appropriate permission. (see EventPermission)

Code fragment

Post an event visible to any MIDlet


import javax.microedition.event.EventData;
import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    // Create the event
	
    Event e  = new EventData("example.event.public", "the event value", null, null);
	
    // Post the event 
	
    em.post(e, false);
	
...

Code fragment

Post an event visible only to authorized MIDlets


import javax.microedition.event.EventData;
import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    // Create the event
	
    Event e  = new EventData("example.event.private", "the event value", null, null);
	
    // Post the event 
	
    em.post(e, true);
	
...

1.2.6 Listing The Supported System Events

A MIDlet can obtain a ‘list’ of the supported system events by calling the getSystemEvents(). The method returns an array of strings

1.2.7 Getting A System Event

A MIDlet can obtain an instance of EventData representing a given system event by calling the

    getCurrent(String event) 

method passing the name of the required system event.

The method returns null if the event specified is not a known system event.

A MIDlet may only get a specific system event if the MIDlet suite containing it has been granted the appropriate permission. (see EventPermission)

Note

It is not entirely clear from the specification what this method is actually doing. I think that the implication is that any supported system event always corresponds to a system state, and the value of the event is always the current state. A call to getCurrent(String) therefore always returns a system event whose value is the current value of the corresponding system state.
</p

Code fragment


import javax.microedition.event.EventData;
import javax.microedition.event.EventManager;

...

    EventManager em = EventManager.getInstance();
	
    // Get the current system state 
	
    String systemState = em.getCurrent(EventData.SYSTEM_STATE).getString();
	
...

1.3 EventPermission

An EventPermission has a target name which specifies the event or events to which it applies, and one or more actions which it grants for the specified event or events.

1.3.1 Target Name

The target name may be a specific event name, an event name prefix, or the wildcard pattern.

An event name prefix is of the form

    <event-name-prefix>*

where <event-name-prefix>* must end with a ‘.’ (dot).

An event name prefix matches any event name with the specified prefix.

Note

This definition of event name prefix is not quite the same as that defined for the

    addEventListener()

and

    registerApplication()

methods

The wildcard pattern is the string “*” and matches all events

1.3.2 Actions

The three actions defined for an EventPermission are

  • post
  • read
  • register

1.3.2.1 Post

The post action controls the use of the

     post(Event, boolean) 

method.

For a MIDlet to successfully post an event, the MIDlet suite containing it must have been granted an EventPermission whose target name matches the name of the event being posted, and whose actions include post.

1.3.2.2 Read

The read action controls the use of both the

    getCurrent(String)

method, and all variants of the

    addEventListener()

method.

For a MIDlet to successfully get a current system event, or register a listener for an event, the MIDlet suite containing it must have been granted an EventPermission whose target name matches that event, and whose actions include read.

1.3.2.3 Register

The register action controls the use of all variants of the

     registerApplication() 

method.

For a MIDlet to successfully use any variant of the registerApplication() method, the MIDlet suite containing it must have been granted an EventPermission whose target name matches the event being registered for and whose actions include register.

2. Installation Time Registration For Application Launch On Event

At installation time a MIDlet suite can register a MIDlet for launch when a given event occurs by specifying one or more

    MIDlet-Event-Launch-<n> 

attributes in the manifest of the MIDlet suite JAR.

The ordinals should start at 1 and be consecutive. All MIDlet-Event-Launch-<n> attributes after the first gap, if any, are ignored.

The value of the attribute is of the form

    <Classname>;<AuthorizationMode>;<Launch-Condition>

ClassName

The value of <Classname> must be the full name of a sub-class of javax.microedition.midlet.MIDlet which implements the application to launch.

Note

In the case of the registerApplication() methods the specification also states that the class must have been explicitly declared as a MIDlet via a MIDlet-<n> attribute. For consistency I would assume that the same constraint applies here.

AuthorizationMode

The value of <AuthorizationMode> must be either true or false. If true then the MIDlet will only be launched if the matching event originates from an authorized MIDlet.

Launch-Condition

The value of <Launch-Condition> can be of the form

    <Event-Name>

or, for an event with a boolean value

    <Event-Name>="true"|"false"

or, for an event with a double value

    <Event-Name>=<Double-Event-Value>,<Double-Event-Value>

or, for an event with a long value

    <Event-Name>=<Long-Event-Value>,<Long-Event-Value>

or, for an event with a String value

    <Event-Name>= ‘"’<String-Event-Value>‘"’ [ , ‘"’<String-Event-Value>‘"’ ]*

The value of <Event-Name> must be the name of an event.

The value of <Double-Event-Value> must be a double literal as accepted by the method

    java.lang.Double.valueOf(String s).

Note

This definition is ambiguous.

The documentation of the method in CLDC 1.1.1 reads as follows

Leading and trailing whitespace characters in s are ignored. The rest
of s should constitute a FloatValue as described
by the lexical rule:


 FloatValue:

        Signopt FloatingPointLiteral
 

The documentation of the method in CDC 1.1 reads as follows

Leading and trailing whitespace characters in s
are ignored. The rest of s should constitute a
FloatValue as described by the lexical rule:

FloatValue:

Signopt NaN

Signopt Infinity

Signopt FloatingPointLiteral

The value of <Long-Event-Value> must be a long literal as accepted by the method

    java.lang.Long.valueOf(String s).

Note

The method

    java.lang.Long.valueOf(String s).

is not actually defined in CLDC, only CDC.

Note

The format of <String-Event-Value> is not particularly well defined by the specification
which merely states that

The event value is quoted and can not contain a quote.

For both the double and long value cases the supplied values specify the inclusive lower and upper bounds respectively within which the event value should lie.

Examples

The examples all assume that the following also appears in the manifest of the MIDlet suite JAR.

MIDlet-1: EventExampleMIDlet, EventExampleMIDlet.png, example.event.MIDlet

Event Name Only

Register the MIDlet EventExampleMIDlet to be launched when an example.event.public event originating from any MIDlet occurs.

MIDlet-Event-Launch-1: example.event.MIDlet;false; example.event.public

Register the MIDlet EventExampleMIDlet to be launched when an example.event.public event originating from an authorized MIDlet occurs.

MIDlet-Event-Launch-1: example.event.MIDlet;true; example.event.public

Event With Boolean Value

Register the MIDlet EventExampleMIDlet to be launched when an example.event.boolean event occurs with a value of true. The event source is ignored.

MIDlet-Event-Launch-1: example.event.MIDlet;false;example.event.boolean=true

Event With Double/Float Value

Register the MIDlet EventExampleMIDlet to be launched when an example.event.temperature event occurs with a value between 0.0 and 20.0. The event source is ignored.

MIDlet-Event-Launch-1: example.event.MIDlet;false;example.event.temperature=0.0,20.0

Event With Int/Long Value

Register the EventExampleMIDlet to be launched when an example.event.altitude event occurs with a value between 1000 and 1500, or 2000 and 2500. The event source is ignored.

MIDlet-Event-Launch-1: example.event.MIDlet;false;example.event.altitude=1000,1500
MIDlet-Event-Launch-2: example.event.MIDlet;false;example.event.altitude=2000,2500

Event With String Value

Register the EventExampleMIDlet to be launched when an example.event.colour event occurs with a value of red, green, or blue. The event source is ignored.

MIDlet-Event-Launch-1: example.event.MIDlet;false;example.event.colour="red","green","blue"

Copyright (c) 2009 By Simon Lewis. All Rights Reserved.

Create a free website or blog at WordPress.com.

%d bloggers like this: