<ANTENNA/>

Antenna

An Ant-to-End Solution For Wireless Java

Version 1.2.1

Package

The WtkPackage task is an extension to Ant's standard Jar task that handles JAD files correctly and is able to include complete libraries into the resulting JAR file. It also allows for preverification and obfuscation of the generated file.

In some more detail, the task does the following:

It creates or updates a JAR from the files you specify the usual way (for the Jar task). If you specify a libclasspath, the content of these JARs will also be included.
If no MANIFEST file is specified, a temporary one is generated. Its contents are taken from the JAD file, with only the following exceptions:
- The MIDlet-Jar-Url and MIDlet-Jar-Size keys are obmitted.
- The MicroEdition-Configuration and MicroEdition-Profile keys are added as you specify them in the corresponding parameters of the task, or they default to "CLDC-1.0" and "MIDP-1.0", or to what has been set using the wtk.cldc.version and wtk.midp.version properties.
It desired, it preverifies and/or obfuscates the new JAR file.
Finally, the JAD file is updated for the new JAR file name and size. If you request automatic version numbering, the MIDlet-Version key is attempted to change.

The task provides the following parameters (in addition to those of the standard Jar task):

Parameter Type Required Purpose

jarfile file yes The name of the JAR file to create or update.

jadfile file yes The name of the JAD file that accompanies the JAR file. Note that the JAD file already has to exist. It is not created by the Ant task.

config string no The value of the MicroEdition-Configuration key to write to the MANIFEST.MF. Defaults to "CLDC-1.0" or to what has been set using the wtk.cldc.version propertiy. Only relevant if no MANIFEST is specified.

profile string no The value of the MicroEdition-Profile key to write to the MANIFEST.MF. Defaults to "MIDP-1.0" or to what has been set using the wtk.midp.version propertiy. Only relevant if no MANIFEST is specified.

autoversion boolean no If set to "true", the version number contained in the MIDlet-Version key of the JAD file is attempted to increase. The version number is assumed to follow the "major.minor.micro" scheme. The latter of the three numbers is incremented by one.

preverify boolean no If set to "true", the resulting JAR file is preverified.

cldc boolean no If set to "false" then "-cldc" is not passed as a parameter to the preverifier. Defaults to "true".

nonative boolean no Can be used to allow/forbid certain langage features during preverification. If set to "true", then "-nonative" is passed to the preverifier. Please turn "cldc" off before. Otherwise this setting might have no effect.

nofloat boolean no Can be used to allow/forbid certain langage features during preverification. If set to "true", then "-nofloat" is passed to the preverifier. Please turn "cldc" off before. Otherwise this setting might have no effect.

nofinalize boolean no Can be used to allow/forbid certain langage features during preverification. If set to "true", then "-nofinalize" is passed to the preverifier. Please turn "cldc" off before. Otherwise this setting might have no effect.

obfuscate boolean no If set to "true", the resulting JAR file is obfuscated. All classes are obfuscated with only three exceptions:

The main MIDlet classes, denoted by the MIDlet-# keys in the JAD file.

Classes to be loaded by name (on a Motorola phone), denoted by an iDEN-Install-Class-# keys.

Classes (or parts thereof) explicitly excluded from obfuscation using the <preserve> nested element.

keepmanifestorder boolean no If set to "true", the task keeps the original order of MANIFEST.MF entries in the resulting JAR. Otherwise then entries might be rearranged by Ant (which is usually not a problem).

bootclasspath path no The bootclasspath is needed for preverification and obfuscation. It defaults to the MIDP API contained in ${wtk.home}/lib/midpapi.zip, or ${wtk.midpapi}, if specified. Only for RetroGuard, the emptied-out MIDP API is used.

classpath path no The classpath is needed for preverification and obfuscation. If you use any external libraries other than the MIDP API itself, and these libraries should not be included in the resulting JAR file (for example because they already exist on a certain phone), specify them here.

libclasspath path no The libclasspath is needed for preverification and obfuscation, and it serves to specify libraries to be included in the resulting JAR file. If you use any external libraries that should be included in the resulting JAR file, specify them here. Consider this an equivalent to the Wireless Toolkit's lib directory. Note that you also use Ant's FileSet, ZipFileSet and ZipGroupFileSet nested elements to include existing classes and resources into the JAR.

classpathref string no A reference to a classpath defined elsewhere.

bootclasspathref string no A reference to a bootclasspath defined elsewhere.

libclasspathref string no A reference to a libclasspath defined elsewhere.

if String no Provides fine-grained control over task execution based on a property definition. The task will only be executed if the given property is defined.

unless String no Provides fine-grained control over task execution based on a property definition. The task will only be executed if the given property is not defined.

verbose boolean no Allows to set the verbosity of the task's output.

Parameter	Type	Required	Purpose
jarfile	file	yes	The name of the JAR file to create or update.
jadfile	file	yes	The name of the JAD file that accompanies the JAR file. Note that the JAD file already has to exist. It is not created by the Ant task.
config	string	no	The value of the MicroEdition-Configuration key to write to the MANIFEST.MF. Defaults to "CLDC-1.0" or to what has been set using the wtk.cldc.version propertiy. Only relevant if no MANIFEST is specified.
profile	string	no	The value of the MicroEdition-Profile key to write to the MANIFEST.MF. Defaults to "MIDP-1.0" or to what has been set using the wtk.midp.version propertiy. Only relevant if no MANIFEST is specified.
autoversion	boolean	no	If set to "true", the version number contained in the MIDlet-Version key of the JAD file is attempted to increase. The version number is assumed to follow the "major.minor.micro" scheme. The latter of the three numbers is incremented by one.
preverify	boolean	no	If set to "true", the resulting JAR file is preverified.
cldc	boolean	no	If set to "false" then "-cldc" is not passed as a parameter to the preverifier. Defaults to "true".
nonative	boolean	no	Can be used to allow/forbid certain langage features during preverification. If set to "true", then "-nonative" is passed to the preverifier. Please turn "cldc" off before. Otherwise this setting might have no effect.
nofloat	boolean	no	Can be used to allow/forbid certain langage features during preverification. If set to "true", then "-nofloat" is passed to the preverifier. Please turn "cldc" off before. Otherwise this setting might have no effect.
nofinalize	boolean	no	Can be used to allow/forbid certain langage features during preverification. If set to "true", then "-nofinalize" is passed to the preverifier. Please turn "cldc" off before. Otherwise this setting might have no effect.
obfuscate	boolean	no	If set to "true", the resulting JAR file is obfuscated. All classes are obfuscated with only three exceptions: The main MIDlet classes, denoted by the MIDlet-# keys in the JAD file. Classes to be loaded by name (on a Motorola phone), denoted by an iDEN-Install-Class-# keys. Classes (or parts thereof) explicitly excluded from obfuscation using the `<preserve>` nested element.
keepmanifestorder	boolean	no	If set to "true", the task keeps the original order of MANIFEST.MF entries in the resulting JAR. Otherwise then entries might be rearranged by Ant (which is usually not a problem).
bootclasspath	path	no	The bootclasspath is needed for preverification and obfuscation. It defaults to the MIDP API contained in ${wtk.home}/lib/midpapi.zip, or ${wtk.midpapi}, if specified. Only for RetroGuard, the emptied-out MIDP API is used.
classpath	path	no	The classpath is needed for preverification and obfuscation. If you use any external libraries other than the MIDP API itself, and these libraries should not be included in the resulting JAR file (for example because they already exist on a certain phone), specify them here.
libclasspath	path	no	The libclasspath is needed for preverification and obfuscation, and it serves to specify libraries to be included in the resulting JAR file. If you use any external libraries that should be included in the resulting JAR file, specify them here. Consider this an equivalent to the Wireless Toolkit's lib directory. Note that you also use Ant's FileSet, ZipFileSet and ZipGroupFileSet nested elements to include existing classes and resources into the JAR.
classpathref	string	no	A reference to a classpath defined elsewhere.
bootclasspathref	string	no	A reference to a bootclasspath defined elsewhere.
libclasspathref	string	no	A reference to a libclasspath defined elsewhere.
if	String	no	Provides fine-grained control over task execution based on a property definition. The task will only be executed if the given property is defined.
unless	String	no	Provides fine-grained control over task execution based on a property definition. The task will only be executed if the given property is not defined.
verbose	boolean	no	Allows to set the verbosity of the task's output.

Preserve

In addition to the various parameters, the task provides one nested element "preserve" that is used during obfuscation. The element has one parameter:

Parameter Type Required Purpose

class string yes Specifies a class to be excluded from obfuscation and/or optimization when RetroGuard or ProGuard are used.

if String no Provides fine-grained control over the classes being preserved. The class will only be preserved if the given property is defined.

unless String no Provides fine-grained control over the classes being preserved. The class will only be preserved if the given property is not defined.

Parameter	Type	Required	Purpose
class	string	yes	Specifies a class to be excluded from obfuscation and/or optimization when RetroGuard or ProGuard are used.
if	String	no	Provides fine-grained control over the classes being preserved. The class will only be preserved if the given property is defined.
unless	String	no	Provides fine-grained control over the classes being preserved. The class will only be preserved if the given property is not defined.

Argument

The "argument" nested element allows to pass obfuscator-specific arguments. In contrast to the general parameters of the obfuscator task and the "preserve" nested element, this one is not portable. Arguments are passed to the obfuscator verbatim. Please see the RetroGuard or ProGuard documentation for a complete list of options supported.

Parameter Type Required Purpose

value string yes/td> Specifies the argument to pass to the obfuscator.

if String no Provides fine-grained control over the arguments. The argument will only be applied if the given property is defined.

unless String no Provides fine-grained control over the arguments. The argument will only be applied if the given property is not defined.

Parameter	Type	Required	Purpose
value	string	yes/td>	Specifies the argument to pass to the obfuscator.
if	String	no	Provides fine-grained control over the arguments. The argument will only be applied if the given property is defined.
unless	String	no	Provides fine-grained control over the arguments. The argument will only be applied if the given property is not defined.

Exclude JAD elements from manifest

MIDP Does not allow conflicts between JAD and Manifest, this means that most devices will refuse to run MIDlets if the JAD and Manifest does not agree on a specific parameter. Normally Antenna include all JAD options into the Manifest, but if you want to allow later changes of options in the JAD, you need to exclude that option from the Manifest. In addition to the various parameters, the task provides one nested element "preserve" that is used during obfuscation. The element has one parameter:

Parameter Type Required Purpose

Name string This or List Specifies the name of a JAD attribute to be excluded from the Manifest

List string This or name Specifies the comma separated list of of a JAD attribute to be excluded from the Manifest

Example:

Parameter	Type	Required	Purpose
Name	string	This or List	Specifies the name of a JAD attribute to be excluded from the Manifest
List	string	This or name	Specifies the comma separated list of of a JAD attribute to be excluded from the Manifest

        <wtkpackage jarfile="hello.jar"
                    jadfile="hello.jad"
                    obfuscate="false"
                    preverify="false">
	    
	    <fileset dir="classes"/>

	    <!-- Exclude FOO from manifest. -->
	    <exclude_from_manifest name="FOO"/>

	    <!-- Exclude A and B from manifest. -->
	    <exclude_from_manifest list="A,B"/>

	</wtkpackage>