Just An Application

July 15, 2009

What’s New In MIDP 3.0 ? Part 26: LCDUI – Notification

Filed under: Java, JME, LCDUI, MIDP, MIDP3, MIDP3LCDUI — Tags: , , , , , , — Simon Lewis @ 5:46 pm

1. The Notification Model

  • A Notification is a small piece of information which should be presented to the user independently of any MIDlet specific UI

  • A Notification has an associated type which is an instance of the NotificationType class

    • The type of a Notifiction may be

      • built-in, or

      • MIDlet specific

    • The built-in types are

      • CALL

      • EMAIL

      • IM

      • MMS

      • SMS

      • REMINDER

    • A MIDlet specific Notification type specifies a default label and a default Image

      • If a Notification of a MIDlet specific type does not have a label and/or Image then
        the label and/or Image specified by it’s type will be used

  • A Notification can be in one of two states

    • removed, when it is not accessible by the user, or

    • available, when it is accessible by the user

  • A Notification is created in the removed state

  • A MIDlet can make a Notification available by posting it

  • A MIDlet can remove an available Notification

  • When a Notification is available a user may dismss it

    • If a user dismisses a Notification it’s state changes to removed

  • A MIDet may specify that when a Notification is available it should be possible for the user to select it

    • If a user selects a Notification it’s state changes to removed

  • A MIDet may specify that a Notification should only be available for a maximum period of time

    • If a Notification is not dismissed, or, if possible, selected during the specified period of time, then its state changes to removed

  • The way in which a Notification is displayed and the use made of it’s label and Image are implementation dependent.

  • An implementation can choose to display Notifications differently on the basis of their types

2. NotificationType

2.1 Creating A NotificationType

A MIDlet specific NotificationType can be created using the

	NotificationType(String defaultLabel, Image defaultImage)

constructor.

It is an error if either the defaultLabel or the defaultImage argument is null and a NullPointerException will be thrown.

2.2 NotificationType Constants

The built-in NotificationType’s can be accessed using the following constants defined in the NotificationType class

    public static final NotificationType CALL

    public static final NotificationType IM

    public static final NotificationType EMAIL

    public static final NotificationType MMS

    public static final NotificationType SMS

    public static final NotificationType REMINDER

3. NotificationListener

The NotificationListener interface enables an object which implements it to listen for the following Notification events

  • when a Notification is dismissed

  • when a Notification is selected

  • when a Notification times out

Each event is reported via a call to a corresponding method defined in the interface.

3.1 Notification Dismissed

If an available Notification has been dismissed by the user, then after the Notification has been removed, if it has an associated NotificationListener object then that object’s

    public void notificationDismissed(Notification notification)

method will be called.

3.2 Notification Selected

If a Notification has been posted using the either the Notification.post(boolean) or Notification.post(boolean,int) methods with a selectable argument of true, and it is subsequently selected by the user then after the Notification has been removed, if it has an associated NotificationListener object then that object’s

    public void notificationSelected(Notification notification)

method will be called.

3.3 Notification Timeout

If a Notification has been posted using the Notification.post(boolean,int) method and it subsequently times out, then after the Notification has been removed, if it has an associated NotificationListener object then that object’s

    public void notificationTimeout(Notification notification)

method will be called.

4. Notification Creation

A Notification can be created using one of the following constructors

    public Notification(NotificationType type)
    public Notification(NotificationType type, String label)
    public Notification(NotificationType type, String label, Image image)

In each case it is an error if the type argument is null and a NullPointerException will be thrown.

5. Getting The Type Of A Notification

The type of a Notification can be obtained by calling it’s

    public NotificationType getType()

method.

6. Getting The Timestamp Of A Notification

The time at which a Notification was last posted can be obtained by calling the Notification’s

    public long getTimestamp()

method.

The return value is the same as the result of a call to the System.currentTimeMillis() method made at the time the Notification was last posted.

If the Notification has not been posted the method will return zero.

7. Setting The Label Of A Notification

The label of a Notification can be set by calling it’s

    public void setLabel(String label)

method.

Note

  1. The method documentation does not explicitly state that the label argument may be null. Presumably by analogy with the Image case it can.

  2. Also by an analogy with the Image case, presumably it is necessary for the Notification to be re-posted for this change to have any effect if the Notification is currently available.

8. Setting The Image Of A Notification

The Image of a Notification may be set by calling it’s

    public void setImage(Image image)

method.

The image may specify an immutable or a mutable Image. It may also be null.

If the Image is mutable then a snapshot, created at the point the post() method is called, will be used.

If the Notification is currently available, then it must be re-posted for the change to have an effect.

9. Setting The Listener Of A Notification

The NotificationListener object associated with a Notification can be set by calling the Notification’s

    public void setListener(NotificationListener listener)

method.

The listener argument may be null in which case in addition to removing the currently associated NotificationListener object, if any, if the Notification is currently available it will be removed.

Note

  • The rather suprising side-effect of passing null to this method when the Notification is available does not appear on the state diagram in the class documentation and is not mentioned in the accompanying text which reads

    A Notification can become removed in the following ways :

    • By the implementation, when a Notification is dismissed or selected by the user, before the callbacks
      (notificationSelected() or notificationDismissed()) are triggered.
    • By a MIDlet using the remove() method.
    • By the implementation, due to the duration being passed (see below), which will trigger the notificationTimeout() method.

    A Notification MUST remain available until removed by application or implementation code in the ways defined above.

    and which could be taken to imply that the method should not be doing what it’s documentation says it does.

10. Posting

10.1 Posting A Notification

A Notification can be posted so that it is available to the user by calling the Notification’s

    public void post(boolean selectable)

method.

If the selectable argument is true then the Notification will be selectable by the user.

If it is not possible for the Notification to be posted then a NotificationException will be thrown.

Note

  • NotificationException is an unchecked exception. An IDE or compiler will not issue a warning if this method is called and NotificationException is not explicitly caught.

10.2 Posting A Notification For A Maximum Period Of Time

A Notification can be posted so that it is only available to the user for a maximum period of time by calling the Notification’s

    public void post(boolean selectable, int duration)

method.

If the selectable argument is true then the Notification will be selectable by the user.

The duration argument should specify the maximum period of time in milliseconds the Notification should be available to the user.

It is an error if the duration argument is not a positive integer and an IllegalArgumentException will be thrown.

If it is not possible for the Notification to be posted then a NotificationException will be thrown.

If the Notification is not dismissed or selected by the user first then at the end of specified period of time the Notification is automatically removed. If there is a NotificationListener object associated with the Notification it’s notificationTimeout() method will be called.

Note

  • NotificationException is an unchecked exception. An IDE or compiler will not issue a warning if this method is called and NotificationException is not explicitly caught.

11. Removing A Notification

A Notification can moved into the removed state by callimg it’s

    public void remove()

method.

It is an error if the Notification is already in the removed state and an IllegalStateException will be thrown.

If it is not possible for the Notification to be removed then a NotificationException will be thrown.

Notes

  1. It is not clear under what circumstances a Notification cannot be removed or whether such a situation is recoverable.

  2. NotificationException is an unchecked exception. An IDE or compiler will not issue a warning if this method is called and NotificationException is not explicitly caught.


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

Advertisements

Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: