Sun Microsystems J2ME manual

Sun Microsystems, Inc. 4150 Network Circle Santa Clara, Calif ornia 95054 U .S.A. 1-800-555-9SUN or 1-650-960-1300 User’ s Guide J2ME Wireless T oolkit 2.2 October 2004[...]

Please Recycle Copyright © 2004 Sun Microsystems, Inc., 4150 Network Cir cle, Santa Clara, California 95054, U.S.A. All rights reserved. U.S. Government Rights - Commercial softwar e. Government users are subject to the Sun Micr osystems, Inc. standard license agreement and applicable pr ovisions of the F AR and its supplements. This distribution [...]

Contents iii Contents Preface ix 1. Introduction 1 1.1 Quick Start 1 1.2 The T ools in the T oolkit 2 1.3 T oolkit Featur es 3 1.4 Supported T echnology 3 2. Developing MIDlet Suites 5 2.1 About Projects 5 2.2 The Simple Development Cycle 7 2.2.1 Edit Source Code 7 2.2.2 Build 8 2.2.3 Run 9 2.3 The Full Development Cycle 1 1 2.3.1 Package 1 1 2.3.2[...]

iv J2ME Wireless Toolkit User’s Guide • October 2004 3.1 Selecting APIs 19 3.2 Changing MIDlet Suite Attributes 21 3.3 Manipulating MIDlets 23 3.4 Using the Push Registry 24 3.5 Project Dir ectory Structur e 25 3.6 Using Third-Party Libraries 25 3.6.1 Third-Party Libraries for One Pr oject 26 3.6.2 Third-Party Libraries for All Pr ojects 26 3.7[...]

Contents v 5.3.1 Filtering Messages 45 5.3.2 Sorting Messages 46 5.3.3 Saving and Loading Network Monitor Information 46 5.3.4 Clearing the Message T r ee 47 6. Security and MIDlet Signing 49 6.1 Permissions 49 6.2 Protection Domains 50 6.3 Signing a MIDlet Suite 51 6.4 Managing Keys 52 6.4.1 Creating a New Key Pair 52 6.4.2 Getting Real Keys 53 6.[...]

vi J2ME Wireless Toolkit User’s Guide • October 2004 8.4 W ell-Behaved MIDlets 66 9. W orking W ith Mobile 3D Graphics 67 9.1 JSR 184 Overview 67 9.2 Immediate Mode 67 9.3 Retained Mode 68 9.4 T rading Quality for Speed 68 9.5 Creating Mobile 3D Graphics Content 69 10. Using the PIM and FileConnection APIs 71 10.1 The FileConnection API 71 10.2[...]

Contents vii A.6.1 Simple T ones 87 A.6.2 Simple Player 87 A.6.3 PausingAudioT est 89 A.6.4 V ideo 89 A.6.5 Attributes for mmademo 90 A.7 ObexDemo 90 A.8 PDAPDemo 92 A.8.1 Browsing Files 92 A.8.2 The PIM API 94 A.9 WMADemo 97 B. Command Line Reference 103 B.1 Prer equisites 103 B.2 The Development Cycle 103 B.2.1 Build 103 B.2.2 Package 104 B.2.3 R[...]

viii J2ME Wireless Toolkit User’s Guide • October 2004 C.4 Font Support in the Default Emulator 1 17 Index 1 19[...]

Preface ix Pr eface This document describes how to work with the J2ME W ireless T oolkit. Who Should Use This Book This guide is intended for developers creating Mobile Information Device Profile (MIDP) applications with the J2ME W ireless T oolkit. Y ou should alr eady understand how to use, the Mobile Information Device Profile (MIDP), and the Co[...]

x J2ME Wireless T oolkit User’s Guide • October 2004 http://developers.sun.com/techtopics/mobility/ How This Book Is Or ganized This guide contains the following chapters and appendixes: Chapter 1 introduces the J2ME W ireless T oolkit and the development featur es it provides. Chapter 2 describes the development processes for creating and runn[...]

