Introduction to the BREW Framework

Porting a mobile application from Java to BREW is not a trivial task. Developing an application from scratch is also quite much harder in BREW than in Java. Generally, Java Microedition is a much higher-level programming platform than the combination of C/C++ and the BREW API. There are quite a number of reasons for this:

• There are substantial differences between the programming languages. It is possible to program for BREW in C++, though most BREW examples you will see on the net are coded in plain C. Yet even C++ is not so similar to Java as you might initially think.

• The BREW phone platform imposes some pretty heavy restrictions on what you can do and what not. We will point out some of the significant restrictions later on.

• The ARM compilers (the compilers for ARM processors which are used in BREW phones) do not support some important features of the C++ language like exceptions or static variables.

• The basic concepts of BREW and Java Microedition are completely different. BREW is an exclusively event-driven platform, while J2ME programs usually rely on using long loops and blocking operations.

• The BREW API is written for programming in C, which means it does not use OOP, while Java is strictly object-oriented. As a result the programming APIs of BREW and J2ME are completely different.

These are just a number of the problems one encounters when developing or porting an application for BREW. Porting normally becomes as heavy as rewriting almost the whole application. This process not only takes a long time but it usually introduces lots of new bugs that have to be fixed and leads to frustrated developers. We do not want this.

The BREW Framework targets to eliminate the problems mentioned above. The result is that porting or developing with the framework is several times faster, much less error-prone and much less frustrating. When porting, the resulting source code is very, very similar to the original code, which makes it much easier to maintain later on. Code produced with the framework is also way more readable than code written in the traditional BREW programming style.

Let's be more specific and take a look at the key problems in BREW programming one by one and see how the framework helps:

Java is object-oriented, BREW is not. The APIs in J2ME and BREW are completely different.

Java has Threads. Java allows for infinite loops and blocking operations. BREW does not.

This is a very important difference. The BREW platform is essentially single-threaded. Everything the phone does happens in a single infinite loop. When your application receives time to do something, it has to do it quickly and return execution, otherwise the phone will hang. You cannot wait for a resource to be fetched from the Internet for example. Instead you instruct the phone to fetch the result, you specify a callback function and return from your code. Then, when the result is ready it will a call your callback function and you can continue. However this means you have lost your implicit program stack context.

This is what we mean by saying that BREW is purely event-driven. This also means you cannot have a single infinite loop in your application and probably 95% of all J2ME games are coded this way.

Java has a Garbage Collector. C++ does not. BREW has very strict requirements for managing memory correctly.

One of the major pains in BREW programming is memory management. First, C++ does not provide a garbage collector. Second, with the C-style BREW APIs you do not get any destructors and you have to free the memory all by yourself. Third, the BREW application certification procedure is very strict - not only must your program release every bit of memory and every limited resource it has used, but also every time it allocates new memory, it has to check whether the memory was really allocated correctly - if it uses the NULL pointer returned by MALLOC() because there is no more free memory, the phone would restart. This, combined with the fact that you cannot use Exceptions is a real pain compared to Java programming.

Java has Exceptions. BREW does not. Error handling is difficult, but the BREW requirements are very strict in this aspect.

Java has native support for Strings. Java arrays have boundary checking and provide a length property. Java has collections.

Java and C++ have a different syntax in many aspects

For example classes are defined in a different way - a class in C++ is split between a header and cpp file and there are many other small differences. Static methods are accessed with Class.method() in Java, but with Class::method() in C++. There are many things like this.

As part of the BREW Framework we have a utility called the BREW Translator that reads J2ME code, applies some transformations and outputs BREW code (which uses the BREW Framework). The result is not ready to compile and run, but it takes care of the most tedious differences automatically.

In BREW you cannot have static variables.

This is again a restriction of the compilers. The BREW Framework helps alleviate this problem by providing static getInstance() methods in the important Singleton classes in the framework. Often this removes the need for some of the static variables. Actually, this restriction is usually not so important, since most J2ME applications use a single (or several) Canvas classes and the static variables in them can just as well be non-static without sacrificing anything. Notice that in BREW you can have static constants.

BREW has strict application certification requirements

Key benefits

Time

Porting a Java application to BREW, or developing a new application is several times faster when using the framework than when starting the BREW application from scratch. There are multiple reasons for this significantly increased productivity:

• The developer does not have to deal with the low-level APIs of BREW, the framework classes provide a much higher-level interface.
• It is not necessary to invest time to understand all the code in order to port it. This saves a lot of time.
• Much less bugs are introduced while porting, so much less time is needed to fix them.
• We, the framework developers have already fallen in enough BREW-specific pitfalls and have cleared the road. You won't hit them.
• Bringing the application from beta state to certification-ready state is much shorter - most of the aspects are already properly handled in the framework.
• Object-oriented programming is easier than C-style programming in a good IDE.

Maintenance costs significantly reduced

Porting with the framework results in source code that is almost identical to the original sources. This is great when costs for maintenance are considered. For example, applying a bug-fix to the ported code is pretty much the same as applying the same bug-fix to the original code. You can usually use file-comparison tools like WinMerge to apply patches to both versions.

Source code produced with the BREW Framework is very readable - just as much as Java code. Much more readable than source code written in the traditional BREW programming style. This makes it easier to introduce new developers to the project at a later time.

Porting is easy

Porting with the BREW Framework is quite easy. Normally you just follow a step-by-step guide. Even unexperienced programmers can do it under the supervision of someone more experienced. Of course, good understanding of C++ always helps.

Porting is much more pleasant

Porting with the framework removes the large part of the unpleasant emotions the developers hit while they struggle to bring an application working on the much higher-level Java to the much lower-level BREW. This is especially valid when it comes to porting someone else's source code - it is usually quite difficult and frustrating to try to understand a badly written or poorly documented code. With the framework you do not need to understand most of it. Besides, it is rewarding to see the application running in the emulator a couple of days after the port has started.

Less risk of failing the certification procedure

The framework has been used for quite a lot of projects that have passed the BREW certification procedure. It is already well tested and handles some requirements automatically. Usually the developer does not have to do almost anything in order to conform to the requirements - the ported, running application already meets them.

Overview of the functionality of the framework. Sample code

We already covered some aspects of the framework, now let's make a more comprehensive list of the supported functionality.

Adapter classes, corresponding to equivalent J2ME functionality. Other important classes.

The BREW Framework implements equivalents for the most important J2ME classes. The framework classes provide the same interface and sometimes add some utility methods that are lacking in Java but are helpful while developing applications from scratch (for example Vector::sort()). Here we will cover the main classes in the framework, giving small code samples for most of them.

String, StringBuffer

The String class is almost fully identical to the Java String class in terms of interface. It is immutable and uses memory sharing between copies of the same String. It provides all the necessary constructors and cast operators to work both with char* and AECHAR* strings.

There is also a StringBuffer class implemented.

Array, Vector, Hashtable

The framework provides both an Array class to replace the standard Java arrays, and Vector and Hashtable classes for the equivalent collection classes in J2ME. All these are template classes, so they can be used with different classes and primitive types (int, char, etc.). This is the reason the framework does not provide classes for Integer, Long and the other Java primitive-type wrapper classes - they are mainly used in Java for storing in collections and with the template classes in the framework there is no need for them.

There are some requirements to the classes that can be used with these template collections - the class should provide a default constructor and also, depending on the collection methods that will be used, it may have to provide a copy constructor, operator=, operator==.

Multi-dimensional arrays can also be used with Array<Array<X>>. Java has a special syntax for initializing arrays - the Array class has some constructors to help converting such code.

These classes implement the Nullable interface. They also provide copy constructors and assignment operators. Array uses memory sharing between the copies - this means copies of the same array will point to the same memory. Unlike Array, Vector and Hashtable do not implement memory sharing between different copies - the copy constructor and assignment operator make a deep copy of the collection (act as clone() in Java). This should be taken into account when porting code like:

Vector v1; 
Vector v2 = v1; 
v2.add("Text"); 
if (!v1.isEmpty()) {
	...
}.

In such cases the user has to use references or pointers in the C++ code.

int[] a = null;
Vector v = new Vector();
Hashtable h = new Hashtable(); // Integer -> String
if (a == null) {
	a = new int[5];
	for (int i=0; i < a.length; i++) {
		a[i] = i;
		v.addElement(new Integer(a[i]));
		h.put(new Integer(a[i]), new String(a[i]));
		String value = (String)(h.get(new Integer(a[i])));
	}
}
int[] b = new int[] { 1, 2, 3 };
int[][] c = new int[][] { {1, 2, 3}, {4} }; //two dimensional array with different length of the rows

Array<int> a = NULL_OBJ;	//or simply Array<int> a;
Vector<int> v;
Hashtable<int, String> h;	//the default constructors of Vector and Hashtable, unlike that of Array, produce a real non-null object
if (a == NULL_OBJ) {
	a = Array<int>(5); //there is a constructor for a specific length
	for (int i=0; i < a.length(); i++) { // length() is a method, not a member field
		a[i] = i;
		v.addElement(a[i]);
		h.put(a[i], String(a[i]));
		String value = (String)(h.get(a[i])); //the cast is redundant here, but we can leave it
	}
}
Array<int> b = Array<int>(3,  1, 2, 3); // variable number of arguments. You should specify the length as a first argument
Array< Array<int> > c = Array< Array<int> > ("{ {1, 2, 3}, {4} }"); //two dimensional array with different length of the rows
// you can use the above two constructors only with native types (int, char, etc.)

Thread

Because the BREW platform is essentially single-threaded there is no way to provide real threading support, but instead we have implemented a Thread class which provides cooperative multithreading. Cooperative multithreading means that only one Thread executes at a given time and it has to explicitly yield from time to time in order to give the other threads time to execute. The Thread class is based on the IThread BREW interface, which is unofficially supported on most phones with BREW 2.1 and is officially supported since BREW version 3.1.

The Thread class is also the way to achieve blocking functionality in BREW. For example if we want our code to look like this:

if (showDialog("Quit?", "Yes", "No")) { quit(); }

then we must call this code from inside a Thread. Code like this is used very often in Java and it is impossible to have similar code in the traditional style of BREW programming - we would have to split it into two parts: 1. show the dialog and register a callback; 2. process the result in the callback function.

Using Thread resembles in many aspects the usage of Threads in Java, but there are also differences. One difference is that if the Thread is going to execute for a long time, the developer is obliged to explicitly add yielding - for example once per every iteration in an infinite loop. Another difference is that wait() and notify() are methods of the Object class in Java, while in the BREW Framework they are methods of Thread.

Since the BREW platform actually never executes more than one piece of code at a time, there is no need for providing a replacement for the synchronized keyword. Because we can have multiple inheritance in C++ there is no need for a Runnable class in the framework, eighter.

Thread does not implement Nullable and its copy constructor and assignment operator are forbidden. This means that usually references or pointers have to be used when dealing with Threads. This is usually not a problem because of the way Thread is used in Java - more to define an interface than to be used directly in the code.

class MainCanvas {
	private MainThread mainThread;

	public void init() {
		mainThread = new MainThread();
		mainThread.start();
	}
}

class MainThread extends Thread {
	public void run() {
		String result;
		...code to fetch something from the Internet in order to authenticate the user...
		if (!result.equals("OK")) {
			midlet.notifyDestroyed();
			return;
		}
		while (true) {
			System.out.println("Doing something in an infinite loop....");
			Thread.sleep(1000);
		}
	}
}

class MainCanvas {
private:
	MainThread* mainThread;

public:
	void init() {
		mainThread = new MainThread();
		mainThread->start();
	}
	
	~MainCanvas() { 
		delete mainThread; // We need to release the memory - there is no GC. We could have used a SmartPointer instead.
	}
}

class MainThread : public Thread {
public:
	void run() {
		String result;
		WebRequest webRequest(this, Applet::getInstance().getCurrentCanvas());
		webRequest.sendRequest("http://some.url.for.authentication");
		if (!webRequest.getResultAsString().equals("OK")) {
			Applet::getInstance().close();
			return;
		}
		while (true) {
			DBGPRINTF("Doing something in an infinite loop....");
			WAIT(1000); //this is called once per iteration and is enough for yielding
		}
	}
}

Canvas

This class serves as an equivalent to the J2ME Canvas class. As in Java, the Canvas class sets an interface which subclasses are supposed to implement. The methods in the class deal with painting the screen and handling application events, such as keypress events, suspend and resume. As in Java the application always has an active Canvas. There are some differences from Java: the paint() method in Java accepts a Graphics object into which to draw, while we think that it is easier to have access to the Graphics object not only in the paint() method so Canvas has a method getGraphics(). Softkey support is closer to that in DoJa - there is no Command concept as in MIDP, instead softkey events are dealt like ordinary keypress events; there is a method setSoftLabel() to set the left or the right softlabel.

Canvas does not implement Nullable and its copy constructor and assignment operator are forbidden. This means that usually references or pointers have to be used when dealing with Canvases. This is usually not a problem because of the way Canvas is used in J2ME - more to define an interface than to be used directly in the code.

class SomeDialog : public Canvas {
	String message;
	Canvas& parent;

public:
	SomeDialog(Canvas& parent, String message) :
		parent(parent),
		message(message)
	{
		setSoftLabel(SOFTLABEL_LEFT, "");
		setSoftLabel(SOFTLABEL_RIGHT, "Ok");
	}

	void paint() {
		Graphics& g = getGraphics();
		g.drawParagraph(message, 0, 0, getWidth(), getHeight()); //takes care of wrapping the string properly
	}

	void processKey(int keyCode) {
		if (keyCode == KEY_SOFTKEY_RIGHT) {
			applet.setCurrentCanvas(parent);
		}
	}
}

Graphics, Image, Font

These classes provide the means for drawing on the screen. Their interface is very close to the interface of the Java equivalents, and some additional features have been added. With these classes it is possible to draw images, flip, scale or rotate images (using an arbitrary angle), draw lines, rectangles, circles, set clipping rectangles or translate the origin of the drawing system, draw strings, draw wrapped text, change fonts, use bold or underlined fonts, compute string width, etc.

Since Images and Fonts are often initialized on the fly and stored in collections, these two classes implement the Nullable interface and provide copy constructors and assignment operators.

Graphics also implements the Nullable interface and provides a copy constructor and an assignment operator, however the copies don't share the same memory for storing things like clipping rectangle, flipping mode, color, translation, etc. - all the mutable properties. This means that the original object and the copy might end up having different properties and this may lead to undesirable results. In such cases it is advisable to use references or pointers to Graphics instead of copying by-value.

Image img = Image.createImage("/image.png");
graphics.drawScaledImage(img, 0, 0, getWidth(), getHeight(), 0, 0, img.getWidth(), img.getHeight()); //scale the image into the whole screen
Font font = font.getFont(Font.FACE_SYSTEM | Font.SIZE_MEDIUM | Font.STYLE_PLAIN);
graphics.setFont(font);
String s = "Hello!";
int width = font.stringWidth(s);
int height = font.getHeight();
graphics.drawString(s, 0, 0);

Image img = ResourceManager::getInstance().loadImage(IDI_IMAGE); //we assume the image is in the BAR file (the BREW application resource file)
graphics.drawScaledImage(img, 0, 0, getWidth(), getHeight(), 0, 0, img.getWidth(), img.getHeight()); //scale the image into the whole screen
Font font = font.getBrewFont(AEE_FONT_NORMAL, -1); //creating fonts is different in BREW than in Java
// in the above line we could have used font.getBrewFont(20) to get the system font which is most close to 20 pixels in height.
// this is very convenient for preparing an application for many different handsets
graphics.setFont(font);
String s = "Hello!";
int width = font.stringWidth(s);
int height = font.getHeight();
graphics.drawString(s, 0, 0);

Scratchpad, RecordStore

These two classes provide persistency in BREW. The BREW Framework does not implement the whole Stream hierarchy from Java, so Scratchpad is a replacement for DoJa's Connector.openInputStream("scratchpad://....") and provides the same functionality using a slightly different interface, again adding some additional helper methods for convenience. Scratchpad has methods for reading and writing byte arrays, bytes, integers and longs at a specific position in the scratchpad.

The RecordStore class is still work in progress and is not part of the current version of the framework. When it is ready, it will have an equivalent interface to MIDP's RecordStore class.

InputStream in = null;
try {
	in = Connector.openInputStream("scratchpad:///0;pos=100");
	DataInputStream dis = new DataInputStream(in);
	int value = dis.readInt();
	...use value...
} catch (IOException e) {
	//handle exception
} finally {
	//properly close the input stream object
	if (in != null) {
		try {
			in.close();
		} catch (Exception ex) {
		}
	}
}

Scratchpad& scratchpad = Scratchpad::getInstance();
TRY( int value = scratchpad.readInt(100) );
...use value...
CATCH(
	//handle exception
);

InputStream, OutputStream, GzipInputStream

InputStream provides reading from a file or from the BAR. Apart from the standard methods known from Java, it also provides some helper methods to read the whole stream with a single call. OutputStream provides outputting into a file. GzipInputStream implements gzip decompression. It can be used to replace the DoJa JarInflater class where compression is needed.

The BREW APIs for gzip decompression require using callbacks (because decompression could be slow), so the GzipInputStream class should be used from inside a thread.

class SomeThread : public Thread {
public:
	void run() {
		InputStream inputFile("zipped.gz");
		Array<signed char> arrData = inputFile.readAll();
		GzipInputStream zipMemory((char*)arrData.getPtr(), arrData.length()); 
		// we could have created the GzipInputStream object around inputFile instead
		zipMemory.decompress();
		zipMemory.join((Thread*)this); // wait for the decompressing thread to finish its job
		Array<char> data = zipMemory.getData();
		...use data...
	}
}

MediaPlayerBox

The MediaPlayerBox provides means for playing sounds in BREW by wrapping the IMedia functionality. This class is distantly following the interfaces of DoJa's AudioPresenter and KDDI's MediaPlayerBox.

MediaPlayerBox mpb;
MediaResource mr("resources.bar", 6100, AEECLSID_MEDIAMMF); //a sound resource from the BAR, resource ID 6100, the type is MMF
mpb.setResource(mr);
mpb.setVolume(50); //set lower volume
mpb.play();

Applet

The Applet class is one of the central classes in the framework. It serves as a central dispatcher for events, provides error handling, memory handling. From developer's standpoint, it is most important with the helper methods it provides. There are methods for checking free memory, free file system space, reading arguments from a configuration file (an equivalent to IApplication.getArgs() from DoJa), dealing with the backlight, vibration, logging, etc. Many of the methods in this class correspond to methods of Java's System class.

Math

The Math class provides some of the methods in the Java Math class, as well as support for generating random numbers (there is no dedicated Random class).

Higher-level functionality

Apart from the adapter classes listed above, there are also several classes which implement functionality without trying to conform to the interface of the corresponding Java classes (actually for some of them there are no corresponding Java classes at all). This allows us to implement them in a way that they are much more convenient to use in most of the use cases. These are also very useful when the framework is used to develop applications from scratch.

