MobilityAntExtensions

Mobility Ant Extensions for Java ME

This library extends Apache Ant about new tasks supporting easy Java ME development.

What does it do?

Mobility Ant Extensions cover following areas:

  • source code preprocessing
  • obfuscation
  • class preverification
  • construction of application descriptor
  • emulator execution and debugging
  • multiple libraries and resources extraction
  • printout with defined encoding
  • overriding Ant properties (implementation of variables)

Where to get it?

Mobility Ant Extensions library is available as a part of NetBeans Mobility Pack and it can be distributed separately under CDDL License.

Inside NetBeans Mobility installation you can find Mobility Ant Extensions as mobility8/modules/org-netbeans-modules-mobility-antext.jar.

Sources are available in NetBeans CVS under module mobility/ant-ext. The document describing checkout and build of Mobility is MobilityDevelopingMobilityPack.

How to use it?

The best way to use Mobility Ant Extensions is through NetBeans Mobility IDE because it is fully integrated in the Mobility project build system and through the build system cooperates with many other parts of NetBeans IDE.

The other posible way is use the power of Mobility Ant Extensions from your custom Ant script. The best start would be by following declaration:

<taskdef resource="org/netbeans/mobility/antext/defs.properties">
    <classpath>
        <pathelement path="???/org-netbeans-modules-mobility-antext.jar;???/org-netbeans-modules-classfile.jar"/>
    </classpath>
</taskdef>

Then following Ant tasks are at your service:

Note: For details about org-netbeans-modules-classfile.jar presence on the tasks definition classpath see <nb-run> paragraph.

<nb-prep>

An Ant task that will preprocess a java source file. Lines marked with tags recognized by the preprocessor will be commented out or in depending on if they are marked as being a part of the current configuration.


Attributes:

  • SrcDir - Semi-required. Source directory location with java source files for preprocessing. At least one of SrcDir, nested fileset, or FileSetRef have to be set.
  • FileSetRef - Semi-required. Fileset specified by reference.
  • DestDir - Optional. Destination directory location. If not specified, files are modified in-place.
  • PreprocessFor - Optional. Defines what abilities should be the sources preprocess for.
  • Encoding - Optional. Specifies encoding used for reading and writing files.

Nested Fileset element - Semi-required. Fileset with sources for preprocessing. Even if fileset contains other files, this task preprocesses .java files only.

Up-to-date check: Check is performed only if DestDir is specified. File is preprocessed if and only if DestDir is specified and the file newer than the one in destination directory.

Sample Usage:

<nb-prep destdir="${preprocessed.dir}" 
         preprocessfor="${config.active.name},${abilities},DebugLevel=${debug.level}"
         encoding="${javac.encoding}">
    <fileset dir="${src.dir}"/>
</nb-prep>

<nb-obfuscate>

Obfuscate Task adds support for jar file obfuscation. Currently it supports ProGuard obfuscator only.

Attributes:

  • SrcJar - Required. Source jar file location for obfuscation.
  • DestJar - Required. Destination (obfuscated) jar file location.
  • ObfuscatorType - Optional. One of these obfuscator names: NONE, ProGuard. Task automatically checks ObfuscatorClassPath. NONE type just copies SrcJar file to DestJar file. Default: PROGUARD
  • ClassPath - Optional. Classpath required by SrcJar classes. It supports nested classpath tag too.
  • ClassPathRef - Optional. Classpath specified by reference required by SrcJar classes.
  • ObfuscatorClassPath - Semi-required. Classpath required by obfuscator to run. There must be obfuscator classpath defined because of automatic check for obfuscators (if they exists). Additionally this task takes value of "libs.<Lower_Case_Ofuscator_Type>.classpath" and adds it into classpath.
  • ObfuscatorClassPathRef - Semi-required. Classpath specified by reference required by obfuscator to run.
  • Exclude - Optional. Comma separated list of classes which should be excluded from obfuscator process.
  • ObfuscationLevel - Optional. Level of obfuscation. Valid values: 0-9. Default: 0.
  • ExtraScript - Optional. An extra obfuscators commands.

Nested ObfuscatorClassPath element - Semi-required. Classpath specified by nested element required by obfuscator to run.

Up-to-date check: Destination (obfuscated) jar file is created if and only if source jar file is newer than destination jar file.

Obfuscation levels (= What is obfuscated):

  • ObfuscationLevel = 0/default: Nothing.
  • ObfuscationLevel = 1: Custom obfuscation level - use ExtraScript to define all commands.
  • ObfuscationLevel = 2: Private fields and methods.
  • ObfuscationLevel = 3-4: Private/default fields, methods, and classes.
  • ObfuscationLevel = 5-6: Private/default/protected fields, methods, and classes. Used mainly for libraries.
  • ObfuscationLevel = 7-8: Everything except public fields and methods of public classes. Used mainly for libraries and applications.
  • ObfuscationLevel = 9: Everything except public methods of MIDlet classes. Used mainly for applications.

