J2ME Polish
J2ME Polish 2.4 Documentation
Enough Software

The <emulator> Section

Launch your application in emulators by specifying the <emulator> element:

<emulator
	wait="true"
	trace="class"
	preferences="myemulator.properties"
	securityDomain="trusted"
	enableProfiler="true"
	enableMemoryMonitor="true"
	enableNetworkMonitor="true"
	transient="true"
	transientPort="9099"
	if="test"
	>
	<parameter name="-Xjam" 
			value="transient=http://localhost:8080/${polish.jadName}" />

</emulator>

In the above example the emulator is only started, when the "test" property is "true".

Supported Attributes

Following attributes are supported by the <emulator> element:

emulator-Attribute  Required  Explanation
wait No Either true or false. Defines whether the J2ME Polish task should wait until the emulator is finished. This is needed when any output should be shown on the Ant-output, therefore wait defaults to "yes".
transient No Either true or false. Starts the emulator in transient mode (install, run, deinstall) if set to true. J2ME Polish will then serve the application via a small HTTP server to the emulator.
transientPort No Sets the port on which the application should be delivered in transient mode. Default port is 9090.
trace No Defines if any virtual machine activities should be shown on the output. Possible values are "class" for showing the loading of classes, "gc" for activities of the garbage collection and "all" for a very extensive output. Several values can be given when they are separated by comma, e.g "class,gc". When it is set to "none" tracing will be deactivated completely.
securityDomain No The MIDP 2.0 security-domain of the application: either "trusted", "untrusted", "minimum" or "maximum". In "trusted" and "maximum" mode all security sensitive activities are allowed; in the "untrusted" mode the user will be questioned before each security sensitive activity and in the "minimum" mode any security sensitive activity will not be allowed.
enableProfiler No Either true or false. When activated the performance will be profiled during the execution of the application. The results will be shown when the emulator itself is closed.
enableMemoryMonitor No Either true or false. When activated the memory usage of the application will be shown.
enableNetworkMonitor No Either true or false. When any network activities are done, a monitor will show details of the sent and received data.
preferences No The file which contains the emulator-preferences. When such a file is used, the profiler and monitor settings are ignored. Please consult the documentation of the Wireless Toolkit for detailed information about the preferences file.
showDecompiledStackTrace No Either true or false. Determines whether a decompiled stack-trace should be shown, even when the source-code position of an exception could be be located. The automatic resolving of stack traces is discussed below.
if No The Ant property which needs to be true when the <emulator> element should be executed.
unless No The Ant property which needs to be true when the <emulator> element should be executed.

The <parameter> Subelement

The <emulator> element supports the nested subelement <parameter> for defining additional command line parameters:

parameter-Attribute  Required  Explanation
name Yes The name of the parameter.
value Yes The value of the parameter, the value can use any J2ME Polish or user-defined variable, the following variables are especially useful:
${polish.jadName}: The name of the JAD-file
${polish.jadPath}: The absolute path of the JAD-file
${polish.jarName}: The name of the JAR-file
${polish.jarPath}: The absolute path of the JAR-file
${polish.midlet.class}: The name of the main MIDlet class.
${polish.class.midlet-1}: The name of the first MIDlet class (same as polish.midlet.class).
${polish.class.midlet-2}: The name of the second MIDlet class, if any.
${polish.class.midlet-n}: The name of the nth MIDlet class, if any.
When only a command-line switch should be defined, just define an empty value, e.g.
<parameter name="-Xsomething" value="" />
if No The Ant property which needs to be "true" or the preprocessing term which needs result true when this parameter should be used.
unless No The Ant property which needs to be "false" or the preprocessing term which needs result false when this parameter should be used.

The <filters> Subelement

You can add filters for filtering and managing debug output. The only currently configured filter is the deadlock filter:

<filters>
	<filter name="deadlock">
		<package name="de.enough.polish.ui" />
		<package name="com.company.myproject" />
	</filter>
</filters>

Please refer to Nokia Asha documentation for a full description.

Emulator-Settings in the Device Database and in the build.xml

J2ME Polish uses the device-database to determine the correct emulator. If an emulator cannot be started, you can tell J2ME Polish how to launch it by modifying these settings.

WTK Emulators

For emulators which are integrated in the Wireless Toolkit the "Emulator.Skin"-capability is used for determining the correct emulator. This is the name which can be found in the "${wtk.home}/wtklib/devices" folder, e.g. "SonyEricsson_P900" etc. When no "Emulator.Skin"-capability is found, the current default emulator will be started instead. When the wrong emulator is started, please check if the "Emulator.Skin"-capability has been set in the "${polish.home}/devices.xml" file. If that capability is missing, please report it also to j2mepolish@enough.de so that the device database can be improved.

You can also set several skins, when several versions of an emulator do exist, for example. J2ME Polish will then choose the the first emulator it finds. Additional skins are defined by the capabilities "Emulator.Skin.2", "Emulator.Skin.3" and so forth.

Nokia Emulators

For launching Nokia emulators it might be necessary to define the "nokia.home" property in the ${polish.home}/global.properties file. This property needs to point to the installation directory of the Nokia emulators and defaults to "C:\Nokia" on Windows machines and to "${user.home}/Nokia" on Unix machines. For many emulators it is sufficient to set the "Emulator.Class" and "Emulator.Skin"-capabilities of the device in the "${polish.home}/devices.xml" file. The "Emulator.Class"-capability then needs to be "NokiaEmulator" and the "Emulator.Skin"-capability needs to correspond with the name of the emulator which can be found in the "${nokia.home}/Devices"-directory.

Some non-standard-emulators make it necessary the use the "GenericEmulator"-class instead. The invocation of such emulators is explained below.

Siemens Emulators

For launching Siemens emulators it might be necessary to define the "siemens.home" property in the ${polish.home}/global.properties file. This property needs to point to the installation directory of the "Siemens Mobile Toolkit" (SMTK) and defaults to "C:\siemens". When a Siemens-emulator should be used, the corresponding device-definition in the "${polish.home}/devices.xml" file needs to set the "Emulator.Class"-capability to "SiemensEmulator" (this is the default for all Siemens-phones). The "Emulator.Skin"-capability needs to specify the name of the emulator, which can be found in the "${siemens.home}/SMTK/emulators"-directory.

Motorola Emulators

For launching Motorola emulators it might be necessary to define the "motorola.home" property in the ${polish.home}/global.properties file. This property needs to point to the installation directory of the Motorola SDKs, e.g. "C:\program files\Motorola".

Blackberry Emulators

For launching BlackBerry emulators it might be necessary to define the "blackberry.home" property in the ${polish.home}/global.properties file. This property needs to point to the installation directory of the BlackBerry JDE, e.g. "C:\program files\Research in Motion". When you have installed several JDE's, J2ME Polish will use the correct one for building and launching the emulator.

Launching any Emulator with the GenericEmulator-Implementation

You can start any kind of emulator with the GenericEmulator class. You should set the "Emulator.Class"-capability of the corresponding device-definition in the "${polish.home}/devices.xml" file to "GenericEmulator".

The "Emulator.Executable"-capability needs to define the program which should be started, e.g. "java" or "${motorola.home}/EmulatorA.1/bin/emujava.exe". This program is responsible for starting the emulator.

You need also to define the command-line arguments for the emulator with the "Emulator.Arguments"-capability. Command-line arguments are separated by two semicolons in a row, e.g. "-Xdescriptor;;${polish.jadPath};;-classpath;;${polish.jarPath}". As you can see in the example, any J2ME Polish-variables as well as Ant-properties can be used within the emulator-arguments. Often used is the "polish.jadPath"-variable, which contains the absolute path to the JAD-file and the "polish.jarPath"-variable, which does the same for the JAR-file. Also useful is the variable polish.classes.midlet-1 that does define the first MIDlet in the suite.

You should try to minimize the dependency on a specific system setup by using properties like "motorola.home" or "nokia.home" in your settings. These properties can then be defined within the corresponding build.xml file.

Please inform the J2ME Polish community about any emulators you have integrated, so that other users can also benefit from your settings. Just send an email to j2mepolish@enough.de. Thanks!

Automatic Resolving of Stack Traces and Exceptions

J2ME Polish can resolve stack traces like "Exception at com.company.MyClass.doSomething(+200)" automatically, when the free "jad" decompiler is installed. This decompiler can be downloaded at http://www.kpdus.com/jad.html. Please adjust the PATH environment variable, so that it includes the installation directory of jad or install the jad-excecutable (jad.exe or jad) to the "${polish.home}/bin" folder.

When jad is installed correctly, J2ME Polish will resolve stack traces automatically. Instead of seeing only the rather obscure stack trace package.class.method(+instructionoffset), an additional message giving the source-location as well as the faulty source code is printed out, e.g. "src/com/company/MyClass.java:97: int result = max / 0;". If you execute J2ME Polish from within an IDE, you can click on such a message and then edit the faulty code directly.

In cases when J2ME Polish is not able to locate the position in the source code, an extract of the decompiled class-code will be shown instead. This extract will help you to identify the source of the error. The following fragment gives an example of a decompiled class code:

            world.animate(System.currentTimeMillis() - lastCycleTime);
    //   87  169:aload_0         
    //   88  170:getfield        #13  <Field World world>
    //   89  173:invokestatic    #17  <Method long System.currentTimeMillis()>
    //   90  176:lload           4
    //   91  178:lsub            
    //   92  179:invokevirtual   #23  <Method void World.animate(long)>

In the first line the actual directive is given and in the following lines the binary equivalent compiled java code is listed. The second number from the left is the number which is given in the original error message (e.g. package.class.method(+179)).

When the "showDecompiledStackTrace"-attribute of the <emulator> element is set to "true" or "yes", a decompiled code fragment will be given out for each stack-trace, even when the source-code position could be located.

Please note that the source-code position can only be located, when the debugging-mode is activated. This is done by setting the "enable"-attribute of the <debug> element to "true". In the default-setup this is done when you call the "emulator" target of the build.xml:

ant emulator
back to top