javax.microedition.event
Class EventData

java.lang.Object
  javax.microedition.event.EventData

public final class EventData
extends java.lang.Object

The EventData class provides methods to create events and to retrieve information from events. The predefined system events are also defined in this class.

Each event has a name, a typed value, a source and may have a message and an information object. The source of the event is either system or another application. The typed value must be one of long, double, boolean, or String. Events can be constructed from any primitive type but are converted to one of the types above using the normal Java Language Specification rules for type conversions (see [JLS] Chapter 5, Conversions and Promotions). The methods getInt, getLong, getFloat, getDouble, getBoolean, getString return the value by converting the value to the type requested as defined in each method. The method getValue returns the value as an Object.

The information object supports a limited set of types to keep the implementation simple. The valid types allowed for the info object is restricted to: java.lang.String, java.lang.Boolean, java.lang.Double, java.lang.Long, and byte[].

The EventData class and EventManager implementations MUST support passing the event name, value, message and info object totaling at least 1024 bytes. Each character of the String objects, including event name, value, and message is counted as two bytes. The number of bytes counted for the primitive value types are: boolean: 1, double: 8, and long: 8. The info object size is counted as the array length if it is a byte array; for all other info object types, it is considered to be exactly the same size as its corresponding primitive data type. The implementation overhead exceeding the previously defined sizes for a particular field MUST NOT be counted towards the 1024 byte requirement.

System Property Events

Some system properties have values that may change at runtime. If notification of changes to system properties is desired then the specification of each such system property must define the associated event of the same name. The system property event values are String objects and will return the current value of the system property as the value of the event. The implementation MUST ensure that when the system property is set that the corresponding event is posted. The event name for each such system property MUST be returned from the EventManager.getSystemEvents method.

Since:

MIDP 3.0

Field Summary

static java.lang.String	APPLICATION_RELAUNCH_PREFIX Prefix of system event names that indicate an attempt was made to relaunch a target MIDlet that is already running.
static java.lang.String	AUDIO_MUTE Indicates whether all audio output devices under the control of the implementation are muted.
static java.lang.String	BACKLIGHT Indicates the backlight illumination level.
static int	BACKLIGHT_DIM Indicates the backlight is dim.
static int	BACKLIGHT_OFF Indicates the backlight is off.
static int	BACKLIGHT_ON Indicates the backlight is on.
static java.lang.String	BATTERY_CHARGING Indicates whether the battery is currently charging.
static java.lang.String	BATTERY_LEVEL Indicates the amount of charge remaining in the battery as a percent represented by int values of 0 to 100 inclusive.
static java.lang.String	BATTERY_LOW Indicates if the battery is low.
static java.lang.String	DATA_NETWORK Indicates the available data networks.
static java.lang.String	EXTERNAL_POWER Indicates whether the device is connected to an external power source.
static java.lang.String	FLIGHT_MODE Indicates that the device is in flight mode.
static java.lang.String	NETWORK_3GPP_CSD Data network technology name for circuit switched data (CSD).
static java.lang.String	NETWORK_3GPP_PD Data network technology name for packet data in the GSM network.
static java.lang.String	NETWORK_3GPP_PD_3G Data network technology name for packet data in the 3G(UMTS) network.
static java.lang.String	NETWORK_3GPP_PD_EDGE Data network technology name for packet data in the EDGE network.
static java.lang.String	NETWORK_3GPP_PD_HSDPA Data network technology name for high speed download packet data in the 3G network (HSDPA).
static java.lang.String	NETWORK_802DOT11 Data network technology name for the 802.11 WiFi family of interfaces.
static java.lang.String	NETWORK_802DOT16 Data network technology name for the 802.16 WiMax interface standards.
static java.lang.String	NETWORK_CDMA Data network technology name for the CDMA/3GPP2 defined set of radio interface technologies.
static java.lang.String	PROFILE_ACTIVATED Indicates that a named profile was activated.
static java.lang.String	PROFILE_GENERAL Constant for the General profile.
static java.lang.String	PROFILE_MEETING Constant for the Meeting profile.
static java.lang.String	PROFILE_OFFLINE Constant for the Offline profile (also known as "Flight Mode").
static java.lang.String	PROFILE_OUTDOOR Constant for the Outdoor profile.
static java.lang.String	PROFILE_PAGER Constant for the Pager profile.
static java.lang.String	PROFILE_SILENT Constant for the Silent profile.
static java.lang.String	PROFILE_SYSTEM1 Constant for first system-reserved profile.
static java.lang.String	PROFILE_SYSTEM2 Constant for second system-reserved profile.
static java.lang.String	PROFILE_SYSTEM3 Constant for third system-reserved profile.
static java.lang.String	PROFILE_SYSTEM4 Constant for fourth system-reserved profile.
static java.lang.String	PROFILE_USER1 Constant for first user-defined profile.
static java.lang.String	PROFILE_USER2 Constant for second user-defined profile.
static java.lang.String	PROFILE_USER3 Constant for third user-defined profile.
static java.lang.String	PROFILE_USER4 Constant for fourth user-defined profile.
static java.lang.String	SCREENSAVER_MODE Indicates the changes in the screen saver execution as a String value.
static java.lang.String	SCREENSAVER_MODE_ACTIVATED Indicates the screen saver is being activated.
static java.lang.String	SCREENSAVER_MODE_DEACTIVATED Indicates the screen saver is being deactivated.
static java.lang.String	SYSTEM_STATE Indicates the system state as a String value.
static java.lang.String	SYSTEM_STATE_NORMAL Indicates the system is running applications normally.
static java.lang.String	SYSTEM_STATE_SHUTDOWN Indicates the system is shutting down.
static java.lang.String	SYSTEM_STATE_STANDBY Indicates the device is entering a potentially low power state in which no applications are running.
static java.lang.String	SYSTEM_STATE_STARTUP Indicates the system is starting up.
static java.lang.String	VOICE_CALL Indicates whether there are voice calls currently active.

Constructor Summary

EventData(java.lang.String event, boolean value, java.lang.String message, java.lang.Object info)
Creates a new instance of EventData with a boolean value.

EventData(java.lang.String event, double value, java.lang.String message, java.lang.Object info)
Creates a new instance of EventData with a double value.

EventData(java.lang.String event, long value, java.lang.String message, java.lang.Object info)
Creates a new instance of EventData with a long value.

EventData(java.lang.String event, java.lang.String value, java.lang.String message, java.lang.Object info)
Creates a new instance of EventData with a String value.

Method Summary

boolean	getBoolean() Gets the value as a boolean.
double	getDouble() Gets the value as a double.
float	getFloat() Gets the value as a float.
java.lang.Object	getInfo() Gets information regarding the event.
int	getInt() Gets the value as an int.
long	getLong() Gets the value as an long.
java.lang.String	getMessage() Gets the message for this event.
java.lang.String	getName() Gets the name of the event.
MIDletIdentity	getSourceInfo() Gets the information about the source of this event.
java.lang.String	getString() Gets the value as a String.
long	getTimestamp() Gets the time when the event was posted.
java.lang.Object	getValue() Gets the value as a java.lang.Object.
java.lang.String	toString() Gets the value as a String.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

BATTERY_LEVEL

public static final java.lang.String BATTERY_LEVEL

Indicates the amount of charge remaining in the battery as a percent represented by int values of 0 to 100 inclusive. Implementations SHOULD map the native battery levels to an aggregate percentile of all batteries in the device. Only changes in battery level detectable by the implementation must be reported.

See Also:

Constant Field Values

BATTERY_LOW

public static final java.lang.String BATTERY_LOW

Indicates if the battery is low. The value is a boolean, if true the battery is low, otherwise the battery is ok. If true MIDlets should save their work and conserve power.

See Also:

Constant Field Values

BATTERY_CHARGING

public static final java.lang.String BATTERY_CHARGING

Indicates whether the battery is currently charging. A boolean value of true indicates that the battery is charging and is false otherwise.

See Also:

Constant Field Values

EXTERNAL_POWER

public static final java.lang.String EXTERNAL_POWER

Indicates whether the device is connected to an external power source. A boolean value of true indicates that the device is connected, otherwise the value is false.

See Also:

Constant Field Values

