Introduction to J2ME

Shahryar Khan
 Agenda
• J2ME Architecture
• Configurations and Profiles
• HelloWorld Application
• User Interface and Event Handling
• UI Examples
• MMAPI Architecture
• MMAPI Examples
 History
• Sun's exploration of java on mobile
devices was centered around the idea of
deploying a subset of JDK1.1.8 on mobile
devices that have a more in depth display
as opposed to just a character display.
– Sun introduced a PersonalJava spec based
on the above in 1998
– It was nicknamed pJava
 Introduction
• Java2 is divided into three platforms
– Targeted for different devices or systems
• J2EE (Java2 Enterprise Edition)
– Business applications.
• J2SE (Java2 Standard Edition)
– General applications
• J2ME (Java2 Micro Edition)
– Small devices such as mobile phone, PDA, car
navigation.
 Intro to J2ME
• J2ME – Java 2 Micro Edition
– Introduced by sun in 1999 for mobile devices
– Scaled down version of J2SE
• Smaller footprint
• No heavyweight classes (swing etc)
– Highly optimized runtime environment
 About J2ME
– Normally used for less memory
and low processing power
devices
– A collection of packages and
classes for application
development on mobile devices
 J2ME Overview
• J2ME architecture is divided in to four different
level
– KVM (Kilobyte Virtual Machine)/CVM
– Configurations
– Profiles
– Optional packages
• KVM (Kilobyte Virtual Machine)
– As the name implies, it is used for small program
– A subset of JVM
– A pool for running java code on the device
 Configurations
• Configurations
• devices that have similar memory constraints,
similar user interface requirements, similar network
capabilities, etc.
– It's the minimum platform (VM, core java classes) that will
support a relatively broad range of similar devices
• e.g. low and medium end PDAs and cellphones could be placed
in the same configuration because they may have similar
requirements and needs as noted above
– There are two current configurations:
• The CDC (Connected Device Configuration),
– for capable devices such as high end PDAs;
• CLDC (Connected Limited Device Configuration),
– for low end PDAs and such limited devices as cell phones, pagers,
and smart cards.
 Profiles
• Profiles sit on top of a configuration and will not
work without the underlying configuration.
• Profiles target devices in a specific vertical
market
– e.g. MIDP profile, which is part of the CLDC
configuration targets low end cell phones.
• There is a PDA profile in the works which will also be in the
CLDC.
– Profiles contain the java classes that focus on specific
implementations such as user interface components
and record management
• i.e. where and how to store persistent data.
 Profiles
• Configurations provide no classes for
– managing the application life-cycle,
– for driving the user interface,
– for maintaining and updating persistent data locally in the device,
– or for accessing securely information that is stored on a network server.
• That type of functionality is provided by the profiles, or by optional
packages.
• A profile adds domain-specific classes to the core set of classes
provided by the configuration
– classes that are geared towards specific uses of devices and provide
functionality missing from the underlying configuration.
• There are two standard CLDC-based profiles:
– the Mobile Information Device Profile (MIDP, versions 1.0 and 2.0)
– And the Information Module Profile (IMP).
• Three profiles are based on CDC:
– the Foundation Profile (FP),
– the Personal Basis Profile (PBP),
– And the Personal Profile (PP).
Configurations & Profiles
 J2ME Overview
• The CLDC and the CDC each
require their own virtual
machine because of their
different memory and display
capabilities.
• The CLDC virtual machine is
far smaller than that required
by the CDC and supports less
features.
• The virtual machine for the
CLDC is called the Kilo Virtual
Machine (KVM)
• The virtual machine for the
CDC is called the CVM.
 CDC
• Targeted for devices that have
– 2 MB or more total available memory
– Memory dedicated to J2ME environment
– More than 2MB ROM/Flash
– More than 512 KB RAM
– Network connectivity
• Full Java 2 Virtual Machine specification
• CDC uses
– Wireless communicators
– High-end PDAs
– TV set-top boxes
– Gateways
– Automotive entertainment and navigation systems
– Telecomm/Networking Equipment
– Industrial Controllers
 CLDC
• Targeted at devices
with:
– 160KB to 512KB
total memory
available for Java
technology
– Limited power
(battery),
•Core java.* libraries
connectivity (often
•Additional I/O and
intermittent), UI
•networking libs
(small screen)
•Security features
•Internationalization
 MIDP
