First, lets take a quick look at the APIs involved. The drawString() method is pretty straightforward:

public void drawString(String str, int x, int y, int anchor);

The purposes of the str, x, and y parameters should be obvious. The anchor parameter defines how the text should be positioned in relation to the specified x and y coordinates. The accepted values are LEFT, HCENTER, RIGHT for the horizontal positioning, and TOP, BASELINE, and BOTTOM for the vertical positioning. These constants can be combined using the logical OR operator, e.g.:

g.drawString("Hello World", 100, 100,
Graphics.TOP | Graphics.HCENTER);

For our first effect, we will draw a string in a specified color with a black outline with the method below.

public void drawStringThick(
  Graphics g, String str, int x, int y,
  int anchor, int fillColor
) {

  g.setColor(0x000000);
  g.drawString(str, x + 1, y + 1, anchor);
  g.drawString(str, x + 1, y - 1, anchor);
  g.drawString(str, x - 1, y + 1, anchor);
  g.drawString(str, x - 1, y - 1, anchor);

  g.drawString(str, x + 2, y + 2, anchor);
  g.drawString(str, x + 2, y - 2, anchor);
  g.drawString(str, x - 2, y + 2, anchor);
  g.drawString(str, x - 2, y - 2, anchor);

  g.setColor(fillColor);
  g.drawString(str, x, y, anchor);

}

The next method will draw a string with a pseudo-3D rainbow effect.

public void drawCrazyString(
  int x, int y, Graphics g,
  String msg, int anchor
) {
  Font font = Font.getFont(
    Font.FACE_PROPORTIONAL,
    Font.STYLE_BOLD,
    Font.SIZE_LARGE
  );
  g.setFont(font);
  g.setColor(0x0000FF);
  g.drawString(msg, x + 10, y + 10, anchor);
  g.setColor(0x00FF00);
  g.drawString(msg, x + 8, y + 8, anchor);
  g.setColor(0xFFFF00);
  g.drawString(msg, x + 6, y + 6, anchor);
  g.setColor(0xFF7700);
  g.drawString(msg, x + 4, y + 4, anchor);
  g.setColor(0xFF0000);
  g.drawString(msg, x + 2, y + 2, anchor);
  g.setColor(0xFFFFFF);
  g.drawString(msg, x, y, anchor);
}

With some creativity, you should be able to come up with other combinations of these method calls that will produce some interesting results. Happy coding!

The complete signature of the enumerateRecords() method looks like this:

public RecordEnumeration enumerateRecords(
RecordFilter, RecordComparator, boolean)
throws RecordStoreNotOpenException

This method returns an object that enumerates a set of records from the RecordStore. The RecordFilter argument allows the application to specify criteria that will used to return a subset of records. Similarly, the RecordComparator argument allows the application to define logic that will determine the order of the records that are returned.

For example, lets say we have an application with a record store containing ZIP codes.

/**
 * Initializes record store with some ZIP codes.
 */
public RecordStore initRecordStore() {
try {
    
    // Open or create RecordStore
    RecordStore recordStore
    = RecordStore.openRecordStore("zipCodes", true);

    // Add records if this record store hasn't yet 
    // been initialized
    if(recordStore.getNumRecords() == 0) {
        recordStore.addRecord("49120".getBytes(), 0, 5);
        recordStore.addRecord("90210".getBytes(), 0, 5);
        recordStore.addRecord("56921".getBytes(), 0, 5);
        recordStore.addRecord("10210".getBytes(), 0, 5);
        recordStore.addRecord("32010".getBytes(), 0, 5);
    }

    return recordStore;

} catch(RecordStoreException e) {

    System.err.println("Could not initialize record store");
    return null;

}
}

Now, let’s say we want to be able to return only ZIP codes that appear in a specific range, and we want them returned in lexicographical order. First we will create a class that implements RecordFilter to specify the filtering. The start and end of the range will be data members of this class.

import javax.microedition.rms.*;

public class RangeRecordFilter implements RecordFilter {

/**
 * Creates a new instance of RangeRecordFilter
 */
public RangeRecordFilter(String start, String end) {
    setStart(start);
    setEnd(end);
}

/**
 * Determines if candidate is in specified range.
 */
public boolean matches(byte[] candidate) {
    String candidateString = new String(candidate);

    return (getStart().compareTo(candidateString) <= 0
        && getEnd().compareTo(candidateString) >= 0);
}

public String getStart() {
    return start;
}

public void setStart(String start) {
    this.start = start;
}

public String getEnd() {
    return end;
}

public void setEnd(String end) {
    this.end = end;
}

private String start;
private String end;
    
}

Next, we will create a class that implements RecordComparator to specify the ordering.

import javax.microedition.rms.*;

public class StringRecordComparator implements RecordComparator {

public int compare(byte[] rec1, byte[] rec2) {
    
    // Convert to String objects
    String rec1String = new String(rec1);
    String rec2String = new String(rec2);

    // Do a string comparison
    int comparison = rec1String.compareTo(rec2String);
    if(comparison < 0) {
        return RecordComparator.PRECEDES;
    } else if(comparison == 0) {
        return RecordComparator.EQUIVALENT;
    } else {
        return RecordComparator.FOLLOWS;
    }

}

}

Now we can use these classes to return an ordered subset of ZIP codes in a specified range from our record store. For example:

RecordStore recordStore = initRecordStore();
if(recordStore != null) {

    // Create filter and comparator
    RangeRecordFilter filter =
        new RangeRecordFilter("40000", "60000");
    StringRecordComparator comparator
        = new StringRecordComparator();

    // Enumerate matching records
    RecordEnumeration records;
    try {
        records = recordStore.enumerateRecords(
        filter, comparator, false);
    } catch(RecordStoreNotOpenException e) {
        System.err.println("Could not enumerate");
        return;
    }

    // Output the results
    while(records.hasNextElement()) {
    byte[] rec;
    try {
        rec = records.nextRecord();
    } catch(Exception e) {
        System.err.println("Could not get record");
        return;
    }
    System.out.println(new String(rec));
}

For more information about record stores, be sure to read the javax.microedition.rms Package Documentation

From a developer perspective, there are three major components you will need to worry about when working with the MMAPI. Player objects are used to process content and rendered it to the user. Manager objects are factories that create Player objects. Lastly, you will need an object to provide the input for the content itself. This can either be a DataSource or an InputStream object.

I’ve contructed a very simple MIDlet that demonstrates how to play a video, which I will be referring to below. The full source code for this MIDlet can be found here: MMAPI Video Demo Source Code. An example MPEG file is included in this file. If you are using NetBeans Mobility Pack, make sure you have enabled the optional package “Mobile Media API” in your project configuration.

In this example, I’ve created a class called VideoForm that encapsulates all of the required logic for initializing and playing the video. A StringItem object is used to inform the user of the current status. The block of code below is used to create the player object. Note that getMediaFileName() and getContentType() are simply accessor methods in my VideoForm class. For this simple example, the video will be a resource stored in the JAR file, and the application will aquire an InputStream for it using the getResourceAsStream() method.

// Create the Player object from an InputStream
InputStream inputStream = 
    getClass().getResourceAsStream(getMediaFileName()); 

Player player = Manager.createPlayer( 
    inputStream, 
    getContentType() 
);

// Set the loop count 
player.setLoopCount(getLoopCount()); 

// Realize (contruct player) 
getStatusItem().setText("Realizing..."); 
player.realize(); 
getStatusItem().setText("Realized."); 

// Prefetch (aquire resources) 
getStatusItem().setText("Prefetching..."); 
player.prefetch(); 
getStatusItem().setText("Prefetched.");

Now we can get a VideoControl object which can be added to our form. As you may have noticed, VideoControl is not part of MIDP 2.0, therefore the device must support MMAPI in order for this to work. Alternatively, if you were using a Canvas instead of a Form as your displayable object, you could take advantage of the VideoControl.USE_DIRECT_VIDEO option to write directly to the Canvas.

// Add VideoControl to form 
VideoControl videoControl = 
    (VideoControl)player.getControl("VideoControl"); 

if(videoControl != null) { 
    Item videoItem = 
    (Item)videoControl.initDisplayMode( 
        VideoControl.USE_GUI_PRIMITIVE, 
        null); 
    append(videoItem); 
}

VideoForm form = new VideoForm("Video Test"); 
form.setContentType("video/mpeg"); 
form.setMediaFileName("/video.mpg"); 
... 
// Start the video 
form.play();

MMAPI Home Page
MMAPI JavaDoc
J2ME Tutorial, Part 4: Multimedia and MIDP 2.0

The Wireless Messaging API can be found in the javax.wireless.messaging package. Sending of messages is handled by the MessageConnection class. MessageConnection objects are obtained by calling the open() method of the javax.microedition.io.Connector class with a URL string in the format:

protocol://address:port

For example:

sms://+12125551212:5000

For SMS, the address part represents the MSISDN of the destination; typically this is a telephone number with country code. The port number is application specific. If you want the default messaging application of the destination device to open the message, simply leave off the port number.

Below is sample code for sending a text message. Note that in a production application, you may want to spawn a new thread for running this code, as it involves a network call that could potentially block the user interface. Also, exception handling has been ommitted from this example for clarity.

import javax.wireless.messaging.MessageConnection;
import javax.wireless.messaging.TextMessage;
import javax.microedition.io.Connector;
import java.io.IOException;

public class SMSUtility {

public static void sendMessage(String msisdn, String text)
    throws IOException {

    // Open connection
    MessageConnection con = (MessageConnection)
    Connector.open("sms://+" + msisdn);

    // Create new message
    TextMessage message = (TextMessage)
    con.newMessage(MessageConnection.TEXT_MESSAGE);

    // Set text
    message.setPayloadText(text);

    // Send message
    con.send(message);

    // Close connection
    con.close();

}

}

For more information about WMA, including other uses such as opening server connections, check out the following links:

Wireless Messaging API (WMA); JSR 120, JSR 205
Sun Java Wireless Toolkit: Using the Wireless Messaging API
Java ME Technical Articles: WMA

A localized application has the ability to display text for the correct language based on the locale of the device. This includes text for labels, alerts, commands, buttons, etc. A localized application should be able to support new languages without making modifications to the application logic. In Java ME, this is achieved through MIDP localization.

The current locale of the device can be determined by querying the microedition.locale system property. For example:

String curLocale = System.getProperty("microedition.locale");

One approach to localization involves the creation of property bundle files containing name-value pairs which represent all the various pieces of text to be displayed in the application. NetBeans Mobility Pack provides an MIDP localization wizard to facilitate the maintenance and use of such property bundle files.

To start, right-click on the node for your MIDP project, select “New File/Folder…”, and then select “MIDP” > “Localization Support Class.” On the next dialog, simply accept the default values by clicking “Finish.”

You should now see a new class in the project tree named LocalizationSupport, as well as a messages.properties file. Open the messages.properties file by double-clicking on its node, and add the following line to define a localization key and value:

Title = Hello World

Now, let’s add a new locale. Right-click on the messages.properties node in the project tree, and select “Add Locale…” Choose a locale from the list; for this example, I selected “es_MX”. Now expand the messages.properties node, and you will see a new sub-node titled “es_MX – Spanish (Mexico)” beneath the “default language” node. Double-click the “es_MX” node to open the localized file. You should see that the “Title” property has been copied from the default language file. Change the value “Hello World” to “Hola Mundo”, and save the file.

Within your application, you can now do the following to retrieve the localized string:

String title = LocalizationSupport.getMessage("Title");

Last but not least, you may want to test your application for different locales. Luckily, it is possible to emulate a user-specified locale in the WTK emulator. Search for a file called “ktools.properties” in your wireless toolkit folder. By adding the line below to this file, the emulator will emulate the specified locale.

microedition.locale=es-MX

For more information about localization in Java ME, check out the resource below. Also, be sure to read the page titled “Adding Localization Support to a MIDP Application” in the NetBeans IDE Help.

• How to create a localized application

The push registry allows your application to request that the device launch a MIDlet asynchronously. This ability can be incredibly useful for many types integration. There are two types of push events: push connections and push alarms. A push connection is triggered in response to an inbound network connection. A push alarm, on the other hand, is triggered by a timer and can be used run some code on a regular interval, for example.

There are two ways to register a push event. Push connections and push alarms can be registered using the PushRegistry API, found in the javax.microedition.io.PushRegistry class. In addition, push connections can be defined in the JAD file or JAR manifest.

The PushRegistry API has a number of limits. First, when using connection events, only one application can be registered on a given port at a time. This means that your application should probably be designed to handle conflicts at port-level. Second, both push and network operations are considered restricted operations in MIDP 2.0. This means that your application must explicitly request push and network permissions in the JAD file or JAR manifest. In addition, your code will probably need to be signed in order for it to be granted those permissions on most devices.

For more detailed information about the PushRegistry, be sure to check out the following links:

• PushRegistry API JavaDoc
• The MIDP 2.0 Push Registry

TiledLayer is part of the javax.microedition.lcdui.game package that was introduced with MIDP 2.0. The constructor for the TiledLayer class accepts five parameters: the number of columns and rows in the grid, an Image object containing the tiles, and the width and height in pixels of each tile.

TiledLayer(int columns, int rows, Image image, int tileWidth, int tileHeight)

The image can have multiple rows of tiles. The tileWidth and tileHeight properties are used to break up the image into individual tiles. The tiles are numbered starting with 1 and incrementing in row-major order. Index 0 is reserved for transparency; TiledLayer won’t draw anything for cells with index 0.

For our example application, we’ll start by creating a class that extends GameCanvas. Extending GameCanvas will allow us to take advantage of the off-screen buffer that this class provides.

import javax.microedition.lcdui.*;
import javax.microedition.lcdui.game.*;
public class DemoCanvas extends GameCanvas {

Next, we’ll add an instance variable for our TiledLayer object, along with the customary setter and getter methods.

public TiledLayer getTiledLayer() {
    return tiledLayer;
}
public void setTiledLayer(TiledLayer tiledLayer) {
    this.tiledLayer = tiledLayer;
}
// Instance variables
private TiledLayer tiledLayer;  // The TiledLayer object

We will also add some constants to store the size of our tiles in pixels, and the background color. Remember that the 0 index tiles are transparent, so we will be responsible for clearing the background ourselves.

// Constants
public static final int TILE_WIDTH = 16;
public static final int TILE_HEIGHT = 16;
public static final int BACKGROUND_COLOR = 0x00000000;

We will need to provide some data for the grid. For the purposes of this example, we can hard code some data into a two-dimensional array. In a real-life application, you would probably read this data from a resource, generated from some sort of map editor software.

public byte[][] getGridData() {      // Create and populate a two-dimensional
    // array with sample grid data
    byte gridData[][] = {
        {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0},
        {0,0,0,1,2,2,2,3,0,0,0,0,10,10,0,0},
        {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0},
        {0,0,0,10,10,0,0,0,1,2,2,3,0,0,0,0},
        {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0},
        {0,0,1,2,2,3,0,0,0,0,0,4,5,6,0,0},
        {0,0,0,0,0,0,0,0,0,0,0,0,12,0,0,0},
        {7,8,8,8,8,8,8,8,8,8,8,8,8,8,8,9}
    };      
    return gridData;
}

Now, we will add a method to create and initialize our TiledLayer object. To initialize the cells, we will simply iterate through the byte array we created above and call the TiledLayer.setCell() for each value.

public void initTiledLayer() {

    // Get the grid data
    byte[][] gridData = getGridData();

    // Derive number of columns and rows
    // from grid data array sizes
    int rows = gridData.length;
    int columns = gridData[0].length;

    // Get the tile Image object
    Image tileImage;
    try {
        tileImage =
        Image.createImage("/tiledlayer-tiles.png");
    } catch(java.io.IOException e) {
        System.err.println("Unable to create image");
        e.printStackTrace();
        return;
    }

    // Create a TiledLayer object
    TiledLayer tiledLayer = new TiledLayer(
    columns, rows, tileImage,
    TILE_WIDTH, TILE_HEIGHT);

    // Transfer grid data to TiledLayer object
    for(int y = 0;  y < rows; y++) {
        for(int x = 0; x < columns; x++) {
            int tileIndex = gridData[y][x];
            if(tileIndex > 0)
                tiledLayer.setCell(x, y, tileIndex);
        }
    }

    // Set the TiledLayer instance variable
    setTiledLayer(tiledLayer);

}

Next, we need a method to draw the background. In addition to rendering the TiledLayer object, it will also need to clear the background. Note that since GameCanvas provides an off-screen buffer, there is no need to override the paint() method; GameCanvas already provides an adequate implementation.

public void drawBackground() {
    
    // Get off-screen buffer
    Graphics g = getGraphics();

    // Clear the background
    g.setColor(BACKGROUND_COLOR);
    g.fillRect(0, 0, getWidth(), getHeight());

    // Paint the tiled layer
    TiledLayer tiledLayer = getTiledLayer();
    if(tiledLayer != null) {
        tiledLayer.paint(g);
    }

}

Now we’ll add a custom constructor to call our initialization method, and to perform the initial drawing of the off-screen buffer. Since we’ll be overriding the keyPressed() method in the next step, we will pass false for the suppressKeyEvents parameter of the GameCanvas constructor.

protected DemoCanvas() {

    // We will be overriding keyPressed,
    // so do not suppress key events
    super(false);

    // Initialize the TiledLayer
    initTiledLayer();

    // Draw to the off-screen buffer
    drawBackground();

}

Lastly, we’ll implement an extremely simple keyPressed() method that will scroll the background when the direction keys are pressed using the convenient TiledLayer.move() method. It will also force a repaint of the off-screen buffer and flush it to the display.

protected void keyPressed(int keyCode) {

    // Handle scrolling in response to key presses
    TiledLayer tiledLayer = getTiledLayer();
    if(tiledLayer != null) {

        // Get game action from key code
        int gameAction = getGameAction(keyCode);

        switch(gameAction) {
            case UP:
                tiledLayer.move(0, -16);
                break;
            case DOWN:
                tiledLayer.move(0, 16);
                break;
            case LEFT:
                tiledLayer.move(-16, 0);
                break;
            case RIGHT:
                tiledLayer.move(16, 0);
                break;
        }

        // Repaint the off-screen buffer
        paintBackground(getGraphics());

        // Flush the off-screen buffer to the display
        flushGraphics();

    }

}

There you have it. The source code for the completed example is available here: TiledLayer Example Source Code

For the purposes of this article, we will be focusing on the NetBeans implementation of preprocessor directives. First, you will need to create a configuration for each platform you wish to support. To do this, open the project properties dialog (available from the “File” menu), and click “Manage Configurations” in the upper right hand corner of the dialog. Click “Add…” to add a new configuration. Choose the template that corresponds to the platform you are developing for, then enter a meaningful name for the configuration, and click OK. Note that if you are targeting a platform that utilizes a third-party API, you may need to download the corresponding development kit from the vendor’s website in order to enable the proper templates.

Next, define any variables you wish to reference from the preprocessor directives in the Abilities table. You can do this from the “Abilities” tree node in the project properties dialog. A number of useful variables are already predefined by NetBeans, and you can add others as necessary.

Now you are ready to put preprocessor directives to work. Revisiting our previous tutorial on Sprint MIDP 1.0 Extensions, here are some snippets of code that could be used to play a sound, in both the MIDP 2.0 and Sprint PCS MIDP 1.0 platforms.

//#if MIDP=="2.0"
import javax.microedition.media.*;
//#elif vendor=="SprintPCS"
import com.sprintpcs.media.*;
//#endif

public void playSound(String uri) throws Exception {
//#if MIDP=="2.0"
    
    // Play sound
    Player p = Manager.createPlayer(uri);
    p.start();

//#elif vendor=="SprintPCS"

     // Create a new clip object
    Clip clip = new Clip(
        uri,
        "audio/vnd.qcelp",  // MIME type
        1,  // Priority
        0   // Seconds of vibration
    );

     // Play sound
    Player.playBackground(
        clip, // Clip object
        0   // Do not repeat
    );

//#endif

}

For a more in depth look at the NetBeans preprocessor directive syntax, check out the following article: Defining and Using Preprocessor Directives in the Mobility Pack. You may also want to take a look at another preprocessing solution offered by J2ME Polish.

One popular third-party library is MathFP, which according to the author is free for non-commercial use. Note, however, that every operation is a method call; that can turn into a lot of overhead. If you are writing an application where performance is a major concern (i.e. video games), your best bet is to roll your own fixed point math code, and implement it inline rather than through method calls.

The following article provides some good examples of using inline fixed point arithmetic in a Java application: Optimizing Fixed Point (FP) Math with J2ME

Sinfah’s Lair reached the 20,000 download mark today on GetJar. Many thanks to everyone who has played and provided feedback!