BlackBerry Developer Blog » Denver C.

Media Actions API in BlackBerry JDE v5.0.0 How-To

Denver C. — Fri, 14 Aug 2009 15:38:00 +0000

I would like to talk about a new API feature in the BlackBerry® Java® Development Environment v5.0 (Beta) I worked on called the Media Actions API. In this article I will discuss how to use this API to respond to media key presses in the same way that the built-in media player does: respond to media key presses while in the background, and respond to key presses on connected wired headsets and paired Bluetooth® headsets. I will also discuss some things to keep in mind when using this API, as well as some implementation details. Finally, I will explain how to use this functionality from MIDlets, even without using non-standard APIs. Included within the BlackBerry JDE v5.0.0 beta is a great sample media player application that demonstrates how to use the API and I would encourage you to look at this demo and play with it. There is also a simple application included at the end of this article for reference.

The key to the Media Actions API is the new interface net.rim.device.api.media.MediaActionHandler, which defines a single method:

public boolean mediaAction(int action, int source, Object context)

The implementation of this method is expected to respond to the specified “action”, which will be equal to one of the MEDIA_ACTION_ constants defined in the interface. These action constants represent common media player actions, such as play/pause, next/previous track, and volume up/down. The “source” and “context” parameters contain additional information about where the action came from and may be used by the implementation to behave differently depending on their values. Examples of values for the “action” parameter are MEDIA_ACTION_PLAYPAUSE_TOGGLE and MEDIA_ACTION_NEXT_TRACK. Examples of values for the “source” parameter are SOURCE_BACKGROUND_KEY and SOURCE_WIRED_HEADSET.

The first use of the MediaActionHandler interface is to respond to media key presses while the application is in the foreground. A new abstract class has been created that implements KeyListener and provides standard mappings from key presses to media actions: net.rim.device.api.media.MediaKeyListener. These mappings depend on the hardware keys available on each BlackBerry smartphone and are the exact mappings used by the built-in BlackBerry Media Player application. For example, if the BlackBerry smartphone does not have dedicated “next” and “previous” keys then pressing-and-holding the volume keys will generate “next track” and “previous track” media actions; however, on devices that do have dedicated “next” and “previous” keys these buttons will be used to generate the next/previous track actions and pressing-and-holding the volume keys will do nothing. The MediaKeyListener class implements all methods defined by KeyListener but does not implement the method defined by MediaActionHandler, as it is left to a subclass. An instance of MediaKeyListener can be registered by invoking addKeyListener(KeyListener) on the Application instance for the application.

The second use of this interface is to respond to media key presses while the application is in the background. Normally, applications are only able to respond to key presses while in the foreground; to respond to key presses while in the background an application must register an instance of MediaActionHandler using the new method addMediaActionHandler(MediaActionHandler), defined in the Application class. After registration, the MediaActionHandler will be notified of media actions resulting from media key presses even when it is in the background. The mappings from key presses to media actions are identical to the standard mappings implemented by MediaKeyListener and cannot be modified.

The third use of the MediaActionHandler interface is to respond to key presses on a connected wired headset and/or paired Bluetooth® headset. In fact, this functionality comes for free when registering a MediaActionHandler. This is because the mediaAction() method is invoked when buttons are pressed on one of these headsets, just like it is invoked when media keys on the BlackBerry smartphone itself are pressed. The only difference is that the “source” parameter will be equal to the SOURCE_ constants defined in MediaActionHandler and the “context” parameter will be non-null, as documented in the javadocs for the SOURCE_ constants. Note, however, that media actions from all sources are delivered even if audio is being played through only one of the sources. For example, if an application is playing audio through a wired headset and the user presses a button on a paired Bluetooth headset, then the corresponding media action will still be delivered to the application; it is up to the application to choose whether or not to respond to it.

Care was taken during implementation to ensure that when multiple applications register a MediaActionHandler only one of them is actually notified, and the choice of which one is notified is made in a fair way. The rationale was that if multiple media player applications were running in the background and the user presses the play/pause button they would want to pause the current song; but if both applications were notified then it would pause one and begin playback in the other, an annoying user experience. Therefore, only the most-recently-foregrounded application that has registered a MediaActionHandler will be notified. This heuristic was chosen because it is assumed that the background media player application that the user wants to control is most likely to be the one that was most recently used explicitly. If that application exits, then the one that was most-recently-foregrounded before it will be the one that gets notified, and so on. Effectively, a “stack” of applications is maintained and only the application on the top of the stack gets notified of media actions, and an application is moved to the top of the stack when it comes to the foreground.

So far, this article has only discussed how to use the Media Actions API in CLDC applications, those that extend net.rim.device.api.system.Application; however, this feature is also available in MIDlet applications, those that extend javax.microedition.midlet.MIDlet. A MIDlet is free to register a MediaActionHandler just like a CLDC application and will receive callbacks in exactly the same way. But the Canvas class has been modified for native support of media keys. Already, applications can override the keyPressed(), keyReleased(), and keyRepeated() methods of Canvas to respond to key presses while in the foreground and the keyCode for volume up and volume down are already documented to be -150 and -151, respectively. In BlackBerry JDE v5.0.0 keyCodes for mute/speakerphone, next, and previous keys were added: -2731, -4100, and -4101, respectively. But one problem with simply implementing keyXXX() to handle these new keyCodes is that another media player application that is in the background will also be notified of these key presses. To fix this problem, the concept of “media player mode” for MIDlets was introduced. If media player mode is enabled then two things change: background applications are not notified of media key presses that occur while the MIDlet is in the foreground and the MIDlet is notified of media key presses that occur while it is in the background. The MIDlet application will be inserted into and moved around in the application “stack” just like CLDC applications to contend for receiving notifications of background media keys. By default, media player mode is disabled and it can be enabled by using the new interface net.rim.device.api.lcdui.control.MediaBehaviourControl, whose instance can be obtained from the Display object (see javadocs for details). Alternately, the JAD attribute RIM-MIDlet-MediaPlayerModeEnabled can be set to “1” for media player mode to instead be enabled by default, thus avoiding the use of any non-standard APIs.

I really hope that media player application developers will find this API easy to use and of value to their applications. Also, I hope to see some creative uses of this API that I could never have foreseen, which always impresses me! Please comment on this article with feedback, both positive and negative, about the API. You can try it out in the BlackBerry 5.0.0 JDE beta that is available at the link below.

BlackBerry® Java® Development Environment v5.0 (Beta)

Below is a very simple application that demonstrates how an application can respond to media actions.

import net.rim.device.api.media.MediaKeyListener;

import net.rim.device.api.ui.Field;

import net.rim.device.api.ui.Screen;

import net.rim.device.api.ui.UiApplication;

import net.rim.device.api.ui.component.LabelField;

import net.rim.device.api.ui.component.SeparatorField;

import net.rim.device.api.ui.container.MainScreen;

public class MediaActionsAPIDemo extends UiApplication {

private static final String INSTRUCTION_TEXT =
“Press a media key, even when in the background, “
+ “and the corresponding action will be logged “
+ “to the screen and standard output.”;

private final MainScreen _screen;

public MediaActionsAPIDemo() {
this._screen = new MainScreen();
this._screen.setTitle(“Media Actions API Demo”);
this._screen.add(new LabelField(INSTRUCTION_TEXT));

this._screen.add(new SeparatorField());
this.pushScreen(this._screen);

final MyMediaKeyListener myMediaKeyListener =
new MyMediaKeyListener(this._screen);
this.addKeyListener(myMediaKeyListener);
this.addMediaActionHandler(myMediaKeyListener);
}

public static void main(String[] args) {
new MediaActionsAPIDemo().enterEventDispatcher();
}

private static class MyMediaKeyListener extends
MediaKeyListener {

private final Screen _logScreen;

public MyMediaKeyListener(Screen logScreen) {
this._logScreen = logScreen;
}

public boolean mediaAction(int action, int source,
Object context) {
final StringBuffer sb = new StringBuffer(200);
sb.append(“mediaAction(action=”);
sb.append(getActionName(action));
sb.append(“, source=”);
sb.append(getSourceName(source));
sb.append(“, context=”);
sb.append(context);
sb.append(‘)’);

final String message = sb.toString();
System.out.println(message);
final LabelField field =
new LabelField(message, Field.FOCUSABLE);
this._logScreen.add(field);

return true;
}

public static String getActionName(int action) {
switch (action) {
case MEDIA_ACTION_NEXT_TRACK:
return “NEXT_TRACK”;
case MEDIA_ACTION_PLAYPAUSE_TOGGLE:
return “PLAYPAUSE_TOGGLE”;
case MEDIA_ACTION_PREV_TRACK:
return “PREV_TRACK”;
case MEDIA_ACTION_VOLUME_DOWN:
return “VOLUME_DOWN”;
case MEDIA_ACTION_VOLUME_UP:
return “VOLUME_UP”;
}
return Integer.toString(action);
}

public static String getSourceName(int source) {
switch (source) {
case SOURCE_BACKGROUND_KEY:
return “BACKGROUND_KEY”;
case SOURCE_BLUETOOTH_HEADSET:
return “BLUETOOTH_HEADSET”;
case SOURCE_FOREGROUND_KEY:
return “FOREGROUND_KEY”;
case SOURCE_WIRED_HEADSET:
return “WIRED_HEADSET”;

}
return Integer.toString(source);
}
}

}

BlackBerry API Hidden Gems (Part Two)

Denver C. — Thu, 13 Aug 2009 12:22:00 +0000

In yesterday’s BlackBerry API Hidden Gems post, I showed you some of my favorite classes and methods oft overlooked within BlackBerry® APIs. I’ve got a few more in store for you today, so let’s get started!

IntVector

In the net.rim.device.api.util package there are a bunch of collections for storing primitive Java types, such as ‘int’, ‘byte’, and ‘long’, which mirror the equivalent java.util classes. Using these classes to store the primitive types is more efficient in both memory and time than storing wrapper objects in standard java.util collections.

My favourite example is IntVector. IntVector has the same methods as java.util.Vector but stores primitive ‘int’ values instead of Object references. Under the hood it uses an int[] array to store values instead of an Object[] array and therefore no conversions between ‘int’ and Integer are necessary. This makes IntVector much better for storing ‘int’ values than java.util.Vector as it is both faster and uses less memory. It is also fully synchronized, just like java.util.Vector.

Other adapted classes in net.rim.device.api.util include:

ByteVector and LongVector: similar to IntVector but for ‘byte’ and ‘long’ types.
IntHashtable, LongHashtable: adaptations of Hashtable that use primitive ‘int’ and ‘long’ values as the keys, and Objects as the values.
ToIntHashtable, ToLongHashtable: similar to IntHashtable and LongHashtable but uses Objects for the keys and ‘int’ and ‘long’ for the values.

Here is an example usage of IntVector to store a list of high scores, with the highest scores at the lowest indices.

public class HighScores {

private IntVector _scores;

public HighScores() {
_scores = new IntVector();
}

public void add(int score) {
if (_scores.contains(score)) {
return; // already there
}

boolean isAdded = false;
for (int i = 0; i < _scores.size(); i++) {
if (_scores.elementAt(i) < score) { _scores.insertElementAt(score, i); isAdded = true; break; } } if (!isAdded) { _scores.addElement(score); } while (_scores.size() > 10) {
_scores.removeElementAt(_scores.size() – 1);
}
}

public int getHighScore() {
if (_scores.isEmpty()) {
return 0;
} else {
return _scores.elementAt(0);
}
}

public int[] getHighScores() {
int[] array = new int[_scores.size()];
_scores.copyInto(array);
return array;
}
}

Timer and TimerTask

Like weak references, this next gem is also defined in CLDC but is mostly overlooked for its utility. Suppose you want to perform background tasks in your application. You can either use Application.invokeLater() or devise a grandiose background thread implementation that cleverly uses Java® synchronization primitives to efficiently perform background event dispatching. The former consumes your application’s event thread, potentially causing UI lag, and the latter is just a lot of work.

I recommend whipping out Timer and TimerTask for background task processing. Each Timer object has exactly one background thread which processes TimerTasks sequentially. These tasks can be scheduled to occur immediately, after some delay, at a particular time, or repeatedly at a given interval.

The sample below shows how to use Timer and TimerTask to notify an object on a non-event thread about the user pressing the trackball.

public class MyScreen extends net.rim.device.api.ui.container.MainScreen {

private Timer _timer;

public MyScreen() {
this.setTitle(“Timer Demo”);
this._timer = new Timer();
}

public void onTrackballClick() {
System.out.println(“Quit pressing the trackball!”);
}

protected boolean navigationClick(int status, int time) {
this._timer.schedule(new ClickTask(), 0);
return super.navigationClick(status, time);
}

private class ClickTask extends TimerTask {
public void run() {
onTrackballClick();
}
}
}

There are many more hidden gems in the BlackBerry® SDK but just not enough time here to share them all. I will be doing a talk on this topic at the 2009 BlackBerry Developer Conference and plan to talk about some hidden gems not mentioned here as well as some lesser-known cool features of the JDE itself. If you have found any hidden gems of your own please comment on this post to share your great discovery with the world! I’d love to know which APIs you find useful.

BlackBerry API Hidden Gems (Part One)

Denver C. — Wed, 12 Aug 2009 12:27:00 +0000

Every time I think I know everything, I am always proven wrong. For example, I used to think I knew everything about BlackBerry® APIs but as I continue developing software I am still finding new, cool classes and methods that make my life easier. I call them “hidden gems” since they are often found by one stumbling across them, but when found are of great use. In this post I will highlight some of my favourite gems, which I hope will make your life as a developer easier too. So let’s dive in.

Weak References

For the longest time I had heard the term “weak references” but never really knew what they were. Once I finally learned, I started to use them all the time to be more efficient and avoid memory leaks. Indeed, weak references are not BlackBerry specific, but are defined right in the CLDC specification in the class java.lang.ref.WeakReference.

So what is a “weak reference” anyways? The behaviour of a weak reference when contrasted with the normal “strong” reference pertains to making an object a candidate for garbage collection. A weak reference gives you the ability to access an object but also makes it available to the garbage collector. So why would this be useful? I find that there are often circumstances when you only care about an object if someone else does. Holding a weak reference to an object is one way of determining if anyone else cares about it, based on the assumption that anyone who cares about it will hold a strong reference to it. Once nobody cares about the object (other than me) it will be garbage collected. This is the opposite of holding a strong reference to the object, as doing so would prevent the object from being garbage collected, wasting precious memory.

One excellent use case for weak references is holding a reference to an application object. In general, you only need to reference an application object while the application it represents is alive; once the application exits you no longer need the reference. By holding a strong reference to the application object, the garbage collector will be prevented from freeing the object’s memory even after the application exits, along with the massive number of objects that it recursively references. Instead, holding a weak reference to the application object allows it to be garbage collected when the application exits.

Below is an example of how a weak reference to an application object can be used in a memory-efficient manner to determine if an application is still alive.

import net.rim.device.api.system.Application;

import java.lang.ref.WeakReference;

public class ApplicationLifeMonitor {

private WeakReference _appRef;

public ApplicationLifeMonitor() {
Application app = Application.getApplication();
_appRef = new WeakReference(app);
}

public boolean isAlive() {
Application app = (Application) _appRef.get();
return (app != null && app.isAlive());
}
}

UIDGenerator

The UIDGenerator class does exactly what its name implies: generates unique IDs. Its class javadocs defines it as “a utility class to generate 32-bit unique IDs that can be used for synchronization or any other purpose.” Here’s an example to show how it could be used:

public class Person {

private int _id;
private String _name;

public Person(String name) {
this._id = UIDGenerator.getUID();
this._name = name;
}

public int getId() {
return this._id;
}

public String getName() {
return this._name;
}
}

IOUtilities.streamToBytes()

Have you ever written code like this to dump the bytes from an InputStream into a byte[] array?

public static byte[] getBytes(InputStream in)

throws IOException {

ByteArrayOutputStream out = new ByteArrayOutputStream();

byte[] buffer = new byte[2048];

int readCount = in.read(buffer);

while (readCount >= 0) {

out.write(buffer, 0, readCount);

readCount = in.read(buffer);

}

return out.toByteArray();

}

Now you can do it in one line:

public static byte[] getBytes(InputStream in)

throws IOException {

return net.rim.device.api.io.IOUtilities.streamToBytes(in);

}

Impress your friends at your next party with this neat trick.

Stay tuned for tomorrow’s post when I’ll share even more BlackBerry API gems with you!