• Targets mobile two-
way devices
implementing J2ME
CLDC
• Profile addresses
– Display toolkit, User
input methods •Application model
•Persistent storage (RMS APIs)
– Persistent data •Networking (HTTP, etc.)
storage •User interface (High and low le
– HTTP 1.1-based
networking using
CLDC Generic
Connection framework
IMP - Information Module Profile
– Profile targeting embedded networked
devices that wish to support a Java runtime
environment, but that do not have graphical
display capabilities
– The Information Module Profile is a strict
subset of MIDP 1.0,
– where the APIs relating to GUI functionality
(the LCDUI) are simply removed.
 J2ME Optional Packages
• RMI
– The RMI Optional Package provides interoperable J2SE RMI support on top of
the CDC and Foundation Profile.
• PDA
– The PDA Optional Package is on top of the CLDC and provides optional APIs
common to PDAs and handsets.
– For example,
• the PIM functionality
• FileConnection API is added to allow GCF to access removable media storage.
• Wireless Messaging API (WMA)
– A set of classes for sending and receiving Short Message Service (SMS)
message
• Mobile Media API (MMAPI)
– defines abstractions for the capture and playback of multimedia content.
– If a device supports the playback of specific audio or video formats, or the
recording of audio or video content (such as through an integrated camera),
those capabilities can be exposed generically through the MMAPI
• JDBC for CDC/FP
– A strict subset of JDBC 3.0 that excludes some of JDBC's advanced and server-
oriented features, such as pooled connections and array types.
 CLDC + MIDP
• The most popular profile and configuration that Sun provides are the
Mobile Information Device Profile (MIDP) and Connected Limited
Device Configuration (CLDC), respectively.
• CLDC is for devices with limited configurations
– Devices that have only 128 to 512KB of memory available for Java
applications.
– Consequently, the JVM that it provides is very limited and supports only
a small number of traditional Java classes.
• The MID profile provides the basic API that is used for creating
application for these devices.
– For example, it provides the [Link] package that allows
us to create the GUI elements that can be shown on a (limited) device
running the MID profile on top of a CLDC configuration.
– Note that MIDP cannot be used with CDC devices.
• The latest versions of MIDP and CLDC are 2.0 and 1.1,
respectively.
– Not many devices currently support these versions, but the list is
growing rapidly.
– Sun maintains a list of devices according to version.
 Steps in Designing a MIDlet
• There are seven steps in the creation of a MIDlet.
• Designing
• Coding
• Compiling
• Pre-verification
• Packaging
• Testing
• Deployment
– Some of these steps are not strictly MIDlet-centric (for example, every application needs to
be designed, coded, and compiled), but we will cover them here because there are MIDlet-
centric differences.
– Using a Toolkit abstracts a lot of these steps so that it is easier for you in the overall scheme
of things.
• This is fine once you know the process, but when you are only starting out, you really should be coding
by hand, rather than using an abstraction.
• We will create a MIDlet that, when executed, will print the current date and time on a
mobile device for a short time.
• The lifecycle of MIDlets will be explained later.
 1-Design
• MIDlets are different from other applications that you
may have created, simply because MIDlets run in an
environment that is very different.
• There are several issues, not just those that are most
visible (for example, the interactivity of your MIDlet with
the user), but others that impact its usability.
– For the example application, our Date-Time MIDlet does not
need user interactivity.
– It needs to display the current date and time for a few seconds
when the user executes the MIDlet.
– For simple cases like this, it is perhaps sufficient to mimic the
design of the MIDlet by drawing it on a piece of paper.
– For more complex designs with multiple screens, it is best to
design the screens professionally before starting the actual
coding process.
 2-Code
• Each MIDlet must extend the abstract MIDlet import [Link];
class found in the [Link]
package import [Link];
– Much like creating an applet by extending the import [Link];
[Link] class.
• At the minimum, your MIDlet must override import [Link];
three methods of this abstract class public class DateTimeApp extends MIDlet {
– startApp(),
– pauseApp(), and Alert timeAlert;
– destroyApp(boolean unconditional)
• In this example, DateTimeApp's constructor public DateTimeApp() {
creates the element that is necessary to
display the time on a device's screen timeAlert = new Alert("Alert!");
• The startApp method does the actual task of [Link](new Date().toString());
displaying this element. }
– Don't worry if you don't understand how the public void startApp()
Alert element works, or when the constructor or { [Link](this).setCurrent(time
the other methods are called. Alert);
– They will be covered in the next part, when we
look at the GUI elements of MIDP 2.0, and the }
MIDlet Lifecycle.
• Copy this code into a file called public void pauseApp() { }
[Link] and save it in a folder that
mimics its package structure.
public void destroyApp(boolean
unconditional) { }
}
 3-Compile
