![]() |
|
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. |
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 :
|
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
|
yes |
execute |
The command to execute after successful extraction. The command is executed
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
|
Zip the directory structure to an archive (layxx.zip for example).
Create a Ant make file with the following content:
build.xml | |||||||||||||||||||||||||||||||||||||||||||||||
|
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
|
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 | |||||||||||||||
|
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 | |||||||||||||||
|
The example below uses the commandline placeholder XYZjstubLocationXYZ:
build.xml | |||||||||||||||
|
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 -
|
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
JNLP File Format tags containing minus ('-') must be written with underscore ('_')
Element resources may contain FileSet's.
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
|
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 |
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 ofApplications 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:
|
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
|
|
|
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 | ||||||||||||||||||||||
|
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.
|
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.
|
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
|
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
|
![]() | 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
|
![]() | The file format is defined here. |
References | |
|
History | ||
Version | Date | Description |
1.1 | 2003-10-16 | |
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. |
||
PreferencesTask documentation added. | ||
PreferencesTask added. this task makes accessing java preferences (java 1.4 preferences) api a piece of cake. | ||
major bug fixed : both sfx and jstub task now do not open a console in win32 (console less) mode. | ||
thanks to darragh curran the jnlp output is now correct for icon element's. | ||
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
|
||
1.0 | 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). |
||
initial release. |