Sun Microsystems J2ME User Manual

Sun Microsystems, Inc.4150 Network CircleSanta Clara, California 95054U.S.A.1-800-555-9SUN or 1-650-960-1300User’s GuideJ2ME Wireless Toolkit2.2Octobe

x J2ME Wireless Toolkit User’s Guide • October 2004http://developers.sun.com/techtopics/mobility/How This Book Is OrganizedThis guide contains the fol

88 J2ME Wireless Toolkit User’s Guide • October 2004A.6.1 Simple TonesThe Simple Tones example demonstrates how to use interactive synthetic tones.The

Appendix A Application Demonstrations 89 Video Capture Simulation simulates viewing input video such as might bepossible on a device equipped with a

90 J2ME Wireless Toolkit User’s Guide • October 2004The commands may or may not be available depending on the media type thatSimple Player is playing.

Appendix A Application Demonstrations 91Animated GIFs and video capture can be implemented using either a Form Item ora Canvas. The Video demonstratio

92 J2ME Wireless Toolkit User’s Guide • October 2004Run two instances of the emulator. One listens for incoming connections, while theother attempts t

Appendix A Application Demonstrations 93FIGURE 48 Prompting to accept a connectionChoose Yes. The image you selected is transferred over the simulated

94 J2ME Wireless Toolkit User’s Guide • October 2004A.8 PDAPDemoPDAPDemo shows how to use the PIM and FileConnection APIs that are part ofthe JSR 75 s

Appendix A Application Demonstrations 95FIGURE 51 Contents of the root1 directoryUsing the commands in the demonstration, you can view the file or see

96 J2ME Wireless Toolkit User’s Guide • October 2004The actual files are located in{toolkit}\appdb\DefaultColorPhone\filesystem, assuming you are usin

Appendix A Application Demonstrations 97FIGURE 54 An empty contact listTo add an item, choose New from the menu. The application prompts you for aForm

Preface xiChapter 7 details support for running and testing wireless messagingapplications.Chapter 8 explains how the J2ME Wireless Toolkit supports t

98 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 56 Saving an itemYou can return to the list by choosing the Back command. You'll see t

Appendix A Application Demonstrations 99To see the magic of the push registry, use the WMA console to send the emulator amessage. Launch the console b

100 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 58 The push registry springs to lifeChoose Yes. The SMSReceive MIDlet is launched and imme

Appendix A Application Demonstrations 101If you are attempting to send text messages to WMADemo using the WMA console,make sure to specify the port nu

102 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 61 Adding parts to an MMS messageClick on Send to send the message.The emulator asks if it

103APPENDIXBCommand Line ReferenceThis appendix describes how to operate the J2ME Wireless Toolkit from thecommand line and details the steps required

104 J2ME Wireless Toolkit User’s Guide • October 2004B.2.1 BuildUsing KToolbar, building a project is a single step. Behind the scenes, however,there

Appendix B Command Line Reference 105As a result of this command, preverified class files are placed in the classesdirectory. If your application uses

106 J2ME Wireless Toolkit User’s Guide • October 2004For example, a JAD file might have the following contents:MIDlet-Name: MyMIDletMIDlet-Vendor: My

Appendix B Command Line Reference 107remove=[<storage_name>|<storage_number> | all]Remove a previously installed application. The applicat

xii J2ME Wireless Toolkit User’s Guide • October 2004Typographic ConventionsAccessing Documentation OnlineThe following sites provide technical docume

108 J2ME Wireless Toolkit User’s Guide • October 2004B.3 Launching Toolkit GUI ComponentsThe components of the J2ME Wireless Toolkit can all be launch

Appendix B Command Line Reference 109kvem.memory.monitor.enable Monitor > Enable memory monitorValue: true | falsekvem.netmon.comm.enable Monitor &

110 J2ME Wireless Toolkit User’s Guide • October 2004B.5 Using Security FeaturesThe full spectrum of the J2ME Wireless Toolkit’s security features are

Appendix B Command Line Reference 111B.5.2 Signing MIDlet SuitesJadTool is a command-line interface for signing MIDlet suites using public keycryptogr

112 J2ME Wireless Toolkit User’s Guide • October 2004B.5.3 Managing CertificatesMEKeyTool manages the public keys of certificate authorities (CAs), ma

Appendix B Command Line Reference 113B.6 Using the Stub GeneratorJ2ME Clients can use the Stub Generator to access web services. The wscompiletool gen

114 J2ME Wireless Toolkit User’s Guide • October 2004Note – Exactly one -gen option must be specified. The -f option requires acomma-separated list of

115APPENDIXCInternationalizationThis appendix describes setting the language displayed in the J2ME WirelessToolkit and the localization setting of the

