User’s Guide J2ME Wireless Toolkit 2.2 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, California 95054 U.S.A.
Copyright © 2004 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. This distribution may include materials developed by third parties.
Contents Preface ix 1. Introduction 1 1.1 Quick Start 1 1.2 The Tools in the Toolkit 1.3 Toolkit Features 1.4 Supported Technology 3 2. Developing MIDlet Suites 5 2 3 2.1 About Projects 2.2 The Simple Development Cycle 2.3 5 2.2.1 Edit Source Code 2.2.2 Build 2.2.3 Run 7 7 8 9 The Full Development Cycle 2.3.1 Package 2.3.2 Install 2.3.3 Run 11 11 12 14 2.4 Using an Obfuscator 2.5 Using a Debugger 2.6 Deploying Applications on a Web Server 3.
3.1 Selecting APIs 3.2 Changing MIDlet Suite Attributes 3.3 Manipulating MIDlets 3.4 Using the Push Registry 3.5 Project Directory Structure 3.6 Using Third-Party Libraries 3.7 19 24 25 26 3.6.2 Third-Party Libraries for All Projects 26 Configuring KToolbar 26 3.7.1 Setting the Application Directory 3.7.2 Setting the javac Encoding Property 3.7.3 Working with Revision Control Systems Emulator Skins 4.2 Using the Emulator 4.3 Setting Emulator Preferences 27 30 32 4.3.
.3.1 Filtering Messages 5.3.2 Sorting Messages 5.3.3 Saving and Loading Network Monitor Information 5.3.4 Clearing the Message Tree 6. Security and MIDlet Signing 6.1 Permissions 6.2 Protection Domains 6.3 Signing a MIDlet Suite 6.4 Managing Keys 6.5 45 46 46 47 49 49 50 51 52 6.4.1 Creating a New Key Pair 6.4.2 Getting Real Keys 6.4.3 Importing an Existing Key Pair 6.4.4 Removing a Key Pair Managing Certificates 52 53 54 54 54 6.5.1 Importing Certificates 55 6.5.
8.4 Well-Behaved MIDlets 66 9. Working With Mobile 3D Graphics 67 9.1 JSR 184 Overview 67 9.2 Immediate Mode 9.3 Retained Mode 9.4 Trading Quality for Speed 9.5 Creating Mobile 3D Graphics Content 67 68 68 10. Using the PIM and FileConnection APIs 10.1 The FileConnection API 10.2 The PIM API 71 71 72 11. Using the Bluetooth and OBEX APIs 73 11.1 Bluetooth Simulation Environment 11.2 OBEX Over Infrared 11.3 Setting OBEX and Bluetooth Preferences 73 73 11.3.
A.6.1 Simple Tones 87 A.6.2 Simple Player 87 A.6.3 PausingAudioTest A.6.4 Video A.6.5 Attributes for mmademo A.7 ObexDemo A.8 PDAPDemo A.9 89 89 90 90 92 A.8.1 Browsing Files A.8.2 The PIM API WMADemo 92 94 97 B. Command Line Reference 103 B.1 Prerequisites 103 B.2 The Development Cycle B.2.1 Build B.2.2 Package B.2.3 Run B.2.4 Debugging 103 103 104 106 107 B.3 Launching Toolkit GUI Components B.4 Setting Emulator Preferences B.5 Using Security Features B.
C.
Preface This document describes how to work with the J2ME Wireless Toolkit. Who Should Use This Book This guide is intended for developers creating Mobile Information Device Profile (MIDP) applications with the J2ME Wireless Toolkit. You should already understand how to use, the Mobile Information Device Profile (MIDP), and the Connected Limited Device Configuration (CLDC). If you need help getting started with Java programming, try the New to Java Center: http://java.sun.
http://developers.sun.com/techtopics/mobility/ Topic Title Customizing the J2ME Wireless Toolkit J2ME Wireless Toolkit Basic Customization Guide Release Notes J2ME Wireless Toolkit Release Notes MIDP 1.0 - JSR 37 Mobile Information Device Profile for the J2ME™ Platform MIDP 2.0 - JSR 118 Mobile Information Device Profile 2.0 CLDC 1.0 - JSR 30 J2ME Connected Limited Device Configuration CLDC 1.1 - JSR 139 J2ME Connected Limited Device Configuration WMA 2.
Chapter 7 details support for running and testing wireless messaging applications. Chapter 8 explains how the J2ME Wireless Toolkit supports the Mobile Media API. Chapter 9 contains information about developing 3D graphics content. Chapter 10 describes how the toolkit implements access to local files and personal information like contacts and calendar appointments. Chapter 11 covers the toolkit’s Bluetooth and OBEX simulation environment. Chapter 12 shows how to use the web services stub generator.
Typographic Conventions Typeface Meaning Examples AaBbCc123 The names of commands, files, and directories; on-screen computer output Edit your .login file. Use ls -a to list all files. % You have mail. AaBbCc123 What you type, when contrasted with on-screen computer output % su Password: AaBbCc123 Book titles, new words or terms, words to be emphasized Read Chapter 6 in the User’s Guide. These are called class options. You must be superuser to do this.
CHAPTER 1 Introduction This book describes how to use the J2ME Wireless Toolkit. The J2ME Wireless Toolkit is a set of tools that makes it possible to create applications for mobile phones and other wireless devices. Although it is based on the Mobile Information Device Profile (MIDP) 2.0, the J2ME Wireless Toolkit also supports a handful of optional packages, making it a widely capable development toolkit. 1.
FIGURE 1 The KToolbar window Next, click on the Open Project... button to open a demonstration application. You'll see a list of all the available applications. Pick one of them and click on the Open Project button in the dialog. Once the application is open, all you need to do is press the Run button. The emulator will pop up running the example application. Most demonstrations are self-explanatory, but some have additional instructions.
KToolbar is the center of the toolkit. You can use it to build applications, launch the emulator, and start the utilities. Alternately, the emulator and utilities can be run by themselves, which is useful in many situations. If you want to demonstrate MIDP applications, for example, it’s useful to run the emulator by itself. The only additional tool you need is a text editor for editing source code. 1.
TABLE 1 4 Supported JCP APIs in the J2ME Wireless Toolkit JSR API Name URL JSR 135 MMAPI 1.1 Mobile Media API http://jcp.org/en/jsr/detail?id=135 JSR 75 PIM and File PDA Optional Packages for the J2ME Platform http://jcp.org/en/jsr/detail?id=75 JSR 82 Bluetooth and OBEX Java APIs for Bluetooth http://jcp.org/en/jsr/detail?id=82 JSR 172 J2ME Web Services Specification http://jcp.org/en/jsr/detail?id=172 JSR 184 3D Graphics Mobile 3D Graphics API for J2ME http://jcp.
CHAPTER 2 Developing MIDlet Suites This chapter describes how you can use the J2ME Wireless Toolkit to create applications. It begins with a description of toolkit projects, then works through the development process. There are two basic development cycles you are likely to follow in creating MIDlet suite applications. The first is quicker and simpler; you will probably use it in your initial development. The second cycle is longer but allows for more comprehensive and realistic testing.
FIGURE 2 The KToolbar window Click on New Project... The toolkit will ask you for the name of the project and the name of the MIDlet class you will write. Fill in the names and click Create Project. FIGURE 3 Creating a new project The project options automatically pop up, allowing you to set up the build environment for the project. The default options are fine for this example; just click on OK to dismiss the window.
FIGURE 4 2.2 File locations in the console The Simple Development Cycle The simple development cycle looks like this: Edit source code → Build → Run 1. Edit source code. In this step, you create Java source files and resource files that will be used by your application. 2. Build. The J2ME Wireless Toolkit compiles and preverifies your Java source files. 3. Run. The compiled Java class files are run on the emulator.
If you are following along with the example project, create a new Java source file TinyMIDlet.java. It should be saved in the source directory of your project, which will be {toolkit}\apps\Tiny\src\TinyMIDlet.java where {toolkit} is the installation directory of the toolkit. The contents of the file are a very simple MIDlet: import javax.microedition.lcdui.*; import javax.microedition.midlet.
FIGURE 5 Messages about building Behind the scenes, the J2ME Wireless Toolkit also preverifies the compiled class files. MIDlet class files must be preverified before they can be run on a MIDP device or emulator. The toolkit quietly handles this detail for you; you probably won’t ever realize it’s happening. See the CLDC specification for more information on preverification. 2.2.3 Run Once the project builds successfully, you are ready to try it out in the emulator. Click on the Run button.
FIGURE 6 List of project MIDlets Choose the MIDlet you want and select Launch.
2.3 The Full Development Cycle The second development cycle is slightly more complicated: Edit source code → Package → Install → Run 1. Edit source code. This is the same as in the simple cycle. 2. Package. In this step, the J2ME Wireless Toolkit compiles and preverifies the source files (essentially the same as the Build step from before). Then it bundles the Java class files and resource files into a MIDlet suite JAR file and a MIDlet suite descriptor. 3. Install.
2.3.2 Install To properly test a MIDlet suite, you should install it into the toolkit’s emulator or a real device. When you press the Run button in KToolbar, the MIDlet suite is not installed into the emulator. Instead, the emulator runs the MIDlet classes directly. The emulator also has the capability of installing applications into its memory in a process that resembles how applications are transmitted and installed on real devices.
FIGURE 9 URL prompt Choose Go from the menu to begin the installation. The emulator shows a list of the applications it finds at the URL. Choose the only one and select Install from the menu. The emulator gives you one last chance to confirm your intentions. FIGURE 10 Confirming the installation Choose Install again to finish the installation. You’ll be returned to the emulator’s installed list of applications, which now includes the application you just installed.
FIGURE 11 The application menu, again Run via OTA is an extremely useful mechanism that makes it easy to install your MIDlet suite on the toolkit emulator. Some features must be tested using this technique, including the push registry and the installation of signed MIDlet suites. If you want to test your MIDlet suite on a real device, you’ll need to install it first. How this happens depends heavily on the device you are using. There are two likely possibilities: ■ ■ 2.3.
FIGURE 12 Launching the installed application Running an application on a real device depends heavily on the device itself. Consult your device documentation for information. 2.4 Using an Obfuscator An obfuscator is a tool that reduces the size of class files. MIDlet suites need to be compact, both to minimize download times and to comply with sometimes stringent limits on JAR size imposed by manufacturers or carriers.
3. Uncompress the proguard.jar file from the lib directory of the ProGuard installation to the bin directory of your J2ME Wireless Toolkit installation. Once ProGuard is installed, you can use it by choosing Project > Package > Create Obfuscated Package. In some cases you will need to provide a script file that controls how the obfuscator works. If you are loading classes using Class.forName(), for example, you need to tell ProGuard to leave the class names unchanged.
2.5 Using a Debugger A variation on running your application is running it with a debugger. A debugger allows you to monitor the running application more closely, set breakpoints, and examine variables. You will need to supply your own debugger. You can use the jdb debugger from J2SE™ or another debugger of your choice. Begin by choosing Project > Debug from the KToolbar menu. Enter the TCP/IP port number that the debugger will use to connect to the emulator. Click on Debug.
The details of how to configure a Web server depend on the specific software used. The emulator implements the device behavior during OTA provisioning. You can use the emulator to test and demonstrate the full provisioning process of MIDlet suites from a server to the device. All you need to do is launch the emulator’s AMS. (You may already be familiar with the AMS if you have used KToolbar’s Run via OTA option.
CHAPTER 3 Working With Projects In the last chapter, you learned how the J2ME Wireless Toolkit helps you with the MIDP development cycle. This chapter delves more deeply into the details of working with projects, including the following: 3.
FIGURE 13 The project settings window On the API Selection tab, the Target Platform setting controls the appearance of the rest of the tab. Choose the setting that best suits your need, and tweak your selection with the controls below. For example, if you’re developing applications for JTWI-compliant devices, choose JTWI from the combo box. Then use the controls below to specify which version of CLDC you want to use and whether MMAPI should be present.
3.2 Changing MIDlet Suite Attributes The project settings window also allows you to control the MIDlet suite attributes, which are stored in the descriptor as well as the manifest file of the MIDlet suite JAR. To see the attributes, run KToolbar and open a project. Then click on Settings.... The three tabs that define attributes are Required, Optional, and User Defined. Consult the MIDP 2.0 specification for the definitions of the required and optional attributes.
FIGURE 14 Editing MIDlet suite attributes To create new user-defined attributes, click on the User Defined tab. Press Add and fill in the key name. You can then edit the attribute value by clicking in the value column next to the key, just as you would with required or optional attributes. Select an attribute and click on Remove if you wish to remove the key and value entirely.
3.3 Manipulating MIDlets The project settings also provide a way to add or modify the MIDlets that are contained in the current MIDlet suite project. To see how this works, start KToolbar and open an existing project. Click on Settings... and choose the MIDlets tab. You will see a list of all MIDlets in the project. If you just created a new project, the toolkit automatically fills in the first MIDlet entry. FIGURE 15 The list of MIDlets in a project To add a new MIDlet, click on Add.
The MIDlet names are presented to the user in the order shown when the MIDlet suite is launched. You can modify the order by selecting a MIDlet and clicking Move Up or Move Down. 3.4 Using the Push Registry You can also use project settings to work with a MIDlet suite’s push registry settings. Click on Settings... and choose the Push Registry tab.
If you do make push registry entries for your application, make sure you also enter the appropriate permissions. See Chapter 6, “Security and MIDlet Signing,” for details. 3.5 Project Directory Structure Projects have a standard directory structure. The project itself is represented by a directory in {toolkit}\apps. For example, the demos project is contained in {toolkit}\apps\demos.
When you use a third-party library in your application, your JAR will expand by the size of the third-party library. You can use an obfuscator to reduce the code size, and a good obfuscator will even eliminate whatever parts of the library you are not using. Even with the use of an obfuscator, a third-party library will probably still be larger than your own custom code, carefully written from scratch.
3.7.1 Setting the Application Directory By default, the J2ME Wireless Toolkit stores applications in directories under {toolkit}\apps. You can change this by adding a line to ktools.properties of the following form: kvem.apps.dir: Any backslash ('\') characters in the directory’s path should be preceded by another backslash. Also, the directory’s path should not contain any spaces. For example, to set the application directory to D:\dev\midlets, you would use: kvem.apps.
28 J2ME Wireless Toolkit User’s Guide • October 2004
CHAPTER 4 Using the Emulator The J2ME Wireless Toolkit emulator simulates a MIDP device on your desktop computer. It is a convenient way to see how your application performs in a MIDP environment and gives you a tight development cycle that is entirely contained on your desktop computer. The emulator does not represent a specific device, but it provides correct implementations of its supported APIs. 4.
4.2 Using the Emulator The emulator looks and acts like a mobile phone. In this section you’ll learn how to control the emulator. Although the description and figures are based on the DefaultColorPhone skin, all the skins operate in a similar way.
FIGURE 17 The DefaultColorPhone emulator skin Chapter 4 Using the Emulator 31
You can use the mouse to click on the buttons to press them. Most buttons also have keyboard shortcuts, which are generally easier to use. Keyboard numbers 0 through 9 correspond to the emulator’s 0 through 9 buttons. Some less obvious keyboard shortcuts are in the following table. TABLE 4 Keyboard shortcuts Emulator button Keyboard key Left soft button F1 Right soft button F2 Power button Esc SELECT Enter Entering text works much as it does on many real devices.
4.3.2 Heap Size The heap is memory where your application’s objects are stored. Many real devices have limited heap size. You can set a maximum heap size to more closely simulate the conditions on a real device. Choose Edit > Preferences... from the KToolbar menu and selecting the Storage tab. Fill in the maximum heap size in the Heap Size field. Remember, one kilobyte (kB) is 1024 bytes. If you don’t specify a heap size, the default is 2 megabytes. FIGURE 18 4.3.
The toolkit enables you to choose a different location for the storage files, and you can limit the size of the storage. This is useful if you wish to test your application’s behavior when a small amount of persistent storage is available. To adjust the persistent storage settings, choose Edit > Preferences... and click on the Storage tab. Enter the name of the directory you wish to use for persistent storage.
FIGURE 19 Adjusting the emulator’s performance Adjust the Graphics primitives latency to have an effect on the amount of time that elapses between your application’s calls to drawing methods in the Graphics class and when the drawing actually takes place. To change the screen characteristics, choose one of the Display refresh types. If you choose a Periodic type, you will also need to specify the Refresh Rate.
When the emulator is running, choose MIDlet > Pause from the emulator window’s menu. The running MIDlet is paused and the screen displays an “Incoming Call...” message. To resume the MIDlet’s operation, choose MIDlet > Resume from the menu. 4.5 Running the Emulator Solo During development, you will most often run the emulator directly from KToolbar by pressing the Run button or using the Project > Run via OTA feature. For testing or demonstrations, you might wish to run the emulator by itself.
is usually to unpack or install the third party emulator, then copy its directory into the /wtklib/devices directory. Next time you run KToolbar, the emulator is available. A partial listing of some of the currently available emulators is available here: http://developers.sun.
38 J2ME Wireless Toolkit User’s Guide • October 2004
CHAPTER 5 Monitoring Applications The J2ME Wireless Toolkit provides several tools to monitor the behavior of your applications. These tools are helpful in debugging and optimizing your code. ■ The profiler lists the frequency of use and execution time for every method in your application. ■ The memory monitor shows the usage of memory while your application runs. ■ The network monitor shows network data transmitted and received by your application.
FIGURE 20 Turning on the profiler Now run your application by clicking on the Run button. Interact with your application as you normally would. When you’re finished, shut down the emulator. The profiler pops up with information about all the method calls in your application. FIGURE 21 The method profiler The profiler displays two types of information: ■ 40 Method relationships are shown in a hierarchical list, the Call Graph.
■ The right side of the profiler shows the execution time and number of calls for each method and its descendants. Note – The profiling values obtained from the emulator do not reflect actual values on a real device. 5.1.1 The Call Graph The call graph shows a hierarchy of method calls. Methods that call other methods are shown as folders. Double-click on a method to open it and see the methods it calls. Methods that do not call any other method are shown as gray circles.
5.1.3 Saving and Loading Profiler Information To save your profiler session, click on the Save button in the profiler window. Choose a file name. To load a profiler session, choose File > Utilities... from the KToolbar menu. Click on Open Session in the Profiler box. When you select a file, the profiler window appears with all the session information. 5.2 Using the Memory Monitor Memory is scarce on many MIDP devices.
■ Maximum. The maximum amount of memory used since program execution began, shown in the graph by a broken red line. ■ Objects. The number of objects in the heap. ■ Used. The amount of memory used. ■ Free. The amount of unused memory available. ■ Total. The total amount of memory available at startup. Remember, you can modify the heap size using the Storage tab of the KToolbar preferences. See Chapter 3, “Working With Projects,” for details.
■ Name. The class name of the objects. ■ Live. The number of instances. Some of these might be eligible for garbage collection. ■ Total. The total number of objects that have been allocated since the application began. ■ Total Size. The total amount of memory used by the objects. ■ Average Size. The average object size, calculated by dividing the live instances into the total size. Click on any column header to sort on that column. You can search for a specific class name by choosing View > Find..
FIGURE 24 The network monitor When your application makes any type of network connection, information about the connection is captured and displayed. The figure shows two HTTP requests and responses. The display on the left side shows a hierarchy of messages and message pieces. Click on a message or a portion of a message to see details in the right side of the network monitor. Message bodies are shown as raw hexadecimal values and the equivalent text.
Press the Filter Settings button to use the filter. Change the filter settings to suit your needs. TABLE 5 Network monitor filter settings Network Protocol Filter Settings HTTP/HTTPS Enter text to match the various parts of HTTP messages: URL, status line, headers, or body. For example, entering “slashdot” in the URL field would filter to show only messages whose URL contained “slashdot”. SMS/CBS You can specify a protocol, message type, and direction to match.
To load a network monitor session, choose File > Utilities... from the KToolbar menu. Click on Open Session in the Network Monitor box. When you select a file, the network monitor window appears with all the session information. 5.3.4 Clearing the Message Tree To remove all messages from the network monitor, choose Edit > Clear from the network monitor menu.
48 J2ME Wireless Toolkit User’s Guide • October 2004
CHAPTER 6 Security and MIDlet Signing MIDP 2.0 includes a comprehensive security model based on protection domains. MIDlet suites are installed into a protection domain which determines access to protected functions. The MIDP 2.0 specification also includes a recommended practice for using public key cryptography to verify and authenticate MIDlet suites. For definitive information, consult the MIDP 2.0 specification.
In the J2ME Wireless Toolkit, you can add these permission attributes to a project by clicking on the Settings... button in KToolbar. Select the Permissions tab. The MIDlet-Permissions box shows permissions which the MIDlet must possess, while the MIDlet-Permissions-Opt box contains permissions that the MIDlet would like to have but does not need absolutley. FIGURE 25 MIDlet suite permissions To add a permission to either box, click on Add and choose the permission you want to add.
■ MIDlets in the minimum domain are denied all permissions. ■ The untrusted domain provides a high level of security for applications whose origins and authenticity cannot be determined. The user is prompted frequently when the application attempts a sensitive operation ■ The trusted domain is a happy place for MIDlets where all permissions are granted. ■ The maximum domain is equivalent to trusted.
FIGURE 26 The MIDlet suite signing window Signing is very easy. Just select the key you want to use in the Alias List and click on the Sign MIDlet Suite... button. 6.4 Managing Keys The MIDlet signing window can also be used to manage keys. 6.4.1 Creating a New Key Pair To create an entirely new key pair, click on New Key Pair... The toolkit prompts you for a key alias and information that will be associated with the key pair.
FIGURE 27 Creating a new key pair After you click on Create, the toolkit prompts you to choose a protection domain. The connection between the key pair you just created and a protection domain might seem oblique, but it makes perfect sense: ■ The toolkit creates a self-signed root certficate using the key pair you just created. ■ The root certificate is added to the emulator’s list of root certificates. ■ The toolkit needs to associate the root certificate with a protection domain.
The procedure for signing MIDlet suites with real keys works like this: 1. Generate a new key pair. In the J2ME Wireless Toolkit you can do this by pressing New Key Pair... in the MIDlet signing window, as described above. 2. Generate a Certificate Signing Request (CSR). Press Generate CSR... in the signing window. To change the location of the CSR file, enter a new path or press Browse... and choose a new file location. Press Create to write the CSR file.
Real devices have similar lists of root certificates, although they cannot usually be modified by the user. When you want to deploy your application on a real device, you’ll have to use signing keys issued by a certificate authority whose root certificate is present on the device. Otherwise, the device will be unable to verify your application.
6.5.2 Removing Certificates To remove a certificate from the list, select the certificate and choose Action > Delete Selection.
CHAPTER 7 Using the Wireless Messaging API The J2ME Wireless Toolkit supports the Wireless Messaging API (WMA) with a sophisticated simulation environment. WMA 1.1 (JSR 120) enables MIDlets to send and receive Short Message Service (SMS) or Cell Broadcast Service (CBS) messages. WMA 2.0 (JSR 205) includes support for MMS messages as well. This chapter describes the tools you can use to develop WMA applications. It begins by showing how to configure the emulator’s support of WMA.
FIGURE 29 Setting WMA preferences The Phone Number of Next Emulator field is just what it sounds like. If you fill in a number for this field, the next emulator instance will have that number. If the Phone Number of Next Emulator is already in use, or if the field is blank, then the First Assigned Phone Number is used for the next emulator instance. Subsequent instances count up.
7.3 Sending Messages With the WMA Console The WMA console is a handy utility that allows you to send and receive messages. You can, for example, use the WMA console to send SMS messages to a MIDlet running on the emulator. To launch the WMA console, choose File > Utilities... from the KToolbar menu. Click on Open Console in the WMA box. FIGURE 30 7.3.1 The WMA console Sending a Text SMS Message To send a text SMS message, click on Send SMS... The send window pops up.
FIGURE 31 Sending a text message The window automatically lists the phone numbers of all running emulator instances. Select a destination (Control-click to select multiple destinations) and enter a port number if you wish. Type your message and click Send. 7.3.2 Sending a Binary SMS Message You can use the WMA console to send the contents of a file as a binary message. Click on Send SMS... to bring up the send window. Click on the Binary SMS tab.
FIGURE 32 Sending a binary message Selecting recipients is the same as for sending text SMS messages. You can type in the path of a file directly, or click on Browse... to open up a file chooser. 7.3.3 Sending Text or Binary CBS Messages Sending CBS messages is similar to sending SMS messages except that you don’t need to choose recipients. To send a text or binary CBS message, click on Send CBS... in the WMA console. The send window pops up.
FIGURE 33 7.3.4 Sending CBS messages Sending MMS Messages MMS messages consist of one or more files, usually images or sounds. MMS message can be sent to multiple recipients. To send an MMS message from the WMA console, click on the Send MMS... button. The window for composing MMS messages has two tabs, one for recipients and one for content. Begin by filling in a subject and recipient. If you wish to add more recipients, click on the Add button.
FIGURE 34 Adding recipients for an MMS message To add media files to the message, click on the Parts tab. Click on Add to add a part to the message. To remove a part, select it and press Remove.
7.4 Receiving Messages in the WMA Console The WMA console can also receive messages. If you look at the WMA console window, you’ll see it has its own phone number in the title bar. You can send messages to the WMA console from your applications running on the emulator. Received messages are shown in the WMA console’s text area. 7.5 Using the Network Monitor with WMA The network monitor was fully described in Chapter 5, “Monitoring Applications.
CHAPTER 8 Using the Mobile Media API The Mobile Media API (MMAPI) provides a standard API for rendering and capturing time-based media, like audio or video. The API was designed to be flexible with respect to the media formats, protocols, and features supported by various devices. 8.
8.2 Using MediaControlSkin The J2ME Wireless Toolkit comes with an emulator skin, MediaControlSkin, that is focused on multimedia playback and control. The skin includes buttons with symbols representing play, stop, volume up and volume down, and other commands. To see the usefulness of MediaControlSkin, try it out with the mmademo demonstration application. 8.3 Media Capture The J2ME Wireless Toolkit emulator supports audio and video capture.
CHAPTER 9 Working With Mobile 3D Graphics This chapter provides a brief overview of working with 3D graphics content. 9.1 JSR 184 Overview JSR 184 is a specification that defines the Mobile 3D Graphics (M3G) API for J2ME. This API provides 3D functionality in a compact package that’s appropriate for CLDC/MIDP devices. The API provides two methods for displaying 3D graphics content. The immediate mode API makes it possible for applications to directly create and manipulate 3D elements.
For an example of immediate mode, see the Life3D MIDlet in the Demo3D example application. 9.3 Retained Mode Most applications, particularly games, will use the retained mode or scene graph API. In this approach, a graphic designer or artist uses 3D modeling software to create a scene graph. The scene graph is saved in the JSR 184 file format. The scene graph file is bundled with the application. At runtime, the application uses the scene graph API to load and display the file.
9.5 Creating Mobile 3D Graphics Content Most mobile 3D applications will use scene graphs in resource files to describe objects, scenes, and characters. Usually it is not programmers but graphic designers or artists who create the scene graphs, using standard 3D modeling tools. Several vendors offer tools for authoring content and converting files to the JSR 184 format. Superscape (http://superscape.com/) is one such vendor.
70 J2ME Wireless Toolkit User’s Guide • October 2004
CHAPTER 10 Using the PIM and FileConnection APIs The J2ME Wireless Toolkit supports JSR 75, the PDA Optional Packages for the J2ME Platform. JSR 75 includes two independent APIs: ■ The FileConnection optional package allows MIDlets access to a local device file system. ■ The Personal Information Management (PIM) optional package includes APIs for manipulating contact lists (address book), calendars, and to-do lists.
Each subdirectory of filesystem is called a root. The J2ME Wireless Toolkit provides a mechanism for managing roots. While the emualtor is running, choose MIDlet > External events from the emulator window’s menu. You’ll see a utility window for adding and removing roots. FIGURE 37 Managing filesystem roots The mounted roots and their contents are available to applications using the FileConnection API. To add a new root directory, click on Mount New... and fill in a name for the directory.
CHAPTER 11 Using the Bluetooth and OBEX APIs The J2ME Wireless Toolkit emulator supports JSR 82, the Java APIs for Bluetooth. JSR 82 includes two independent APIs: ■ The Bluetooth API provides an interface to Bluetooth wireless networking, including device discovery and data exchange. ■ The OBEX API allows applications to use the Object Exchange (OBEX) protocol over Bluetooth or other communication channels. This chapter describes how the J2ME Wireless Toolkit implements the Bluetooth and OBEX APIs.
11.3 Setting OBEX and Bluetooth Preferences The J2ME Wireless Toolkit allows you to configure the Bluetooth and OBEX simulation environment. Choose Edit > Preferences... from the KToolbar menu to see the following window. FIGURE 38 11.3.1 Bluetooth and OBEX preferences OBEX Preferences Devices using IrDA in the real world discover other devices by “listening”.
11.3.2 Bluetooth Discovery Timeout In the Bluetooth section of the preferences window, the Device discovery timeout is the amount of time, in milliseconds, the emulator will wait while attempting to locate other devices in the simulated Bluetooth environment. 11.3.3 Bluetooth System Properties The System Properties tab in the Bluetooth section of the preferences contains properties that can be retrieved in an application using the getProperty() method in javax.bluetooth.LocalDevice.
76 J2ME Wireless Toolkit User’s Guide • October 2004
CHAPTER 12 Using Web Services The J2ME Wireless Toolkit emulator supports JSR 172, the J2ME Web Services Specification. JSR 172 provides APIs for accessing web services from J2ME applications. It also includes an API for parsing XML documents. The J2ME Wireless Toolkit provides a stub generator that automates creating source code for accessing web services. To get to the stub generator, choose File > Utilities... from the KToolbar menu. Click on Stub Generator.
78 J2ME Wireless Toolkit User’s Guide • October 2004
APPENDIX A Application Demonstrations This appendix describes the application demonstrations that are bundled with the J2ME Wireless Toolkit. A.1 Overview The J2ME Wireless Toolkit includes demonstration applications that highlight some of the technologies and APIs that are supported by the emulator. The following table lists all the demonstration applications that are included in this release. The demonstrations that are new or enhanced in this release are marked with NEW.
\WTK22, the source code for the SMS sender MIDlet (example.sms.SMSSend) in WMADemo is contained in \WTK22\apps\WMADemo\src\example\sms\SMSSend.java. TABLE 8 Special Instructions Demonstration APIs Description Audiodemo MMAPI 1.1 Demonstrates audio capabilities, including mixing and playing audio with an animation BluetoothDe mo JSR 82 Bluetooth Demonstrates device discovery and data exchange using Bluetooth Section A.
Application demonstrations TABLE 8 NEW A.2 Special Instructions Demonstration APIs Description Photoalbum MIDP 2.0 Demonstrates a variety of image formats UIDemo MIDP 2.0 Showcases the breadth of MIDP 2.0's user interface capabilities WMADemo WMA 2.0 Shows how to send and receive SMS, and CBS, and MMS messages Section A.9 General Instructions It's usually very simple to run one of the demonstration applications. This section describes the general procedure.
FIGURE 41 Opening a demonstration application project Select one and click on the Open Project button in the dialog. Once the application is opened, all you need to do is press the Run button. The device emulator will pop up running the example application. Choose a specific demonstration to run from the menu and press the soft button for Launch. Some demonstrations require other setup and instructions. Check the full list to see if there are specific instructions for a demonstration. A.
FIGURE 42 Running the Bluetooth Demo server On the second emulator, choose Bluetooth Demo, then Client. The MIDlet tells you it’s ready to search for images. Choose Find. The MIDlet will find the other emulator and get a list of images from it. Select one from the list and choose Load. The emulator asks if you want to allow the connection. Choose Yes. In the first emulator, the server, a prompt appears, asking if you want to authorize the connection from the client. Choose Yes.
FIGURE 43 An image transferred via simulated Bluetooth You can avoid the permission prompts by running the demonstration in the trusted protection domain. A.4 Demo3D This application contains three MIDlets that show off the emulator's support of JSR 184, the Mobile 3D Graphics API. A.4.1 Life3D Life3D implements the popular Game of Life in three dimensions. Live cells are represented by cubes. Each cell has 26 possible neighbors (including diagonals).
FIGURE 44 The Game of Life in three dimensions The keypad buttons provide control over the game. TABLE 9 Controls for Life3D Button Description 0 Pause the animation 1 Resume the animation at its default speed 2 Speed up the animation 3 Slow down the animation 4 Choose the previous preset configuration from a list that includes gems like P4 Glider, Skew beehive plus, and P4 Rotor. 5 Choose the next preset configuration from the list.
FIGURE 45 A bouncing kangaroo You can get the kangaroo to bounce around the landscape by using the arrow keys. Push up to go forward, down to go backward, and left and right to change direction. You might need to hold down the keys to see an effect. A.4.3 retainedmode The retainedmode MIDlet plays back a scene file that shows a tireless skateboarder in an endless loop.
FIGURE 46 A.5 A tireless skateboarder JSR172Demo JSR172Demo shows how to access a web service from a MIDlet. The web service is already running on an Internet server. You should be able to simply build and run the example. If you are behind a firewall, you’ll need to configure the emulator’s proxy server settings. Choose Edit > Preferences... from the KToolbar menu, then select the Network Preferences tab. Fill in the proxy server addresses and ports. JSR172Demo contains a single MIDlet, Server Script.
A.6.1 Simple Tones The Simple Tones example demonstrates how to use interactive synthetic tones. The first menu entries play tones with different pitch and duration using Manager.playTone(). Choosing the third menu item will play a chord on the interactive MIDI device (locator "device://midi"). The shortMidiEvent() method of MIDIControl is used to trigger the notes of the chord. A.6.2 Simple Player The Simple Player application demonstrates the range of audio and video capabilities of the emulator.
■ Video Capture Simulation simulates viewing input video such as might be possible on a device equipped with a camera. ■ [enter URL] allows you to play back media files from arbitrary HTTP servers. Type a valid URL at the insertion point and click OK to play a file. If you want to open an HTTP directory from which to select media, be sure to add a slash to the end of the URL. In addition, Simple Player parses ring tones in Ringing Tones text transfer language (RTTTL). See http://www.convertyourtone.
TABLE 10 Command Simple Player commands Key Loop Mode Skip Plays back the audio file immediately after completion of play. Running Loopmode once plays the audio file once. Pressing a second time plays the file three times. Pressing a third time plays the file repeatedly. Pressing a fourth time returns to single play. 1 and 3 Rewind Stop and Rewind Quick Help Description Skips forward or backward five percent of the duration of the media file. The sound track syncs to the video.
Animated GIFs and video capture can be implemented using either a Form Item or a Canvas. The Video demonstration includes all the possibilities: A.6.5 ■ Animated GIF - Form [jar] shows an animated GIF as a Form Item. The form also includes some information about the playback, including the current time. Choose the Snapshot command to take a snapshot of the running animation. The snapshot will be placed in the form following the animated GIF.
Run two instances of the emulator. One listens for incoming connections, while the other attempts to send an image. In the first emulator, choose Obex Demo, then Receive Image. The emulator will ask for permission to listen. Choose Yes. The emulator will display a screen that indicates it’s waiting for incoming connections. FIGURE 47 Waiting for an OBEX connection In the second emulator, launch Obex Demo, then choose Send Image. You’ll see a list of images. Select one and choose Send.
FIGURE 48 Prompting to accept a connection Choose Yes. The image you selected is transferred over the simulated infrared link and displayed on the first emulator.
A.8 PDAPDemo PDAPDemo shows how to use the PIM and FileConnection APIs that are part of the JSR 75 specification. A.8.1 Browsing Files To run the file browser, you’ll need to give the MIDlet appopriate security authorization. The easiest way to do this is to choose Edit > Preferences... from the KToolbar menu. Click on the Security tab. Change the Security domain to trusted and press OK. Now open and run the PDAPDemo project. Launch the FileBrowser MIDlet. You will see a directory listing.
FIGURE 51 Contents of the root1 directory Using the commands in the demonstration, you can view the file or see its properties. Try selecting the file and choosing Properties or View from the menu.
The actual files are located in {toolkit}\appdb\DefaultColorPhone\filesystem, assuming you are using the DefaultColorPhone emulator skin. You can add files and root directories as you wish and they will be visible to the JSR 75 File API. See Chapter 10 for more information. A.8.2 The PIM API The JSR75 PIM APIs example demonstrates how to access personal information, like contact lists, calendars, and to-do lists. After you launch the example, choose a type of list from the main menu.
FIGURE 54 An empty contact list To add an item, choose New from the menu. The application prompts you for a Formatted Name for the item. You can add more data fields to this item using Add Field in the menu. You'll see a list of field names. Pick one, then enter the value for the new field. FIGURE 55 Adding contact fields To actually save the list item, choose Commit from the menu.
FIGURE 56 Saving an item You can return to the list by choosing the Back command. You'll see the item you just created in the list. The items that you create are stored in standard vCard or vCalendar format in the {toolkit}\appdb\{skin}\pim directory. See Chapter 10 for more information. The PIM API allows for exporting contact, calender, and to-do items in a standard format. The exact format depends on the list type.
To see the magic of the push registry, use the WMA console to send the emulator a message. Launch the console by choosing File > Utilities... from the KToolbar menu. Click on the Open Console button in the WMA box to launch the WMA console. Click on the Send SMS... button in the WMA console window. Choose the number that corresponds to the emulator, probably +5550000. If you're not sure what number the emulator is using, look in its title bar.
FIGURE 58 The push registry springs to life Choose Yes. The SMSReceive MIDlet is launched and immediately displays the incoming SMS message. FIGURE 59 An incoming text message You can also use the WMA console to send and receive CBS and MMS messages. See Chapter 7, “Using the Wireless Messaging API,” for more information.
If you are attempting to send text messages to WMADemo using the WMA console, make sure to specify the port number as 50000. Use port 50001 for CBS messages. For MMS messages, use example.mms.MMSDemo as the application ID. For example, to send an MMS message from the WMA console to the emulator, make sure that WMADemo has been installed using Run via OTA as described above. Leave the emulator running. In the WMA console, click on Send MMS... to pop up the MMS composition window.
FIGURE 61 Adding parts to an MMS message Click on Send to send the message. The emulator asks if it can launch WMADemo. Click on Yes. The image and its information are displayed.
APPENDIX B Command Line Reference This appendix describes how to operate the J2ME Wireless Toolkit from the command line and details the steps required to build and run an application. It also describes the J2ME Wireless Toolkit certificate manager utility, called MEKeyTool, and the MIDlet signing utility, called JAD Tool (Java Application Descriptor Tool). B.1 Prerequisites Before building and running an application from the command line, verify that you have a version no earlier than 1.4.
B.2.1 Build Using KToolbar, building a project is a single step. Behind the scenes, however, there are actually two steps. First, Java source files are compiled into Java class files. Next, the class files are preverified, which means they are prepared for the CLDC KVM. Use the javac compiler from the J2SE SDK to compile Java source files. You can use the existing J2ME Wireless Toolkit project directory structure.
As a result of this command, preverified class files are placed in the classes directory. If your application uses WMA, MMAPI, or other versions of CLDC or MIDP, be sure to include the relevant .jar files in the classpath. B.2.2 Package To package a MIDlet suite, you must create a manifest file, an application JAR, and finally, a MIDlet suite descriptor. Create a manifest file containing the appropriate attributes as specified in the MIDP specification.
For example, a JAD file might have the following contents: MIDlet-Name: MyMIDlet MIDlet-Vendor: My Organization MIDlet-Version: 1.0 MIDlet-Jar-URL: MyApp.jar MIDlet-Jar-Size: 24601 B.2.3 Run You can run the emulator from the command line. The J2ME Wireless Toolkit’s bin directory contains the command emulator. The syntax for the emulator command is as follows: emulator [options] The general options are: -help: Display a list of valid options. -version: Display version information about the emulator.
remove=[ | | all] Remove a previously installed application. The application is specified by its valid storage name or storage number. Specifying all, all previously installed applications are removed. transient= Install, run, and remove the application with the specified JAD file. Specifying transient causes the application to be installed and run and then removed three times. B.2.
B.3 Launching Toolkit GUI Components The components of the J2ME Wireless Toolkit can all be launched from the command line. Each component is in the toolkit’s bin directory. B.
TABLE 13 Emulator Preferences Properties List Property Name Property Description and Legal Values kvem.memory.monitor.enable Monitor > Enable memory monitor Value: true | false kvem.netmon.comm.enable Monitor > Enable Comm monitoring Value: true | false kvem.netmon.datagram.enable Monitor > Enable Datagram monitoring Value: true | false kvem.netmon.http.enable Monitor > Enable HTTP monitoring Value: true | false kvem.netmon.https.
TABLE 13 B.5 Emulator Preferences Properties List Property Name Property Description and Legal Values mm.control.mixing MMedia > Audio Mixing Value: true | false mm.control.record MMedia > Audio Record Value: true | false mm.control.volume Value: true | false mm.format.midi MMedia > MIDI format Value: true | false mm.format.video MMedia > Video format Value: true | false mm.format.wav MMedia > WAV Audio format Value: true | false wma.client.
B.5.2 Signing MIDlet Suites JadTool is a command-line interface for signing MIDlet suites using public key cryptography according to the MIDP 2.0 specification. Signing a MIDlet suite is the process of adding the signer certificates and the digital signature of the JAR file to a JAD file. JadTool only uses certificates and keys from J2SE keystores. J2SE provides keytool, the command-line tool to manage J2SE keystores. JadTool is packaged in a JAR file.
B.5.3 Managing Certificates MEKeyTool manages the public keys of certificate authorities (CAs), making it functionally similar to the keytool utility that comes with the J2SE SDK. The keys can be used to facilitate secure HTTP communication over SSL (HTTPS). Before using MEKeyTool, you must first have access to a Java Cryptography Extension (JCE) keystore. You can create one using the J2SE keytool utility; see http://java.sun.com/j2se/1.4/docs/tooldocs/win32/keytool.html for more information.
B.6 Using the Stub Generator J2ME Clients can use the Stub Generator to access web services. The wscompile tool generates stubs, ties, serializers, and WSDL files used in JAX-RPC clients and services. The tool reads a configuration file, which specifies either a WSDL file, a model file, or a compiled service endpoint interface. The syntax for the stub generator command is as follows: wscompile [options] configuration_files B.6.
Note – Exactly one -gen option must be specified. The -f option requires a comma-separated list of features. TABLE 15 lists the features (delimited by commas) that can follow the -f option. The wscompile tool reads a WSDL file, compiled service endpoint interface (SEI), or model file as input. The Type of File column indicates which of these files can be used with a particular feature. TABLE 15 B.6.1.
APPENDIX C Internationalization This appendix describes setting the language displayed in the J2ME Wireless Toolkit and the localization setting of the emulation environment. C.1 Locale Setting A locale is a geographic or political region or community that shares the same language, customs, or cultural conventions. In software, a locale is represented by a collection of files, data, and code, which contains the information necessary to adapt software to a specific location.
C.2 Emulated Locale The microedition.locale property is the MIDP system property that defines the current locale of the device, which is null by default. For the J2ME Wireless Toolkit emulator, this value is automatically set to the default locale for the J2SE environment you are running. For example: ■ If you are running in an English system in the US, the microedition.locale is set to en-US. ■ If you are running in a French system, the microedition.locale is set to fr-FR.
Note – All the J2SE encoders are available in the emulated environment. See the J2ME Wireless Toolkit Basic Customization Guide for information on how to limit the list of available encoders for a specific device. C.3.1 Java Compiler Encoding Setting The javac.encoding property determines the encoding used by the javac compiler to compile your source files. The property’s value is set to the default encoding for the J2SE environment running on the same window system.
118 J2ME Wireless Toolkit User’s Guide • October 2004
Index A advanced configuration options, 26 application descriptor, 11 Application Management Software (AMS), 12 applications running remotely, 17 applications directory, setting, 27 attributes, 21 B building source code, 8 C call graph, 41 CBS message, sending, 61 certificate importing, 55 certificate management, 54 certificate manager utility, 103 character encodings, 116 -classpath option, 104 command line operations, 103 command path, 103 D debugging, 17 from command line, 107 debugging options, 107
IrDA, 73 J Mobile Media API (MMAPI), 65 capture, 66 formats and protocols, 65 JAD, 11 attributes, 21 creating, 11 MIME type, 17 JAR creating, 11 MIME type, 17 Java Cryptography Extension (JCE) keystore, 112 JSR 184, 67 JSR 75, 71 N K OBEX, 73 preferences, 74 obfuscation, 15 installing ProGuard, 15 installing RetroGuard, 16 optional APIs, 3 key management, 52 key pair creating, 52 importing, 54 keytool utility, 112 KToolbar advanced configuration options, 26 application directory, 27 starting, 1, 5 kt
push registry, 24 R remotely-deployed applications, 17 revision control, 27 revision control files, 27 Revision Control System (RCS), 27 RevisionControl property, 27 run options, 106 Run via OTA, 12, 51 running from command line, 106 S signed MIDlet suites, 49 signing MIDlet suites, 51 SMS binary message, sending, 60 SMS text message, sending, 59 source code creating, 7 location, 6 supported APIs, 3 T Target Platform, 20 tracing options, 107 V version control, 27 -version optopn, 106 W Wireless Messagi
122 J2ME Wireless Toolkit User’s Guide • October 2004