• With this simple code in place, you now need to know how to
compile it so that it is ready for mobile devices.
– Compiling MIDlets is not very much different from compiling normal
Java applications.
• You still use javac as the compiler, except you need to change the boot
CLASSPATH while compiling MIDlets.
• This has the effect of changing the base Java classes that the Java compiler
uses to compile your MIDlet against,
– Ensuring that compilation is targeted towards the narrow set of Java's APIs for
the J2ME platform.
– So instead of compiling against the [Link] in "normal" Java, you actually
want compilation done for J2ME's [Link].
– This is done by pointing to the CLDC and MIDP classes for javac's
-bootclasspath option while compiling.
– C:\someDirectory> javac -bootclasspath
CLDC_DIR\lib\[Link];CLDC_DIR\lib\[Link] [Link]
– Notice that the compilation is done against the CLDC API's 1.1 and
MIDP API's 2.0 versions, respectively, by including these libraries in the
bootclasspath option.
– Compilation against other versions can be done if required, by simply
pointing to their respective libraries.
 4-Preverify
• Before you can deploy your MIDlet class, it needs to be preverified.
– Verification of byte code is a step performed by the JVM before it runs any class file to
ensure that the class file is structurally and conceptually correct as per the JVM
specification.
• If the class file fails this check, it is rejected and the JVM shuts down, indicating either security or
integrity violation of the class file.
– This verification is done by all JVMs, even the tiny JVM contained in a CLDC configuration
for a J2ME device.
• Although this is not a problem for "normal" applications, verification in J2ME devices is a resource and
memory constraint that they simply cannot handle (or should not handle).
• Therefore, the need for preverification.
• Preverification is one part of a special two-step verification process, especially
designed for constrained devices, such as the ones running CLDC-based JVMs.
– The idea is to let a developer preverify his classes, which limits the amount of work needed
to be performed when the classes are verified in the device.
– This preverification process adds special information to the classes that identifies them as
preverified and makes the process on the device much more efficient.
• Sun’s Wireless Toolkit comes with a preverification tool in the bin folder of its
installation (e.g. C:\WTK22\bin).
– The following command, when executed from will preverify the [Link] created
in the previous step.
• C:\dir_with_class_file>TOOLKIT_DIR\bin\[Link] -classpath
CLDC_DIR\lib\[Link];CLDC_DIR\lib\[Link] DateTimeApp
– By default, the preverifier will create the preverified version of your [Link] file in
a folder called output in the current directory.
– You can point the output to another folder, using the -d option for the preverify tool.
 5-Package
• Packaging is done in a sequence of steps and you have to follow the order
of steps
– The first step is to create a Manifest file.
– This Manifest file describes the contents of the Java Archive (JAR) file that we
will be creating in the next step.
– There are several attributes that can go in this file, but for our Date-Time MIDlet,
lets stick to only the ones that are required.
MIDlet-Name: DateTimeApp
MIDlet-Version: 1.0.0
MIDlet-Vendor: BIT4
– Save this file as [Link] in the output folder that contains your preverified
class.
• (Note the newline after the last attribute, MIDlet-Vendor. It must be present, otherwise
this attribute will not be recognized.)
• Next, create the JAR file that packages up the preverified
[Link] file and the Manifest file.
– To create this JAR file, navigate to the output directory and issue the following
command:
• jar cvfm [Link] [Link] [Link]
• This will create the [Link] file in the current folder.
 Package…
• The second-to-last step is to create a file that has an extension of .jad.
– A Java Application Descriptor (JAD) file points to the location of the MIDlet it describes so
that a J2ME device can install it.
– Again, this file can contain several attributes for a single MIDlet (or for several MIDlets), but
for your Date-Time MIDlet, we will stick with the ones that are required.
– MIDlet-1: DateTimeApp, , DateTimeApp
MIDlet-Name: DateTimeApp
MIDlet-Version: 1.0.0
MIDlet-Vendor: BIT4
MIDlet-Jar-URL: [Link]
MIDlet-Jar-Size:
MicroEdition-Profile: MIDP-2.0
MicroEdition-Configuration: CLDC-1.1

– Save this file as [Link] in the same folder as the JAR file.
• Note that the value of the MIDlet-Jar-Size attribute is missing.
– This missing value brings you to the last step of the packaging step, where you determine the size of the
[Link] file, and put that value in this JAD file, in actual bytes.
– It is very important to get this exactly right, as the installation of this MIDlet will fail if this value is different from the
actual size.
• MIDlet-Jar-Size: 1469
• This completes the packaging part.
– (there are other steps in the packaging (for example, signing and obfuscation), but to keep
things simple, I will leave those steps for later discussion.
 6-Testing
• Before deploying your MIDlets, they must be tested by
using a base common emulator device that mimics the
functionality of an actual device on your computer.
– This emulator is part of the Wireless Toolkit and provides
functionality that is sure to be present in the majority of
devices for which the MIDlet is targeted.
– This emulator is present in the bin folder of the Toolkit.
• From the output directory created in the pre-verify step
earlier, and where we now have a packaged MIDlet in
the form of JAR and JAD files, issue the following
command to run the emulator with this JAD file as an
option.
• OUTPUT_DIR>TOOLKIT_DIR\bin\[Link]
-Xdescriptor [Link]
– You should see the emulator pop up on your screen with
the DateTimeApp MIDlet selected.
– If it doesn't, the most likely error at this point would be
incorrect JAR size information.
• Make sure you have the exact size listed in the JAD file.
– At the lower right-hand corner of the emulated device's
screen, you can see the "Launch" menu item listed.
• The emulator has installed the MIDlet and is ready to launch it.
• Click on the phone button just underneath that menu item and
the MIDlet should display the current date time for a few
seconds and then disappear.
• Note that the MIDlet is still running even after the date and
time disappear, because in code, you did not destroy it.
 7-Deploy
• Now you have reached the stage where you can deploy the MIDlet directly
on your mobile device.
– There are two ways to do this.
• The first is via a network connection between your computer and your handset.
– This can either be via a USB cable or a Bluetooth wireless connection, depending on your
device.
– Most Java-enabled devices will allow you to install J2ME applications via this connection.
• Second, and the one that is more interesting, because it opens up your MIDlet to the
outside world, is via the Internet.
– This requires that your device should be able to connect to the Internet using its internal
browser.
– Before you proceed further, recall that when you created the JAD file, you
entered two attributes in it that specified the version of CLDC (1.1) and MIDP
(2.0) for which the MIDlet was created.
• Since the DateTimeApp MIDlet does not use any of the features of these versions, it
should theoretically run on devices that support the lower versions of these attributes,
as well.
• Therefore, the DateTimeApp MIDlet should run on CLDC 1.0 and MIDP 1.0, but
because the JAD file restricts these versions to the newer ones, devices will fail to
install this MIDlet if they do not support these new versions.
– If this is the case with your device, do not worry!
– Because we are not using any MIDP-2.0- or CLDC-1.1-specific features, you can simply
change these version numbers in the JAD file, and this will be sufficient to install this device on
all Java-enabled devices.
– If this is the case with your device, or the device that you are going to test this MIDlet on,
simply change these values in the JAD file and you are good to go.
 Deploy…
• To be able to deploy your MIDlet via the Internet, you need to have access
to a web server with a real-world IP address or domain name.
– You also need to have administrative privileges to be able to modify the
configuration files of your web server to add some MIME types for the JAD and
JAR extensions.
– If you are using Jakarta/Tomcat as your web server, you don't need to do this, as
it already has these MIME types.
• For the Apache web server, modify the [Link] file and add the following extension
types.
– text/[Link]-descriptor jad
– application/java-archive jar
– By adding these MIME types, you are informing the browser, or any client
accessing these files from the server, how to handle these files when they are
downloaded into the device.
• Next, create an HTML file that will become the point of reference.
• Strictly, this is not necessary, because a device that can access an HTML page can
also access a JAD file.
• But an HTML page provides a point of reference, and therefore, let's create one for
your Date-Time MIDlet.
• The HTML doesn't need to be anything fancy.
– Don't forget that users will be accessing this page via a mobile device, so it is prudent to keep
the size of this page to the minimum.
<HTML> Click <a href="[Link]">here</a> to download DateTimeApp MIDlet!
</HTML>
 Deploy
• The page provides a link to the JAD file
– The JAD file provides a link to the associated JAR file via the MIDlet-Jar-URL:
[Link] attribute.
– However, since this is now going to be accessed via a web server over the
Internet, it is advisable to make this link absolute instead of relative.
• The behavior of relative URLs is inconsistent as far as MIDlet access is concerned
• MIDlet-Jar-URL: [Link]
– Finally, upload the modified JAD file, the newly created HTML file, and the
original JAR file to your web server to a directory location where you will be able
to navigate to the HTML page via your mobile device browser.
• Now, anyone with a mobile device that can browse the Internet should be able to point
to your [Link] file and download, install, and run the DateTimeApp MIDlet.
• That's it!
– You have completed all the steps required to manually create and deploy a
MIDlet.
– This process has helped you to understand what goes on behind the scenes and
given you confidence in all the steps of MIDlet creation.
– Because a lot of these steps are repetitive, it makes sense to use an automated
tool.
• This is where the Wireless Toolkit comes in,
• Let's recreate the same MIDlet using this Toolkit so that you can get familiar with its
interface.
 Using the Toolkit
• Run the toolkit
– Create a new project
– The toolkit will create a folder with your project
name under the apps directory
• Create a folder named src within that directory and
copy all source files there
• Click Run.
 MIDlet Lifecycle
• Mobile devices, whether AMS
emulators or real, interact with a new()
MIDlet using their own software,
which is called Application startApp()
MIDlet
Management Software (AMS). MIDlet
MIDlet MIDlet
Paused Active
Active
– The AMS is responsible for Paused pauseApp()
initializing, starting, pausing,
resuming, and destroying a
MIDlet.
destroyApp() destroyApp()
• Besides these services, AMS
may be responsible for installing
and removing a MIDlet, as well.
– To facilitate this management, a MIDlet
MIDlet
Destroyed
MIDlet can be in one of three Destroyed
states which is controlled via the
MIDlet class methods, that every
MIDlet extends and overrides.
– These states are
• Active
• Paused, and
• Destroyed
Simple DateTimeApp
Application
 UI Architecture
• MIDP (2.0) provides UI classes in two packages:
– [Link]
– [Link]
• lcdui stands for liquid crystal display user interface (LCD UI).
• The game package contains classes for development of a wireless game UI
• The UI classes of MIDP 2.0's [Link] package can
be divided into two logical groups:
– the high- and low-level groups.
– The classes of the high-level group are perfect for development of MIDlets that
target the maximum number of devices
• The high-level classes are heavily abstracted to provide minimal control over their look
and feel,
– which is left for device on which they are deployed to manage, according to its capabilities.
– The classes of the low-level group are perfect for MIDlets where precise control
over the location and display of the UI elements is important and required.
• With more control comes less portability.
• If your MIDlet is developed using these classes, it may not be deployable on certain
devices, because they require precise control over the way they look and feel.
• There are only two classes in this group
High Level and Low Level UI
Classes

High Level UI Classes

Low Level UI Classes

 UI Architecture
• For you to be able to show a UI element
on a device screen, whether high- or low-
level, it must implement the Displayable
interface.
– This implies that both the Screen and Canvas
classes and their subclasses implement this
interface
 UI Display
• A Displayable class is a UI element that can be
shown on the device's screen
• A MIDlet shows a Displayable UI element on a
Display using the setCurrent(Displayable
element) method of the Display class.
– As the method name suggests, the Display can have only one
Displayable element at one time, which becomes the current
element on display.
– The current element that is being displayed can be accessed
using the method getCurrent(), which returns an
instance of a Displayable element.
– The static method getDisplay(MIDlet midlet)
returns the current display instance associated with your MIDlet
method.
 Revisiting DateTimeApp
// …

Alert timeAlert;

public DateTimeApp()
{
timeAlert = new Alert("Alert!");
[Link](new Date().toString());
}

public void startApp()

{
[Link](this).setCurrent(timeAlert);
}
 Displayable Elements
• There are 4 Displayable elements
• Alert
– Alerts are best used in informational or error messages that stay on the
screen for a short period of time and then disappear.
• The title must be set while creating the alert and it cannot be changed
afterwards: Alert("Confirm?");.
• To set the message the alert displays use, setString("Message to
display") or pass the message as part of the constructor, Alert( "Confirm",
"Are you sure?", null, null); .
• Use setTimeout(int time) to set the time (in milliseconds) for which
the alert is displayed on the screen.
• If you pass [Link] as the value of time, you will show the alert
forever and make the alert a modal dialog.
• There are five types of alerts defined by the class AlertType: ALARM,
CONFIRMATION, ERROR, INFO, and WARNING.
– These have different looks and feels and can have a sound played along with the
alert.
• Associate an image with the alert using the method setImage(Image
img);.
• Set an indicator with the alert using setIndicator (Gauge gauge);
method.
 Displayable Elements

• List
– A list contains one or more choices
(elements), which must have a text part,
an optional image part, and an optional
font for the text part.
– The List element implements the Choice
interface, which defines the basic
operations of this element.
– The list must itself have a title, and must
define a policy for the selection of its
elements.
• This policy dictates whether only one
element can be selected
([Link]), multiple elements
can be selected ([Link]), or
the currently highlighted element is
selected ([Link])
– You can create a list in one of two ways.
• Create an list that contains no elements,
and then append or insert individual
elements.
• Create the elements beforehand and
then create a list with these elements.
• [Link]
 Displayable Elements
• TextBox
– Text is entered by the user using a textbox.
– Like the other UI elements, a textbox has simple features that can be set
based on your requirements.
– You can restrict the maximum number of characters that a user is allowed
to enter into a textbox,
• You need to be aware of the fact that the implementation of this value depends
upon the device that you are running it on.
• For example, suppose that you request that a textbox is allowed a maximum of
50 characters, by using setMaxSize(50), but the device can only allocate a
maximum of 32 characters.
– Then, the user of your MIDlet will only be able to enter 32 characters.
– You can also constrain the text that is accepted by the textbox, as well as
modify its display using bitwise flags defined in the TextField class.
• For example, to only accept email addresses in a textbox, you will need to set
the [Link] flag using the method setConstraints().
• To make this field uneditable, you will need to combine it with the
[Link] flag.
– This is done by doing a bitwise OR operation between these two flags:
setConstraints([Link] |
[Link]);.
 Displayable Elements
– There are six constraint settings for restricting content:
• ANY,
• EMAILADDR,
• NUMERIC,
• PHONENUMBER,
• URL, and
• DECIMAL.
– ANY allows all kinds of text to be entered, while the rest constrain according to
their names.
– Similarly, there are six constraint settings that affect the display.
– These are:
• PASSWORD,
• UNEDITABLE,
• SENSITIVE, NON_PREDICTIVE,
• INITIAL_CAPS_WORD, and
• INITIAL_CAPS_SENTENCE.
– Not all of these settings may be functional in all devices.
• To set the contents of a textbox, you can use a couple of methods.
– Use setString(String text) to set the contents with a String value.
– Use insert(String text, int position) to position text where you want
it to go.
• [Link]
 Displayable Elements
• Form
• An item is added to a form using the append(Item item) method,
which simply tacks the added item to the bottom of the form and
assigns it an index that represents its position in the form.
– The first added item is at index 0, the second at index 1, and so on.
– You can also use the insert(int index, Item newItem) method
to insert an item at a particular position or use set(int index, Item
newItem) to replace an item at a particular position specified by the
index.
• There are eight Item types that can be added to a form.
• StringItem:
– A label that cannot be modified by the user.
• DateField:
– Allows the user to enter date/time in one of three formats: DATE, TIME,
or DATE_TIME.
• TextField:
– Same as a TextBox.
 Displayable Elements
• ChoiceGroup:
– Same as a List.
• Spacer:
– Used for positioning UI elements by putting some space between them.
– This element is an invisible UI element and can be set to a particular size.
• Gauge:
– A gauge is used to simulate a progress bar.
– However, this progress bar look can also be used in an interactive mode by the
user.
• For example, if you wanted to show the user a volume control, a gauge would be used
to show an interactive knob.
• ImageItem:
– An item that holds an image!
• CustomItem:
– CustomItem is an abstract class that allows the creation of subclasses that
have their own appearances, their own interactivity, and their own notification
mechanisms.
– If you require a UI element that is different from the supplied elements, you can
subclass CustomItem to create it for addition to a form.
 Handling User Commands
• None of the UI elements so far have allowed any interaction from the user!
• A MIDlet interacts with a user through commands.
– A command is the equivalent of a button or a menu item in a normal application,
and can only be associated with a displayable UI element.

• The Command class holds the information about a command.

– You create a command by providing these values in its constructor:
– Command exitCommand = new Command("EXIT", [Link], 1);
– Note that commands are immutable once created.
• By specifying the type of a command, you can let the device running the
MIDlet map any predefined keys on the device to the command itself.
– For example, a command with the type OK will be mapped to the device's OK
key.
– The rest of the types are: BACK, CANCEL, EXIT, HELP, ITEM, SCREEN, and
STOP.
– The SCREEN type relates to an application-defined command for the current
screen.
– Both SCREEN and ITEM will probably never have any device-mapped keys.
 Handling User Commands
• By specifying a priority, you tell the AMS running
the MIDlet where and how to show the command.
• A lower value for the priority is of higher
importance, and therefore indicates a command
that the user should be able to invoke directly.
– For example, you would probably always have an
exit command visible to the user and give it a priority
of 1.
– Since the screen space is limited, the device then
bundles less-important commands into a menu.
– The actual implementation varies from device to
device, but the most likely scenario involves one
priority-1 command displayed along with an option to
see the other commands via a menu.
– The responsibility for acting on commands is
performed by a class implementing the
CommandListener interface, which has a single
method: commandAction(Command com,
Displayable dis).
– However, before command information can travel to
a listener, the listener is registered with the method
setCommandListener(CommandListener
listener) from the Displayable class.
– [Link]
Handling User Commands Example
 Multimedia in MIDP 2.0
• MIDP 2.0 , along with the optional Mobile Media API 1.1
(MMAPI), offers a range of multimedia capabilities for
mobile devices,
– including playback and recording of audio and video data
from a variety of sources.
– Of course, not all mobile devices support all the options,
• MMAPI is designed in such a way that it takes full advantage of the
capabilities that are available, while ignoring those that it cannot
support.
• MIDP 2.0 comes with a subset of the MMAPI which ensures that if a
device does not support MMAPI, you can still use a scaled down
version.
– This scaled down version only supports audio (including tones) and
excludes anything to do with video or images.
Multimedia and MIDP 2.0
 MMAPI
• Mobile Multimedia API
– MMAPI defines the superset of the multimedia capabilities that are
present in MIDP 2.0.
– The current version is distributed as an optional jar file in the J2ME
wireless toolkit 2.2 and 2.3.
» Although the release notes (2.2) for the toolkit state that MMAPI 1.1 is
bundled, the actual version is 1.0.
• The MMAPI is built on a high-level abstraction of all the multimedia
devices that are possible in a resource-limited device.
– This abstraction is manifest in three classes that form the bulk of
operations that you do with this API.
– These classes are
• the Player interface
• Control interface,
• and the Manager class.
– Another class, the DataSource abstract class, is used to locate
resources
• Unless you define a new way of reading data you will probably never need to
use it directly.
 MMAPI
• In a nutshell, you use the
Manager class to create
Player instances for
different media by
specifying DataSource
instances.
• The Player instances thus
created are configurable by
using Control instances.
– For example, almost all
Player instances would
theoretically support a
VolumeControl to control
the volume of the Player
 Manager
• Manager is the central class for creating players and it
provides three methods to indicate the source of media.
– These methods, all static, are
• createPlayer(DataSource source),
• createPlayer(InputStream stream, String type)
• and createPlayer(String locator).
– The last method provides a URI style syntax for locating
media.
• For example, if you wanted to create a Player instance on a web based
audio file, you can use
createPlayer("[Link]
av")
• Similarly, to create a media Player to capture audio, you can use
createPlayer("capture://audio")
 Supported Syntax Examples
Media Type Example syntax

"capture://audio" to capture audio on the default audio capture device or

Capture audio "capture://devmic0?encoding=pcm" to capture audio on the devmic0
device in the PCM encoding

"capture://video" to capture video from the default video capture device or

"capture://devcam0?encoding=rgb888&width=100&height=50" to capture from a
Capture video
secondary camera, in rgb888 encoding mode and with a specified
width and height

Start listening in on the "capture://radio?f=105.1&st=stereo" to tune into 105.1 FM frequency and

built-in radio stereo mode

Start streaming
video/audio/text from "rtp://host:port/type" where type is one of audio, video or text
an external source

"device://tone" will give you a player that you can use to play tones or
Play tones and MIDI
"device://midi" will give you a player that you can use to play MIDI
 Supported Protocols and Content Types
• A list of supported protocols for a given content type can be
retrieved by calling the method
getSupportedProtocols(String contentType) which
returns a String array.
– For example, if you call this method with the argument "audio/x-wav" it
will return an array with three values in it:
• http, file and capture (for the wireless toolkit)
• This lets you know that you can retrieve the content type "audio/x-wav", by
using http and file protocols, and capture it using the capture protocol.
– Similarly, a list of supported content types for a given protocol can be
accessed by calling the method
getSupportedContentTypes(String protocol)
– Thus, calling getSupportedContentTypes("capture") will
return
• audio/x-wav and video/[Link].rgb565 (for the wireless toolkit)
• Indicating that you can capture standard audio and rgb565 encoded video.
– Note that passing null in any of these methods will return all supported
protocols and content types respectively.
 Player Lifecycle
• Once a Player instance is created using the Manager class methods, it
needs to go through various stages before it can be used.
– Upon creation, the player is in an UNREALIZED state and must be REALIZED and
PREFETCHED before it can be STARTED.
– Realization is the process in which the player examines the source or destination
media resources and has enough information to start acquiring them.
– Prefetching happens after realization and the player actually acquires these
media resources.
• Both realization and pre-fetching processes may be time and resource consuming,
– doing them before the player is started ensures that there is no latency when the actual start
happens.
• Once a player is started, using the start() method, and is processing media data, it
may enter the PREFETCHED state again when the media processing stops on its own
– because the end of the media was reached
– you explicitly call the stop() method on the Player instance
– or when a predefined time is reached.
• Going from STARTED to PREFETCHED state is like pausing the player,
– Calling start() on the Player instance restarts from the previous paused point
» if the player had reached the end of the media, this means that it will restart from the
beginning
 Player Lifecycle
• Good programming practice requires that
you call the realize() and
prefetch() methods before you call the
start() method to avoid any latency
when you want the player to start.
– The start() method implicitly calls the
prefetch() method (if the player is not in
a PREFETCHED state), which in turn calls
the realize() method (if the player is not
in a REALIZED state),
• but if you explicitly call these methods
first, you will have a Player instance that
will start playing as soon as you call
start().
– A player can go into the CLOSED state if
you call the close() method on it, after
which the Player instance cannot be
reused.
– Instead of closing, you can de-allocate a
player by calling deallocate(), which
returns the player to the REALIZED state,
• thereby releasing all the resources that it
would have acquired.
 MIDP and MMAPI
• MIDP 2.0 contains a subset of the broad
MMAPI 1.1.
– The subset only supports tones and audio
with only two controls for each,
• ToneControl
• and VolumeControl.
– Additionally, datasources are not supported,
and hence, the Manager class in MIDP 2.0 is
simplified and does not provide the
createPlayer(DataSource source)
method.
 Using MMAPI
• Perhaps the easiest way to learn about
MMAPI is to start by acquiring and playing
a simple audio file.
– All multimedia operations, whether simple
audio playback or complex video capture, will
follow similar patterns.
– The Manager class will be used to create a
Player instance using a String locator.
– The Player will then be realized, prefetched
and played till it is time to close it
 Playing Audio
• [Link]
• You have an audio player with code that leaves room to add playback for
other media.
• To start, the MIDlet displays a list of items that can be played.
– At the moment, it only contains a single item called "Siren from jar".
– Notice that in the code, "Siren from jar" corresponds to a file-based access.
• This implies that the actual location of this media will be in the MIDlet jar file.
– When the user selects this item, a Player object is created specifically for it in
the playMedia() method.
• This method loads this player, attaches a listener to it, prefetches it, realizes it and
finally, starts it.
– Also notice that it plays the media continually.
• Because the listener for the Player is the MIDlet class itself, the
playerUpdate() method catches the player events.
– Thus, when the user starts hearing the siren, the Form is displayed, allowing the
user to stop or pause it.
• Stop takes the user back to the list,
• Pause pauses the siren and replays from the paused marker when restarted.
 Playing Video
• Having created this generic class, it is now fairly easy to add other types of media to it.
• Besides audio, video is the primary media that would be played.
– To allow the MediaMIDlet to play video, the only change that needs to be made is in the
playerUpdate() method, to create a video screen.
// see if we can show a video control, depending on whether the media
// is a video or not
VideoControl vc = null;
if((vc = (VideoControl)[Link]("VideoControl")) != null) {
Item videoDisp = (Item)[Link](vc.USE_GUI_PRIMITIVE, null);
[Link](videoDisp);
}
• [Link]
– The change allows you to play video files with the help of this MediaMIDlet as well.
– If the method determines that the player has a VideoControl, it exposes it by creating a GUI for it.
• This GUI is then attached to the current form.
• Of course, now you need to attach a video file to the list so that you can test it.
– Recall that not all mobile phones will play all video files (or audio files for that matter).
– To see the list of video files supported by a device, use the
[Link](null) method.
• In the case of the Wireless Toolkit, video/mpeg is supported and therefore, the mpeg video provided with this
lecture will play.
• Add this to the list
– [Link]("Promo Video from jar", "[Link]
– [Link]("Promo Video from jar", "video/mpeg");
• put the video in the res folder, and you should now be able to select and play it as well when the MIDlet is
run.
 Streaming Media
• It is highly likely that the media files, especially video files, will not be distributed with
your MIDlet, unless they are really small in size.
– For a successful MIDlet application, the ability to stream media over the network is essential.
– MediaMIDlet can play media over the network easily by specifying an HTTP based file.
– However, there are two issues to be considered in such a case.
• First, media access over the network requires explicit permission from the end user.
– After all, this network usage will likely incur a cost to the user, which he must agree to.
• Second, media access over the network can be a time consuming operation.
• This operation should not be done in the main application thread, in case it ties it up in an intermittent
network and blocks forever.
– All network access should be done in a separate thread.
– [Link]
• The first issue is taken care of by the underlying Application Management Software (AMS).
• It explicitly asks for user permission once network access is required.
– Notice how the MIDlet asks for user permission to access the network before the player can be created.
– Permission granted once is assumed granted for the whole time the MIDlet is running;
» therefore, repeated network access to access other files does not bring up this screen.
• The second issue is taken care of by separating the network media access code in its own thread.
– All of the code that interacts with the media has been moved to the PlayerManager class, which is run in its own
thread.