116 J2ME Wireless Toolkit User’s Guide • October 2004C.2 Emulated LocaleThe microedition.locale property is the MIDP system property that definesthe c

Appendix C Internationalization 117Note – All the J2SE encoders are available in the emulated environment. See theJ2ME Wireless Toolkit Basic Customiz

1CHAPTER1IntroductionThis book describes how to use the J2ME Wireless Toolkit.The J2ME Wireless Toolkit is a set of tools that makes it possible to cr

118 J2ME Wireless Toolkit User’s Guide • October 2004

119IndexAadvanced configuration options, 26application descriptor, 11Application Management Software (AMS), 12applicationsrunning remotely, 17applicati

120 J2ME Wireless Toolkit User’s Guide • October 2004IrDA, 73JJAD, 11attributes, 21creating, 11MIME type, 17JARcreating, 11MIME type, 17Java Cryptogra

Index 121push registry, 24Rremotely-deployed applications, 17revision control, 27revision control files, 27Revision Control System (RCS), 27RevisionCon

122 J2ME Wireless Toolkit User’s Guide • October 2004

2 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 1 The KToolbar windowNext, click on the Open Project... button to open a demonstration appli

Chapter 1 Introduction 3KToolbar is the center of the toolkit. You can use it to build applications, launch theemulator, and start the utilities. Alte

4 J2ME Wireless Toolkit User’s Guide • October 2004JSR 135MMAPI 1.1Mobile Media APIhttp://jcp.org/en/jsr/detail?id=135JSR 75PIM and FilePDA Optional P

5CHAPTER2Developing MIDlet SuitesThis chapter describes how you can use the J2ME Wireless Toolkit to createapplications. It begins with a description

6 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 2 The KToolbar windowClick on New Project... The toolkit will ask you for the name of the pr

Chapter 2 Developing MIDlet Suites 7FIGURE 4 File locations in the console2.2 The Simple Development CycleThe simple development cycle looks like this

PleaseRecycleCopyright © 2004 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.U.S. Government R

8 J2ME Wireless Toolkit User’s Guide • October 2004If you are following along with the example project, create a new Java source fileTinyMIDlet.java.

Chapter 2 Developing MIDlet Suites 9FIGURE 5 Messages about buildingBehind the scenes, the J2ME Wireless Toolkit also preverifies the compiled classfi

10 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 6 List of project MIDletsChoose the MIDlet you want and select Launch. If you’re following

Chapter 2 Developing MIDlet Suites 112.3 The Full Development CycleThe second development cycle is slightly more complicated:Edit source code → Packag

12 J2ME Wireless Toolkit User’s Guide • October 20042.3.2 InstallTo properly test a MIDlet suite, you should install it into the toolkit’s emulator or

Chapter 2 Developing MIDlet Suites 13FIGURE 9 URL promptChoose Go from the menu to begin the installation. The emulator shows a list ofthe application

14 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 11 The application menu, againRun via OTA is an extremely useful mechanism that makes it ea

Chapter 2 Developing MIDlet Suites 15FIGURE 12 Launching the installed applicationRunning an application on a real device depends heavily on the devic

16 J2ME Wireless Toolkit User’s Guide • October 20043. Uncompress the proguard.jar file from the lib directory of the ProGuardinstallation to the bin

Chapter 2 Developing MIDlet Suites 172.5 Using a DebuggerA variation on running your application is running it with a debugger. A debuggerallows you t

Contents iiiContentsPreface ix1. Introduction 11.1 Quick Start 11.2 The Tools in the Toolkit 21.3 Toolkit Features 31.4 Supported Technology 32. Devel

18 J2ME Wireless Toolkit User’s Guide • October 2004The details of how to configure a Web server depend on the specific software used.The emulator imp

19CHAPTER3Working With ProjectsIn the last chapter, you learned how the J2ME Wireless Toolkit helps you with theMIDP development cycle. This chapter d

20 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 13 The project settings windowOn the API Selection tab, the Target Platform setting control

Chapter 3 Working With Projects 213.2 Changing MIDlet Suite AttributesThe project settings window also allows you to control the MIDlet suite attribut

22 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 14 Editing MIDlet suite attributesTo create new user-defined attributes, click on the User

Chapter 3 Working With Projects 233.3 Manipulating MIDletsThe project settings also provide a way to add or modify the MIDlets that arecontained in th

24 J2ME Wireless Toolkit User’s Guide • October 2004The MIDlet names are presented to the user in the order shown when the MIDletsuite is launched. Yo

Chapter 3 Working With Projects 25If you do make push registry entries for your application, make sure you also enterthe appropriate permissions. See

26 J2ME Wireless Toolkit User’s Guide • October 2004When you use a third-party library in your application, your JAR will expand bythe size of the thi

Chapter 3 Working With Projects 273.7.1 Setting the Application DirectoryBy default, the J2ME Wireless Toolkit stores applications in directories unde

iv J2ME Wireless Toolkit User’s Guide • October 20043.1 Selecting APIs 193.2 Changing MIDlet Suite Attributes 213.3 Manipulating MIDlets 233.4 Using t

28 J2ME Wireless Toolkit User’s Guide • October 2004

29CHAPTER4Using the EmulatorThe J2ME Wireless Toolkit emulator simulates a MIDP device on your desktopcomputer. It is a convenient way to see how your

30 J2ME Wireless Toolkit User’s Guide • October 20044.2 Using the EmulatorThe emulator looks and acts like a mobile phone. In this section you’ll lear

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

32 J2ME Wireless Toolkit User’s Guide • October 2004You can use the mouse to click on the buttons to press them. Most buttons alsohave keyboard shortc

Chapter 4 Using the Emulator 334.3.2 Heap SizeThe heap is memory where your application’s objects are stored. Many real deviceshave limited heap size.

34 J2ME Wireless Toolkit User’s Guide • October 2004The toolkit enables you to choose a different location for the storage files, and youcan limit the

Chapter 4 Using the Emulator 35FIGURE 19 Adjusting the emulator’s performanceAdjust the Graphics primitives latency to have an effect on the amount of

36 J2ME Wireless Toolkit User’s Guide • October 2004When the emulator is running, choose MIDlet > Pause from the emulatorwindow’s menu. The running

Chapter 4 Using the Emulator 37is usually to unpack or install the third party emulator, then copy its directory intothe <toolkit>/wtklib/device

Contents v5.3.1 Filtering Messages 455.3.2 Sorting Messages 465.3.3 Saving and Loading Network Monitor Information 465.3.4 Clearing the Message Tree 4

38 J2ME Wireless Toolkit User’s Guide • October 2004

39CHAPTER5Monitoring ApplicationsThe J2ME Wireless Toolkit provides several tools to monitor the behavior of yourapplications. These tools are helpful

40 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 20 Turning on the profilerNow run your application by clicking on the Run button. Interact

Chapter 5 Monitoring Applications 41 The right side of the profiler shows the execution time and number of calls foreach method and its descendants.N

42 J2ME Wireless Toolkit User’s Guide • October 20045.1.3 Saving and Loading Profiler InformationTo save your profiler session, click on the Save butt

Chapter 5 Monitoring Applications 43 Maximum. The maximum amount of memory used since program executionbegan, shown in the graph by a broken red line

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 elig

Chapter 5 Monitoring Applications 45FIGURE 24 The network monitorWhen your application makes any type of network connection, information aboutthe conn

46 J2ME Wireless Toolkit User’s Guide • October 2004Press the Filter Settings button to use the filter. Change the filter settings to suityour needs.W

Chapter 5 Monitoring Applications 47To load a network monitor session, choose File > Utilities... from the KToolbarmenu. Click on Open Session in t

vi J2ME Wireless Toolkit User’s Guide • October 20048.4 Well-Behaved MIDlets 669. Working With Mobile 3D Graphics 679.1 JSR 184 Overview 679.2 Immedia

48 J2ME Wireless Toolkit User’s Guide • October 2004

49CHAPTER6Security and MIDlet SigningMIDP 2.0 includes a comprehensive security model based on protection domains.MIDlet suites are installed into a p

50 J2ME Wireless Toolkit User’s Guide • October 2004In the J2ME Wireless Toolkit, you can add these permission attributes to a projectby clicking on t

Chapter 6 Security and MIDlet Signing 51 MIDlets in the minimum domain are denied all permissions. The untrusted domain provides a high level of sec

52 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 26 The MIDlet suite signing windowSigning is very easy. Just select the key you want to use

Chapter 6 Security and MIDlet Signing 53FIGURE 27 Creating a new key pairAfter you click on Create, the toolkit prompts you to choose a protection dom

54 J2ME Wireless Toolkit User’s Guide • October 2004The procedure for signing MIDlet suites with real keys works like this:1. Generate a new key pair.

Chapter 6 Security and MIDlet Signing 55Real devices have similar lists of root certificates, although they cannot usually bemodified by the user. Whe

56 J2ME Wireless Toolkit User’s Guide • October 20046.5.2 Removing CertificatesTo remove a certificate from the list, select the certificate and choos

57CHAPTER7Using the Wireless Messaging APIThe J2ME Wireless Toolkit supports the Wireless Messaging API (WMA) with asophisticated simulation environme

Contents viiA.6.1 Simple Tones 87A.6.2 Simple Player 87A.6.3 PausingAudioTest 89A.6.4 Video 89A.6.5 Attributes for mmademo 90A.7 ObexDemo 90A.8 PDAPDe

