J2ME in a Nutshell 255 separated by the platform's path separator (i.e., a semicolon for the Windows platform, colon for Unix). -cp path A synonym for -classpath. -help Displays the valid command arguments and exits. -version Prints the version numbers of the J2ME Wireless Toolkit and the embedded CLDC and MIDP implementations, then exits. -Xdebug Prepares the emulator for runtime debugging. This option must be used in conjunction with -Xrunjdwp. -Xdevice:name Runs the emulation using the named device. Selecting a difference device affects the quantity of memory and the input and display capabilities available to MIDlets, and it also causes a different skin to be used for the benefit of the user. The following name values are recognized by default: DefaultColorPhone A cell phone with a color display DefaultGrayPhone A cell phone with a grayscale display MinimumPhone A basic telephone with a two-color display Motorola_i85s The Motorola i85s cell phone PalmOS_Device A PalmOS pseudo-device J2ME in a Nutshell 256 RIMJavaHandheld The Research In Motion wireless handheld -Xdescriptor:fileName Loads a MIDlet suite given the location of a JAD file and allows the user to select a MIDlet to be executed. If the optional classname argument is supplied, it is assumed to be a MIDlet in that MIDlet suite to be executed. The fileName argument may be a URL or a local filename. -Xheapsize:size Sets the size of the Java heap, overriding the implementation-dependent default value. The size parameter may be an absolute value in bytes (such as 131072) or an abbreviated value like 512k or 2M. -Xjam:command Starts the emulator and performs the operation indicated by the command argument using its application management software. The legal operations are described in the next section. -Xquery Lists the properties of all the devices that the emulator can emulate, including the device description and details of its screen and input capabilities. See Section 8.5.6 for some example output. -Xrunjdwp:options When used in conjunction with -Xdebug, this argument sets the transport type and transport address at which the VM listens for a connection from a remote debugger. The options value is specified as follows: transport=<transport>,address=<address>,server=<y/n> where transport must currently take the value dt_socket, and address has the form host:port. The server argument should always be y. -Xverbose:options Switches on verbose output of trace information according to options, which can either take the value all or be a comma-separated list of one or more of the following: allocation bytecodes class classverbose events exceptions frames gc gcverbose methods methodsverbose monitors networking stackchunks stackmaps J2ME in a Nutshell 257 threading verifier 8.5.5 Application Management Commands You can control the emulator's application management software by using the -Xjam argument, followed by a colon and one of the commands from Table 8-1. The -Xjam argument may also be used on its own to start the emulator and run the graphical interface to the AMS, as described in Section 3.6.2. Table 8-1. Wireless Toolkit Emulator AMS Control Commands Command Description f orce When used in conjuction with install, forces installation even if the MIDlet suite is already installed. install=descriptor_URL Installs the MIDlet suite whose JAD is at the given location. list Lists information regarding the installed MIDlet suites, including the suite number and storage name. The format of this data is described in Section 8.4.4.2. remove=storage_name Removes the MIDlet suite with the given storage name. remove=suite_number Removes the MIDlet suite with the given suite number. remove=all Removes all installed MIDlet suites. run=storage_name Displays a menu allowing the user to select a MIDlet from the installed suite with the given storage name, then executes the MIDlet. storageNames Lists the storage names of all installed MIDlet suites. Storage names are described in Section 8.4.4.2. transient=descriptor_URL Temporarily installs a MIDlet suite, allows the user to select and run a MIDlet, and then removes the MIDlet suite. If the suite is already installed, the installation step is skipped, but the removal is still performed. 8.5.6 Examples emulator -cp dir1;dir2;dir3 ora.ch5.AttributesMIDlet Executes the MIDlet ora.ch5.AttributesMIDlet, loading its classes from the supplied classpath. emulator -Xdebug -Xrunjdwp:transport=dt-socket,address=2000,server=y -cp dir1;dir2;dir3 ora.ch5.AttributesMIDlet Executes the MIDlet ora.ch5.AttributesMIDlet, loading its classes from the supplied classpath and preparing the VM for debugging. emulator -Xdescriptor:http://servername/path/suite.jad Loads the MIDlet suite whose JAD file is at the given URL and allows the user to select a MIDlet to be executed. emulator -Xdescriptor:http://servername/path/suite.jad ora.ch5.AttributesMIDlet Loads the MIDlet suite whose JAD file is at the given URL and runs the MIDlet from the suite whose class file is ora.ch5.AttributesMIDlet. J2ME in a Nutshell 258 emulator -Xquery Prints information for all the devices supported by the emulator. The following is typical output for a single device: # Properties for device DefaultGrayPhone DefaultGrayPhone.description: DefaultGrayPhone DefaultGrayPhone.screen.width: 96 DefaultGrayPhone.screen.height: 128 DefaultGrayPhone.screen.isColor: false DefaultGrayPhone.screen.isTouch: false DefaultGrayPhone.screen.width: 96 DefaultGrayPhone.screen.bitDepth: 8 emulator -Xjam:install=http://servername//path/suite.jad Installs a MIDlet suite over the network given the location of its JAD file. If the MIDlet suite is already installed, this command fails. emulator -Xjam:install=http://servername//path/suite.jad -Xjam:force Installs the given MIDlet suite, forcing it to overwrite any copy of the MIDlet suite that is already installed. emulator -Xjam:run=#J2#M#E%0020in%0020a%0020#Nutshell_#Chapter5_ Displays a menu listing all the MIDlets in the suite with the given storage name, and allows the user to select one to be executed. emulator -Xjam:storageNames Lists the storage names of all installed MIDlet suites. emulator -Xjam:remove=1 Removes the installed MIDlet suite with suite number 1. 8.5.7 See Also • Section 8.4 8.6 preverify: The KVM Class Preverifier 8.6.1 Availability CLDC Reference Implementation, MIDP Reference Implementation, Wireless Toolkit 8.6.2 Synopsis preverify [options] classnames | dirnames | JARnames J2ME in a Nutshell 259 8.6.3 Description The class preverifier for classes to be loaded into a CLDC-conformant virtual machine, such as the KVM. All classes must be preverified before use to ensure that they are valid and do not attempt to circumvent Java programming language rules in such a way as to cause a potential security breach. The preverify command processes a set of input class files and writes them to an output location, which must be different from the input location. The set of class files to be processed can be specified using any combination of the following: • A set of class names, in which each class is located relative to the class path given by the -classpath argument or via the CLASSPATH environment variable • A JAR file or ZIP file containing Java class files • A directory that is recursively searched for class files, JAR files, or ZIP files The output from this process is written to the directory specified by the -d argument or to a directory called output if the -d argument is omitted. JAR or ZIP file contents are written to a JAR or ZIP file with the same name in the output directory. 8.6.4 Options @filename Supplies the name of a file from which command-line arguments are read. The file must contain only a single line consisting of legal program arguments, which are processed as the file is read. Directory and class names included in this file must be enclosed in double quotes and may contain whitespace. -classpath path Lists the locations of class files. Locations, which may be directory names or JAR file names, are separated by the platform's path separator (i.e., a semicolon for the Windows platform or colon for Unix). The -classpath option should specify the location of the core libraries as well as that of the classes to be preverified, unless this information can be obtained from the CLASSPATH environment variable. -cldc If present, this argument causes the preverifier to check that class files do not attempt to use VM features that are not part of the CLDC specification; that is, they may not use native methods, floating point operations, or object finalization. It is equivalent to supplying all of the -nofinalize, -nofp, and -nonative arguments. -d outputdirname Supplies the name of the directory to which the preverified classes will be written, defaulting to output if this argument is not supplied. If the preverify command reads any ZIP or JAR files, the processed versions will also be written to this directory. J2ME in a Nutshell 260 -nofinalize If present, this argument causes the preverifier to ensure that classes do not attempt to make use of object finalization. If this argument is omitted, and the -cldc option is not supplied, use of object finalization causes an error at runtime. -nofp If present, this argument causes the preverifier to ensure that classes do not attempt to use floating point operations. If this argument is omitted, and the -cldc option is not supplied, use of floating point operations causes an error at runtime. -nonative If present, this argument causes the preverifier to ensure that classes do not declare native methods. If this argument is omitted and the -cldc option is not supplied, use of native methods may cause an error at runtime. Note, however, that applications specifically written for a customized version of the KVM may use native methods, as described in Section 2.4.2. In such cases, use of this argument would not be appropriate. -verbose Causes debug information to be written to the standard error stream. -verify-verbose Causes detailed debug information for the class verification process to be written to the standard error stream. This option can result in large amounts of output. 8.6.5 Examples To preverify a single class called ora.ch2.KVMProperties at location tmpclasses\ora\ch2\KVMProperties.class relative to the current directory, where the core library classes are located in the directory c:\j2me\j2me_cldc\bin\common\api\lclasses, and writing the verified class to a file called output\ora\ch2\KVMProperties.class: preverify -classpath c:\j2me\j2me_cldc\bin\common\api\lclasses;tmpclasses ora.ch2.KVMProperties To preverify all the classes in tmpclasses\native.jar, writing the output to native.jar in the current directory and ensuring that floating point operations and object finalization are not used: preverify -classpath c:\j2me\j2me_cldc\bin\common\api\lclasses -nofp -nofinalize -d . tmpclasses\native.jar To preverify all the classes in the directory tmpclasses and all of its subdirectories, writing the output to an identical directory hierarchy in the current directory: J2ME in a Nutshell 261 preverify -classpath c:\j2me\j2me_cldc\bin\common\api\lclasses -d . tmpclasses 8.6.6 See Also • Section 8.3 • The KVM Porting Guide in the CLDC reference implementation download 8.7 MakeMIDPApp: JAD to PRC Conversion Tool 8.7.1 Availability MIDP for PalmOS 8.7.2 Synopsis java -cp Converter.jar com.sun.midp.palm.database.MakeMIDPApp [options] jarfile 8.7.3 Description The MakeMIDPApp command converts a MIDlet suite in the form of a JAR and a JAD file into a form suitable for installation on a PalmOS device. MakeMIDPApp is a Java language utility found in the file %INSTALL_DIR%\Converter\Converter.jar, where %INSTALL_DIR% is the installation directory of the MIDP for PalmOS product, of which it is a part. 8.7.4 Options -help Prints a synopsis of the command and the options that it recognizes. -v Provides verbose output. If you use this option twice (i.e., -v -v), slightly more output is produced. -jad file Supplies the Java Archive Descriptor (JAD) for the MIDlet suite. This argument is optional, but if you don't supply it, any application properties held in the JAD file that are not also in the manifest file of the JAR will not be accessible at runtime. See Section 3.5.3 for a discussion of application properties. -name name Gives the name to be associated with the MIDlet suite when it is displayed on the PalmOS device's application launcher screen. The name may contain spaces, provided that quotes are used to separate it from other arguments. Names longer than nine characters are not guranteed to be displayed in full. If this argument is not supplied, J2ME in a Nutshell 262 the MIDlet suite name from the manifest file or the JAD file (if supplied) is used instead. -longname name Supplies a name of up to 31 characters that will be used to describe the MIDlet where there is room for a slightly longer name, such as in the list of MIDlets that can be displayed from the developer preferences dialog (which is accessible from the Options menu of the MIDlet while it is running). Quotes should be used to delimit the name if it contains spaces. -icon file Specifies an icon to be used for the MIDlet suite when it appears on the device's launcher screen in "icon" mode. A default icon is used if this argument is supplied. The icon may be in one of three image formats: BMP Windows bitmap format PBM Portable bitmap format BIN PalmOS bitmap format Compressed or color Windows bitmaps are not supported. For best results, the image should be a 32-pixel square bitmap, in which the 5 leftmost and rightmost columns and the last 10 rows should be white. If the image size is incorrect, it will be adjusted to the right size, which may result in a loss of quality. -smallicon file Specifies an icon to be used for the MIDlet suite when it appears on the device's launcher screen in "list" mode. A default icon is used if this argument is supplied. The image bitmap should be 15 pixels wide and 9 pixels high. -creator id Assigns a four-character PalmOS creator ID to the MIDlet suite. If you intend to assign a creator ID to a commercial product, you should register it at http://www.palm.com/devzone/. The creator ID is assigned to the RMS storage that the MIDlet suite creates and also appears in the list of installed MIDlet suites available from the developer preferences dialog. If you don't supply a creator ID, one will be assigned for you. In this case, you must also supply the arguments -type Data. J2ME in a Nutshell 263 -type type Specifies the type of output file to create. The type argument is case sensitive and may take the values appl (which is the default) or Data. If you do not use the -creator argument to assign an explicit creator ID, the type must be given as Data. MIDlet suites created with type Data cannot be beamed between PalmOS devices. -outfile file The name of the file to which the converted MIDlet suite should be written. Output file names conventionally use the suffix .prc. -o file Synonym for -outfile. 8.7.5 Examples java -cp Converter.jar com.sun.midp.palm.database.MakeMIDPApp -icon myIcon.bmp -smallicon myListIcon.bmp -jad Chapter3.jad -o Chapter3.prc -type Data Chapter3.jar Converts the MIDlet suite packaged in the file Chapter3.jar and its associated attributes from the file Chapter3.jad into a form suitable for loading onto a PalmOS device. The output is written to a file called Chapter3.prc. The icons to be displayed on the device's launcher screen are held in the files myIcon.bmp (for icon mode) and myListIcon.bmp (for list mode), respectively. Since an explicit creator ID is not being assigned, the type is given as Data. java -cp Converter.jar com.sun.midp.palm.database.MakeMIDPApp -jad Chapter3.jad -o Chapter3.prc -creator ORA3 -name "Ch 3" -longname "J2ME Chapter 3" Chapter3.jar Converts the MIDlet suite packaged in the file Chapter3.jar and its associated attributes from the file Chapter3.jad into a form suitable for loading onto a PalmOS device. The output is written to a file called Chapter3.prc. On the launcher screen, the MIDlet suite will be displayed with the default icons and with the name "Ch 3". In contexts where a longer name is used, the text "J2ME Chapter 3" will appear. A creator ID of ORA3 is associated with this MIDlet suite, so the -type argument does not need to be supplied. Be aware that not all combinations of creator ID and type result in a MIDlet suite that can be executed on a PalmOS device. The following list, in which XXXX represents any four- character creator ID, summarizes the various combinations of these arguments and the results that are obtained: -creator XXXX -type appl Always results in an executable MIDlet suite. MIDlets can be beamed to another PalmOS device. J2ME in a Nutshell 264 -creator XXXX -type Data The MIDlet suite can be installed but is not executable and cannot be beamed. -type Data The MIDlet suite is executable but cannot be beamed. 8.8 chMEKeyTool: Public Key Certificate Management Tool 8.8.1 Availability MIDP Reference Implementation, Wireless Toolkit 8.8.2 Synopsis java -jar MEKeyTool.jar -help java -jar MEKeyTool.jar -list [-MEkeystore filename] java -jar MEKeyTool.jar -import [-MEkeystore filename] [-keystore filename] [-storepass password] -alias keyAlias [-domain domain] java -jar MEKeyTool.jar -delete [-MEKeystore filename] -owner ownerName 8.8.3 Description MEKeyTool is a Java language utility used to manage a keystore that holds public key certificates required to use the support for secure networking (HTTPS) provided by the MIDP reference implementation and the J2ME Wireless Toolkit. MEKeyTool is shipped in the form of a JAR file called MEKeyTool.jar in the directory %INSTALL_DIR%\bin, where %INSTALL_DIR% is the directory in which the J2ME Wireless Toolkit is installed. It is also provided in source code form as part of the MIDP reference implementation. When used with the J2ME Wireless Toolkit, MEKeyTool maintains a certificate keystore (it is referred to here as the ME keystore), that is held, by default, in a file called %INSTALL_DIR%\appdb\_main.ks. All operations implicitly apply to this keystore, unless you supply an alternative using the -MEkeystore option. MEKeyTool can list the content of the keystore, import a certificate from a J2SE keystore, or delete a certificate from the keystore. In order to make proper use of MEKeyTool, you need to be familiar with the J2SE keystore and the keytool command that is used to manage it, both of which are covered in Java in a Nutshell by David Flanagan (O'Reilly). 8.8.4 Options -MEKeystore filename Specifies the location of the ME keystore. By default, the keystore is held in the file appdb\_main.ks below the installation directory of the wireless toolkit. [...]... certificates are extremely important to SSL A company or individual obtains a certificate by applying to a certification authority or root CA (such as Thawte or Verisign) After applying vetting procedures, the CA issues the certificate in electronic form The certificate is actually one end of a certificate chain that may have two or more entries A certificate obtained directly from a CA might have only... JAR and ZIP files containing classes that are not part of the project you want to be incorporated when compiling, running, and packaging the MIDlet suite The content of these libraries is extracted and included in the JAR created when the MIDlet suite is packaged Files stored in this directory are used only in connection with its containing project You can arrange for libraries to be available to all... trustedCertEntry, Certificate fingerprint (MD5): EC:40:7D:2B: 76: 52 :67 :05:2C:EA:F2: 3A: 4F :65 :F0:D8 Each entry begins with an alias that can refer to the certificate The first certificate shown above, for example, has the alias thawtepersonalfreemailca As you can see, all these certificates are issued either by Thawte, Inc., or Verisign, Inc 279 J2ME in a Nutshell To import a certificate into the keystore used... behave on a device with lesser capabilities Drawing Speed lets you choose between smooth or fast animation The App Memory setting determines the size of the heap that will be available to the Java VM The initial setting depends on the amount of memory available in the emulated device, subject to a maximum of 64 KB Although you can decrease this value to simulate operation in a smaller device, you cannot... implementation It is, therefore, possible that new error codes will be added in the future 280 J2ME in a Nutshell 10 11 12 The certificate has an inappropriate keyUsage or extendedKeyUsage extension A certificate in the chain was not issued by the next certificate above it in the chain This is like receiving a Verisign certificate chained to a Thawte root CA certificate One of the certificates in the chain... font.system.plain.medium: Comic Sans MS-plain-11 font.system.plain.large: Comic Sans MS-plain-14 font.system.bold.italic.large: Comic Sans MS-bolditalic-14 You need to restart the Wireless Toolkit for the font change to take effect 9.1.4.2 Changing the available character encodings The set of character encodings available to an emulated device can be configured in its properties file by associating the appropriate... the 6 client connected This check is intended to prevent one server masquerading as another by copying its certificate chain and claiming it as its own 7 The certificate chain exceeds the maximum length supported by the implementation 8 A certificate in the chain does not contain a signature A certificate in the exchange has one or more critical extensions that are unrecognized An extension is an optional... installation and management and display and input devices If you are planning to use POSE for MIDlet development, you can use it as a standalone program and install MIDlet suites into it as you would any other PalmOS applications (converting them first, as described in the next section) Alternatively, you can use POSE as just another emulated device for the J2ME wireless emulator, which takes care of... caveat indicating that it is acceptable for some preprocessing of the JAR to be performed before it is actually installed, in order to create a delivery package suitable for devices that have their own storage mechanisms PalmOS devices expect to receive installable applications in the form of PRC files Since MIDP for PalmOS uses the standard installation mechanism, it is necessary to convert any MIDlet... Wireless Toolkit in the near future 9.1.4 Wireless Toolkit Localization Features The MIDP specification requires a device to support only a single locale and a single character encoding at a time In the real world, MIDP device manufacturers are likely to customize a device for the locale in which it is being used For example, a cell phone intended for use in Japan or by a Japanese-speaking person will . class names, in which each class is located relative to the class path given by the -classpath argument or via the CLASSPATH environment variable • A JAR file or ZIP file containing Java class. networking stackchunks stackmaps J2ME in a Nutshell 257 threading verifier 8.5.5 Application Management Commands You can control the emulator's application management software by using. 9.1.4.2 Changing the available character encodings The set of character encodings available to an emulated device can be configured in its properties file by associating the appropriate values