Preface xi Chapter 7 details support for running and testing wireless messaging applications. Chapter 8 explains how the J2ME W ir eless T oolkit 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 cont[...]

xii J2ME Wireless T oolkit User’s Guide • October 2004 T ypographic Conventions Accessing Documentation Online The following sites provide technical documentation related to Java technology . http://developer.sun.com/ http://java.sun.com/docs/ W e W elcome Y our Comments W e ar e interested in improving our documentation and welcome your commen[...]

1 CHAPTER 1 Intr oduction This book describes how to use the J2ME W ir eless T oolkit. The J2ME W ireless T oolkit 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 Prof ile (MIDP) 2.0, the J2ME W ireless T oolkit also supports a handfu[...]

2 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 1 The KT oolbar window Next, click on the Open Project... button to open a demonstration application. Y ou'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[...]

Chapter 1 Introduction 3 KT oolbar is the center of the toolkit. Y ou 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 [...]

4 J2ME Wireless Toolkit User’s Guide • October 2004 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 Specif icatio[...]

5 CHAPTER 2 Developing MIDlet Suites This chapter describes how you can use the J2ME W ireless T oolkit to create applications. It begins with a description of toolkit projects, then works through the development process. There ar e two basic development cycles you are likely to follow in creating MIDlet suite applications. The first is quicker and[...]

6 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 2 The KT oolbar 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 pr oject The project options automatically pop up, allowing you to se[...]

Chapter 2 Dev eloping MIDlet Suites 7 FIGURE 4 File locations in the console 2.2 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 f iles and resour ce files that will be used by your application. 2. Build . The J2ME W ir eless T o[...]

8 J2ME Wireless Toolkit User’s Guide • October 2004 If you are following along with the example project, cr eate a new Java source f ile TinyMIDlet.java . It should be saved in the source directory of your pr oject, which will be {toolkit} appsTinysrcTinyMIDlet.java where {toolkit} is the installation directory of the toolkit. The contents [...]

Chapter 2 Dev eloping MIDlet Suites 9 FIGURE 5 Messages about building Behind the scenes, the J2ME W ireless T oolkit also preverifies the compiled class files. MIDlet class f iles must be preverified befor e 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 happ[...]

10 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 6 List of project MIDlets Choose the MIDlet you want and select Launch . If you’re following along with the TinyMIDlet example, you’ll see the fruit of your labors: FIGURE 7 TinyMIDlet in action[...]

