ROXES ANT Tasks
Author:lars gersmann
Homepage:http://www.roxes.com/produkte/rat.html
Version:1.1 (2003-10-16)
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.2.         jstub
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.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.2.             Element get
2.4.3.             Element remove
2.4.4.             Element test
2.4.5.             Element export
2.4.6.             Element import

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.1-2003-10-16.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.

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
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).

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.

no

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.1-2003-10-16.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.

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.

Properties

Name Description Required
archive the zip/jar archive to use. yes
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.

yes
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

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.1-2003-10-16.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.1-2003-10-16.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.1-2003-10-16.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 placecholder occurence will be replaced. Multiple placeholders will be ignored.

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
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 FileSet instances can be added as sub elements. All matching files of the 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/

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.1-2003-10-16.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

Example

Set Preferences data
<?xml version="1.0"?>
<project basedir="." name="foo" default="main">
<taskdef classpath="roxes-ant-tasks-1.1-2003-10-16.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

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.1-2003-10-16.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.

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.1-2003-10-16.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.

Example

<?xml version="1.0"?>
<project basedir="." name="foo" default="main">
<taskdef classpath="roxes-ant-tasks-1.1-2003-10-16.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

Example

<?xml version="1.0"?>
<project basedir="." name="foo" default="main">
<taskdef classpath="roxes-ant-tasks-1.1-2003-10-16.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.

Example

<?xml version="1.0"?>
<project basedir="." name="foo" default="main">
<taskdef classpath="roxes-ant-tasks-1.1-2003-10-16.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.


References
  • Preferences
  • Ant

    Ant is a tool similar to Make. Ant is based on XML formatted configuration files.

  • ROXES Technologies

    ROXES Technologies is a company specialized in Web Application Development. ROXES Technologies is the owner of ANT Tasks.

  • ZLib library

    A general purpose library for reading/writing zip file contents.

  • Java Webstart

    Java Webstart is a technology to make java applications available to the desktop.

  • JNLP File Format
  • FileSet
History
VersionDateDescription
1.12003-10-16
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.