WebRequest

The WebRequest implements fetching resources over HTTP. Both GET and POST requests are supported. The class supports using custom HTTP headers. WebRequest implements blocking functionality so it is a Thread.

WebRequest webRequest((Thread*)this, (Canvas*)this);
SEND_REQUEST(webRequest, "http://some.url");
int resCode = webRequest.getResultCode();
String webResult = webRequest.getResultAsString();

ResourceManager

ResourceManager is used to load images, resources or byte arrays from the BAR file or from files. It also supports loading gzip-compressed resources.

ResourceManager& res = ResourceManager::getInstance();
TRY( Image image1 = res.loadImage(IDI_IMAGE) ); 			//load an image from the BAR
TRY( Image image2 = res.loadImage("image.png") ); 			//load an image from a file
TRY( String text = res.loadString(IDS_TEXT, "alternate.bar") ); 	//load a string from a different BAR file
TRY( Array<char> data = res.loadBlob(someThread, IDI_GZIPPED_DATA));	//load an (optionally) gzipped data from the BAR
...use the loaded objects...
CATCH(
	//handle exceptions
);

SoundManager

The SoundManager implements sound playback. It is very well suited for the Yamaha MA3 and MA5 sound systems used in Japanese BREW handsets and provides transparent solutions for some specific restrictions of these sound systems - for example it is impossible to play an SPF file and a MMF file or more than four SPF files simultaneously; SPF files can only have up to four tracks while the file formats used in J2ME allow more tracks, etc.

Porting sound-related functionality from Java proved to be difficult without such a centralized solution, so we built the SoundManager on top of MediaPlayerBox. This class also brings the interface for audio playback closer to DoJa's AudioPresenter.

SoundManager supports playing different file formats, registering for sound-related events, setting volume, provides transparent suspend/resume functionality and generally makes dealing with sounds easy.

The SoundManager does not currently support jumping at arbitrary positions in the sound or playing streaming audio. This class is still work in progress.

AudioPresenter[] players = new AudioPresenter[2] {AudioPresenter.getAudioPresenter(), AudioPresenter.getAudioPresenter()};
for (int i = 0; i < players.length; i++) {
	players[i].setMediaListener(this);
}
MediaSound[] sounds = new MediaSound[5];
for (int i = 0; i < sounds.length; i++) {
	sounds[i] = MediaManager.getSound("scratchpad://...."); //loading sound resources
}
......
players[0].setSound(sounds[0]);
players[0].play(); //play some sound 

SoundManager players(2);
for (int i = 0; i < 2; i++) {
	players[i].setMediaListener(this);
}
Array<MediaResource> sounds(5);
for (int i = 0; i < sounds.length(); i++) {
	sounds[i] = MediaResource(BAR_FILE, 6001 + i, AEECLSID_MEDIAPHR); //AEECLSID_MEDIAPHR is for SMAF Phrase files
}
players.start(); //the SoundManager runs in a separate Thread, so we need to start it
......
players[0].setMediaResource(sounds[0]);
players[0].play(); //play some sound  

SpritesFont, StringsToSprites utility

Making a game run on many different handsets is difficult. One of the hard things is making strings look well-aligned on all handsets. In order to simplify this, the BREW Framework comes with a Java utility called StringsToSprites, and a class SpritesFont. With the Java utility, the developer can preliminary render all the strings that will be used in the game into pictures and then can use a special subclass of Font - SpritesFont in order to draw strings using these pictures instead of using the ordinary string-drawing routines in BREW. This ensures that the drawn strings will look the same on all handsets. This combo can also work for drawing strings in a more fancy manner, using custom symbol images - for example for game scores, for the titles in the main menu, etc.

The utility is run on the BRX file where all the strings are defined and it builds a number of images, containing all the characters that are used in the strings of the game. It also creates a mapping to describe where each character can be located in these images. The utility automatically updates the BRX file to include the images and the mapping string. Later on, when using the SpritesFont, the application will use the mapping string to find each one of the characters in the string that it has to draw. The whole process is very, very transparent from the developer's standpoint.

The BREW Framework still supports changing the color of strings when strings are drawn using the SpritesFont.

Usage: StringsToSprites -brx <input brx> -res <resources directory> [-out <output brx>]
        [-fontface <"Font Face">] [-bgcolor <RRGGBB>] [-fgcolor <RRGGBB>]
        [-width <charmap image width>] [-height <charmap image height>]

The default values are:
        -out <the input brx file>                                  -  by default the input brx will be overwritten
        -fontface "MS Gothic" -bgcolor 000000 -fgcolor FFFFFF      -  white on black
        -width 120 -height 120                                     -  compatibility with small screens

String title = ResourceManager::getInstance().loadString(IDS_TITLE_TEXT);
graphics.setFont(Font::getSpritesFont());
graphics.drawString(title, graphics.getWidth()/2, graphics.getHeight()/2, Graphics::VCENTER | Graphics::HCENTER);

YesNoDialog, TextBoxDialog

The YesNoDialog class implements a dialog with a customizable title, text and softlabels. TextBoxDialog implements a dialog for text input from the user (this class is work in progress - we will provide a more powerful and customizable control for user input).

// from inside a Thread:
YesNoDialog dialog;
dialog.showDialog(this, "Question", "Really quit?", "No", "Yes");
if (dialog.getResult()) {
	Applet::getInstance().close();
}

PNGPalette

This class can be used to change some of the colors in a PNG image to other colors. This is useful for large applications, when space is restricted and some of the images are the same except for the colors. It can also be used to achieve some cool visual effects.

Array<signed char> imageData = ResourceManager::getInstance().loadBytes(IDI_IMAGE);
PNGPalette pal;
unsigned int oldColor = 0xFF0000; //red
unsigned int newColor = 0x0000FF; //blue
pal.changePalette((unsigned char*)imageData.getPtr(), 0, imageData.length(), oldColor, newColor);
Image image = Image::createImage((char*)imageData.getPtr(), 0, imageData.length());

Other important aspects of the framework. Solutions for BREW-specific problems and restrictions.

Apart from providing the classes listed above, the BREW Framework also provides solutions to some of the most severe BREW-specific problems and restrictions.

Exceptions

The lack of Exception support in the ARM compilers is one of the worst restrictions in BREW programming. The framework provides a set of macros - TRY and CATCH, and an error-setting mechanism to help in this aspect. The methods in the framework that can potentially fail use this mechanism to raise errors in case of failure. Such methods usually have the phrase "Requires TRY" in the documentation. The calling code is supposed to wrap calls to such methods in TRY(), like this:

If the code fails, TRY would notice the raised error and would jump directly to the CATCH() section.

1. TRY should surrounds just a single statement - if we have several statements in a row and each of them could fail, we have to put each of them in a separate TRY. This is because everything TRY surrounds is executed at once, but if the first statement fails we don't want to execute the rest of the statements.

2. In each method that uses TRYs, there should be a single CATCH somewhere below the TRYs. This is because the CATCH actually defines a label and TRY uses goto to jump to this label. This means we cannot have different catch sections in the same method. If we need such fine control, we might use the methods Applet::setError() and Applet::getError() manually.

3. TRY and CATCH cannot jump through the function call stack like Exceptions do. The sample code below demonstrates what should be done in such cases.

void f1() {
	try {
		f2();
	} catch (Exception e) {
		//handle exceptions
	}
}

void f2() throws Exception {
	f3();
}

void f3() throws Exception {
	loadImage1();
	loadImage2(); //this will not be executed if the line above throws an exception
}

void f1() {
	TRY( f2(); );
	CATCH(
		//handle exceptions
	);
}