Chapter 2 Dev eloping MIDlet Suites 11 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 W ireless T oolkit compiles and preverifies the source f iles (essentiall[...]

12 J2ME Wireless Toolkit User’s Guide • October 2004 2.3.2 Install T o pr operly test a MIDlet suite, you should install it into the toolkit’s emulator or a real device. When you pr ess the Run button in KT oolbar , the MIDlet suite is not installed into the emulator . Instead, the emulator runs the MIDlet classes directly . The emulator also[...]

Chapter 2 Dev eloping MIDlet Suites 13 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[...]

14 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 11 The application menu, again Run via OT A 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 wan[...]

Chapter 2 Dev eloping MIDlet Suites 15 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 f iles. MIDlet suites need to be compact, both to minimiz[...]

16 J2ME Wireless Toolkit User’s Guide • October 2004 3. Uncompress the proguard.jar f ile from the lib directory of the Pr oGuard installation to the bin directory of your J2ME W ireless T oolkit installation. Once ProGuar d is installed, you can use it by choosing Project > Package > Create Obfuscated Package . In some cases you will nee[...]

Chapter 2 Dev eloping MIDlet Suites 17 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. Y ou will need to supply your own debugger . Y ou can use the jdb debugger from J2SE™ or another debugge[...]

18 J2ME Wireless Toolkit User’s Guide • October 2004 The details of how to configur e a W eb server depend on the specific softwar e used. The emulator implements the device behavior during OT A pr ovisioning. Y ou can use the emulator to test and demonstrate the full provisioning process of MIDlet suites from a server to the device. All you ne[...]

19 CHAPTER 3 W orking W ith Pr ojects In the last chapter , you learned how the J2ME W ireless T oolkit helps you with the MIDP development cycle. This chapter delves more deeply into the details of working with projects, including the following: ■ Selecting the target APIs for a project ■ Manipulating MIDlet suite attributes, including the lis[...]

20 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 13 The project settings window On the API Selection tab, the T arget 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 JT[...]

Chapter 3 Working With Projects 21 3.2 Changing MIDlet Suite Attributes The project settings window also allows you to control the MIDlet suite attributes, which are stor ed in the descriptor as well as the manifest file of the MIDlet suite JAR. T o see the attributes, run KT oolbar and open a project. Then click on Settings... . The three tabs tha[...]

22 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 14 Editing MIDlet suite attributes T o cr eate new user-def ined attributes, click on the User Def ined tab. Pr ess Add and fill in the key name. Y ou can then edit the attribute value by clicking in the value column next to the key , just as you would with required or optional attribu[...]

Chapter 3 Working With Projects 23 3.3 Manipulating MIDlets The project settings also pr ovide a way to add or modify the MIDlets that are contained in the current MIDlet suite pr oject. T o see how this works, start KT oolbar and open an existing project. Click on Settings... and choose the MIDlets tab. Y ou will see a list of all MIDlets in the p[...]

24 J2ME Wireless Toolkit User’s Guide • October 2004 The MIDlet names are pr esented to the user in the order shown when the MIDlet suite is launched. Y ou can modify the order by selecting a MIDlet and clicking Move Up or Move Down . 3.4 Using the Push Registry Y ou can also use pr oject settings to work with a MIDlet suite’s push registry s[...]

Chapter 3 Working With Projects 25 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 Pr oject Dir ectory Structur e Projects have a standar d directory structur e. The project itself is repr esented by a directory in {t[...]

26 J2ME Wireless Toolkit User’s Guide • October 2004 When you use a third-party library in your application, your JAR will expand by the size of the third-party library . Y ou 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 obfuscat[...]

Chapter 3 Working With Projects 27 3.7.1 Setting the Application Dir ectory By default, the J2ME W ir eless T oolkit stores applications in directories under {toolkit} apps . Y ou can change this by adding a line to ktools.properties of the following form: kvem.apps.dir: <application_directory> Any backslash ('') characters in the[...]

28 J2ME Wireless Toolkit User’s Guide • October 2004[...]

29 CHAPTER 4 Using the Emulator The J2ME W ir eless T oolkit 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 repr esent a specific device, b[...]

30 J2ME Wireless Toolkit User’s Guide • October 2004 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 figur es are based on the DefaultColorPhone skin, all the skins operate in a similar way .[...]

Chapter 4 Using the Emulator 31 FIGURE 17 The DefaultColorPhone emulator skin[...]

32 J2ME Wireless Toolkit User’s Guide • October 2004 Y ou can use the mouse to click on the buttons to press them. Most buttons also have keyboard shortcuts, which are generally easier to use. Keyboar d numbers 0 through 9 corr espond to the emulator ’s 0 through 9 buttons. Some less obvious keyboard shortcuts are in the following table. Ente[...]

Chapter 4 Using the Emulator 33 4.3.2 Heap Size The heap is memory where your application’s objects are stor ed. Many real devices have limited heap size. Y ou can set a maximum heap size to more closely simulate the conditions on a real device. Choose Edit > Preferences... from the KT oolbar menu and selecting the Storage tab. Fill in the max[...]

34 J2ME Wireless Toolkit User’s Guide • October 2004 The toolkit enables you to choose a differ ent 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. T o adjust the persistent storage settings, choose[...]

Chapter 4 Using the Emulator 35 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. T o change the screen characteristics, choose one of the [...]

36 J2ME Wireless Toolkit User’s Guide • October 2004 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. T o r esume the MIDlet’s operation, choose MIDlet > Resume from the menu. 4.5 Running the Emulator Solo During[...]

Chapter 4 Using the Emulator 37 is usually to unpack or install the third party emulator , then copy its dir ectory into the <toolkit>/wtklib/devices directory . Next time you run KT oolbar , the emulator is available. A partial listing of some of the currently available emulators is available here: http://developers.sun.com/techtopics/mobili[...]

38 J2ME Wireless Toolkit User’s Guide • October 2004[...]

39 CHAPTER 5 Monitoring Applications The J2ME W ireless T oolkit provides several tools to monitor the behavior of your applications. These tools are helpful in debugging and optimizing your code. ■ The prof iler lists the frequency of use and execution time for every method in your application. ■ The memory monitor shows the usage of memory wh[...]

40 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 20 T urning on the prof iler 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 prof iler pops up with information about all the method calls in your application. FIGURE 21 T[...]

Chapter 5 Monitoring Applications 41 ■ The right side of the prof iler shows the execution time and number of calls for each method and its descendants. Note – The prof iling values obtained from the emulator do not ref lect actual values on a real device. 5.1.1 The Call Graph The call graph shows a hierarchy of method calls. Methods that call [...]

42 J2ME Wireless Toolkit User’s Guide • October 2004 5.1.3 Saving and Loading Pr ofiler Information T o save your pr ofiler session, click on the Save button in the prof iler window . Choose a file name. T o load a pr ofiler session, choose File > Utilities... from the KT oolbar menu. Click on Open Session in the Prof iler box. When you sele[...]

Chapter 5 Monitoring Applications 43 ■ 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. ■ To t a l . The total amount of memory available at s[...]

44 J2ME Wireless Toolkit User’s Guide • October 2004 ■ Name . The class name of the objects. ■ Live . The number of instances. Some of these might be eligible for garbage collection. ■ T otal . The total number of objects that have been allocated since the application began. ■ T otal Size . The total amount of memory used by the objects[...]

Chapter 5 Monitoring Applications 45 FIGURE 24 The network monitor When your application makes any type of network connection, information about the connection is captured and displayed. The figur e 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 o[...]

46 J2ME Wireless Toolkit User’s Guide • October 2004 Press the Filter Settings button to use the f ilter . Change the filter settings to suit your needs. When you are done entering f ilter settings, press OK to return to the network monitor . The Filter checkbox is checked, indicating that a filter is in use. T o disable the filter and see all [...]

Chapter 5 Monitoring Applications 47 T o load a network monitor session, choose File > Utilities... from the KT oolbar 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 T r ee T o r emove all messages from the network mon[...]

48 J2ME Wireless Toolkit User’s Guide • October 2004[...]

49 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 specif ication also includes a recommended practice for using public key cryptography to verify and authenticate MIDl[...]

50 J2ME Wireless Toolkit User’s Guide • October 2004 In the J2ME W ir eless T oolkit, you can add these permission attributes to a project by clicking on the Settings... button in KT oolbar . Select the Permissions tab. The MIDlet-Permissions box shows permissions which the MIDlet must possess, while the MIDlet-Permissions-Opt box contains perm[...]

Chapter 6 Security and MIDlet Signing 51 ■ 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 [...]

52 J2ME Wireless Toolkit User’s Guide • October 2004 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 Cr eating a New Key Pair T o cr eate an entir[...]

Chapter 6 Security and MIDlet Signing 53 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 certf icate using the ke[...]

54 J2ME Wireless Toolkit User’s Guide • October 2004 The procedur e for signing MIDlet suites with real keys works like this: 1. Generate a new key pair . In the J2ME W ireless T oolkit you can do this by pressing New Key Pair ... in the MIDlet signing window , as described above. 2. Generate a Certificate Signing Request (CSR). Pr ess Generate[...]

Chapter 6 Security and MIDlet Signing 55 Real devices have similar lists of r oot 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 r oot certificate is pr esent on the device. Otherwise, the device[...]

56 J2ME Wireless Toolkit User’s Guide • October 2004 6.5.2 Removing Certif icates T o r emove a certificate from the list, select the certif icate and choose Action > Delete Selection .[...]

57 CHAPTER 7 Using the W ir eless Messaging API The J2ME W ireless T oolkit supports the W ir eless 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 Br oadcast Service (CBS) messages. WMA 2.0 (JSR 205) includes support for MMS messages as well.[...]

58 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 29 Setting WMA prefer ences 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 f ield is blank, then the First [...]

Chapter 7 Using the Wireless Messaging API 59 7.3 Sending Messages W ith the WMA Console The WMA console is a handy utility that allows you to send and receive messages. Y ou can, for example, use the WMA console to send SMS messages to a MIDlet running on the emulator . T o launch the WMA console, choose File > Utilities... from the KT oolbar m[...]

60 J2ME Wireless Toolkit User’s Guide • October 2004 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. T ype your message and click Send . 7.3.2 Sending a Binary SMS Message[...]

Chapter 7 Using the Wireless Messaging API 61 FIGURE 32 Sending a binary message Selecting recipients is the same as for sending text SMS messages. Y ou can type in the path of a file dir ectly , or click on Browse... to open up a file chooser . 7.3.3 Sending T ext or Binary CBS Messages Sending CBS messages is similar to sending SMS messages excep[...]

62 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 33 Sending CBS messages 7.3.4 Sending MMS Messages MMS messages consist of one or more files, usually images or sounds. MMS message can be sent to multiple r ecipients. T o send an MMS message fr om the WMA console, click on the Send MMS... button. The window for composing MMS messages[...]

Chapter 7 Using the Wireless Messaging API 63 FIGURE 34 Adding recipients for an MMS message T o add media f iles to the message, click on the Parts tab. Click on Add to add a part to the message. T o remove a part, select it and pr ess Remove . FIGURE 35 Adding parts to an MMS message[...]

64 J2ME Wireless Toolkit User’s Guide • October 2004 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 . Y ou can send messages to the WMA console from your applications running on the emulator . Received messages[...]

65 CHAPTER 8 Using the Mobile Media API The Mobile Media API (MMAPI) provides a standard API for r endering and capturing time-based media, like audio or video. The API was designed to be flexible with r espect to the media formats, protocols, and features supported by various devices. 8.1 Supported Formats and Pr otocols The emulator ’s MMAPI im[...]

66 J2ME Wireless Toolkit User’s Guide • October 2004 8.2 Using MediaContr olSkin The J2ME W ireless T oolkit comes with an emulator skin, MediaControlSkin ,t h a t is focused on multimedia playback and control. The skin includes buttons with symbols repr esenting play , stop, volume up and volume down, and other commands. T o see the usefulness[...]

67 CHAPTER 9 W orking W ith 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 def ines the Mobile 3D Graphics (M3G) API for J2ME. This API provides 3D functionality in a compact package that’s appr opriate for CLDC/MIDP devices. The API provides two [...]

68 J2ME Wireless Toolkit User’s Guide • October 2004 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. [...]

Chapter 9 Working With Mobile 3D Graphics 69 9.5 Cr eating Mobile 3D Graphics Content Most mobile 3D applications will use scene graphs in resource f iles to describe objects, scenes, and characters. Usually it is not pr ogrammers but graphic designers or artists who create the scene graphs, using standard 3D modeling tools. Several vendors offer t[...]

70 J2ME Wireless Toolkit User’s Guide • October 2004[...]

71 CHAPTER 10 Using the PIM and FileConnection APIs The J2ME W ireless T oolkit 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 A[...]

72 J2ME Wireless Toolkit User’s Guide • October 2004 Each subdirectory of filesystem is called a roo t . The J2ME W ireless T oolkit provides a mechanism for managing roots. While the emualtor is r unning, choose MIDlet > External events from the emulator window’s menu. Y ou’ll see a utility window for adding and removing r oots. FIGURE [...]

73 CHAPTER 11 Using the Bluetooth and OBEX APIs The J2ME W ireless T oolkit emulator supports JSR 82, the Java APIs for Bluetooth. JSR 82 includes two independent APIs: ■ The Bluetooth API provides an interface to Bluetooth wir eless networking, including device discovery and data exchange. ■ The OBEX API allows applications to use the Object E[...]

74 J2ME Wireless Toolkit User’s Guide • October 2004 1 1.3 Setting OBEX and Bluetooth Pr efer ences The J2ME W ir eless T oolkit allows you to configur e the Bluetooth and OBEX simulation environment. Choose Edit > Preferences... from the KT oolbar menu to see the following window . FIGURE 38 Bluetooth and OBEX prefer ences 1 1.3.1 OBEX Pr e[...]

Chapter 11 Using the Bluetooth and OBEX APIs 75 1 1.3.2 Bluetooth Discovery T imeout 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. 1 1.3.3 Bluetooth System Pr operties Th[...]

76 J2ME Wireless Toolkit User’s Guide • October 2004[...]

77 CHAPTER 12 Using W eb Services The J2ME W ireless T oolkit emulator supports JSR 172, the J2ME W eb Services Specification. JSR 172 pr ovides APIs for accessing web services from J2ME applications. It also includes an API for parsing XML documents. The J2ME W ireless T oolkit provides a stub generator that automates cr eating source code for acc[...]

78 J2ME Wireless Toolkit User’s Guide • October 2004[...]

79 APPENDIX A Application Demonstrations This appendix describes the application demonstrations that are bundled with the J2ME W ireless T oolkit. A.1 Overview The J2ME W ireless T oolkit includes demonstration applications that highlight some of the technologies and APIs that are supported by the emulator . The following table lists all the demons[...]

80 J2ME Wireless Toolkit User’s Guide • October 2004 WTK22 , the source code for the SMS sender MIDlet ( example.sms.SMSSend )i n WMADemo is contained in WTK22appsWMADemosrcexamplesmsSMSSend.java . T ABLE 8 Application demonstrations Demonstration APIs Description Special Instructions Audiodemo MMAPI 1.1 Demonstrates audio capabilities,[...]

Appendix A Application Demonstrations 81 A.2 General Instructions It's usually very simple to run one of the demonstration applications. This section describes the general procedure. Mor e detailed instructions for specific demonstrations are r eferenced in the table above. The first step is to run KT oolbar . T o do this, go to the W indows S[...]

82 J2ME Wireless Toolkit User’s Guide • October 2004 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 [...]

Appendix A Application Demonstrations 83 FIGURE 42 Running the Bluetooth Demo server On the second emulator , choose Bluetooth Demo , then Client . The MIDlet tells you it’s ready to sear ch for images. Choose Find . The MIDlet will find the other emulator and get a list of images from it. Select one fr om the list and choose Load . The emulator [...]

84 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 43 An image transferred via simulated Bluetooth Y ou can avoid the permission prompts by r unning the demonstration in the trusted protection domain. A.4 Demo3D This application contains three MIDlets that show of f the emulator's support of JSR 184, the Mobile 3D Graphics API. A.[...]

Appendix A Application Demonstrations 85 FIGURE 44 The Game of Life in three dimensions The keypad buttons provide control over the game. This source code for this example is particularly well-documented. T ake a look at {toolkit} appsDemo3Dsrccomsuperscapem3gwtksampleslife3dLif e3D.java . A.4.2 PogoRoo PogoRoo shows you the rear end of a [...]

86 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 45 A bouncing kangaroo Y ou can get the kangar oo 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. Y ou might need to hold down the keys to see an effect. A.4.3 r etainedmode The retainedmode MID[...]

Appendix A Application Demonstrations 87 FIGURE 46 A tireless skateboar der A.5 JSR172Demo JSR172Demo shows how to access a web service from a MIDlet. The web service is already running on an Internet server . Y ou should be able to simply build and run the example. If you are behind a f irewall, you’ll need to configur e the emulator ’s proxy [...]

88 J2ME Wireless Toolkit User’s Guide • October 2004 A.6.1 Simple T ones The Simple T ones example demonstrates how to use interactive synthetic tones. The first menu entries play tones with dif ferent pitch and duration using Manager.playTone() . Choosing the third menu item will play a chord on the interactive MIDI device (locator "devic[...]

Appendix A Application Demonstrations 89 ■ 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 fr om arbitrary HTTP servers. T ype a valid URL at the insertion point and click OK to play a file. If you want to open an HTTP director[...]

90 J2ME Wireless Toolkit User’s Guide • October 2004 The commands may or may not be available depending on the media type that Simple Player is playing. In addition, some commands can be invoked using the keypad buttons. The following table describes the availability of commands, their keypad equivalents, and the relevant class fr om MMAPI. Not[...]

Appendix A Application Demonstrations 91 Animated GIFs and video capture can be implemented using either a Form Item or a Canvas . The V ideo demonstration includes all the possibilities: ■ 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. Choos[...]

92 J2ME Wireless Toolkit User’s Guide • October 2004 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 ,t h e n Receive Image . The emulator will ask for permission to listen. Choose Ye s . The emulator will display a screen that indicate[...]

Appendix A Application Demonstrations 93 FIGURE 48 Prompting to accept a connection Choose Ye s . The image you selected is transferred over the simulated infrared link and displayed on the first emulator . FIGURE 49 A successfully transferred image[...]

94 J2ME Wireless Toolkit User’s Guide • October 2004 A.8 PDAPDemo PDAPDemo shows how to use the PIM and FileConnection APIs that are part of the JSR 75 specification. A.8.1 Br owsing Files T o run the f ile browser , you’ll need to give the MIDlet appopriate security authorization. The easiest way to do this is to choose Edit > Preferences[...]

Appendix A Application Demonstrations 95 FIGURE 51 Contents of the root1 directory Using the commands in the demonstration, you can view the file or see its properties. T ry selecting the file and choosing Properties or Vi e w from the menu. FIGURE 52 V iewing f ile properties and contents[...]

96 J2ME Wireless Toolkit User’s Guide • October 2004 The actual files ar e located in {toolkit} appdbDefaultColorPhonefilesystem , assuming you are using the DefaultColorPhone emulator skin. Y ou can add files and r oot 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[...]

Appendix A Application Demonstrations 97 FIGURE 54 An empty contact list T o add an item, choose New from the menu. The application pr ompts you for a Formatted Name for the item. Y ou can add more data f ields to this item using Add Field in the menu. Y ou'll see a list of f ield names. Pick one, then enter the value for the new field. FIGURE[...]

98 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 56 Saving an item Y ou can r eturn to the list by choosing the Back command. Y ou'll see the item you just created in the list. The items that you create are stor ed in standard vCar d or vCalendar format in the {toolkit} appdb {skin} pim directory . See Chapter 10 for more inf[...]

Appendix A Application Demonstrations 99 T o see the magic of the push r egistry , use the WMA console to send the emulator a message. Launch the console by choosing File > Utilities... from the KT oolbar 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 . C[...]

100 J2ME Wireless Toolkit User’s Guide • October 2004 FIGURE 58 The push registry springs to life Choose Y es. The SMSReceive MIDlet is launched and immediately displays the incoming SMS message. FIGURE 59 An incoming text message Y ou can also use the WMA console to send and receive CBS and MMS messages. See Chapter 7, “Using the W ireless M[...]

Appendix A Application Demonstrations 101 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 [...]

102 J2ME Wireless Toolkit User’s Guide • October 2004 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 Ye s . The image and its information are displayed. FIGURE 62 WMADemo receives the image[...]

103 APPENDIX B Command Line Refer ence This appendix describes how to operate the J2ME W ir eless T oolkit from the command line and details the steps requir ed to build and run an application. It also describes the J2ME W i r eless T oolkit certif icate manager utility , called MEKeyT ool, and the MIDlet signing utility , called JAD T ool (Java Ap[...]

104 J2ME Wireless Toolkit User’s Guide • October 2004 B.2.1 Build Using KT oolbar , building a project is a single step. Behind the scenes, however , there ar e actually two steps. First, Java source files ar e compiled into Java class files. Next, the class f iles are pr everified , which means they ar e prepared for the CLDC KVM. Use the java[...]

Appendix B Command Line Reference 105 As a result of this command, preverif ied class files ar e placed in the classes directory . If your application uses WMA, MMAPI, or other versions of CLDC or MIDP , be sure to include the r elevant .jar files in the classpath. B.2.2 Package T o package a MIDlet suite, you must create a manifest f ile, an appli[...]

106 J2ME Wireless Toolkit User’s Guide • October 2004 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 Y ou can run the emulator fr om the command line. The J2ME W ireless T oolkit’s bin directory conta[...]

Appendix B Command Line Reference 107 remove=[< storage_name >|< storage_number > | 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=< jad_file_url > Install, run, and remove the a[...]

108 J2ME Wireless Toolkit User’s Guide • October 2004 B.3 Launching T oolkit GUI Components The components of the J2ME W ireless T oolkit can all be launched from the command line. Each component is in the toolkit’s bin directory . B.4 Setting Emulator Pr efer ences Y ou can change the emulator prefer ences from the command line by using the [...]

Appendix B Command Line Reference 109 kvem.memory.monitor.enable Monitor > Enable memory monitor V alue: true | false kvem.netmon.comm.enable Monitor > Enable Comm monitoring V alue: true | false kvem.netmon.datagram.enable Monitor > Enable Datagram monitoring V alue: true | false kvem.netmon.http.enable Monitor > Enable HTTP monitoring[...]

110 J2ME Wireless Toolkit User’s Guide • October 2004 B.5 Using Security Featur es The full spectrum of the J2ME W ir eless T oolkit’s security features ar e also available from the command line. Y ou can adjust the emulator ’s default protection domain, sign MIDlet suites, and manage certificates. B.5.1 Changing the Emulator ’s Default P[...]

Appendix B Command Line Reference 111 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 signatur e of the JAR file to a JAD file. JadTool only uses cer[...]

112 J2ME Wireless Toolkit User’s Guide • October 2004 B.5.3 Managing Certif icates 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 mus[...]

Appendix B Command Line Reference 113 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 conf iguration file, which specif ies either a WSDL file, a model file, or a compiled service [...]

114 J2ME Wireless Toolkit User’s Guide • October 2004 Note – Exactly one -gen option must be specified. The -f option r equires a comma-separated list of features. T ABLE 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 [...]

115 APPENDIX C Internationalization This appendix describes setting the language displayed in the J2ME W ireless T oolkit 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 re[...]

116 J2ME Wireless Toolkit User’s Guide • October 2004 C.2 Emulated Locale The microedition.locale property is the MIDP system pr operty that defines the current locale of the device, which is null by default. For the J2ME W ireless T oolkit emulator , this value is automatically set to the default locale for the J2SE environment you ar e runnin[...]

Appendix C Internationalization 117 Note – All the J2SE encoders are available in the emulated environment. See the J2ME Wir eless T oolkit 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[...]

118 J2ME Wireless Toolkit User’s Guide • October 2004[...]

119 Index A advanced configuration options, 26 application descriptor, 1 1 Application Management Software (AMS), 12 applications running remotely, 17 applications directory , setting, 2 7 attributes, 21 B building source code, 8 C call graph, 41 CBS message, sending, 6 1 certificate importing, 5 5 certificate management, 54 certificate manager[...]

120 J2ME Wireless T oolkit User’s Guide • October 2004 IrDA, 73 J JAD, 1 1 attributes, 21 creating, 1 1 MIME type, 1 7 JAR creating, 1 1 MIME type, 1 7 Java Cryptography Extension (JCE) keystore, 1 12 JSR 184, 67 JSR 75, 71 K key management, 5 2 key pair creating, 52 importing, 54 keytool utility, 1 12 KT oolbar advanced configuration options,[...]

Index 121 push registry, 24 R remotely-deployed applications, 17 revision contr ol, 2 7 revision contr ol files, 2 7 Revision Control System (RCS), 27 RevisionControl property, 27 run options, 106 Run via OT A, 1 2, 51 running from command line, 106 S signed MIDlet suites, 4 9 signing MIDlet suites, 5 1 SMS binary message, sending, 6 0 SMS text me[...]

122 J2ME Wireless T oolkit User’s Guide • October 2004[...]