Tuesday, February 3, 2009

Developing mobile applications using Gear episode 5: Display a splash screen

During the first phase of a MIDlet's life, it's common to find a lot of setup code used to initialize resources, data structures, user interfaces and anything else will be required. In this case, it's a best practice to display a splash screen to inform the user that the application is not frozen but is starting up. With the release of version 1.2.0 of Gear Java Mobile Framework, we've included a consistent yet customizable implementation for this feature.

1 How to achieve it ?
To properly setup Gear SplashScreen, all you have to do is create some keys inside the JAD file:
  • "SplashScreenImage:" -> contains a string with the path to the desired background image
  • "SplashScreenText:" -> contains a string with the desired text
If you are developing your application inside Eclipse with MTJ plugin (former EclipseME), you can easily achieve this by opening the Application Descriptor tab and "Add" the two key-value entries.


If your development environment is a different one, you have to manually insert those keys inside your application's JAD file.

As long as there is at least one of the two keys inside your JAD file, Gear will display the SplashScreen, so if you don't want it, simply don't specify anything.

2 Writing initialization code
Now that the SplashScreen is enabled, all you have to do is to override a single method inside your MIDlet
protected void onMidletInitializationComplete()
and fill it with your custom initializzation logic. We encourage users to follow this practice to put setup code inside this function rather than into the GearMIDlet constructor so they can take advantage from SplashScreen avoiding user interface freezes.
Here is an example of a possible implementation:
protected void onMidletInitializationComplete() {
// Call some custom initializzation methods
initDatabase();
doSomeHeavyDutyWork();
initUserInterface();
// ... and finally show the user the UI
EventManager.getInstance().enqueueEvent(new DisplayWidget(this, LoginForm.class));
}

3 The result
Gear's SplashScreen can display an image background, text and comes with an animated throbber centered vertically and anchored to the bottom of the screen. This is a possible result obtained with it:


Unfortunately this screen-shot is just a static image and you can't actually see the spinning animation of the throbber.

Monday, February 2, 2009

Developing mobile applications using Gear episode 4: On-device debug

Last version of Gear framework (1.2) introduced a new message logging system.
By using Gear logger it's now possible to trace various types of application messages and print out the resulting log on different output types, including device screen.

1. New library debug release
Introducing a logging system in the framework brought a big advantage but leaded also to a performance issue: most of the times the whole logger is useless in the final release of an application and the operations required by the logger to do its work may "steal" precious resources to the rest of the application.
So, starting from version 1.2 we dediced to make two separate releases of the library's JAR: one including the whole logging sub-system and one including only the method stubs.
The two packages are fully compatible, so you can switch anytime between them.

2. Logger structure and usage
The base class of the logging sub-system is Logger. Through this class it is possible to select what kind of messages have to be printed
// Tells the Logger to print gear system level messages
Logger.logSystemMessages(true);
and select the desired output destination
// Tells the Logger to print his messages on to the Standart Output
Logger.out = new StandardOutput();
By default the Logger class is created with NullLogger set as output destination (it doesn't print any message) and logs just user messages (printed by the programmer inside code) and exceptions (any exception printed within code using Logger.out.println(Exception)).
Gear provides three implementation for LogOutput:
  • NullLogger : every method is implemented with an empty body and thus no message will be traced.
  • StandardOutput : prints messages on the Standard Output, usually the development console.
  • GWConsole : displays a graphic console directly on device's screen and prints messages on it.
For example, to print a log message on device's screen, the following code should be used:
Logger.out = new GWConsole();
Logger.logUserMessages(true);
Logger.out.println("Log message");
Note that the second line is not compulsory since user messages logging is enabled by default.

3. Make your own LogOutput
If you have special logging requirements, such as redirecting logs to a remote server, you can write your own custom output target and then use it with Gear's Logger. The class must implement LogOutput interface and should extend the InternalLogger abstract class.
The class structure should look like this one:
public class RemoteLogger implements LogOutput
extends InternalLogger {

// Instance fields ...
// ...

public void println(int logLine) {
if (Logger.isUserMessagsLogged()){
// Network communication ...
}
}

public void println(double logLine) {
if (Logger.isUserMessagsLogged()){
// Network communication ...
}
}

public void println(String logLine) {
if (Logger.isUserMessagsLogged()){
// Network communication ...
}
}

public void println(Exception logLine, Object sender) {
if (Logger.isExceptionsLogged()){
// Network communication ...
}
}

public void println(Exception logLine,
Object sender, String methodName) {
if (Logger.isExceptionsLogged()){
}
}

protected void printSystemMessage(String message) {
if (Logger.isSystemMessagsLogged()){
// Network communication ...
}
}

}

4. Conclusions
Gear's logging system allows keeping track of application activities for debug, statistical or any other purpose, it provides a simple system to filter messages and handle different output targets. In addition to this, the overhead introduced by the Logger system can be stripped without changing any line of code, just by switching from Gear's debug JAR to the release one.