58 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 29 Setting WMA preferencesThe Phone Number of Next Emulator field is just what it sounds li

Chapter 7 Using the Wireless Messaging API 597.3 Sending Messages With the WMAConsoleThe WMA console is a handy utility that allows you to send and re

60 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 31 Sending a text messageThe window automatically lists the phone numbers of all running em

Chapter 7 Using the Wireless Messaging API 61FIGURE 32 Sending a binary messageSelecting recipients is the same as for sending text SMS messages. You

62 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 33 Sending CBS messages7.3.4 Sending MMS MessagesMMS messages consist of one or more files,

Chapter 7 Using the Wireless Messaging API 63FIGURE 34 Adding recipients for an MMS messageTo add media files to the message, click on the Parts tab.

64 J2ME Wireless Toolkit User’s Guide • October 20047.4 Receiving Messages in the WMAConsoleThe WMA console can also receive messages. If you look at

65CHAPTER8Using the Mobile Media APIThe Mobile Media API (MMAPI) provides a standard API for rendering andcapturing time-based media, like audio or vi

66 J2ME Wireless Toolkit User’s Guide • October 20048.2 Using MediaControlSkinThe J2ME Wireless Toolkit comes with an emulator skin, MediaControlSkin,

67CHAPTER9Working With Mobile 3D GraphicsThis chapter provides a brief overview of working with 3D graphics content.9.1 JSR 184 OverviewJSR 184 is a s

viii J2ME Wireless Toolkit User’s Guide • October 2004C.4 Font Support in the Default Emulator 117Index 119

68 J2ME Wireless Toolkit User’s Guide • October 2004For an example of immediate mode, see the Life3D MIDlet in the Demo3Dexample application.9.3 Retai

Chapter 9 Working With Mobile 3D Graphics 699.5 Creating Mobile 3D Graphics ContentMost mobile 3D applications will use scene graphs in resource files

70 J2ME Wireless Toolkit User’s Guide • October 2004

71CHAPTER10Using the PIM and FileConnectionAPIsThe J2ME Wireless Toolkit supports JSR 75, the PDA Optional Packages for theJ2ME Platform. JSR 75 inclu

72 J2ME Wireless Toolkit User’s Guide • October 2004Each subdirectory of filesystem is called a root. The J2ME Wireless Toolkitprovides a mechanism fo

73CHAPTER11Using the Bluetooth and OBEXAPIsThe J2ME Wireless Toolkit emulator supports JSR 82, the Java APIs for Bluetooth.JSR 82 includes two indepen

74 J2ME Wireless Toolkit User’s Guide • October 200411.3 Setting OBEX and Bluetooth PreferencesThe J2ME Wireless Toolkit allows you to configure the B

Chapter 11 Using the Bluetooth and OBEX APIs 7511.3.2 Bluetooth Discovery TimeoutIn the Bluetooth section of the preferences window, the Device discov

76 J2ME Wireless Toolkit User’s Guide • October 2004

77CHAPTER12Using Web ServicesThe J2ME Wireless Toolkit emulator supports JSR 172, the J2ME Web ServicesSpecification. JSR 172 provides APIs for access

Preface ixPrefaceThis document describes how to work with the J2ME Wireless Toolkit.Who Should Use This BookThis guide is intended for developers crea

78 J2ME Wireless Toolkit User’s Guide • October 2004

79APPENDIXAApplication DemonstrationsThis appendix describes the application demonstrations that are bundled with theJ2ME Wireless Toolkit.A.1 Overvie

80 J2ME Wireless Toolkit User’s Guide • October 2004\WTK22, the source code for the SMS sender MIDlet (example.sms.SMSSend)inWMADemo is contained in\W

Appendix A Application Demonstrations 81A.2 General InstructionsIt's usually very simple to run one of the demonstration applications. This secti

82 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 41 Opening a demonstration application projectSelect one and click on the Open Project butt

Appendix A Application Demonstrations 83FIGURE 42 Running the Bluetooth Demo serverOn the second emulator, choose Bluetooth Demo, then Client. The MID

84 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 43 An image transferred via simulated BluetoothYou can avoid the permission prompts by runn

Appendix A Application Demonstrations 85FIGURE 44 The Game of Life in three dimensionsThe keypad buttons provide control over the game.This source cod

86 J2ME Wireless Toolkit User’s Guide • October 2004FIGURE 45 A bouncing kangarooYou can get the kangaroo to bounce around the landscape by using the

Appendix A Application Demonstrations 87FIGURE 46 A tireless skateboarderA.5 JSR172DemoJSR172Demo shows how to access a web service from a MIDlet. The