Oracle® Java Micro Edition Software Development Kit Developer's Guide Release 3.4 for Eclipse on Windows E37550-04 |
|
Previous |
Next |
This topic describes how to operate the Oracle Java ME SDK from the command line and details the command line tools required to build and run an application.
The Device Manager is a component that runs as a service. It detects devices (real or emulated) that conform to the Unified Emulator Interface Specification (http://www.oracle.com/technetwork/java/javame/documentation/ueispecs-187994.pdf
), version 1.0.2. The Device Manager automatically restarts every time you use the SDK. You can manually launch the Device Manager from a script or a command line.
installdir\bin\device-manager.exe
To see a log of activities, launch the Device Manager with the -XenableOutput
option.
installdir\bin\device-address is a tool for viewing, adding, and removing devices that the SDK is not able to discover automatically. The Microsoft device emulator is an example of such a device. The syntax is:
Table 12-1 Device Address Commands
Command | Action |
---|---|
|
Add the specified address. |
|
Delete the specified address. |
|
List all addresses. |
|
List the address of the specified type. |
For example, the following command adds a device:
installdir\bin\device-address.exe add ip 192.168.1.2
You can launch the emulator independent of the GUI using bin\emulator
. The syntax is as follows:
emulator options
The general options are as follows:
Table 12-2 Emulator Commands
Command | Action |
---|---|
|
Specifies a search path for application classes. The path consists of directories, ZIP files, and JAR files separated by semicolons. |
-Dproperty=value |
Sets a system property value. |
Display a list of valid options. |
|
Display version information about the emulator. |
|
Run an application on the emulator using the given device instance name. |
|
|
Print emulator skin information on the standard output stream and exit immediately. The information includes the skin name, screen size, and other capabilities. |
This is a simple example of running the emulator from the command line:
emulator.exe -Xdescriptor:"C:\Program Files\Java_ME_platform_SDK_3.4\apps\Games\dist\Games.jad" -Xdevice:JavaMEPhone2
emulator.exe
also supports "MIDlet Options" and "Debugging and Tracing Options."
Options for running MIDlets in the emulator are as follows:
-Xautotest
:JAD-file-URL
Run in autotest mode. This option installs a MIDlet suite from a URL, runs it, removes it, and repeats the process. The purpose is to run test compatibility kits (TCKs) with the emulator, using a test harness such as JT Harness (http://jtharness.java.net
), or Java Device Test Suite (JDTS http://www.oracle.com/technetwork/java/javame/javadevice-140362.html
). For example:
emulator -Xautotest:http://localhost:8080/test/getNextApp.jad
Given the above command, -Xautotest
causes the emulator to repeatedly install, run, and remove the first MIDlet from the MIDlet suite provided through the HTTP URL. When the emulator starts, it queries the test harness, which then downloads and installs the TCK MIDletAgent.
-Xdescriptor:
jad-file
Install a MIDlet, run it, and uninstall it after it finishes.
-Xdomain:
domain-name
Set the MIDlet suite's security domain.
The Xjam
argument runs an application remotely using the Application Management Software (AMS) to run over-the-air (OTA) provisioning. If no application is specified with the argument, the graphical AMS is run.
-Xjam[:install=<JAD-file-url> |force|list|storageNames| run=[<storageNames>|<StorageNumber>]|remove=[<storage name>|<storage number> | all]]
Installs the application with the specified JAD file onto a device.
force
. If an existing application has the same storage name as the application to be installed, force
removes the existing application before installing the new application.
list
. List all the applications installed on the device and exit. The list is written to standard output before the emulator exits.
storageNames
. List all applications installed on the device. The list is written to standard output before the emulator exits. Each line contains one storage name in numerical order. The list contains only the name so the order is important. For example the first storage name must be storage number 1.
-Xjam:
run=[<
storage-name> | <
storage-number>]
Run a previously installed application. The application is specified by its valid storage name or storage number.
-Xjam:
remove=[<
storage-name> |
<storage-number> | all]
Remove a previously installed application. The application is identified by its valid storage name or storage number. If all
is supplied, all previously installed applications are removed.
-Xjamtransient=
jad-file-url
If specified, transient
is an alias for installing, running, and removing the application with the specified JAD file.
This example illustrates OTA installation:
emulator -Xjam:install=http://www.myserver.com/apps/MyApp.jad -Xdevice:JavaMEPhone2
The above command returns the ID of the installed application. When you obtain the ID you can run it with: emulator=Xjam:run=
ID
See also "Emulator Command Line Options" and "Debugging and Tracing Options."
You can use the following options with the emulator for debugging and tracing CLDC projects.
Enable runtime debugging. The -Xrunjdwp
option must be called to support -Xdebug
.
Start a Java debug wire protocol session, as specified by a list of comma-separated debug settings. Both -Xrunjdwp
and -Xdebug
must be called.
Valid debug settings include the following:
transport=
transport-mechanism - Transport mechanism used to communicate with the debugger. The only transport mechanism supported is dt_socket
.
address=
host:port - Transport address for the debugger connection. If host is omitted, localhost is assumed to be the host machine.
server=
{y|n} - Starts the debug agent as a server. The debugger must connect to the port specified. The possible values are y
and n
. Currently, only y
is supported (the emulator must act as a server).
suspend=
{y|n} - The possible values are y
and n
.
When suspend
is set to n, the application starts immediately and the debugger can be attached at any time during its run.
When suspend is set to y, the application does not start until a debugger attaches to the debugging port and sends a resume command, so an application can be debugged from the very beginning.
This example shows debugging:
emulator.exe -Xdevice:JavaMEPhone1 -Xdebug -Xrunjdwp:transport=dt_socket,suspend=n, server=y,address=51307 -Xdescriptor:..\apps\Games\dist\Games.jad -Xdomain:maximum
With the emulator running you can attach a debugger.
To find more information on how to attach a command line debugger, see:
http://docs.oracle.com/javase/6/docs/technotes/tools
A sample command would be:
jdk/bin/jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=51307
In the user interface, building a project is a single step. Behind the scenes, however, there are 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 VM. See the following topics:
Before building and running an application from the command line, verify that the jar
command is in your path. To find the version of the development kit, run java -version
at the command line.
Use the javac
compiler from the Java SE development kit to compile Java source files. You can use the existing Oracle Java ME SDK project directory structure. Use the -bootclasspath
option to tell the compiler to use the MIDP APIs, and use the -d
option to tell the compiler where to put the compiled class files.
The following example demonstrates how you might compile a MIDP 2.1 application, taking source files from the src
directory and placing the class files in the tmpclasses
directory. Newlines have been added for clarity.
javac -target 1.3 -source 1.3 -bootclasspath ..\..\lib\cldc_10.jar;..\..\lib\midp2.1.jar -d tmpclasses src\*.java
For more information on javac
, consult the Java SE documentation.
The next step is to preverify the class files. The bin
directory of the Oracle Java ME SDK includes the preverify
utility. The syntax for the preverify command is as follows:
preverify files | directories
Some of the options are as follows:
Table 12-3 Options to preverify
Command
Name | Description |
---|---|
|
Specify the directories or JAR files (given as a semicolon-delimited list) from which classes are loaded. |
|
Specify the target directory for the output classes. This directory must exist before preverifying. If this option is not used, the preverifier places the classes in a directory called |
Following the example for compiling, use the following command to verify the compiled class files. As before, newlines are added for clarity.
preverify.exe -classpath ..\..\lib\cldcapi10.jar;..\..\lib\midpapi20.jar -d classes tmpclasses
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.
To package a MIDlet suite manually you must create a manifest file, an application JAR file, and finally, a MIDlet descriptor (also known as a Java Application Descriptor or JAD).
Create a manifest file containing the appropriate attributes as specified in the MIDP specification. You can use any text editor to create the manifest file. For example, a manifest might have the following contents:
MIDlet-1: My MIDlet, MyMIDlet.png, MyMIDlet MIDlet-Name: MyMIDlet MIDlet-Vendor: My Organization MIDlet-Version: 1.0 MicroEdition-Configuration: CLDC-1.1 MicroEdition-Profile: MIDP-2.1
Create a JAR file containing the manifest and the suite's classes and resource files. To create the JAR file, use the jar
tool that comes with the Java SE software development kit. The syntax is as follows:
jar cfm file manifest -C class-directory . -C resource-directory .
The arguments are as follows:
file - JAR file to create.
manifest - Manifest file for the MIDlets.
class-directory - Directory containing the application's classes.
resource-directory -
Directory containing the application's resources.
For example, to create a JAR file named MyApp.jar
whose classes are in the classes
directory and resources are in the res
directory, use the following command:
jar cfm MyApp.jar MANIFEST.MF -C classes . -C res .
Create a JAD file containing the appropriate attributes as specified in the MIDP specification. You can use any text editor to create the JAD file. This file must have the extension .jad
.
Note: You must set the |
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
The full spectrum of the Oracle Java ME SDK's security features are also available from the command line. You can adjust the emulator's default protection domain, sign MIDlet suites, and manage certificates.
To adjust the emulator's default protection domain, use the following option with the emulator
command:
-Xdomain:
domain-type
Assigns a security domain to the MIDlet suite. Enter an appropriate security domain as described in "Security Domains.". For example, -Xdomain:maximum
.
jadtool
is a command-line interface for signing MIDlet suites using public key cryptography according to the MIDP 2.1 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 Java SE platform keystores. Java SE software provides keytool
, the command-line tool to manage Java SE platform keystores.
jadtool
is packaged in a JAR file. To run it, open a command prompt, change the current directory to installdir\bin
, and enter the following command:
jadtool command
The commands are as follows:
-help
Prints the usage instructions for jadtool
.
-addcert -alias
key alias[-storepass
password]
[-keystore
keystore]
[-certnum
number]
[-chainnum
number] [-encoding
encoding]
-inputjad
filename -outputjad
filename
Adds the certificate of the key pair from the given keystore to the JAD file or JPP file.
-addjarsig
[
-jarfile
filename]
-keypass
password -alias key alias -storepass
password]
[-keystore
keystore]
[-chainnum
number]
[-encoding
encoding] -inputjad
filename -outputjad
filename
Adds a digital signature of the input JPP file to the specified output JPP file.
-showcert
[<[-certnum
number]
[-chainnum
number]>
|[-all]]
[-encoding
encoding]
-inputjad
filename
Displays information about certificates in JAD files.
The default values are as follows:
-encoding
- UTF-8
-jarfile
- MIDlet-Jar-URL
property in the JAD file
-keystore
- $HOME/.keystore
-certnum
- 1
-chainnum
- 1
MEKeyTool manages the public keys of certificate authorities (CAs), making it functionally similar to the keytool utility that comes with the Java SE SDK. The purpose of the keys is to facilitate secure HTTP communication over SSL (HTTPS).
Before using MEKeyTool
, you must first have access to a Java Cryptography Extension keystore. You can create one using the Java SE keytool
utility (found in the \bin
directory for your JDK). For more information on keytool, see:
http://docs.oracle.com/javase/7/docs/technotes/tools
To run MEKeyTool
, open a command prompt, change the current directory to installdir\bin
, and enter the following command:
installdir\bin\mekeytool.exe -
command
The command keywords follow.
The Oracle Java ME SDK contains a default ME keystore named _main.ks,
which is located in:
installdir\runtimes\cldc-hi\appdb
This keystore includes all the certificates that exist in the default Java SE platform keystore that comes with the Java SE installation.
Also, each emulator instance has its own _main.ks
file located in username\javame-sdk\3.4\work\
devicename\appdb
. If you do not specify a value for MEkeystore
, a new key is added to the default ME key for this emulator instance.
If you do not specify a value for -keystore
, the default keystore is used:
username\keystore.ks
-help
Prints the usage instructions for MEKeyTool.
-import
-alias
alias [-keystore
JCEkeystore][-MEkeystore
filename] [-storepass
storepass] [-domain
domain-name]
Imports a public key into the ME keystore from the given JCE keystore using the given Java Cryptography Extension keystore password. and the default Java Cryptography Extension keystore is username\.keystore
.
-list
[-MEkeystore
filename]
Lists the keys in the ME keystore, including the owner and validity period for each.
-delete (-owner
owner | -number
key-number)
[-MEkeystore
filename]
Deletes a key from the given ME keystore with the given owner.
Mobile clients can use the Stub Generator to access web services. The wscompile tool generates stubs, ties, serializers, and WSDL files used in Java API for XML (JAX) RPC clients and services. The tool reads a configuration file, that 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
Table 12-4 lists the wscompile
options:
Table 12-4 wscompile
Options
Option | Description |
---|---|
|
Same as |
|
Generates client artifacts (stubs, etc.) |
|
Generates interfaces and value types only |
|
Specifies where to place generated output files |
|
Enables the given features |
|
Generates debugging info |
|
Same as |
|
Specifies a HTTP proxy server (port defaults to 8080) |
|
Writes the internal model to the given file |
|
Optimizes generated code |
|
Specifies where to place generated source files |
|
Outputs messages about what the compiler is doing |
|
Prints version information |
|
Sets the CLDC version to 1.0 (default). Float and double become String. |
|
Sets the CLDC version to 1.1 (float and double are OK) |
|
Shows all CLDC 1.0 information and warning messages. |
Note: Exactly one |
Table 12-5 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 is used with a particular feature.
Table 12-5 Command Supported Features (-f
) for wscompile
Option | Description | Type of File |
---|---|---|
|
Turns on explicit service context mapping |
WSDL |
|
Turns off data binding for literal encoding |
WSDL |
|
Turns off encoding type information |
WSDL, SEI, model |
|
Turns off support for multiple references |
WSDL, SEI, model |
|
Turns off full validation of imported WSDL documents |
WSDL |
|
Searches schema aggressively for subtypes |
WSDL |
|
Turns on direct serialization of interface types |
WSDL, SEI, model |
|
Enables WSI-Basic Profile features (default) |
WSDL |
|
Resolves |
WSDL |
|
No unwrap. |
WSDL |
Examples
wscompile -gen -d generated config.xml wscompile -gen -f:nounwrap -O -cldc1.1 -d generated config.xml