FLIGHT_MODE

public static final java.lang.String FLIGHT_MODE

Indicates that the device is in flight mode. For example, the device's radio(s) are powered off. The value is a boolean, true indicates that flight mode is active; otherwise false.

See Also:

Constant Field Values

SYSTEM_STATE

public static final java.lang.String SYSTEM_STATE

Indicates the system state as a String value. Valid values are SYSTEM_STATE_STARTUP, SYSTEM_STATE_NORMAL, SYSTEM_STATE_SHUTDOWN, and SYSTEM_STATE_STANDBY.

Events for each system state are delivered when the system enters the state. The current system state can be queried with EventManager.getCurrent. When the system is initialized the STARTUP state is entered and startup applications are automatically launched. When the system is ready to begin running MIDlets under user control or resuming from the standby state the NORMAL state is entered. When the system is in a low power or standby state the STANDBY state is entered. When the system is shutting down applications the SHUTDOWN state is entered.

See Also:

Constant Field Values

SYSTEM_STATE_NORMAL

public static final java.lang.String SYSTEM_STATE_NORMAL

Indicates the system is running applications normally.

See Also:

SYSTEM_STATE, Constant Field Values

SYSTEM_STATE_STARTUP

public static final java.lang.String SYSTEM_STATE_STARTUP

Indicates the system is starting up.

See Also:

SYSTEM_STATE, Constant Field Values

SYSTEM_STATE_SHUTDOWN

public static final java.lang.String SYSTEM_STATE_SHUTDOWN

Indicates the system is shutting down.

See Also:

SYSTEM_STATE, Constant Field Values

SYSTEM_STATE_STANDBY

public static final java.lang.String SYSTEM_STATE_STANDBY

Indicates the device is entering a potentially low power state in which no applications are running.

See Also:

SYSTEM_STATE, Constant Field Values

VOICE_CALL

public static final java.lang.String VOICE_CALL

Indicates whether there are voice calls currently active. A boolean value of true indicates that there are voice calls active while a value of false indicates that no voice calls are active.

See Also:

Constant Field Values

BACKLIGHT

public static final java.lang.String BACKLIGHT

Indicates the backlight illumination level. The value of this state MUST NOT be changed due to calls to Display.flashBacklight(int). The value SHOULD NOT be changed due to any programmatic flashing of the backlight through any other API. The value is an integer with values: BACKLIGHT_ON, BACKLIGHT_OFF, or BACKLIGHT_DIM.

See Also:

Constant Field Values

BACKLIGHT_OFF

public static final int BACKLIGHT_OFF

Indicates the backlight is off.

See Also:

BACKLIGHT, Constant Field Values

BACKLIGHT_ON

public static final int BACKLIGHT_ON

Indicates the backlight is on.

See Also:

BACKLIGHT, Constant Field Values

BACKLIGHT_DIM

public static final int BACKLIGHT_DIM

Indicates the backlight is dim. Any illumination level other than fully on or off MUST be reported as dim.

See Also:

BACKLIGHT, Constant Field Values

AUDIO_MUTE

public static final java.lang.String AUDIO_MUTE

Indicates whether all audio output devices under the control of the implementation are muted. A boolean value of true indicates all audio output devices are muted and false otherwise.

See Also:

Constant Field Values

SCREENSAVER_MODE

public static final java.lang.String SCREENSAVER_MODE

Indicates the changes in the screen saver execution as a String value. Valid values are:

• SCREENSAVER_MODE_ACTIVATED - The screen saver is activated.
• SCREENSAVER_MODE_DEACTIVATED - The screen saver is deactivated.

See Also:

Constant Field Values

SCREENSAVER_MODE_ACTIVATED

public static final java.lang.String SCREENSAVER_MODE_ACTIVATED

Indicates the screen saver is being activated.

See Also:

SCREENSAVER_MODE, Constant Field Values

SCREENSAVER_MODE_DEACTIVATED

public static final java.lang.String SCREENSAVER_MODE_DEACTIVATED

Indicates the screen saver is being deactivated.

See Also:

SCREENSAVER_MODE, Constant Field Values

APPLICATION_RELAUNCH_PREFIX