Sample Usage:

<nb-obfuscate srcjar="${obfuscator.srcjar}"
              destjar="${obfuscator.destjar}"
              obfuscatorclasspath="${proguard.jar}"
              classpath="${platform.bootclasspath}"
              obfuscationLevel="${obfuscation.level}"
              extraScript="${obfuscation.custom}"/>

<nb-preverify>

Preverify Task adds support for classes preverification.

Attributes:

  • SrcDir - Required. Source directory location with classes for preverification.
  • DestDir - Required. Destination (preverified) directory location.
  • PlatformHome - Required. Home directory location of platform/emulator.
  • PlatformType - Optional. Platform type - one of these: "UEI 1.0", "UEI 1.0.1" (default), Custom. When Custom is set, Configuration is ignored.
  • Configuration - Optional. Device configuration - one of these: "CLDC-1.0", "CLDC-1.1". Default value depends on platform.
  • ClassPath - Optional. Classpath required by classes in SrcDir. It supports nested classpath tag too.
  • ClassPathRef - Optional. Classpath specified by reference required by SrcJar classes.
  • CommandLine - Semi-required. Command line for running preverification. Required when PlatformType is Custom. CommandLine attribute allows you to fully customize command line for running preverification. Command Line string processed using EMapFormat class (see its javadoc for formatting hints). This task presets following identificators:
  • {platformhome} - always set - value of PlatformHome attribute
  • {srcdir} - value of SrcDir attribute
  • {destdir} - value of DestDir attribute
  • {classpath} - classpath string composed from ClassPath, ClassPathRef, nested ClassPath
  • {/} - value of File.separator

Up-to-date check: Classes are preverified if and only if any file in the source directory is newer than any file in the target directory or there is no file in target directory.

Sample Usage:

<nb-preverify srcdir="${obfuscated.classes.dir}"
              destdir="${preverify.classes.dir}"
              classpath="${platform.bootclasspath}"
              configuration="${platform.configuration}"
              platformhome="${platform.home}"
              platformtype="${platform.type}"
              commandline="${platform.preverifycommandline}"/>

<nb-jad>

Jad Task adds support for updating values of MIDlet-Jar-Size and MIDlet-Jar-URL attributes in jad file.

Attributes:

  • JadFile - Required. Specifies source jad file location. If Output does not exist, this is destination jad file location too.
  • JarFile - Required. Specifies jar file location.
  • Output - Optional. If specified, this is destination jad file location.
  • Url - Optional. If specified, value of MIDlet-Jar-URL attribute in jad file is updated with it.
  • Encoding - Optional. Encoding of destination jad file. If not specified, "UTF-8" is used.
  • Sign - Optional. Specifies if jar file should be signed. Default: false.
  • KeyStore - Semi-required. Required when Sign is true. Specifies keystore file location.
  • KeyStoreType - Optional. Specifies keystore type. Valid: Default, PKCS12. If not specified, type is recognized by extension of keystore file: ".p12" or ".pkcs12" extensions are recognized as PKCS12 type. Other extensions are recognized as Default type.
  • KeyStorePassword - Semi-required. Required when Sign is true. Specifies keystore file password.
  • Alias - Semi-required. Required when Sign is true. Specifies alias name.
  • AliasPassword - Semi-required. Required when Sign is true. Specifies alias key password.

Sample Usage:

<nb-jad jadfile="${dist.dir}/${dist.jad}" 
        jarfile="${dist.dir}/${dist.jar}"
        url="${dist.jar}"
        sign="${sign.enabled}"
        keystore="${sign.keystore}"
        keystorepassword="${sign.keystore.password}"
        alias="${sign.alias}"
        aliaspassword="${sign.alias.password}"
        encoding="${javac.encoding}"/>

<nb-run>

Run Task adds support for application running and debugging.

Important feature of nb-run task is ability to translate emualtor stack traces from bytecode offset form into a line number form. Some of the emulators do not show line numbers in stack trace when an exception is thrown. This translation feature helps to quickly locate a source of any exception thrown from the emulator within your source code. You need a library called ClassFile to enable this functionality. The library should be a part of Ant tasks definition classpath but the other functionality of nb-run task is not affected when the library is missing.

