ROXES ANT Tasks
Author:lars gersmann
Homepage:http://www.roxes.com/produkte/rat.html
Version:1.2 (2004-01-30)
Abstract:

ROXES ANT Tasks is a collection of Tasks for Jakarta Ant. The ANT Tasks provided by ROXES Technologies are created for multi platform deployment.

Table of contents

1.     Usage
2.     Tasks
2.1.         sfx
2.1.1.             Example
2.1.2.             Dynamic commandline example
2.2.         jstub
2.2.1.             Example
2.3.         jnlp
2.3.1.             Element information
2.3.1.1.                 Element title
2.3.1.2.                 Element vendor
2.3.1.3.                 Element homepage
2.3.1.4.                 Element description
2.3.1.5.                 Element icon
2.3.1.6.                 Element offline_allowed
2.3.2.             Element security
2.3.2.1.                 Element all_permissions
2.3.2.2.                 Element j2ee_application_client_permissions
2.3.3.             Element resources
2.3.3.1.                 Element j2se
2.3.3.2.                 Element jar
2.3.3.3.                 Element nativelib
2.3.3.4.                 Element extension
2.3.3.4.1.                     Element ext_download
2.3.3.5.                 Element property
2.3.3.6.                 Element package
2.3.4.             Element application_desc
2.3.4.1.                 Element argument
2.3.5.             Element applet_desc
2.3.5.1.                 Element parameter
2.3.6.             Element component_desc
2.3.7.             Element installer_desc
2.3.8.             An excurse about security in Java Web Start
2.3.9.             Example
2.4.         preferences
2.4.1.             Set Preferences data
2.4.1.1.                 Element boolean
2.4.1.2.                 Element bytearray
2.4.1.3.                 Element double
2.4.1.4.                 Element float
2.4.1.5.                 Element int
2.4.1.6.                 Element long
2.4.1.7.                 Element string
2.4.1.8.                 Example
2.4.2.             Element get
2.4.2.1.                 Example
2.4.3.             Element remove
2.4.3.1.                 Example
2.4.4.             Element test
2.4.4.1.                 Example
2.4.5.             Element export
2.4.5.1.                 Example
2.4.6.             Element import
2.4.6.1.                 Example
2.5.         properties
2.5.1.             Element merge
2.5.2.             Element property
2.5.3.             Example
2.6.         find
2.6.1.             Example
2.7.         compare
2.7.1.             Element equal
2.7.2.             Element greater
2.7.3.             Element greaterOrEqual
2.7.4.             Element lesser
2.7.5.             Element lesserOrEqual
2.7.6.             Element contains
2.7.7.             Example
2.8.         call
2.8.1.             Example
2.9.         os.properties
2.9.1.             List of created properties
2.9.2.             Example
2.10.         execute
2.10.1.             Example
2.11.         Unix related tasks
2.11.1.             unix.properties
2.11.1.1.                 Example
2.11.2.             unix.link
2.11.2.1.                 Example
2.11.3.             unix.kde.shortcut
2.11.3.1.                 Element property
2.11.3.2.                 Example
2.11.4.             unix.kde.shortcutdirectory
2.11.4.1.                 Element property
2.11.4.2.                 Example
2.12.         Win32 related tasks
2.12.1.             win32.properties
2.12.1.1.                 List of created properties
2.12.1.2.                 Example
2.12.2.             win32.registry
2.12.2.1.                 Element exists
2.12.2.1.1.                     Example
2.12.2.2.                 Element delete
2.12.2.2.1.                     Example
2.12.2.3.                 Element export
2.12.2.3.1.                     Example
2.12.2.4.                 Element get
2.12.2.4.1.                     example
2.12.2.5.                 Element import
2.12.2.5.1.                     Example
2.12.2.6.                 Element set
2.12.2.6.1.                     example
2.12.3.             win32.shortcut
2.12.3.1.                 examples
2.12.3.2.                 Excursion to the .url File Format
2.12.3.3.                 Complete HotKey Code Reference
3.     Dynamic commandline(s)

51. Usage

To use ROXES ANT Tasks you can add the jar file to Ant's lib directory or attach the jar to the CLASSPATH.

To make ROXES ANT Tasks available in your classpath simply add the following line to to head of your build.xml :

<taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>

Now you can use all ROXES ANT Tasks.

52. Tasks

52.1. sfx

sfx creates self extracting executables for various platforms.

sfx takes an archive and makes it executable for a variete of platforms. The started executable extracts to contents of the archive to a platform depended temp directory [temp-dir]/[executable] and executes an command int the extracted path.

sfx is very handy to create setup's. Zip the required resources of your application and make start script available for each platform. That's all you need.

Version 1.2 introduced new customization features for dynamic commandline parameters. Both enviroment and registry (for win32* modes only :-) expressions can be used in the execute and workingDirectoryparameter (See chapter Dynamic commandline(s) for details).

Version 1.2 also includes the often requested custom icon feature (for win32* and java modeonly). The icon parameter lets you define a custom icon (provided as gif file) which is patched into the executable as its default icon.

Attributes

Name Description Required
archive the zip/jar archive to use yes
mode 5 types of self executables can be created by sfx
  • win32

    Creates a win32 executable (exe file) which is executed without opening a shell window. Use this mode for silent extraction.

  • win32-console

    Creates a win32 executable (exe file) which is executed by opening a shell window. All output goes to the console.

  • unix

    Creates an executable shell script (sh file) which is executed

    1. silent when opened outside a shell
    2. with output when opened in a shell

  • java

    Creates a executable java jar file which opens a status window with extraction progress bar.

  • java-console

    Creates a executable java jar file which opens a console shell window. All output goes to the console.

yes
icon

The icon parameter defines an executable icon. The icon is used in mode win32, win32-console, java and java-console.

The icon can be provided in any format readable from Java (gif, jpg, png and so on).

The icon SHOULD be provided in 256 color depth. Otherwise the displayed icon may shown incorrect. It is also a good advise to provide the icon with 32x32 pixels. Otherwise it is reduced to 32x32 which may sometimes look ugly.

For windows executables the icon is also patched into the executable binary.

no
execute

The command to execute after successful extraction.

The command is executed

  1. in the temp directory where the files were extracted when no workingDir was defined.
  2. in the workingDir inside the temp directory if workingDir was defined.

In case of executables created for windows the execute will be executed with "command /B" (for Windows 95/98) or "cmd /B" (Windows NT/2000/XP).

The execute parameter may contain Dynamic commandline(s) which are evaluated at runtime.

Version 1.2: execute can also be defined using a child element <execute>.

yes
output The name of the output file (setup.exe or setup.sh for example). yes
workingDirectory

The working directory were the command defined in execute should be executed.

If not defined the command will be executed with the extraction path as working directory.

The path separator used in workingDir can always be a slash (/). It is transformed to the platform dependend path separator by sfx.

The workingDirectory parameter may contain Dynamic commandline(s) which are evaluated at runtime.

Version 1.2: workingDirectory can also be defined using a child element <workingDirectory>.

no

52.1.1. Example

Suppose an sample application named layxx with the following directory structure

bin/
  layxx.bat
  layxx.sh
lib/
  layxx.jar
  common.jar
native/
  common.dll
  common.so
doc/
  index.html

  1. Zip the directory structure to an archive (layxx.zip for example).

  2. Create a Ant make file with the following content:

    build.xml
    <?xml version="1.0"?>  
    <project basedir="." name="layxx" default="sfx">
      <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
     
      <target name="sfx">
          <!-- create windows executable -->
        <sfx
        archive="layxx.zip"
        mode="win32"
        workingDirectory="/bin"
        execute="hello.bat"
        output="layxx.exe"
      />
            <!-- create windows console executable -->
      <sfx
        archive="layxx.zip"
        mode="win32-console"
        workingDirectory="bin"
        execute="layxx.bat"
        output="layxx-console.exe"
      />
        <!-- create unix executable -->
      <sfx
        archive="layxx.zip"
        mode="unix"
        workingDirectory="/bin"
        execute="layxx.sh"
        output="layxx"
      />
        <!-- create java console executable -->
      <sfx
        archive="layxx.zip"
        mode="java-console"
        execute="javaw -jar layxx-console.jar"
        output="layxx-console.jar"
      />
            <!-- create java executable -->
      <sfx
        archive="layxx.zip"
        mode="java"
        execute="javaw -jar layxx.jar"
        output="layxx.jar"
      />
      </target>
    </project>

Thats it. After running Ant you have 5 exectables created by sfx.

When starting the windows executable created by this example the contents of the executable are extracted to [temp-dir]/layxx.exe, the current directory is set to [temp-dir]/layxx.exe/bin and layxx.bat will be started.

As you can see in the example you don't really need to create start scripts for your application. It is also possible to pack the whole start command into the execute attribute.

Attention windows exececutable creators : The created java jar files are only working successfully when started from command line. Otherwise the current working directory is not known and the archive cannot extract itself.

52.1.2. Dynamic commandline example

The following example shows you how to use dynamic commandline feature of the sfx task.

<?xml version="1.0"?>  
<project basedir="." name="foo" default="main">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
 
  <target name="main">
    <sfx
    archive="foo.jar"
    mode="win32"
        icon="images/foo.gif"
    execute="javaw -cp lib; -Djava.ext.dirs=${env:TOMCAT_HOME|c:\tomcat}\common\lib -Ddesktop=${reg:HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Desktop} foo.bar"
    output="foo.exe"
  />
     
      <sfx
    archive="foo.jar"
    mode="unix"
    execute="java -cp lib; -Djava.ext.dirs=${env:TOMCAT_HOME|c:\tomcat}\common\lib -Ddesktop=${env:HOME\Desktop} foo.bar"
    output="foo.exe"
  />  
  </target>
</project>

The created executable will extract the contents to the temp directory, evaluates the ccommandline string and executes it.

The evaluation replaces ${env:TOMCAT_HOME|c:\tomcat} by the value of enviroment variable TOMCAT_HOME or (if it not exists) by c:\temp.

On windows: ${reg:HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Desktop} will be replaced by the path of the windows desktop directory or an empty string (if it is not found).

On unix: ${env:HOME\Desktop} will be replaced by the pathof the kde desktop directory or an empty string (if it is not found).

How does it work ?

For win32 and unix modes the zip file will be appended to a native stub (an exe for win32, shell script for unix).

At execution time the executable unzips itself ! In general the magic behind extraction is the ZLib library. The ZLib library library tries not to read the zip stream at start of file instead the library seeks forward until the zip header signature is found. Is'nt it easy and elegant ?

52.2. jstub

jstub creates native executables from jar files.

You never need to create shell scripts to start you application. The only thing which has to be installed is java itself.

New since version 1.1 is support for commandline arguments. They will appended to the given execute string.

Also introduced in version 1.1 is the automatic executable detection for Windows executables (feature proposed by jc dufourd). This feature allows to use a placeholder for the executable inside the given commandline option. The executable evaluates its name and path at runtime and replaces the placeholder before executing them. See the examples.

Version 1.2 introduced new customization features for dynamic commandline parameters. Both enviroment and registry (for win32* modes only :-) expressions can be used in the execute (See chapter Dynamic commandline(s) for details).

Version 1.2 also includes the often requested custom icon feature (for win32* and java modeonly). The icon parameter lets you define a custom icon (provided as gif file) which is patched into the executable as its default icon.

Since version 1.2 you the archive attribute is no more required. This gives you the ability to create executablke wrappers for almost anything !!

Properties

Name Description Required
archive

the zip/jar archive to use.

Since version 1.2 the archive attribute is no more required to give developers the ability to create windows executables executing shell commands.

no
execute

The command line to execute.

When your archive is an regular executable jar file (containing a manifest with guilty main-class attribute) execute has to be java -jar [output] where [output] is the name of the generated executable.

Since Version 1.1 the commandline to execute can contain the placeholder XYZjstubLocationXYZ which is replaced at runtime by path and name of the executable. This feature is Windows specific.

The execute parameter may contain Dynamic commandline(s) which are evaluated at runtime.

Version 1.2: execute can also be defined using a child element <execute>.

yes
icon

The icon parameter defines an executable icon. The icon is used in mode win32, win32-console, java and java-console.

The icon can be provided in any format readable from Java (gif, jpg, png and so on).

The icon SHOULD be provided in 256 color depth. Otherwise the displayed icon may shown incorrect. It is also a good advise to provide the icon with 32x32 pixels. Otherwise it is reduced to 32x32 which may somtimes look ugly.

For windows executables the icon is also patched into the executable binary.

no
mode 3 types of self executables can be created by sfx
  • win32

    Creates a win32 executable (exe file) which is executed without opening a shell window.

  • win32-console

    Creates a win32 executable (exe file) which is executed by opening a shell window. All output goes to the console.

  • unix

    Creates an executable shell script (sh file) which is executed

    1. silent when opened outside a shell
    2. with output when opened in a shell

yes
output The name of the output file (myapp.exe or myapp.sh for example). yes

52.2.1. Example

Suppose you have a working self executable jar file which is named myapp.jar.

build.xml
<?xml version="1.0"?>  
<project basedir="." name="myapp" default="main">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
 
  <target name="main">
    <jstub
      archive="myapp.jar"
      mode="win32"
      execute="java -jar myapp.exe"
      output="myapp.exe"
    />
</target>
</project>

In case of a jar file which contains all resources required by your application named myapp.zip and is not a self executable jar file with main class com.mycompany.myapp you can use the following example.

build.xml
<?xml version="1.0"?>  
<project basedir="." name="myapp" default="main">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
 
  <target name="main">
    <jstub
      archive="myapp.jar"
      mode="win32"
      execute="java -cp myapp.exe com.mycompany.myapp"
      output="myapp.exe"
    />
</target>
</project>

The example below uses the commandline placeholder XYZjstubLocationXYZ:

build.xml
<?xml version="1.0"?>  
<project basedir="." name="myapp" default="main">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
 
  <target name="main">
    <jstub
      archive="myapp.jar"
      mode="win32"
      execute="java -cp XYZjstubLocationXYZ com.mycompany.myapp"
      output="myapp.exe"
    />
</target>
</project>

The key difference to the example before is that you can rename the application or put it somewhere in the path. The placeholder XYZjstubLocationXYZ will be replaced before execution by the real name and path of the executable.

An scenario: You rename the executable (configured with commandline javaw -cp XYZjstubLocationXYZ com.mycompany.myapp) to test.exe and store it under c:\winnt (which is registered in the PATH enviroment). When opening a console in c:\temp and execute test.exe the executable substitutes the placeolder and executes java -cp c:\winnt\test.exe com.mycompany.myapp.

Only the first placeholder will be replaced. Multiple placeholders will be ignored.

This example shows how to create a unix executable using dynamic commandline substitution.

build.xml
<?xml version="1.0"?>  
<project basedir="." name="myapp" default="main">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
 
  <jstub output="test.sh" mode="unix" archive="../layxx.jar">
    <execute>
      java -cp "${env:PATH}" -jar "${app:absolutepath}"
    </execute>
  </jstub>
</project>

The executable will execute java with the contents of the PATH environment variable as classpath and the executable itself as jar file.

How does it work ?

The jstub native stubs (written in c) originally contains only a few lines of code -

int main( int argc char** argv)
{
  system( "java -jar %s", (char*)&argv[0]);
 
  return 0;
}

which executes java using the executable as regular jar file.

For win32 and unix modes the zip file will be appended to a native stub (an exe for win32, shell script for unix).

In general the magic behind extraction is the ZLib library. The ZLib library library tries not to read the zip stream at start of file instead the library seeks forward until the zip header signature is found. Is'nt it easy and elegant ?

When i read about zlib and who the hell the ZLib library includes in his software (Adove, Sun etc.) i thought "Why not try to attach an executable as jar file to java ?" - and it works ! You can attach almost any file which has a guilty ZIP header signature inside as jar file to java's classpath.

In short terms: Take any file you want and append a jar file and it will be accepted as regular jar file from java.

52.3. jnlp

The jnlp task generates a Java Webstart xml file. In general the task is very easy.

The reason we wrote jnlp is to have a smart integration within Ant. Regularly you have to enter every jar/native library required by you application into the jnlp file. Using the jnlp task you can delegate this task to Ant using FileSet's.

In general the jnlp task is exactly the same like JNLP File Format with 2 differences

Properties

Name Description Required
codebase The URI describing the download location. yes
encoding

The encoding to use for the output xml file. If undefined it is set to UTF-8.

New feature since version 1.2.

no
spec

application being launched, as well as the version of the JNLP file itself.

The according Java Webstart specification of the file. This attribute defaults to 1.0+ if not set.

no
version The codebase attribute of the jnlp element specifies the codebase for the application. This is also used as the base URL for all relative URLs in href attributes. yes
toFile the file to write the resulting jnlp file yes

jnlp task contains many nested elements reflecting the structure of JNLP File Format

52.3.1. Element information

The information element contains various descriptive information about the application being launched.

This element may occur multiple times for different locales.

Properties

Name Description Required
locale The locale attribute of the information element specifies the locale for which this information element should be used. no

52.3.1.1. Element title

The title element contains the name of the application.

52.3.1.2. Element vendor

The vendor element contains the name of the vendor.

52.3.1.3. Element homepage

The homepage element contains a href attribute to the homepage for the application.

Properties

Name Description Required
href The href attribute of the homepage element specifies the URL for the homepage. yes

52.3.1.4. Element description

This Element may occur multiple times.

Properties

Name Description Required
kind The kind attribute for the description element indicates the use of a description element. The values are
  • one-line

    for a one-line description

  • short

    for a one paragraph description

  • tooltip

    for a tool-tip description

Longer descriptions should be put on a separate web page and referred to using the homepage element.
no

52.3.1.5. Element icon

This element may occure multiple times depending of the kind of use.

Properties

Name Description Required
href The href attribute of an icon contains a URL to a location on the web containing an image file for an icon. The file must be in either JPEG or GIF format. yes
version The version attribute of an icon contains a string describing the version of the image that is requested. no
width The width attribute of the icon element describes the width of the icon in pixels. no
height The height attribute of the icon element describes the height of the icon in pixels. no
kind

The kind attribute of the icon element describes the use of the icon.

Valid values are default, selected, disabled and rollover.

no
depth The depth attribute of the icon element describes the color depth of the image in bits-per-pixel. Common values will be 8, 16, or 24. no
size The size attribute of an icon element indicates the size of an icon file in bytes. no

52.3.1.6. Element offline_allowed

The offline-allowed element indicates if the application can be launched offline. Default value (i.e., if the element is not specified) is online.

52.3.2. Element security

The security element describes the security requirements of the application.

52.3.2.1. Element all_permissions

The all-permissions element indicates that the application needs full access the the local system and network.

52.3.2.2. Element j2ee_application_client_permissions

The j2ee-application-client-permissions element indicates that the application needs the set of permissions defined for a J2EE application client.

52.3.3. Element resources

The resources element contains an ordered set of resources that constitutes an application.

The nested resources element lets you specify jars, native libs and extensions that you want to add to the JNLP launch descriptor. You can use any number of nested fileset's, jars, native libs or extensions. Note, that only files ending with jar, dll, so, or jnlp will be accepted and that resources must be defined inside a jnlp element.

The most importatn point of this task is that multiple Ant FileSet instances can be added as sub elements. All matching files of the Ant FileSet's will be added either as jar element or nativelib element.

Properties

Name Description Required
os The os attribute of the resources element specifies for which operating system this element should be considered. no
arch The arch attribute of the resources element specifies for what platform this element should be considered. no
locale The locale attribute of the resources element specifies for which locales this element should be considered. no

52.3.3.1. Element j2se

The j2se element describes a supported JRE version and an optional resources element to be used by the particular JRE.

Properties

Name Description Required
version The version attribute of the j2se element describes the versions of the JRE that this application is supported on. no
href The href attribute of the j2se element specifies the location where the JRE should be downloaded from. no
initial-heap-size The initial-heap-size attribute of the j2se element specifies the initial size of the object heap. no
max-heap-size The max-heap-size attribute of the j2se element specifies the preferred maximum size of the object heap. no

The j2se element can also contain resources elements.

52.3.3.2. Element jar

The jar element describes a jar file resource.

Properties

Name Description Required
href The href attribute of the jar element contains the location of a jar file as a URL. yes
version The version attribute of a jar element describes the version of a particular JAR file that is requested. no
main

The main attribute of a jar element indicates whether this element contains the main class (true | false).

The atribute defaults to false.

no
download

The download attribute of a jar element indicates if this element must be downloaded before an application is launched (eager), or not (lazy).

The attribute defaults to eager.

no
size The size attribute of a jar element indicates the size of a JAR file in bytes. no
part The size attribute of a jar element indicates the size of a JAR file in bytes. no

52.3.3.3. Element nativelib

The nativelib element describes a resource containing native files.

Properties

Name Description Required
href The href attribute of a nativelib element contains the location of a nativelib file as a URL. yes
version The version attribute of a nativelib element describes the version of a particular nativelib file that is requested. no
download

The download attribute of a nativelib element indicates if this element must be downloaded before an application is launched (eager), or not (lazy).

The attribute defaults to eager.

no
size The size attribute of a nativelib element indicates the size of a nativelib file in bytes. no
part The part attribute of a nativelib element describes the name of the part it belongs to. no

52.3.3.4. Element extension

The extension element describes an extension that is required in order to run the application.

Properties

Name Description Required
version The version attribute of an extension element specifies the version of the extension requested. no
name The name attribute of an extension element specifies the name of the extension. no
href

The href attribute of an extension element specifies the location of the extension.

The attribute defaults to eager.

yes

52.3.3.4.1. Element ext_download

The ext_download element defines how parts of the extension are downloaded.

Properties

Name Description Required
ext_part The ext-part attribute of an ext-download element describes the name of a part in the extension. yes
download

The download attribute of an ext-download element describes if the resource may be lazily downloaded (lazy|eager).

The attribute defaults to eager.

no
part The part attribute of an ext-download element describes the name of the part it belongs to in the current JNLP file. yes

52.3.3.5. Element property

The property element describes a name/value pair that is available to the launched application as a system property.

Properties

Name Description Required
name The name attribute of the property element describes the name of a system property. yes
value The value element describes the value of a system property. yes

52.3.3.6. Element package

The package element defines a relationship between a Java package or class name and a part.

Properties

Name Description Required
name The name attribute of the package element describes the name of a package or class. yes
part The part attribute of the package element describes the part that contains the specified package or class. yes
recursive

The recursive attribute of the package element indicates if all subpackages of this particular package is also included.

The attribute defaults to false.

no

52.3.4. Element application_desc

The application-desc element describes how to launch a Java-based application. It contains information about the main class and arguments.

Properties

Name Description Required
main_class The main-class attribute of the application-desc element describes the main class of an application. yes

52.3.4.1. Element argument

The argument elements describe the ordered set of arguments to an application. These arguments will be passed into the main method of the application’s main class.

52.3.5. Element applet_desc

The applet-desc element describes how to launch a Java Technology-based Applet. It contains information about, e.g., the main class, size, and parameters.

Properties

Name Description Required
documentbase The documentbase attribute of the applet-desc element describes the documentbase for the applet as a URL. no
main_class The main-class attribute of the applet-desc element describes the name of the main Applet class. yes
name The name attribute of the applet-desc element describes the name of the Applet. yes
width The width attribute of the applet-desc element describes the width of the Applet in pixels. yes
height The height attribute of the applet-desc element describes the height of the Applet in pixels. yes

52.3.5.1. Element parameter

The param element describes a parameter to an Applet.

Properties

Name Description Required
name The name attribute of the param element describes the name of a parameter. yes
value The value attribute of the param element describes the value of a parameter. yes

52.3.6. Element component_desc

The component-desc element specifies a component extension.

52.3.7. Element installer_desc

The installer-desc element specifies an installer extension.

Properties

Name Description Required
main_class The main-class attribute of the installer-desc element describes the main class for the installer/uninstaller. yes

52.3.8. An excurse about security in Java Web Start

Java Webstart addresses the security issues of

Applications launched with Java Webstart are -- by default -- run in a restricted environment where they have limited access to local computing resources, such as storage devices and the local network. In this sandbox environment, Java Webstart can guarantee that a downloaded and potentially untrusted application cannot compromise the security of the local files or the network.

An additional security feature supported by Java Webstart is digital code signing. If an application being invoked is delivered in one or more signed JAR files, Java Webstart will verify that the contents of the JAR file have not been modified since they were signed. If verification of a digital signature fails, Java Webstart will not run the application, since it may have been compromised by a third-party.

The support for code signing is important for both users and for application service providers. This service makes it possible for users to verify that an application comes from a trusted source. Because the application service provider signs the code, both can be ensured that no other party can impersonate the application on the Web. A signed application that is trusted by the user can also request additional system privileges, such as access to a local disk.

Java Webstart presents a dialog displaying the application's origin, based on the signer's certificate, before the application is launched. Thereby allowing the user to make an informed decision whether to grant additional privileges to the downloaded code, or not.

An application can request full access to a client system when all its JAR files are signed by including the following settings in the JNLP file:

<security>
<all-permissions/>
</security>

The implementation of code signing in Java Webstart is based on the security API in the core Java 2 Platform. The Java 2 SE JRE 1.2.x supports code signing with the SHAwithSDA algorithm. Java 2 SE JRE 1.3 also supports MD2withRSA and MD5withRSA. The MD5withRSA is currently the most often used algorithm.

Developers sign code for use with Java Webstart in the same manner as for Java Applets by using the standard jarsigner tool from the Java 2 SE SDK. The documentation for the jarsigner tool provides examples on how to sign code, create test certificates, and other signing related issues.

Java Webstart also support use of the Netscape signtool when used with the Java 2 SE JRE 1.3.0. See the Netscape Web site for details: http://developer.netscape.com/software/signedobj/

52.3.9. Example

Suppose the following directory structure of an application foo

/
  lib/
    foo.jar
    common.jar
    gui.jar
  native
    foo.dll

The following sample Ant build file creates a jnlp file using jnlp task:

<?xml version="1.0"?>  
<project basedir="." name="foo" default="main">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
 
  <target name="main">
    <jnlp toFile="foo.jnlp" href="foo.jnlp" codebase="http://www.foo.com/products/foo/jws-start">
      <information>
        <title>Foo</title>
        <vendor>Foo Bar Limited</vendor>
        <homepage href="http://www.foo.com/products/foo"/>
        <icon kind="splash" href="images/splash.gif"/>
        <icon href="logo.gif"/>
        <description>Foo is an extremely useful application for doing almost everything</description>
        <description kind="tooltip">Foo - the extremely useful application</description>
        <offline_allowed/>
      </information>
     
      <security>
    <all_permissions/>
      </security>
     
      <resources>
        <j2se version="1.4+"/>
        <fileset dir="." includes="**/*.jar, **/*.lib"/>
      </resources>
      <application_desc main_class="com.foo.Main"/>
    </jnlp>  
  </target>
</project>

The file set is expanded by the jnlp task and the matched resources are added to the generated jnlp file:

<jnlp href="foo.jnlp" codebase="http://www.foo.com/products/foo/jws-start">
  <information>
    <title>Foo</title>
    <vendor>Foo Bar Limited</vendor>
    <homepage href="http://www.foo.com/products/foo"/>
    <icon kind="splash" href="images/splash.gif"/>
    <icon href="logo.gif"/>
    <description>Foo is an extremely useful application for doing almost everything</description>
    <description kind="tooltip">Foo - the extremely useful application</description>
    <offline-allowed/>
  </information>
 
  <security>
      <all-permissions/>
  </security>
 
  <resources>
    <j2se version="1.4+"/>
    <jar href="lib/foo.jar"/>
    <jar href="lib/common.jar"/>
    <jar href="lib/gui.jar"/>
    <nativelib href="native/foo.dll"/>
  </resources>
  <application-desc main-class="com.foo.Main"/>
</jnlp>

As you can see, alle jar, dll and so files are added to the jnlp file.

52.4. preferences

The preferences task is the interface to the Java Preferences API (available since JAVA 1.4).

preferences let's you read, write, test, import and export data out of the Java Preferences Store. Use this task to setup the required Preferences data for your application.

The preferences task is able to handle a bunch of sub elements containing various commmands executed on the specified part of the Preferences.

You can combine the elements in any kind. The elements (i.e. commands) will be executed in the same order they are defined in the make file.

Attributes

Name Description Required
type Type value has to be either user or system. Depending on the type value a Preferences root will be used. yes
path

The base path of the Preferences subtree to work on. If the given path does not exists it will be created.

no

52.4.1. Set Preferences data

The preferences Task provides sub elements to set entries for each data type defined in the Preferences API.

52.4.1.1. Element boolean

The boolean element defines a single boolean data entry in a Preferences node.

Attributes

Name Description Required
name The name of the entry. yes
value

The value will be taken either from attribute value or from the body of the element. The value must be compatible with the boolean type (either true or false).

yes
path

The path of the node where the entry should set. The path is used relative to the base path defined in the preferences task. If the given path does not exists it will be created.

no

52.4.1.2. Element bytearray

The bytearray element defines a single bytearray data entry in a Preferences node.

Attributes

Name Description Required
name The name of the entry. yes
value

The value will be taken either from attribute value or from the body of the element. bytearray data is defined as a bunch of numbers (representing single bytes) separated by a separator.

yes
path

The path of the node where the entry should set. The path is used relative to the base path defined in the preferences task. If the given path does not exists it will be created.

no
separator

The separator defines the characters which separate the numbers of single bytes.

separator defaults to ", " which means that without defining a special separator you can simply write your data comma separated (1,5,120,-4 for example).

no
radix

The radix defines the encoding of a number representing a single byte .

radix defaults to 10 which means that an entry will be edited decimal encoded (set radix to 16 for hexadecimal encoding etc).

no

52.4.1.3. Element double

The double element defines a single double data entry in a Preferences node.

Attributes

Name Description Required
name The name of the entry. yes
value

The value will be taken either from attribute value or from the body of the element. The value must be compatible with the double type (a number either specified in scientific or simplified syntax).

yes
path

The path of the node where the entry should set. The path is used relative to the base path defined in the preferences task. If the given path does not exists it will be created.

no

52.4.1.4. Element float

The float element defines a single float data entry in a Preferences node.

Attributes

Name Description Required
name The name of the entry. yes
value

The value will be taken either from attribute value or from the body of the element. The value must be compatible with the float type (a number either specified in scientific or simplified syntax).

yes
path

The path of the node where the entry should set. The path is used relative to the base path defined in the preferences task. If the given path does not exists it will be created.

no

52.4.1.5. Element int

The int element defines a single int data entry in a Preferences node.

Attributes

Name Description Required
name The name of the entry. yes
value

The value will be taken either from attribute value or from the body of the element. The value must be compatible with the int type (a integer number).

yes
path

The path of the node where the entry should set. The path is used relative to the base path defined in the preferences task. If the given path does not exists it will be created.

no

52.4.1.6. Element long

The long element defines a single long data entry in a Preferences node.

Attributes

Name Description Required
name The name of the entry. yes
value

The value will be taken either from attribute value or from the body of the element. The value must be compatible with the long type (a integer number).

yes
path

The path of the node where the entry should set. The path is used relative to the base path defined in the preferences task. If the given path does not exists it will be created.

no

52.4.1.7. Element string

The string element defines a single text data entry in a Preferences node.

Attributes

Name Description Required
name The name of the entry. yes
value

The value will be taken either from attribute value or from the body of the element.

yes
path

The path of the node where the entry should set. The path is used relative to the base path defined in the preferences task. If the given path does not exists it will be created.

no

52.4.1.8. Example

Set Preferences data
<?xml version="1.0"?>  
 
  <project basedir="." name="foo" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
      <preferences type="user" path="com/roxes/tools/foo">
        <string name="workingDir" value="${app.home}/"/>
        <string name="lru">
          ${app.home}/examples/test.bar,${user.home}/examples/trial.bar
        </string>
        <bytearray name="signature" path="bar">  
            1, 127, 34, 5, 33 <!-- heading/trailing spaces will be removed -->
        </bytearray>
        <bytearray name="sig2" path="bar/signatures" radix="16" separator=":">  
            01:7F:0A:5:3:7
        </bytearray>
        <int name="listeners" path="current/version" value="0"/>
      </preferences>
    </target>
  </project>

52.4.2. Element get

get copies a Preferences data entry into a property.

Attributes

Name Description Required
name The name of the entry to retrieve. yes
property The name of the property to use as entry data container. yes
path

The path of the node. The path is used relative to the base path defined in the preferences task. If the given path does not exists an exception will be thrown.

no
defaultValue

If the entry was not found in the Preferences path, the defaultValue will be returned, otherwise the property will be not set.

no

52.4.2.1. Example

The following example queries a Preferences entry and prints the value.

<?xml version="1.0"?>  
 
  <project basedir="." name="foo" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
      <preferences type="user" path="com/roxes/tools/foo">
        <get name="signature" path="bar" property="signature"/>  
      </preferences>
      <echo message="Signature is ${signature}"/>
    </target>
  </project>

52.4.3. Element remove

remove removes a node (subtree) or data entry of the Preferences.

Attributes

Name Description Required
name The name of the entry to remove. yes (if node is not given)
node The name of the node (subtree) to remove. yes (if name is not given)
path

The path of the node. The path is used relative to the base path defined in the preferences task. If the given path does not exists an exception will be thrown.

no

Either name(to remove a data entry) or node(to remove a node/subtree) must be set.

52.4.3.1. Example

The following example removes a entry and a subtree.

<?xml version="1.0"?>  
 
  <project basedir="." name="foo" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
      <preferences type="user" path="com/roxes/tools/foo">
        <remove name="signature" path="bar"/>  
       
        <remove node="current" path="bar"/>
      </preferences>
    </target>
  </project>

52.4.4. Element test

test checks if either a node of a entry exists. Furthermore you can test a data entry against a user defined value. test sets a property as result of the condition.

Attributes

Name Description Required
name The name of the entry to remove. yes (if node is not given)
node The name of the node (subtree) to remove. yes (if name is not given)
property The name of the property to set if the condition is fulfilled. yes
path

The path of the node. The path is used relative to the base path defined in the preferences task. If the given path does not exists an exception will be thrown.

no
value

If value is defined test checks first if the entry exists and second compares the data entry with this value. if the values are equals the property will be defined.

no

Either name(to remove a data entry) or node(to remove a node/subtree) must be set.

52.4.4.1. Example

<?xml version="1.0"?>  
 
  <project basedir="." name="foo" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="check">
      <preferences type="user" path="com/roxes/tools/foo">
          <!--
            property version_found will be defined if
            node current/version exists
          -->
        <test path="current" node="version" property="version_found"/>
          <!--  
            property listeners_ok will be defined if entry listeners
            exists in current/version and its value is 2
          -->
        <test path="current/version" name="listeners" value="2" property="listeners_ok"/>
      </preferences>
    </target>
  </project>

52.4.5. Element export

export exports the entries of a node or the whole subtree into a file.

Attributes

Name Description Required
file The file to export to. yes
path

The path of the node. The path is used relative to the base path defined in the preferences task. If the given path does not exists an exception will be thrown.

no
noSubElements

If noSubElements is defined to be true export exports only data entries of the node.

no

52.4.5.1. Example

<?xml version="1.0"?>  
 
  <project basedir="." name="foo" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="check">
      <preferences type="user" path="com/roxes/tools/foo">
          <!-- export whole subtree -->
        <export file="foo.xml"/>
          <!-- export only data entries of the path -->
        <export noSubElements="true" file="foo-entries.xml"/>
      </preferences>
    </target>
  </project>

The file format is defined here.

52.4.6. Element import

import imports data from one ore more files into Preferences.

Attributes

Name Description Required
file The file to import from. yes (if no inner fileset is defined)
one ore more filesets The files to import from. You can define one ore more filesets inside this element. All matching files will be imported. yes (if file is not defined)

Due the restrictions of the Java Preferences API the import is everytime absolute which means that the node to import to is defined in the import xml file.

52.4.6.1. Example

<?xml version="1.0"?>  
 
  <project basedir="." name="foo" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="check">
      <preferences type="user" path="com/roxes/tools/foo">
        <import file="foo.xml"/>
        <import>
          <fileset dir="." includes="preferences*.xml"/>
          <fileset dir="./preferences" includes="**/*_pref.xml"/>
        </import>
      </preferences>
    </target>
  </project>

The file format is defined here.

52.5. properties

The properties task can write a property file. You can merge existing property files and set properties (conditional set of properties supported !) out of Ant.

Attributes

Name Description Required
file the properties file to create. yes
header The header to use for the properties file. This property can also be set using inner element <header>. no
overwrite If the propertyfile exists and overwrite is false, it is readed. Otherwise it will be overwritten. overwrite defaults to true. no

52.5.1. Element merge

The merge element is a Ant FileSet used to define a set of property files to merge into properties. Every file defined by the Ant FileSet is interpreted as property file and in order of occurence merged into the properties represented by this task.

The merge element may occur only once.

See Ant FileSet for details.

52.5.2. Element property

To define a property you can use element property.

The property element supports various conditions which affect's in setting the property or not.

Attributes

Name Description Required
name The name of the property. yes
value The value of the property. The value can also be set by attaching the text as element content. yes
Condition attributes (only one condition can be defined)
if The property will be set only if a property with this name exists. false
unless The property will be set only if no property with this name exists. false
available

The property will be set only if the resource or class exists.

In case of a Java class the existence will be tested using Class.forName( class).

In case of a Resource the existence will be tested using ClassLoader.getSystemResource( resource).

false
istrue The property will be set if the attribute value is "true" (ignoring case). false
isfalse The property will be set if the queried property does exist and the attribute value is "false" (ignoring case). false

52.5.3. Example

build.xml
<?xml version="1.0"?>  
<project basedir="." name="properties-test" default="main">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
 
 
  <target name="main">
    <property name="myProp" value="hach"/>
   
    <properties file="deploy/test.properties">
      <header>
        a header (myProp=${myProp})
      </header>
        <!--
          merge all property files in directory deploy
        -->
      <merge dir="deploy" includes="**/*.properties"/>
     
        <!-- add property "one" -->
      <property name="one" value="1"/>
     
        <!--
          add property "myProp_exists"
          if a property "myProp" exists
          (-> will succeed)
        -->
      <property name="myProp_exists" value="yes" if="myProp"/>
        <!--
          add property "yourProp_exists"
          if a property "yourProp" exists
          (-> will fail)
        -->
      <property name="yourProp_exists" value="yes" if="yourProp"/>
        <!--
          add property "myProp_notexists"
          if property "myProp" not exists
          (-> will fail)
        -->
      <property name="myProp_notexists" value="yes" unless="myProp"/>
     
        <!--
          add property "yourProp_notexists"
          if property "yourProp" not exists
          (-> will succeed)
        -->
      <property name="yourProp_notexists" value="yes" unless="yourProp"/>
     
        <!--
          add property "class_test_available"
          if a class or resource "test" exists
          (-> will fail)
        -->
      <property name="class_test_available" value="yes" available="test"/>
     
        <!--
          add property "class_com_roxes_tools_ant_PropertiesTask_exists"
          if class or resource "com.roxes.tools.ant.PropertiesTask" exists
          (-> will succeed)
        -->      
      <property name="class_com_roxes_tools_ant_PropertiesTask_exists" value="yes" available="com.roxes.tools.ant.PropertiesTask"/>
     
        <!--
          add property "trueistrue"
          if istrue attribute value is "true"
          (-> will succeed)
        -->
      <property name="trueistrue" value="yes" istrue="true"/>
        <!--
          add property "falseistrue"
          if istrue attribute value is "false"
          (-> will fail)
        -->
      <property name="falseistrue" value="yes" istrue="false"/>
        <!--
          add property "trueisfalse"
          if isfalse attribute value is "false"
          (-> will fail)
        -->
      <property name="trueisfalse" value="yes" isfalse="true"/>
        <!--
          add property "falseisfalse"
          if isfalse attribute value is "false"
          (-> will succeed)
        -->
      <property name="falseisfalse" value="yes" isfalse="false"/>
    </properties>
  </target>
</project>

52.6. find

The find task finds a single file matching a given pattern. This task gives you the ability to get the filename, path etc. into separate ant properties.

This task is useful if you use files containing version and build informations which may vary over the time. Using find you can match the requested file by its constant name parts.

If more than one file will be found the first one will be taken. Additional a warn message will be written.

If no matching file was found no property will be defined.

Attributes

Name Description Required
dir The base directory for the search. yes
file

The file pattern to match. Every file matching the pattern will be accepted. The pattern format for the file attribute is identical to the one of Ant FileSet includes pattern format.

The file property can also be set by using the inner element <file> (which is Ant FileSet conform).

yes if no inner element <file> is defined.
nameNoExtensionProperty This property will contain the name of the found file witout path and extension. yes if no other *Property attribute is defined.
nameProperty This property will contain the name of the found file without path. yes if no other *Property attribute is defined.
pathProperty This property will contain the path of the found file (without name). yes if no other *Property attribute is defined.
property This property will contain the path and name of the found file. yes if no other *Property attribute is defined.

52.6.1. Example

Suppose you want to use the a library file (my-custom-tasks-*.jar) which contains version and build informations and don't want to modify the build file everytime you use a new version of it.

build.xml
<?xml version="1.0"?>  
<project basedir="." name="properties-test" default="main">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
  <target name="main">
      <!--
        find the jar file and put its name
        into property "custom-tasks-jarfile"
      -->
    <find dir="lib"
          file="my-custom-tasks-*.jar"
          nameProperty="custom-tasks-jarfile"
    />
      <!--
        use the jar file name
        to load the tasks and taskdefs
      -->
    <taskdef resource="custom/tasks/taskdefs.properties">
      <classpath>
        <pathelement path="."/>
        <pathelement location="lib/${custom-tasks-jarfile}"/>
      </classpath>
    </taskdef>
  </target>
</project>

The find task supports currently only finding files. If finding classpath resources/classes is on your wishlist - drop me a line.

52.7. compare

The compare task compares two values either numerical or alphanumerical and sets properties depending of the comparison result.

The properties and will be defined by inner elements (named as the condition) of the compare task.

Attributes

Name Description Required
arg1 the left hand argument to compare yes
arg2 the right hand argument to compare yes
ignorecase

If set to true alphanumerical comparison's will ignore case.

Default is false.

no
trim

If set to true the values will be trimmed before comparison (Trimming removes all whitespaces, linefeed, carriage return and tabs from start ans end of the values.).

Default is false.

no
numeric If set to true the values will be compared as numbers. In other words the values will be converted to numbers before comparison. If the conversion failed the build process will fail.

Default value is false.

no

52.7.1. Element equal

The equal element defines a property if the comparison result is equality.

Attributes

Name Description Required
property the name of the property to set. yes

52.7.2. Element greater

The greater element defines a property if arg1 > arg2.

Attributes

Name Description Required
property the name of the property to set. yes

52.7.3. Element greaterOrEqual

The greaterOrEqual element defines a property if arg1 >= arg2.

Attributes

Name Description Required
property the name of the property to set. yes

52.7.4. Element lesser

The lesser element defines a property if arg1 < arg2.

Attributes

Name Description Required
property the name of the property to set. yes

52.7.5. Element lesserOrEqual

The lesserOrEqual element defines a property if arg1 <= arg2.

Attributes

Name Description Required
property the name of the property to set. yes

52.7.6. Element contains

The contains element defines a property if arg1 contains arg2. contains checks if string arg1 contains string arg2. In case of attribute numeric st to true, the arguments will always be reconverted to strings.

Attributes

Name Description Required
property the name of the property to set. yes

52.7.7. Example

This simple example tests if the java runtime version is 1.4 (or higher). Otherwise fails with an error message. The comparison is done numerical.

build.xml
<?xml version="1.0"?>  
<project basedir="." name="properties-test" default="main">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
  <target name="main">
    <compare arg1="${ant.java.version}" arg2="1.4" numeric="true">
      <lesser property="lesserThanJava14"/>
    </compare>
    <fail if="lessThanJava14">  
      java version 1.4 or higher is required !
    </fail>
  </target>
</project>

You can use multiple inner elements with same comparison at once. Defining multiple <lesser> elements inside compare for example is allowed.

52.8. call

call executes a target either once or multiple times depending on a condition.

The target dependencies will be executed too. In other words if a target depends on another, the other task will be executed too.

Attributes

Name Description Required
target the name of the target to execute. yes
if Executes the target task if a property named as the value exists. yes (if no other condition was defined).
unless Executes the target task if no property named as the value exists. yes (if no other condition was defined).
while Executes the target task again and again while a property named as the value exists. The loop will be aborted if the property no more exists. I'm not really sure but probably this condition may be senseless because Ant properties are immutable.

Be careful using this condition. You may configure endless loops !

yes (if no other condition was defined).
until Executes the target task again and again until a property named as the value exists. The loop will be aborted if the property exists.

Be careful using this condition. You may configure endless loops !

yes (if no other condition was defined).

52.8.1. Example

This example is just a snippet of a real world use of call. First call use: If property yul_present is defined the install-yul target will be executed. Because install-yul depends on target license it is also executed. The snippet contains some more use cases of call. See yourself.

build.xml
...
<target name="prepare" depends="checkup">
      <!-- create property yul_present if a matching file was found with the name of the file as value -->
    <find dir="${tomcat}/common/lib" file="roxes-yul-*.jar" property="yul_present"/>
   
      <!-- call target install-yul if the file exists -->
    <call unless="yul_present" target="install-yul"/>
   
    <input validargs="Install YUL examples,Create new YUL web application,Nothing more" addproperty="option">
      Select optional installations.
    </input>
   
    <compare arg1="${option}" arg2="Install YUL examples">
      <equal property="install-examples"/>
    </compare>
    <condition property="windows-integration">
      <and>
      <isset property="install-examples"/>
      <os family="windows"/>
      </and>
    </condition>
    <call if="windows-integration" target="install-windows-integration"/>
    <call if="install-examples" target="install-examples"/>
    <compare arg1="${option}" arg2="Create new YUL web application">
      <equal property="install-new"/>
    </compare>
    <call if="install-new" target="install-new"/>
  </target>    
 
  <target name="install-yul" depends="license">
    <unzip src="dist/common.zip" dest="${tomcat}/common"/>
  </target>
...

52.9. os.properties

The os.properties task creates some Ant variables providing information about name, type, architecture and version of the underlying operating system.

In general you may eval this information using the properties provided by java.lang.System.getProperty( name). But the clou is that os.properties creates Ant properties DEPENDING of the underlying operating system. If the task is executed on Windows a property os.family.windows will be created for example.
By having such a tagging property you can easily configure your Ant file to execute a target depending on the underlying platform.

52.9.1. List of created properties

os.properties creates a fixed amount of properties plus an additional property depending of the operating system type.

Fixed Properties

Additionally an ant property named os.family.[family] will be created (where [family] is replaced by windows, os/2, netware, dos, mac, unix, win9x or macosx).

Sometimes more than one family matches the operating system. In this case multiple properties starting with os.family. will be created.
For example on a Mac OS X the properties os.family.unix, os.family.mac and os.family.macosx are created.

The value of the os.family.[family] property is always set to "true".

os.properties takes no attributes.

52.9.2. Example

<?xml version="1.0"?>  
<project basedir="." name="layxx" default="sfx">
  <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
 
  <target name="prepare">
    <os.properties/>
  </target>
 
  <target name="setup" depends="prepare,windows,unix,os2,netware,dos,mac,win9x,macosx">
   
  </target>
    <!-- do windows specific stuff -->
  <target name="windows" if="os.family.windows">
    ...
  </target>
    <!-- do unix specific stuff -->
  <target name="unix" if="os.family.unix">
    ...
  </target>
      <!-- do os2 specific stuff -->
  <target name="os2" if="os.family.os2">
    ...
  </target>
      <!-- do netware specific stuff -->
  <target name="netware" if="os.family.netware">
    ...
  </target>
      <!-- do dos specific stuff -->
  <target name="dos" if="os.family.dos">
    ...
  </target>
 
        <!-- do mac specific stuff -->
  <target name="mac" if="os.family.mac">
    ...
  </target>
      <!-- do win9x specific stuff -->
  <target name="win9x" if="os.family.win9x">
    ...
  </target>
      <!-- do macosx specific stuff -->
  <target name="macosx" if="os.family.macosx">
    ...
  </target>
</project>

52.10. execute

The execute task works similar to the call task except that is executes a bunch of tasks instead of a target.

The tasks to execute are defined as inner elements of the execute task.

Attributes

Name Description Required
if Executes the target task if a property named as the value exists. yes (if no other condition was defined).
unless Executes the target task if no property named as the value exists. yes (if no other condition was defined).
while Executes the target task again and again while a property named as the value exists. The loop will be aborted if the property no more exists. I'm not really sure but probably this condition may be senseless because Ant properties are immutable.

Be careful using this condition. You may configure endless loops !

yes (if no other condition was defined).
until Executes the target task again and again until a property named as the value exists. The loop will be aborted if the property exists.

Be careful using this condition. You may configure endless loops !

yes (if no other condition was defined).

52.10.1. Example

The example asks for the tomcat home only if the environment variable TOMCAT_HOME is undefined.

build.xml
...
<target name="checkup">
    <!-- verify TOMCAT_HOME enviroment variable -->
  <execute if="${env.TOMCAT_HOME}">
    <property name="tomcat" value="${env.TOMCAT_HOME}"/>
  </execute>
 
  <execute unless="tomcat">    
    <input addproperty="tomcat">
      No TOMCAT_HOME enviroment variable found.
     
      Enter TOMCAT_HOME:
    </input>        
  </execute>
  <fail unless="tomcat">
    no TOMCAT_HOME defined
  </fail>
    <!-- -->
</target>
...

52.11. Unix related tasks

ROXES Ant Tasks provides a bunch of tasks related to Unix. These tasks can be used to access the KDE desktop, create unix soft links and many more.

52.11.1. unix.properties

unix.properties provides a bunch of Ant properties targeting Unix enviroments. After task execution these properties are available to any other task.

The unix.properties task has no attributes.

52.11.1.1. Example

build.xml
<project name="test project" basedir="." default="main">
  <taskdef resource="com/roxes/tools/ant/taskdefs.properties">
    <classpath>
      <pathelement path=".."/>
      <pathelement location="../lib/roxes-win32forjava-1.0-2003-11-11.jar"/>
    </classpath>
  </taskdef>
 
  <target name="main">
    <unix.properties/>
   
    <echo>unix.user.isRoot = ${unix.user.isRoot}</echo>
   
    <echo>unix.programfiles = ${unix.programfiles}</echo>
    <echo>unix.common.programfiles = ${unix.common.programfiles}</echo>
   
    <echo>unix.kde.home = ${unix.kde.home}</echo>
    <echo>unix.kde.icons = ${unix.kde.icons}</echo>
   
    <echo>unix.kde.personal.desktop = ${unix.kde.personal.desktop}</echo>
    <echo>unix.kde.common.desktop = ${unix.kde.common.desktop}</echo>
   
    <echo>unix.kde.personal.programs_menu = ${unix.kde.personal.programs_menu}</echo>
    <echo>unix.kde.common.programs_menu = ${unix.kde.common.programs_menu}</echo>
   
    <echo>unix.kde.personal.autostart_menu = ${unix.kde.personal.autostart_menu}</echo>
    <echo>unix.kde.common.autostart_menu = ${unix.kde.common.autostart_menu}</echo>
   
    <echo>unix.kde.personal.documents = ${unix.kde.personal.documents}</echo>
    <echo>unix.kde.common.documents = ${unix.kde.common.documents}</echo>
   
    <echo>unix.kde.personal.templates = ${unix.kde.personal.templates}</echo>
    <echo>unix.kde.common.templates = ${unix.kde.common.templates}</echo>    
  </target>
</project>

The example above produce something like the following output:

build.xml output
[echo] unix.user.isRoot = ${unix.user.isRoot}
[echo] unix.programfiles = /home/lars/bin
[echo] unix.common.programfiles = /usr/local
[echo] unix.kde.home = /home/lars/.kde
[echo] unix.kde.icons = /home/lars/.kde/share/icons/
[echo] unix.kde.personal.desktop = /home/lars/Desktop/
[echo] unix.kde.common.desktop = ${unix.kde.common.desktop}
[echo] unix.kde.personal.programs_menu = /home/lars/.kde/share/applnk/
[echo] unix.kde.common.programs_menu = /etc/opt/kde3/share/applnk/
[echo] unix.kde.personal.autostart_menu = /home/lars/.kde/Autostart/
[echo] unix.kde.common.autostart_menu = ${unix.kde.common.autostart_menu}
[echo] unix.kde.personal.documents = /home/lars/Documents/
[echo] unix.kde.common.documents = ${unix.kde.common.documents}
[echo] unix.kde.personal.templates = /home/lars/.kde/share/templates/
[echo] unix.kde.common.templates = /opt/kde3/share/templates/

As you can see some properties may not be set (depends on your KDE configuration).

52.11.2. unix.link

unix.link creates a unix soft link by calling the underlying ln command (using the command pattern /bin/ln --backup=numbered -s [target] [file]).

As the command pattern shows a soft link will be created using numbered backup. Numbered backup means that an existing link will be backed up using numbering.

Attributes

Name Description Required
file The link file to create. yes
target The file to link to. yes

52.11.2.1. Example

The example creates a link scite_start in ${user.home}/bin targeting /opt/gnome/bin/scite.

build.xml
<project name="test project" basedir="." default="main">
  <taskdef resource="com/roxes/tools/ant/taskdefs.properties">
    <classpath>
      <pathelement path=".."/>
      <pathelement location="../lib/roxes-win32forjava-1.0-2003-11-11.jar"/>
    </classpath>
  </taskdef>
 
  <target name="main">
    <unix.properties/>
 
    <unix.link file="${unix.programfiles}/scite_start" target="/opt/gnome/bin/scite"/>
  </target>
</project>

52.11.3. unix.kde.shortcut

unix.kde.shortcut creates a KDE shortcut file. KDE shortcut files are similar to shortcut files used in windows. They are used to define icon, command, label etc. of a desktop/program menu entry.

Using unix.kde.shortcut in consumption with unix.properties you are able to create desktop and program menu entries for the KDE desktop environment.

Attributes

Name Description Required
execute The command to execute. execute can also be defined using inner element <execute>. yes (if type Application is used)
workingDir The working directory where to execute the command. The workingdirectory can also be defined using inner element <workingdirectory>. yes (if type Application is used)
url The url to open. Use this parameter to create a shortcut to a document. yes (if type Link is used)
name The title of the shortcut. The name is the default shortcut title used by KDE. If you want to create a localized shortcut you can use the <property> inner element. yes
file

The shortcut file to create. If the file doesnt end with suffix .desktop (the default suffix for KDE shortcuts) it will be appended.

If a parent folder of the file doesnt exist it will be created.

yes
type

The type of the shortcut. Valid types are Application and Link.

If using Application parameter execute and workingDirectory are required. In case of type Link the url parameter is required.

type defaults to Application.

no
comment The comment for this shortcut, Usually used to display tooltips. no
icon The icon to use. The icon refers to an icon in the KDE icon directory. no
iconfile The icon to use. Using this iconfile an icon residing somewhere in the filessystem will be used. no
terminal Execute command using a terminal or without terminal. Valid values are true or false. no
terminaloptions if terminal is true using this attribute you can define additional terminal options. no

52.11.3.1. Element property

Because KDE shortcuts may contains many more entries the unix.kde.shortcut task provides the inner element property which can be used to define any entry.

Especially for localizing kde shortcuts this element is very useful. See the example.

52.11.3.2. Example

build.xml
<project name="test project" basedir="." default="main">
  <taskdef resource="com/roxes/tools/ant/taskdefs.properties">
    <classpath>
      <pathelement path=".."/>
      <pathelement location="../lib/roxes-win32forjava-1.0-2003-11-11.jar"/>
    </classpath>
  </taskdef>
 
  <target name="main">
    <unix.properties/>
 
      <!-- create a application shortcut -->
    <unix.kde.shortcut
      file="${unix.kde.personal.programs_menu}/roxes/xmlwrite.desktop"
      name="XmlWrite"
      execute="java -Djava.ext.dirs ~/bin/xmlwrite/lib com.roxes.xmlwrite.XmlWrite"
      IconFile="~/bin/xmlwrite/xmlwrite.gif"
      workingDirectory="${user.home}">
      <property name="Name[de]" value="XmlWrite starten"/>
      <property name="Name[us]">
        Execute XmlWrite
      </property>
    </unix.kde.shortcut>    
      <!-- create a link shortcut -->
    <unix.kde.shortcut
      file="${unix.kde.personal.programs_menu}/roxes/xmlwrite-docs.desktop"
      name="XmlWrite Documentation"
      IconFile="~/bin/xmlwrite/xmlwrite.gif"
      type="Link"
      url="http://www.roxes.com/produkte/xmlwrite">
      <property name="Name[de]" value="XmlWrite Dokumentation"/>
      <property name="Name[us]">
        XmlWrite
Documentation
      </property>
    </unix.kde.shortcut>    
    </target>
</project>

Regularly KDE shortcut files have file suffix .desktop (see the example). In some special cases (in the KDE desktop for example) the filename will be used as label instead the name property. In such cases you should NOT append file suffix .desktop to the shortcut filename.

52.11.4. unix.kde.shortcutdirectory

unix.kde.shortcutdirectory is similar to unix.kde.shortcut instead is is used to create shortcut files for KDE desktop folders or program file groups.

Attributes

Name Description Required
directory The directory where to create the directory shortcut. yes
name The title of the directory shortcut. The name is the default shortcut title used by KDE. If you want to create a localized shortcut you can use the <property> inner element. no
hidden

Sets the hidden property of the directory shortcut. Valid values are true or false.

no
comment The comment for this directory shortcut, Usually used to display tooltips. no
icon The icon to use. The icon refers to an icon in the KDE icon directory. no
iconfile The icon to use. Using this iconfile an icon residing somewhere in the filessystem will be used. no

52.11.4.1. Element property

Because KDE directory shortcuts may contains many more entries the unix.kde.directoryshortcut task provides the inner element property which can be used to define any entry.

Especially for localizing kde shortcuts this element is very useful. See the example.

52.11.4.2. Example

build.xml
<project name="test project" basedir="." default="main">
  <taskdef resource="com/roxes/tools/ant/taskdefs.properties">
    <classpath>
      <pathelement path=".."/>
      <pathelement location="../lib/roxes-win32forjava-1.0-2003-11-11.jar"/>
    </classpath>
  </taskdef>
 
  <target name="main">
    <unix.properties/>
 
    <unix.kde.shortcutdirectory
      directory="${unix.kde.personal.programs_menu}/roxes"
      IconFile="${unix.kde.personal.desktop}/roxes.gif"
      name="ROXES Technologies"
      <property name="Name[de]">
        ROXES Technologien
      </property>
    />
  </target>
</project>

52.12. Win32 related tasks

52.12.1. win32.properties

win32.properties is a task which imports windows system specific directories into the Ant project as properites. After execution you can access these directories as Ant properties

This task's functionality is based on the ROXES Win32 for Java library which provides access to common Windows functionality. ROXES Win32 for Java is included in the roxes-ant-tasks-1.2-2004-01-30.jar. The library is also available as separate package at ROXES Win32 for Java Homepage.

This task has no attributes.

win32.properties is especially useful to create/remove shortcuts/favorites for applications. The properties also allow you to install your application in the windows application directory.

52.12.1.1. List of created properties

The following list of windows specific directories is accessible after execution:

52.12.1.2. Example

This example shows executes the task and dumps out all properties created by this task.

build.xml
<?xml version="1.0"?>  
 
  <project basedir="." name="myapp" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
       
      <win32.properties/>
      <echo message="win32.common.autostart_menu = ${win32.common.autostart_menu}"/>
      <echo message="win32.common.desktop = ${win32.common.desktop}"/>
      <echo message="win32.common.documents = ${win32.common.documents}"/>
      <echo message="win32.common.files = ${win32.common.files}"/>
      <echo message="win32.common.programs_menu = ${win32.common.programs_menu}"/>
      <echo message="win32.common.start_menu = ${win32.common.start_menu}"/>
      <echo message="win32.common.templates = ${win32.common.templates}"/>
      <echo message="win32.personal.autostart_menu = ${win32.personal.autostart_menu}"/>
      <echo message="win32.personal.desktop = ${win32.personal.desktop}"/>
      <echo message="win32.personal.favorites = ${win32.personal.favorites}"/>
      <echo message="win32.personal.documents = ${win32.personal.documents}"/>
      <echo message="win32.personal.programs_menu = ${win32.personal.programs_menu}"/>
      <echo message="win32.personal.sentto = ${win32.personal.sentto}"/>
      <echo message="win32.personal.start_menu = ${win32.personal.start_menu}"/>
      <echo message="win32.personal.templates = ${win32.personal.templates}"/>
      <echo message="win32.programfiles = ${win32.programfiles}"/>  
      <echo message="win32.windows = ${win32.windows}"/>
      <echo message="win32.system = ${win32.system}"/>
    </target>
  </project>

output build.xml
[echo] win32.common.autostart_menu = C:\Dokumente und Einstellungen\All Users\Startmen³\Programme\Autostart
  [echo] win32.common.desktop = C:\Dokumente und Einstellungen\All Users\Desktop
  [echo] win32.common.documents = C:\Dokumente und Einstellungen\All Users\Dokumente
  [echo] win32.common.files = C:\Programme\Gemeinsame Dateien
  [echo] win32.common.programs_menu = C:\Dokumente und Einstellungen\All Users\Startmen³\Programme
  [echo] win32.common.start_menu = C:\Dokumente und Einstellungen\All Users\Startmen³
  [echo] win32.common.templates = C:\Dokumente und Einstellungen\All Users\Vorlagen
  [echo] win32.personal.autostart_menu = C:\Dokumente und Einstellungen\Administrator\Startmen³\Programme\Autostart
  [echo] win32.personal.desktop = C:\Dokumente und Einstellungen\Administrator\Desktop
  [echo] win32.personal.favorites = C:\Dokumente und Einstellungen\Administrator\Favoriten
  [echo] win32.personal.documents = C:\Dokumente und Einstellungen\Administrator\Eigene Dateien
  [echo] win32.personal.programs_menu = C:\Dokumente und Einstellungen\Administrator\Startmen³\Programme
  [echo] win32.personal.sentto = C:\Dokumente und Einstellungen\Administrator\SendTo
  [echo] win32.personal.start_menu = C:\Dokumente und Einstellungen\Administrator\Startmen³
  [echo] win32.personal.templates = C:\Dokumente und Einstellungen\Administrator\Vorlagen
  [echo] win32.programfiles = C:\Programme          
  [echo] win32.windows = C:\Windows
  [echo] win32.system = C:\Windows\System32

win32.properties works only on Win32 compliant systems (Win95, Win98, Win2000, WinXP and above).

52.12.2. win32.registry

win32.registry lets you access the Windows registry out of Ant.

This task's functionality is based on the ROXES Win32 for Java library which provides access to common Windows functionality. ROXES Win32 for Java is included in the roxes-ant-tasks-1.2-2004-01-30.jar. The library is also available as separate package at ROXES Win32 for Java Homepage.

This feature is especially useful for install/unistall your java application in a windows conform way. Furthermore it can beused to retrieve almost any information you need out of the registry.

win32.registry provides sub elements to any job to to.

Properties

Name Description Required
root root is the name of the registry part to access. Valid values are
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
yes
key key is the path of a registry subtree to access. You should use this attribute when accessing multiple entries to save typing the same path again and again. no

52.12.2.1. Element exists

exists test for the existence of a subkey or an extry and sets a Ant property as its result. The property will be created only if the test is successful (property value will set to true).

Properties

Name Description Required
property The name of the property to set if the test succeeds. yes
subKey subKey is the path of a registry subtree to access. The subKey will be appended to the key attribute of the win32.registry task if set. no
entry if entry is set exists tests if an entry named entry exists. Otherwise the subKey will be tested for existence. no

52.12.2.1.1. Example

build.xml
<?xml version="1.0"?>  
   
  <project basedir="." name="myapp" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
       
      <win32.registry root="HKEY_LOCAL_MACHINE" key="SOFTWARE">  
          <!--
            softwareExists will be set if
            HKEY_LOCAL_MACHINE\SOFTWARE exists
          -->
        <exists property="softwareExists"/>  
         
          <!--
            rtExists will be set if
            HKEY_LOCAL_MACHINE\SOFTWARE\ROXES Technologies exists
          -->      
        <exists property="rtExists" subkey="ROXES Technologies"/>
         
          <!--
            testExists will be set if
            HKEY_LOCAL_MACHINE\SOFTWARE\ROXES Technologies exists
            and the subkey has an entry "test"
          -->              
        <exists property="testExists" subkey="ROXES Technologies" entry="test"/>
      </win32.registry>
     
      <echo message="softwareExists=${softwareExists}"/>
      <echo message="rtExists=${rtExists}"/>
      <echo message="testExists=${testExists}"/>
    </target>
  </project>

52.12.2.2. Element delete

delete deletes a registry subkey or entry.

Properties

Name Description Required
subkey subKey is the path of a registry subtree. The subKey will be appended to the key attribute of the win32.registry task if set.
If the subkey is not set, the key of the win32.registry will be deleted.
no
entry The subkey entry to delete. If the entry is not set, the subkey will be deleted. no

52.12.2.2.1. Example

build.xml
<?xml version="1.0"?>  
   
  <project basedir="." name="myapp" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
        <!--
          deletes the "bounds" and "history" entry of
          HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ROXES Technologies\xmlwrite
        -->
      <win32.registry root="HKEY_LOCAL_MACHINE"
                      key="SOFTWARE\Microsoft\Windows\CurrentVersion\ROXES Technologies">  
        <delete subkey="xmlwrite" entry="bounds"/>
        <delete subkey="xmlwrite" entry="history"/>
      </win32.registry>
 
      ...
 
        <!--
          deletes the "xmlwrite" and "xpathspy" subtree of
          HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ROXES Technologies
        -->
      <win32.registry root="HKEY_LOCAL_MACHINE"
                      key="SOFTWARE\Microsoft\Windows\CurrentVersion\ROXES Technologies">  
        <delete subkey="xmlwrite"/>
        <delete subkey="xpathspy"/>
      </win32.registry>
   
      ...
 
          <!--
            deletes the whole "ROXES Technologies" subtree of
            HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion
          -->
      <win32.registry root="HKEY_LOCAL_MACHINE"
                      key="SOFTWARE\Microsoft\Windows\CurrentVersion\ROXES Technologies">  
        <delete/>
      </win32.registry>
   
      </target>
  </project>

52.12.2.3. Element export

The export element exports an registry subtree into a file. The file format is a simple XML schema (see example).

Properties

Name Description Required
file The file to export to. yes
subKey subKey is the path of a registry subtree to export. The subKey will be appended to the key attribute of the win32.registry task if set. no

52.12.2.3.1. Example

build.xml
<?xml version="1.0"?>  
   
  <project basedir="." name="myapp" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
       
      <win32.registry root="HKEY_LOCAL_MACHINE" key="SOFTWARE\ROXES Technologies\ant-test">  
        <export file="ant-test.xml"/>
      </win32.registry>
    </target>
  </project>

example output
<?xml version="1.0" encoding="UTF-8"?>
  <registry key="SOFTWARE\ROXES Technologies\ant-test" root="HKEY_LOCAL_MACHINE">
    <entry name="test" type="REG_SZ" value="huhu"/>
    <entry name="int" type="REG_DWORD" value="2147483647"/>
    <entry name="long" type="REG_DWORD" value="2000"/>
    <entry name="short" type="REG_DWORD" value="32767"/>
    <entry name="true" type="REG_DWORD" value="1"/>
    <entry name="false" type="REG_DWORD" value="0"/>
    <entry name="bigdecimal" type="REG_SZ" value="333"/>
    <entry name="bigint" type="REG_SZ" value="300"/>
    <entry name="byte" type="REG_DWORD" value="127"/>
    <entry name="bytearray" type="REG_BINARY" value="[B@17725c4"/>
    <entry name="test1" type="REG_SZ" value="huuhu"/>
    <entry name="test2" type="REG_SZ" value="i'm here again"/>
    <subkey name="prima">
      <entry name="dummy" type="REG_SZ" value="sadasdas"/>
      <subkey name="besser">
        <entry name="komma" type="REG_SZ" value="sadadas"/>
        <entry name="inthu" type="REG_DWORD" value="18"/>
        <entry name="" type="REG_SZ" value="sadad"/>
      </subkey>
    </subkey>
  </registry>

The exported file contains all subkeys and entries of the selected registry part including the entry data type.

52.12.2.4. Element get

The get element retrieves the value of a registry entry into a Ant property.

Properties

Name Description Required
property The property to put the entry value into. yes
entry The name of the entry to get. yes
subKey subKey is the path of a registry subtree to use. The subKey will be appended to the key attribute of the win32.registry task if set. no

52.12.2.4.1. example

build.xml
<?xml version="1.0"?>  
   
  <project basedir="." name="myapp" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
       
      <win32.registry root="HKEY_LOCAL_MACHINE" key="SOFTWARE">  
        <get property="test" subKey="ROXES Technologies" entry="test"/>
        <get property="int" subKey="ROXES Technologies" entry="int"/>
      </win32.registry>
     
      <echo message="test=${test}, int=${int}"/>
    </target>
  </project>

example output
[echo] test=huhu, int=2147483647

52.12.2.5. Element import

The import element imports a whole registry subtree from XML.

import can be used with a file argument referencing the import xml data or with embedded import xml data as body content.

Properties

Name Description Required
file The file containing the registry data to import. The file format is XML. yes if the import data is not given as body content of the import element.
subKey subKey is the path of a registry subtree to use. The subKey will be appended to the key attribute of the win32.registry task if set. no

52.12.2.5.1. Example

build.xml
<?xml version="1.0"?>  
   
  <project basedir="." name="myapp" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
       
        <!-- import using a file -->
      <win32.registry root="HKEY_LOCAL_MACHINE" key="SOFTWARE">  
        <import file="ROXES Technologies.xml" subKey="ROXES Technologies"/>
      </win32.registry>
     
        <!-- import using embedded body content -->
      <win32.registry root="HKEY_LOCAL_MACHINE" key="SOFTWARE">  
        <import subKey="ROXES Technologies">
          &lt;![CDATA[
          <registry key="SOFTWARE\ROXES Technologies" root="HKEY_LOCAL_MACHINE">  
            <entry name="test" type="REG_SZ" value="huhu"/>
            <entry name="int" type="REG_DWORD" value="2147483647"/>
            <entry name="long" type="REG_DWORD" value="2000"/>
            <entry name="short" type="REG_DWORD" value="32767"/>
            <entry name="true" type="REG_DWORD" value="1"/>
            <entry name="false" type="REG_DWORD" value="0"/>
            <entry name="bigdecimal" type="REG_SZ" value="333"/>
            <entry name="bigint" type="REG_SZ" value="300"/>
            <entry name="byte" type="REG_DWORD" value="127"/>
            <entry name="bytearray" type="REG_BINARY" value="[B@17725c4"/>
            <entry name="test1" type="REG_SZ" value="huuhu"/>
            <entry name="test2" type="REG_SZ" value="i'm here again"/>
            <subkey name="prima">
              <entry name="dummy" type="REG_SZ" value="sadasdas"/>
              <subkey name="besser">
                <entry name="komma" type="REG_SZ" value="sadadas"/>
                <entry name="inthu" type="REG_DWORD" value="18"/>
                <entry name="" type="REG_SZ" value="sadad"/>
              </subkey>
            </subkey>
          </registry>
          ]]&gt;
        </import>
      </win32.registry>
    </target>
  </project>

Version 1.2 imports data entries always as REG_SZ (string) and ignores the given data type !

Both key and root attribute of the import xml data will be ignored. The root and key/subKey informations given be win32.registry and import will be used.

52.12.2.6. Element set

The set element allows setting registry entries. If the entry always exist, the value will be overwritten, otherwise it is new created.

Properties

Name Description Required
entry Name of the entry to set. yes
value The value of the entry. yes
subKey

subKey is the path of a registry subtree to use. The subKey will be appended to the key attribute of the win32.registry task if set.

If the subKey not exists it will be created.

no

52.12.2.6.1. example

build.xml
<?xml version="1.0"?>  
   
  <project basedir="." name="myapp" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
       
      <win32.registry root="HKEY_LOCAL_MACHINE" key="SOFTWARE">  
          <!--
            entry will be created in HKEY_LOCAL_MACHINE\SOFTWARE\ROXES Technologies
          -->
        <set subKey="ROXES Technologies" entry="test1" value="huuhu"/>
 
          <!--
            entry will be created in HKEY_LOCAL_MACHINE\SOFTWARE
          -->
        <set entry="test2">
          i'm here again
        </set>
      </win32.registry>
    </target>
  </project>

Task win32.registry works only on Win32 compliant systems (Win95, Win98, Win2000, WinXP and above).

52.12.3. win32.shortcut

win32.shortcut creates Windows Shortcut files usable for Windows specific Start Menu entries, Favorites and SentTo Menu and many more.
Since Version 1.2 this task is able to create the more flexible binary .lnk Shortcuts files.

This task's functionality is based on the ROXES Win32 for Java library which provides access to common Windows functionality. ROXES Win32 for Java is included in the roxes-ant-tasks-1.2-2004-01-30.jar. The library is also available as separate package at ROXES Win32 for Java Homepage.

Especially in conjuction with win32.properties this task is a powerful tool to create ant based installations.

There exists 2 versions of shortcut files - binary and text based.

.url shortcuts

Text based shortcut files (with suffix .url) are mostly used to create shortcuts to web locations and Internet Explorer Favorites.

.lnk shortcuts

Binary shortcut files (with suffix .lnk) are used to create shortcuts for starting application or link to local files.

Properties

Name Description Required
file The full path to the shortcut file to create. If the path to the file does not exist it will be created. The filename HAVE TO end with either .url (for text based shortcuts) or .lnk (for binary shortcuts) to let Windows identify it as shortcut file.

Use the ant variables created by win32.properties to get special windows directories.

yes
url The url to the file to execute. If the url references a executable (exe, bat, cmt etc.) it will be executed, otherwise the referenced file will be opened using the associated viewer application.

You can use the ant variables created by win32.properties to get the right directory.

url can also be defined using a child element <url>.

yes if an .url shortcut should be created.
execute The command to execute. If the command references a executable (exe, bat, cmt etc.) it will be executed. the execute property may also contain commandline arguments.

You can use the ant variables created by win32.properties to get the right directory.

execute can also be defined using a child element <execute>.

yes if an .lnk shortcut should be created.
workingDirectory

The working directory for the execution.

workingDirectory can also be defined using a child element <workingDirectory>.

no
showCommand

The show mode for the file. Valid values are minimized, maximized and normal. Default is normal.

In most cases this attribute will be ignored by windows :-(

showCommand will be ignored for .lnk shortcuts.

no
comment

The comment of .lnk will be used for tooltips.

comment will be ignored for .url shortcuts.

no
modified

Modification date of the .url information. See Excursion to the .url File Format for details.

modified will be ignored for .lnk shortcuts.

no
hotKey

Hotkey to execute the shortcut. See Complete HotKey Code Reference for details.

hotkey will be ignored for .lnk shortcuts.

no
iconFile

The icon file to use. This may be a exe, dll or ico file.

The icon file will be ignored by windows for web addresses as url parameter.

no
iconIndex

The index of the icon to use inside the iconFile. Start index is always 0.

no

52.12.3.1. examples

.url example
<?xml version="1.0"?>  
   
  <project basedir="." name="myapp" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
          <!--
            required to fetch the windows specific directories
            into ant properties
          -->
        <win32.properties/>
       
          <!--
            creates a entry in the programs menu
         
            will be opened using the associated
            viewer program (notepad i think :-)
          -->
      <win32.shortcut
        file="${win32.personal.programs_menu}/ROXES Technologies/read license.url"
        url="${win32.personal.programfiles}/ROXES Technologies/test/license.txt"
      />
          <!--
            creates a entry in the programs menu
           
            will be opened using the associated
            viewer program (internet explorer, mozilla, opera - whatever)
          -->      
      <win32.shortcut
        file="${win32.personal.programs_menu}/ROXES Technologies/Go to ROXES.url"
        url="http://www.roxes.com"
      />  
          <!--
            creates favorites entry
          -->      
      <win32.shortcut
        file="${win32.personal.favorites}/ROXES Technologies/Go to ROXES.url"
        url="http://www.roxes.com"
      />  
        <!--
          creates a entry in the programs menu        
          the file is executed when opening
        -->
      <win32.shortcut
        file="${win32.personal.programs_menu}/ROXES Technologies/layxx.url"
        url="${win32.personal.programfiles}/ROXES Technologies/roxes-layxx-1.4-2003-10-23.exe"
        iconFile="C:\winnt\explorer.exe"
        iconIndex="0"
      />
    </target>
  </project>

.lnk example
<?xml version="1.0"?>  
   
  <project basedir="." name="myapp" default="main">
    <taskdef classpath="roxes-ant-tasks-1.2-2004-01-30.jar" resource="com/roxes/tools/ant/taskdefs.properties"/>
   
    <target name="main">
          <!--
            required to fetch the windows specific directories
            into ant properties
          -->
        <win32.properties/>
       
        <!-- create a .lnk shortcut in programs menu -->
      <win32.shortcut
        file="${win32.personal.programs_menu}/ROXES Technologies/Open notepad.lnk"
        execute="c:\winnt\notepad.exe"
      />
 
        <!--
          create a .lnk shortcut in programs menu
          (see the use embedded <execute> tag)
        -->
      <win32.shortcut
        file="${win32.personal.programs_menu}/ROXES Technologies/Open explorer in temp.lnk"
      >  
        <execute>
          c\winnt\explorer.exe c:\temp
        </execute>
      </win32.shortcut>
 
        <!--
          create a .lnk shortcut at the desktop
        -->
      <win32.shortcut
        file="${win32.personal.desktop}/ROXES Technologies/layxx.lnk"
        url="${win32.personal.programfiles}/ROXES Technologies/roxes-layxx-1.4-2003-10-23.exe"
      >
        <workingdirectory>
          ${win32.personal.documents}
        </workingdirectory>
        <execute>
          c\winnt\explorer.exe c:\temp
        </execute>
      </win32.shortcut>
 
        <!-- create a shortcut in send to menu -->
      <win32.shortcut
        file="${win32.personal.sendto}/ROXES Technologies/notepad.lnk"
      >
        <execute>
          c:\winnt\notepad.exe
        </execute>
      </win32.shortcut>
    </target>
  </project>

You can use embedded elements for workingDirectory, url and execute. See the example above.

52.12.3.2. Excursion to the .url File Format

The classic URL file format is pretty simple; it has a format similar to an INI file:

[InternetShortcut]
  URL=http://www.someaddress.com/
  WorkingDirectory=C:\WINDOWS\
  ShowCommand=7
  IconIndex=1
  IconFile=C:\WINDOWS\SYSTEM\url.dll
  Modified=20F06BA06D07BD014D
  HotKey=1601

The syntax of the file format is like the following:

[Group\Section]
  Field=Value
  Field=Value
  .
  .

Each line terminates with CR and LF characters, and uses ANSI as it’s character set. The files can be manipulated using basic file I\O or the GetPrivateProfileString, GetPrivateProfileSection, WritePrivateProfileSection, WritePrivateProfileSring API functions provided by Windows.

URL

The URL field is self-explanatory. It’s the address location of the page to load. It should be a fully qualifying URL with the format protocol://server/page. A URL file is not restricted to the HTTP protocol. In general, at least, whatever that can be saved as a favorite is a valid URL.

WorkingDirectoy

It’s the “working folder” that your URL file uses. The working folder is possibly the folder to be set as the current folder for the application that would open the file. However Internet Explorer does not seem to be affected by this field.

This setting does not seem to appear in some versions of Internet Explorer/Windows.

IconIndex

The Icon Index within the icon library specified by IconFile. In an icon library, which can be generally be either a ICO, DLL or EXE file, the icons are indexed with numbers. The first icon index starts at 0.

IconFile

Specifies the path of the icon library file. Generally the icon library can be an ICO, DLL or EXE file. The default icon library used tends to be the URL.DLL library on the system’s Windows\System directory

Modified

This field is generally the most cryptic of all the fields.

example
Modified=20F06BA06D07BD014D

I’m not aware exactly how the date is encoded in the URL file format. However the code is clearly in a hexadecimal and is a counter, counting from a specific year, month and day. It also appears to be divided in 9 words. With some experimentation I was able to see the following:
Changes at a fast pace Changes slowly ?
20 F0 6B A0 6D 07 BD 01 4D

The second character of the first word also never changes: possibly the resolution of the timer does not go this deep in detail. However the count is deep enough that it’s smaller than a microsecond (or it seems). To be useful, the words above have to have it’s order reversed, possibly the ninth can be removed. Therefore:

20 F0 6B A0 6D 07 BD 01 4D
Invert Rem.
01 BD 07 6D A0 6B F0 20

Then convert the first 4 words (most significant) from hex to a double precision number, do the same with the 4 last hex values (least significant), and apply the following formula:

MostSignificant = HexToDec(?01BD076D?)
  LeastSignificant = HexToDec(?A06BF020?)
  BDN = MostSignificant * 4294967295 + LeastSignificant

The following functions can be used as a “poor man’s” date approximation tool:

Year = 1600 + Int(BDN / k / 1000 / 1000 / 60 / 60 / 24 / 356.25)
  Month = Int(BDN / k / 1000 / 1000 / 60 / 60 / 24 / 30 Modulus 12)

The k constant here is “guessed” as 10.2215, as it gave somewhat acceptably close months from 1995 to 2002. However it is far from being correct. While these functions are definitely crude, it provides a bit of insight how the Modified field was probably constructed. Creating your own functions to process these dates is recommended.

ShowCommand

This setting does not seem to appear in some versions of Internet Explorer/Windows.

HotKey

The HotKey field specifies what is the shortcut key used to automatically launch the Internet shortcut. The field uses a number to specify what hotkey is used.

833 ? Ctrl + Shift + A
  834 ? Ctrl + Shift + B
  835 ? Ctrl + Shift + C
  .
  .
  1345 ? Shift + Alt + A
  1346 ? Shift + Alt + B
  1347 ? Shift + Alt + C
  .
  .
  1601 ? Ctrl + Alt + A
  1602 ? Ctrl + Alt + B
  1603 ? Ctrl + Alt + C

Refer to Complete HotKey Code Reference.

Settings not stored in the .url format

Visits, "Make this page available offline”, Synchronization settings, Download Settings and Schedule Settings are not kept in .url files.

Issues about using the .url format

It seems that Microsoft wants to hide the structure of the file format, even make it seem like it isn’t even a file at all. The URL file in the newer Microsoft Windows operating systems behaves almost like a LNK file. For example, in Microsoft Windows 2000 Professional, the URL file is treated like a shortcut, even in Windows Notepad, making the file format harder to be revealed and viewed. In order to view a file in these operating systems, use the DOS EDIT.EXE program. By typing EDIT in a command prompt window.

Read more about creating and maintaining URL files using IshellLink related Windows interfaces http://msdn.microsoft.com/library/psdk/shellcc/shell/Internet_Shortcuts.htm

52.12.3.3. Complete HotKey Code Reference

C+S S+A C+A C+S+A C+S S+A C+A C+S+A
A 833 1345 1601 1857 0 817 1329 1584 1841
B 834 1346 1602 1858 1 818 1330 1585 1842
C 835 1347 1603 1859 2 819 1331 1586 1843
D 836 1348 1604 1860 3 820 1332 1587 1844
E 837 1349 1605 1861 4 821 1333 1588 1845
F 838 1350 1606 1862 5 822 1334 1589 1846
G 839 1351 1607 1863 6 823 1335 1590 1847
H 840 1352 1608 1864 7 824 1336 1591 1848
I 841 1353 1609 1865 8 825 1337 1592 1849
J 842 1354 1610 1866 9 826 1338 1593 1850
K 843 1355 1611 1867 ; 954 1466 1722 1978
L 844 1356 1612 1868 = 955 1467 1723 1979
M 845 1357 1613 1869 , 956 1468 1724 1980
N 846 1358 1614 1870 - 957 1469 1725 1981
O 847 1359 1615 1871 . 958 1470 1726 1982
P 848 1360 1616 1872 / 959 1471 1727 1983
Q 849 1361 1617 1873 ` 960 1472 1728 1984
R 850 1362 1618 1874 [ 987 1499 1755 2011
S 851 1363 1619 1875 \ 988 1500 1756 2012
T 852 1364 1620 1876 ] 989 1501 1757 2013
U 853 1365 1621 1877 990 1502 1758 2014
V 854 1366 1622 1878
W 855 1367 1623 1879
X 856 1368 1624 1880
Y 857 1369 1625 1881
Z 858 1370 1626 1882
None Ctrl Alt Shift C+A S+A C+S C+S+A
F1 112 624 1136 368 1648 1392 880 1904
F2 113 625 1137 369 1649 1393 881 1905
F3 114 626 1138 370 1650 1394 882 1906
F4 115 627 1139 371 1651 1395 883 1907
F5 116 628 1140 372 1652 1396 884 1908
F6 117 629 1141 373 1653 1397 885 1909
F7 118 630 1142 374 1654 1398 886 1910
F8 119 631 1143 375 1655 1399 887 1911
F9 120 632 1144 376 1656 1400 888 1912
F10 121 633 1145 377 1657 1401 889 1913
F11 122 634 1146 378 1658 1402 890 1914
F12 123 635 1147 379 1659 1403 891 1915

Task win32.shortcut works only on Win32 compliant systems (Win95, Win98, Win2000, WinXP and above).

53. Dynamic commandline(s)

Version 1.2 of ROXES Ant Tasks extends the commandine parameters of jstub and sfx task. You can add placeholders for enviroment and registry settings to the commandline which are evaluated and replaced at runtime.

When do i need this feature ?

Suppose your application setup installs a private java runtime and the path to it is stored in the windows registry. Your application does not know about the location of the private java runtime.
By using the registry/enviroment features of sfx and jstub you are able to retrieve registry/enviroment informations at executable runtime.
The following example commandline will query the registry and replace the ant tokens by the queries value:

${reg:HKEY_LOCAL_MACHINE\SOFTWARE\myProduct\myjre}\bin\java -Djava.home=${reg:HKEY_LOCAL_MACHINE\SOFTWARE\myProduct\myjre} foo.bar

The commandline(s) patched into executables created with jstub and sfx are parsed for ant styled variable placeholders containing

Syntax

Placeholders in general are defined using the following syntax:

${type:name(|default)*}

The registry feature is only available for win32 executables created with sfx/jstub.


References

History

VersionDateDescription
1.22004-01-30
2004-01-12 Another JNLP extension bug fixed. Thanks to Daniel Laird.
2003-12-18 Thanks to James Shiell i fixed some bugs in the JNLP task.
2003-11-47 win32.properties extended to reflect the windows and windows system directory as Ant properties.
2003-11-26

Made a bunch of code modifications to make the tasks more handy.

Task os.properties added.

Task writefile removed because the functionality is always a builtin of Ant (Task concat)

2003-11-12

Documentation updated to reflect the newly added tasks.

Great news: Tasks compare, execute, call, writefile, unix.properties, unix.kde.shortcut, unix.shortcut and unix.kde.directoryshortcut added. Its time for a new release.

2003-11-12

docs refreshed

Additional property encoding to jnlp task added (proposed by R. A. Rivas Diaz). If not defined it is set to UTF-8.

Antony now encapsulates the standard tasks echo and input to provide graphical user interfaces to this tasks.

Find task added. The find task is able to find a file conforming to a pattern and can return parts of the file name/location into properties.

2003-11-06

Antony added. Antony is a GUI for Ant (not an development eviroment). It can be used to create GUI setup's based ONLY on Ant make files ! Currently the GUI is mostly similar to INF file execution on windows including syntaxcolored output window. The ROXES Ant Tasks jar is now self executable and starts Antony. Antony is fully commandline compatible to Apache Ant (some additional customization commandline optins are available to).

win32.registry and win32.shortcut now execute the win32.properties task automatically if not executed before. You dont need to execute win32.properties manually before using the win32 properties created by win32.properties when used in win32.registry or win32.shortcut.

2003-11-05

Task properties added. this task can write a properties file. supported features are merge existing properties files (via fileset) and settings properties depending on rules (if, unless, available, isfalse, istrue rules supported).

2003-11-01 values provided as text content will always be substituted (replaced by matching properties). this notice affects all tasks of this suite.
2003-11-01

documentation for win32.shortcut, win32.properties and win32.registry added.

win32.shortcut task added. win32.shortcut creates windows shortcut files. these files can be used to create entries in special windows folders like program menu, desktop, favorites or sendto.

win32.properties task added. This task makes windows specific directories (program menu, favorites etc.) available as ant properties.

2003-10-30

win32.registry task added. Use this task to access the windows registry.

2003-10-23

Documentation refreshed to reflect the new features.

icon parameter implemented for jstub and sfx windows excutables and sfx java executable. The icon is patched into the executables. Requested by Janek Schwarz.

2003-10-22 jstub and sfx windows commandline substitution added. both executables can now substitute enviroment and registry values into the commandline. This feature was requested by Janek Schwarz.
2003-10-22 Bug fixed: Thanks to Ray who informed me about the extension bug in the jnlp task. The bug was removed and the cleaned up implementation is available in version 1.2.
1.12003-10-10
2003-10-15

jstub windows executable rewritten to reflect the ideas of jc duford. See jstub chapter for details.

jstub windows executable can now handle command line arguments.

2003-09-26 PreferencesTask documentation added.
2003-09-25 PreferencesTask added. this task makes accessing java preferences (java 1.4 preferences) api a piece of cake.
2003-09-17 major bug fixed : both sfx and jstub task now do not open a console in win32 (console less) mode.
2003-09-12 thanks to darragh curran the jnlp output is now correct for icon element's.
2003-09-10

thanks to darragh curran: the docs were polished to reflect the current jar file version in the examples, the examples taskdef are corrected and the jnlp task now handles the href top level attribute. furthermore the sfx unix executable stub was updated. the jnlp task now handles filesets correct. jnlptask's homepage element output fixed.

sfx task mode java
bug fixed: if started on windows "start /B" will be set as starting sequence. before command /C or cmd /c was set as starting sequence (which is not correct).

1.02003-09-08
2003-09-08

bug fixed: sfx windows executables now working like expected when started with full or partial path.

urls to ant website refreshed, docs (chapter usage) corrected. (thanx to jan.materne@rzf.fin-nrw.de).

2003-09-04 initial release.