public static final java.lang.String APPLICATION_RELAUNCH_PREFIX

Prefix of system event names that indicate an attempt was made to relaunch a target MIDlet that is already running. The full event name includes the prefix, the vendor, name, and version of the target MIDlet formatted according to MIDletIdentity.toString(). Specifically, it is the concatenation of APPLICATION_RELAUNCH_PREFIX + target.getMIDletIdentity().toString() where target is an placeholder for the target MIDlet. The type of the value is boolean and the value is always true.

To be notified of relaunch attempts the MIDlet should concatenate this prefix with the string returned from MIDletIdentity.toString() and register to listen for the event.

See Also:

Constant Field Values

PROFILE_ACTIVATED

public static final java.lang.String PROFILE_ACTIVATED

Indicates that a named profile was activated. Only one profile at a time can be active, so that when a profile is activated, the previously active profile is deactivated, but there is no specific event for this implicit operation. The initial profile is implementation dependent. The type of the event is String. The event String value MUST be one of the following:

• 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

USER1...4 and SYSTEM1...4 are placeholders for user-defined profiles and existing system profiles that do not fit the defined semantics. As event information, the implementation SHOULD set a String containing the display name of the activated profile, if any. Applications MUST NOT be able to post PROFILE_ACTIVATED events to other applications or the system.

See Also:

Constant Field Values

PROFILE_GENERAL

public static final java.lang.String PROFILE_GENERAL

Constant for the General profile. All tones are set to the default, and there is no need for the application to restrict its audio output.

See Also:

Constant Field Values

PROFILE_SILENT

public static final java.lang.String PROFILE_SILENT

Constant for the Silent profile. The application is not expected to play any audio when this profile is active.

See Also:

Constant Field Values

PROFILE_MEETING

public static final java.lang.String PROFILE_MEETING

Constant for the Meeting profile. The application is expected to issue only brief audio segments. Visual cues are preferred.

See Also:

Constant Field Values

PROFILE_OUTDOOR

public static final java.lang.String PROFILE_OUTDOOR

Constant for the Outdoor profile. Audio output does not need to be restricted, and it could even be louder than usual.

See Also:

Constant Field Values

PROFILE_PAGER

public static final java.lang.String PROFILE_PAGER

Constant for the Pager profile. The application is expected to issue only alert tones, and audio playback is not desirable.

See Also:

Constant Field Values

PROFILE_OFFLINE

public static final java.lang.String PROFILE_OFFLINE

Constant for the Offline profile (also known as "Flight Mode"). Typically no network connectivity is available when this profile is active, but applications SHOULD NOT rely on this to find out about network availability. In terms of audio, this profile is like General.

See Also:

Constant Field Values

PROFILE_USER1

public static final java.lang.String PROFILE_USER1

Constant for first user-defined profile.

See Also:

Constant Field Values

PROFILE_USER2

public static final java.lang.String PROFILE_USER2

Constant for second user-defined profile.

See Also:

Constant Field Values

PROFILE_USER3

public static final java.lang.String PROFILE_USER3

Constant for third user-defined profile.

See Also:

Constant Field Values

PROFILE_USER4

public static final java.lang.String PROFILE_USER4

Constant for fourth user-defined profile.

See Also:

Constant Field Values

PROFILE_SYSTEM1

public static final java.lang.String PROFILE_SYSTEM1

Constant for first system-reserved profile. Used if the profile does not match any of the predefined profile semantics.

See Also:

Constant Field Values

PROFILE_SYSTEM2

public static final java.lang.String PROFILE_SYSTEM2

Constant for second system-reserved profile.

See Also:

Constant Field Values

PROFILE_SYSTEM3

public static final java.lang.String PROFILE_SYSTEM3

Constant for third system-reserved profile.

See Also:

Constant Field Values

PROFILE_SYSTEM4

public static final java.lang.String PROFILE_SYSTEM4

Constant for fourth system-reserved profile.

See Also:

Constant Field Values

DATA_NETWORK

public static final java.lang.String DATA_NETWORK

Indicates the available data networks. This event is sent to the requested applications whenever there is a change in the list of available data networks. This notification MUST be sent if a new data network appears or a data network is lost. The event contains the list of all currently available data networks. The data networks are indicates as a semicolon separated list of the technology names in the EventData value field. The data network technology names MUST be the following:

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

See Also:

Constant Field Values

NETWORK_3GPP_CSD

public static final java.lang.String NETWORK_3GPP_CSD

Data network technology name for circuit switched data (CSD). This is part of the 3GPP defined set of radio interface technologies.

See Also:

Constant Field Values

NETWORK_3GPP_PD

public static final java.lang.String NETWORK_3GPP_PD

Data network technology name for packet data in the GSM network. This is part of the 3GPP defined set of radio interface technologies.

See Also:

Constant Field Values

NETWORK_3GPP_PD_3G

public static final java.lang.String NETWORK_3GPP_PD_3G

Data network technology name for packet data in the 3G(UMTS) network. This is part of the 3GPP defined set of radio interface technologies.

See Also:

Constant Field Values

NETWORK_3GPP_PD_EDGE

public static final java.lang.String NETWORK_3GPP_PD_EDGE

Data network technology name for packet data in the EDGE network. This is part of the 3GPP defined set of radio interface technologies.

See Also:

Constant Field Values

NETWORK_3GPP_PD_HSDPA

public static final java.lang.String NETWORK_3GPP_PD_HSDPA

Data network technology name for high speed download packet data in the 3G network (HSDPA). This is part of the 3GPP defined set of radio interface technologies.

See Also:

Constant Field Values

NETWORK_802DOT11

public static final java.lang.String NETWORK_802DOT11

Data network technology name for the 802.11 WiFi family of interfaces. This value includes access technology variants of 802.11a, 802.11b, 802.11g and 802.11n, along with support for any of the optional QoS and hand-over extensions.

See Also:

Constant Field Values

NETWORK_802DOT16

public static final java.lang.String NETWORK_802DOT16

Data network technology name for the 802.16 WiMax interface standards. This is primarily for the 802.16e mobile WiMax specification, but can also be used for the fixed 802.16 specification.

See Also:

Constant Field Values

NETWORK_CDMA

public static final java.lang.String NETWORK_CDMA

Data network technology name for the CDMA/3GPP2 defined set of radio interface technologies. This includes CDMA, CDMA-2000, CDMA 1X, CDMA-EvDO and EVDO rev A(DOrA).

See Also:

Constant Field Values

Constructor Detail

EventData

public EventData(java.lang.String event,
                 java.lang.String value,
                 java.lang.String message,
                 java.lang.Object info)

Creates a new instance of EventData with a String value. The event name may be either a custom application specific event name or one of the predefined system events.

Parameters:

event - The name of the event.

value - The String value for this event

message - The message text explaining the current event, or null if this event has no message.

info - Additional information about this event, or null for no information.

Throws:

java.lang.NullPointerException - If event or value parameter is null.

java.lang.IllegalArgumentException - If the Java type of info is not one of the valid types.

EventData

public EventData(java.lang.String event,
                 long value,
                 java.lang.String message,
                 java.lang.Object info)

Creates a new instance of EventData with a long value. The event name may be either a custom application specific event name or one of the predefined system events.

Parameters:

event - The name of the event.

value - The value for this event; the full range of long values MUST be stored.

message - The message text explaining the current event, or null if this event has no message.

info - Additional information about this event, as an Object or null for no information.

Throws:

java.lang.NullPointerException - If event parameter is null

java.lang.IllegalArgumentException - If the Java type of info is not one of the valid types.

See Also:

getLong(), getInt()

EventData

public EventData(java.lang.String event,
                 double value,
                 java.lang.String message,
                 java.lang.Object info)

Creates a new instance of EventData with a double value. The event name may be either a custom application specific event name or one of the predefined system events.

Parameters:

event - The name of the event.

value - The value for this event; the full range of double values MUST be stored.

message - The message text explaining the current event, or null if this event has no message.

info - Additional information about this event, as an Object or null for no information.

Throws:

java.lang.NullPointerException - If the event parameter is null.

java.lang.IllegalArgumentException - If the Java type of info is not one of the valid types.

EventData

public EventData(java.lang.String event,
                 boolean value,
                 java.lang.String message,
                 java.lang.Object info)

Creates a new instance of EventData with a boolean value. The event name may be either a custom application specific event name or one of the predefined system events.

Parameters:

event - The name of the event.

value - The boolean value for this event.

message - The message text explaining the current event, or null if this event has no message.

info - Additional information about this event, as an Object or null for no information.

Throws:

java.lang.NullPointerException - If the event parameter is null.

java.lang.IllegalArgumentException - If the Java type of info is not one of the valid types.

Method Detail

getName

public java.lang.String getName()

Gets the name of the event.

Returns:

The name of the event.

getMessage

public java.lang.String getMessage()

Gets the message for this event. The event message is typically a single sentence or phrase explaining the current event.

Returns:

The message text explaining the current event, or null if this event has no message.

getInfo

public java.lang.Object getInfo()

Gets information regarding the event. This information may include more data about the event. The instance returned will be of one of the valid types types. It is up to the application to cast the object to a usable type. The instanceof operator or the object's Class may be used to determine the type of the value.

Returns:

Information regarding the event, or null if there is no further information about this event.

getFloat

public float getFloat()
               throws java.lang.NumberFormatException

Gets the value as a float.

Value	Convert to float
long	(float)value
double	(float)value
boolean	(value ? 1.0f : 0.0f)
String	java.lang.Float.parseFloat(value)

Returns:

The value as a float.

Throws:

java.lang.NumberFormatException - If the value is a boolean or can not be parsed as a float value.

getDouble

public double getDouble()
                 throws java.lang.NumberFormatException

Gets the value as a double.

Value	Convert to float
long	(double)value
double	value
boolean	(value ? 1.0d : 0.0d)
String	java.lang.Double.parseDouble(value)

Returns:

The value as a double.

Throws:

java.lang.NumberFormatException - If the value can not be parsed as a double value.

getInt

public int getInt()
           throws java.lang.NumberFormatException

Gets the value as an int.

Value	Convert to int
long	(int)value
double	(int)value
boolean	(value ? 1 : 0)
String	java.lang.Integer.parseInt(value)

Returns:

The value as an int.

Throws:

java.lang.NumberFormatException - If the value can not be parsed as an int.

getLong

public long getLong()
             throws java.lang.NumberFormatException

Gets the value as an long.

Value	Convert to int
long	value
double	(long)value
boolean	(value ? 1L : 0L)
String	java.lang.Long.parseLong(value)

Returns:

The value as an int.

Throws:

java.lang.NumberFormatException - If the value can not be parsed as an long.

getBoolean

public boolean getBoolean()

Gets the value as a boolean.

Value	Convert to boolean
long	(value == 0 ? false : true)
double	(value == 0.0f ? false : true
boolean	value
String	value.equals("true")

Returns:

The value as a boolean.

getValue

public java.lang.Object getValue()

Gets the value as a java.lang.Object. The value of the event is converted to an Object depending on the type of the value:

Value	Convert to Object
long	new java.lang.Long(value)
double	new java.lang.Double(value)
boolean	new java.lang.Boolean(value)
String	new java.lang.String(value)

Returns:

The value as an Object.

getString

public java.lang.String getString()

Gets the value as a String. The value of the event is converted to a String depending on the type of the value:

Value	Convert to String
long	java.lang.Long.toString()
double	java.lang.Double.toString()
boolean	java.lang.Boolean.toString()
String	value

Returns:

The value as a String.

toString

public java.lang.String toString()

Gets the value as a String. The value of the event is using getString.

Overrides:

toString in class java.lang.Object

Returns:

The value as a String.

getSourceInfo

public MIDletIdentity getSourceInfo()

Gets the information about the source of this event. If the event was posted by a MIDlet then the return value MUST be non-null and identify the MIDlet, otherwise null is returned.

Returns:

an MIDletIdentity instance containing information about the source of the event; null if this EventData was not posted by a MIDlet.

See Also:

MIDletIdentity

getTimestamp

public long getTimestamp()

Gets the time when the event was posted. The time is in the same format as java.lang.System.currentTimeMillis.

Returns:

the time when the event was posted. If the event has not been posted zero is returned.