//Requires TRY
void f2() {
	TRY( f3(); );
	CATCH(); // do nothing here - just declare it so that TRY can jump here. The error will be handled in an upper function.
}

//Requires TRY
void f3() {
	TRY( loadImage1(); );
	TRY( loadImage2(); ); //this will not be executed if the line above fails
	CATCH(); // do nothing here - just declare it so that TRY can jump here. The error will be handled in an upper function.
}

4. In Java you could have different types of Exceptions. With TRY and CATCH you cannot have such fine control.

Sometimes the compiler will complain with the following error: initialization of 'someVar' is skipped by 'goto CATCH_LABEL'. Most probably your code looks like this:

TRY(something); // or TRY_MEM;
int someVar = 5; // or whatever the type of someVar is
...use someVar...
CATCH();

You can fix the error by wrapping the usage of someVar in an inner block:

TRY(something);
//use a block to wrap the usage of someVar:
{ 
	int someVar = 5;
	...use someVar...
}
CATCH();

Memory handling

The Nullable class

Using real objects instead of pointers in the BREW Framework comes at some price - with pointers you could have a NULL value (as you can with references in Java), while real objects cannot be NULL. To avoid this trouble most adapter classes in the framework, such as String, Image, Array, etc. implement the Nullable interface. This means that they have a so called NULL-state, which can be checked using the isNull() method. They also have a constructor, which puts them in the NULL-state initially - usually it can be invoked with code like Array<int> a = NULL_OBJ. For some of the Nullable classes, the default constructor also constructs a NULL-state object. Such classes are String, Array, Image. However, for some classes like Vector, Hashtable and StringBuffer the default constructor makes more sense to create a real object. The NULL_OBJ constant we used several times is a constant from a special type and Nullable classes always provide a constructor for it, which puts the object in the NULL-state.

Since null and NULL in C++ are defined as 0, and some of the classes in the framework have meaningful constructors from integer values, you should be careful with the null-s used in the Java code. Usually you can search for "null" and replace it with "NULL_OBJ". Checks like a == null or a != null can eighter be translated as a == NULL_OBJ (respectively a != NULL_OBJ), or as a.isNull() (respectively !a.isNull()).

Suspending and resuming

The BREW certification procedure mandates that the suspend and resume events are handled in a proper manner by the application. This means that on suspend the application should release some specific limited resources like IMedia and IWeb objects and should cancel all set timers. On resume it should continue from the same state as the one it was in when the suspend event was received.

The BREW Framework classes are all implemented to release limited resources, cancel timers and pause threads on suspend and continue properly on resume. The BREW Framework also takes care to redraw the screen properly when resuming - it keeps a copy of the drawn screen and uses it to redraw the screen on resume. Using this intermediate drawing buffer causes a very small speed decrease - the developer can turn it off by passing false for useIntermediateBuffer to the Canvas constructor. In this case the application should ensure the screen is properly redrawn on resume - the paint() method of the active Canvas will be called on resume and it should repaint the whole screen.

This usually means the developer does not have to do anything for suspend and resume to work properly. Still, in the rare cases when some application class has to perform specific suspend/resume actions, it can register a listener for system events with Applet::registerEventListener().

Step-by-step porting guide. Porting a sample application

In order to demonstrate better the framework and to help developers who are using it become faster acquainted with it we prepared a simple MIDP application and ported it to BREW, describing the porting process step-by-step. The demo application consists of three classes: Demo, DemoCanvas and PaintThread. Demo is a MIDlet, it activates the DemoCanvas. The DemoCanvas loads some resources and starts several PaintThreads. The PaintThreads draw various things on the screen in infinite loops. Though the source is really short, this application demonstrates many aspects of J2ME programming - there is resource loading, working with strings and arrays, multithreading, various drawing operations, processing keys. The keys are: * to clear the screen, 0 to exit, any other key to pause or resume drawing.

You will see that the code of the BREW equivalent is really close to the original code and it performs just as well as the original.

Download