Attributes:

  • JadFile - Semi-required. Jad file location with application description. This is used/mandatory for standard/default execution method.
  • JadUrl - Semi-required. Jad file URL with application description. This is used/mandatory for OTA execution method. If not set, default execution method is forced.
  • PlatformHome - Required. Home directory location of platform/emulator.
  • PlatformType - Optional. Platform type - one of these: "UEI 1.0", "UEI 1.0.1" (default), Custom. When Custom is set, ExecMethod is ignored.
  • Device - Optional. Target device.
  • ExecMethod - Optional. One of these values: STANDARD (default), OTA.
  • ClassPath - Optional. Classpath required by classes in SrcDir. It supports nested classpath tag too.
  • ClassPathRef - Optional. Classpath specified by reference required by SrcJar classes.
  • SecurityDomain - Optional. Security domain.
  • Debug - Optional. Boolean value. True for run application in debugger. Default: false.
  • DebugAddress - Optional. Address debug property should contain only port number since localhost is assumed. If not set a free ephemeral port is used.
  • DebuggerAddressProperty - Optional. Name of the attribute for the debugger task that specifies the address to which the debugger will connect.
  • DebugTransport - Optional. Transport debug property. Default: dt_socket.
  • DebugServer - Optional. Server debug property. Default: true
  • DebugSuspend - Optional. Suspend debug property. Default: true
  • JarFile - Optional. Used to copy the Jad and Jar to a temporary folder for execution. The copy is performed when the Jad and Jar are located in the same folder only.
  • CmdOptions - Optional. Command line options added to the execution of emulator.
  • CommandLine - Semi-required. Command line for running emulator. Required when PlatformType is Custom. CommandLine attribute allows you to fully customize command line for running a emulator in execution or debug mode. Command Line string processed using EMapFormat class (see its javadoc for formatting hints). This task presets following identificators:
  • {platformhome} - always set - value of PlatformHome attribute
  • {device} - value of Device attribute
  • {classpath} - classpath string composed from ClassPath, ClassPathRef, nested ClassPath
  • {jadfile} - value of JadFile attribute
  • {jadurl} - value of JadUrl attribute
  • {securitydomain} - value of SecurityDomain attribute
  • {debug} - value of Debug attribute
  • {debugaddress} - value of DebugAddress attribute
  • {debugtransport} - value of DebugTransport attribute
  • {debugserver} - value of DebugServer attribute. Default: true.
  • {debugsuspend} - value of DebugSuspend attribute. Default: true.
  • {cmdoptions} - command line options propagated from project settings. Empty by default.
  • {/} - value of File.separator

If value of attribute is not set, its value is not passed to Command Line string formatter.

Sample Usage:

<nb-run debug="true"
        debugsuspend="true"
        debugserver="true"
        debuggeraddressproperty="jpda.port"
        platformtype="${platform.type}"
        platformhome="${platform.home}"
        device="${platform.device}"
        jadfile="${dist.dir}/${dist.jad}"
        jarfile="${dist.dir}/${dist.jar}"
        execmethod="${run.method}"
        securitydomain="${evaluated.run.security.domain}"
        commandline="${platform.debugcommandline}"
        classpath="${platform.bootclasspath}:${dist.dir}/${dist.jar}"
        cmdoptions="${run.cmd.options}"/>

<nb-extract>

ExtractTask Task adds support for extracting libraries from classpath.

Attributes:

  • ClassPath - Semi-required. Specifies classpath. All archives on classpath. It supports jar and zip archives only, not directories. If this attribute is not specified, you need to specified either ClassPathRef attribute or nested ClassPath tag.
  • ClassPathRef - Semi-required. Specifies classpath by reference.
  • Dir - Required. Specifies target directory in which all files from classpath should be extracted to.
  • ExcludeManifest - Optional. Specifies if META-INF/Manifest.mf files should be excluded from extraction. Default: false.

Nested ClassPath element - Semi-required. Specifies classpath using nested element.

Sample Usage:

<nb-extract dir="${build.classes.dir}" excludeManifest="true">
    <classpath>                                               
        <path path="${libs.classpath}"/>                      
    </classpath>                                              
</nb-extract>                                                 

<nb-output>

OutputTask Task adds support for writing properly encoded text into a file.

  • Attributes:
  • File - Required. Specifies file where the text will be written to.
  • Encoding - Optional. Specifies encoding used (system default file encoding is used by default).
  • Append - Optional. Specifies if the text should be appended to the file (false by default).
  • Text - Optional. Text to be written to the file (empty by default). Nested CDATA section may contain multi-line text.

Sample Usage:

<nb-output file="${dist.dir}/${dist.jad}" encoding="UTF-8" append="true">MicroEdition-Configuration: ${platform.configuration}
</nb-output>

<nb-overrideproperty>

This target is the extension of standard Property task except it overides the property (properties) if already defined.

Sample Usage:

<nb-overrideproperty name="buildsystem.baton" value="${src.dir}"/>

Back to Mobility

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo