There is no single answer to which JSRs are supported on Symbian smartphones. The list of detected JSRs in Table 1
represents the family of devices to which the three reference devices
belong (respectively, S60 5th Edition, S60 3rd Edition FP1, and UIQ
3.0). As you have seen, the support provided by the Nokia N95, the Nokia
5800 XpressMusic, and the Sony Ericsson W960i exceeds the list of MSA
Subset Component JSRs and is nearly at the level of full MSA Component
JSRs. New devices are coming out all the time and so more JSRs may be
supported.
For example, S60 3rd Edition FP2 and S60 5th Edition include additional APIs and UIQ 3.3 supports JSR-248 MSA Fullset. A Forum Nokia Wiki page lists the supported APIs for both Nokia S40 and S60 devices. However, you can assume that generally the direction of Java ME on Symbian OS is towards MSA Fullset and beyond.
In this section, we cover additional (non-JSR) APIs
that are supported. But first we look at the advantage of having a
common and consistent JSR implementation for a variety of devices and
manufacturers.
1. Consistent Implementation
The major shortcoming of Java ME on feature phones is
having inconsistent implementations. For example, to take a snapshot on
different feature phones, you might need to call the same methods in a
different order. You may also find different defects on different
devices, differences in the interpretation of a JSR's specification, and
so on. Symbian OS provides a single common Java ME implementation which
is the base for a variety of models from many manufacturers.
Although not a technical issue, it is important to
understand the delivery chain in which Symbian OS plays a central role
but is not the only actor. The Symbian ecosystem is not a single
monolithic entity. At the time of writing, Symbian OS, including the
Java ME subsystem, is shipped to phone manufacturers who can extend and
customize the operating system. The Java ME platform is equipped with a
large standard selection of Java ME APIs
when it reaches the phone manufacturer, who can then add additional
JSRs of their own. This customization approach is what ensures one
common platform for a large number of devices from many handset
manufacturers, all of whom can still configure the platforms for their
needs and brand for network operators.
The Java ME developer, at the end of the delivery
chain, sees many devices which have much in common.
Apart from JSR APIs, there are other APIs that are
not standardized by the Java Community Process (JCP) but which can help
you to implement a solid mobile application.
2. Nokia UI API
The Nokia UI API has been available since the days of
MIDP 1.0 and devices such as the Nokia 6600. Back then, MIDP 1.0 was
the standard for ensuring maximum portability and concentrated only on
features that could be implemented by all mass-market devices. Some of
those devices had very limited graphics capabilities and sometimes no
sound capabilities at all. The Nokia UI API was introduced to make such
features available to Java applications on Nokia devices, which already
had sound capabilities and better graphics capabilities.
Although the API is named after Nokia, it is also
available on phones that belong to other manufacturers. Because of its
success among MIDP 1.0 developers, other phone manufacturers (including
Sony Ericsson) made the API available on their platforms.
The Nokia UI API consists of a small number of classes defined in the proprietary com.nokia.mid.ui and com.nokia.mid.sound packages. They add the following features:
control of vibration and the LCD backlight
a basic sound API for playing tones and digitized audio
the ability to draw and fill polygons and triangles
rotation and flipping of images
alpha-channel color support
low-level access to image pixel data.
At the time of writing, the Nokia UI API is still
available on many SDKs and devices from different manufacturers. For
example, it is available on the Nokia S60 5th Edition SDK; on S60 3rd
Edition FP2 SDK and devices such as the Nokia N95; and on the Sony
Ericsson SJP-3 SDK and devices such as the UIQ 3 Sony Ericsson W960i.
However, MIDP 2.0 includes almost all the Nokia UI
API's features and since then the Nokia UI API has been a deprecated API
which remains available mostly to maintain backward compatibility. It
is strongly recommended that developers do not develop using it, but use
standard APIs, such as MIDP 2.0 LCDUI, to guarantee that their MIDlets
work in future devices.
3. Embedded Standard Widget Toolkit
From S60 3rd Edition FP2, Nokia introduced support
for the Embedded Standard Widget Toolkit (eSWT) which is an alternative
UI toolkit to LCDUI. eSWT is a subset of the Standard Widget Toolkit
(SWT) API, which was jointly developed by IBM and Nokia as part of the
Eclipse Foundation eRCP project.
The SWT was developed as an alternative to the AWT and Swing desktop UI
toolkits included in Java SE. For example, the Eclipse IDE uses SWT for
its user interface.
It is very easy for SWT developers who are already
experienced with Java ME development to use eSWT, since eSWT shares the
core components, design, idioms and development principles of SWT. The
core features of eSWT are:
native platform look and feel
high performance and minimal overhead
customizable UI components
low-level graphics support.
eSWT is divided into three components (see Figure 1):
Core eSWT, Expanded eSWT and SWT Mobile Extensions. Core eSWT includes
the basic SWT classes and a set of the most commonly used widgets, such
as buttons and text fields, low-level graphics APIs and layout managers,
and defines the event model. More advanced widgets, such as tables,
trees, dialogs and a powerful browser control are part of the Expanded
eSWT component. SWT Mobile Extensions includes widgets that are specific
to mobile devices, such as commands or full-screen shells. The eSWT
widgets gallery presents the range of eSWT widgets.
The eSWT APIs provide:
visually compelling and rich user interface components
flexible components layout using layout managers
fine-grained support for user interface events.
We show two examples for eSWT: the first is a very
basic example and the second demonstrates one of the more powerful
features of eSWT – embedding a browser in your application.
3.1. Basic Use of eSWT
Figure 2 shows a simple 'Hello World' application written using eSWT. The basic building blocks of every eSWT MIDlet are org.eclipse.swt.widgets.Display, Shell, and other widgets. Every eSWT application requires a single display object and one or more shells. The org.eclipse.swt.widgets.Display singleton can contain one or more shells which can contain other shells and other types of widget.
import org.eclipse.ercp.swt.mobile.*;
import org.eclipse.swt.*;
import org.eclipse.swt.graphics.*;
import org.eclipse.swt.widgets.*;
import org.eclipse.swt.events.*;
public class eSWTExamplet extends MIDlet implements Runnable,
SelectionListener, PaintListener {
private Display display;
private Shell shell;
private Thread eSWTUiThread;
private boolean exit = false;
public void startApp() {
// start a Thread in which eSWT will execute its event loop
if (eSWTUiThread == null) {
eSWTUiThread = new Thread(this);
eSWTUiThread.start();
}
}
...
public void run() {
// init eSWT core objects
display = new Display();
shell = new Shell(display);
shell.open();
// init rendering of the "Hello World"
shell.addPaintListener(this);
shell.redraw();
// allow eSWT to execute the event loop
while (!exit) {
if (!display.readAndDispatch()) {
display.sleep();
}
}
// perform cleanup required for eSWT objects
display.dispose();
notifyDestroyed();
}
...
public void paintControl(PaintEvent e) {
e.gc.setForeground(new Color(display, 255, 0, 0));
e.gc.drawText("Hello eSWT!", 0, 0, SWT.DRAW_TRANSPARENT);
}
}
As you can see in the example code, eSWT MIDlets
implement the MIDlet lifecycle methods just like any other MIDP MIDlets.
When the MIDlet enters the active state for the first time, it creates
the eSWT application UI thread, which constructs a single org.eclipse.swt.widgets.Display
instance that is not disposed of until the MIDlet enters the destroyed
state. Before exiting, the eSWT widgets and objects must generally be
manually deallocated by calling the dispose() method.
3.2. Advanced Use of eSWT
To demonstrate a highly powerful feature of eSWT, we use org.eclipse.swt.browser.Browser embedded into an application (see Figure 3).
In the following example code, the user can set a URL and navigate back and forth between visited web pages. (Using MIDlet.platformRequest() does not allow you to programmatically navigate between different pages; the eSWT Browser API does let you do it.)
import org.eclipse.swt.browser.Browser;
public class BrowserMIDlet extends MIDlet implements SelectionListener,
Runnable {
...
// UI Thread run() method
public void run() {
...
browser = new Browser(shell, SWT.NONE);
browser.setUrl("http://forumnokia.mobi");
shell.open();
while (!exiting) {
if (!display.readAndDispatch()) {
display.sleep();
}
}
browser.dispose();
shell.dispose();
display.dispose();
notifyDestroyed();
}
public void widgetSelected(SelectionEvent evt) {
if (evt.widget.equals(urlCommand)) {
QueryDialog urlDialog =
new QueryDialog(shell, SWT.NONE, QueryDialog.STANDARD);
urlDialog.setPromptText("URL:", "http://");
browser.setUrl(urlDialog.open());
shell.redraw();
}
// handle "Back"
else if (evt.widget.equals(backCommand)) {
if (browser.isBackEnabled()) {
browser.back();
}
}
// handle "Forward"
else if (evt.widget.equals(forwardCommand)) {
if (browser.isForwardEnabled()) {
browser.forward();
}
}
}
...
3.3. When to Use eSWT
There are some considerations to be taken into
account when choosing to use eSWT instead of LCDUI. MIDP LCDUI has not
been updated with any significant improvements since it was designed,
because it must be available on low-end devices. For that reason, LCDUI
does not provide much support for the user experience of high-end
devices, such as Symbian smartphones.
On the other hand, although SWT was designed as a
cross-platform GUI toolkit and the embedded version aims to reach more
mobile platforms, eSWT is not defined by the JCP and remains a
non-standard API that is not supported by every mobile platform.
In summary, eSWT is a powerful option on Symbian
smartphones, which provides a rich and compelling set of UI components
that can be used as an alternative to MIDP LCDUI, provided that the Java
ME implementation supports it.
4. IAPInfo API
The IAPInfo API, which was introduced in S60 3rd Edition FP2, enables Java applications to access information, such as:
Internet Access Points (IAP) information, such as ID, name, bearer and service type
Destination Network information, such as ID, name and associated access points
Preferred access points
Last-used access point.
The following code snippet demonstrates simple usage of the IAP information:
// get the singleton IAPInfo object
IAPInfo iapInfo = IAPInfo.getIAPInfo();
// get the available Destination Networks and the list of IAPs
DestinationNetwork destNetworks[] = iapInfo.getDestinationNetworks();
if(destNetworks.length > 0) {
AccessPoint accessPoints[] = destNetworks [0].getAccessPoints();
}
// get the last used IAP
AccessPoint lastUsedIAP = iapInfo.getLastUsedAccessPoint();
The Generic Connection Framework (GCF) of Java ME
does not have a notion of choosing between Internet Access Points and
the default behavior is to use the system default IAP. The IAP-Control
feature of the IAPInfo API allows code to explicitly specify the IAP
that should be used when creating a new GCF network. This is done by
extending the GCF URI scheme definition with two optional parameters: nokia_apnid and nokia_netid. For example, this short code snippet opens a new connection, using the IAP whose system ID is 2:
Connector.open("http://www.nokia.com;nokia_apnid=2")
The parameters are removed from the URL before
opening the connection. They are used internally without being sent to a
web server.
AccessPoint.getURL(String aURL) is a
convenience utility method which returns a new URL string with the
optional IAP ID parameter added. For example, the following snippet of
code opens the new connection with the IAP encapsulated by accessPoint:
AccessPoint accessPoint;
...
Connection.open(accessPoint.getURL("http://www.nokia.com"));
5. SNAP Mobile
The Scalable Network Application Package (SNAP) is
Nokia's end-to-end solution for developing connected Java games and
creating mobile games communities. SNAP Mobile
includes a lightweight, client-side Java library (the SNAP Mobile
Client API) that communicates over HTTP or TCP with a remote backend
system called the 'SNAP gateway'.
The SNAP Mobile Client API enables creation of
connected games with features such as account creation and login,
presence, instant messaging, score tables and rankings, and multiplayer
game playing.
The SNAP gateway includes a Session Manager and a
Virtual Client system that handle requests from SNAP Mobile clients and
responses from SNAP community services, such as web services, the
Instant Messaging and Presence Service (IMPS), and SNAP Game services.
Once your game successfully completes the SNAP Mobile
Compliance Test, you can take it to market via a number of Nokia and
third-party channels.
6. Retrieving Telephony Information
From S60 3rd edition FP2 onwards, there are
additional system properties that provide access to telephony
information. The information provided is minimal but it is meant to
serve telephony services to applications that are not themselves
telephony-oriented.
For example, consider an application that requires
locking onto a specific device. Developers have to make their
applications aware of the unique IMEI of the phone and provide a
mechanism to lock their applications to it. The scenario in such a case
could be:
The user sends the phone IMEI when they purchase the application.
The IMEI is used to bind the application to the device.
The application verifies the phone IMEI at first launch.
There is no Java API that provides access to
telephony information. The information is available only via the
following system properties:
com.nokia.mid.imei: International Mobile Equipment Identity (IMEI) number
com.nokia.mid.imsi: International Mobile Subscriber Identity (IMSI) number
com.nokia.mid.networkid: network identification parameters
com.nokia.mid.networksignal: current (GSM/CDMA) network signal strength
com.nokia.mid.networkavailability: network availability
com.nokia.mid.batterylevel: percentage of battery level
com.nokia.mid.countrycode: current network country code.
7. Summary
Symbian OS provides a wide, common Java ME platform
for a plethora of devices by various manufacturers, which minimizes JSR
support differences between different families of devices. The rich
selection of JSRs allows you to create rich applications using standard
Java APIs only.
Nevertheless, additional APIs
are added to the Java stack by vendors in order to enrich their
platform. You may see these APIs as additional opportunities or you may
choose to stay on the common and generic ground of using only
JCP-standardized JSRs. In any case, Java ME on Symbian OS gives you the
power of choice.
