We need you!

Icon

The IzPack documentation needs work, and you are invited to edit it!

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Documented schema hanges for 5.0

In this section the common ant task custom actions are described in detail. It is only for developers who are not acquainted with IzPack or it's custom actions. In addition to the basics there are some recapitulations of the common custom action techniques and some hints for pitfalls. In the package com.izforge.izpack.event there are the ant related custom actions AntActionInstallerListener and AntActionUninstallerListener. As recapitulation, to add any custom action a reference in install.xml will be needed, as IzPack provides support to execute Ant tasks during installation and uninstallation.

For example:

<listeners>
Code Block
languagehtml/xml
<resources>
    <listener classname="AntActionInstallerListener" stage="install...
    <res id="AntActionsSpec.xml" src="myInstallSpecs/MyAntActionsSpec.xml" />
    <listener classname="AntActionUninstallerListener...
</resources>

<jar src="jar/ant.jar" stage="uninstallboth" />
</listeners>

For all referenced listeners a jar file with the same name must exist in IzPackRoot/bin/customActions. If compilation (packaging) fails with a "not found" error, first verify, that the jar file exists. If not, create it. With this custom action it is possible to perform ant calls at installation and/or uninstallation time. It is not only a wrapper for a comand-line ant call, but also an intersected description file defining what target of the ant build file should be performed at what time of (un)installation and specifies which properties for what IzPack pack are to be used. The intersected description file is written as XML, the corresponding dtd is placed in src/dtd/event/antaction.dtd. The description file should be declared as a resource in the install.xml with the id AntActionsSpec.xml e.g.

Code Block
<resources>
    ...
    <res id="AntActionsSpec.xml"
    src="myInstallSpecs/MyAntActionsSpec.xml" />
    ...
</resources>

...

<jar src="jar/customtasks.jar" stage="both"/>

<listeners>
    <listener classname="AntActionInstallerListener" stage="install" />
    <listener classname="AntActionUninstallerListener" stage="uninstall" />
</listeners>

In the above:

  • the AntActionsSpec.xml resource determines the Ant tasks to be executed. The base path of src is the installation project path.

...

Code Block
<jar src="jar/ant/ant.jar" stage="both" />

...

  • the <jar/> element specifies jar dependencies required to execute the Ant tasks. At a minimum, this must include the Ant jar.
  • the <listeners> element is used to hook execution of the Ant tasks into the installer and uninstaller
 

Nor that an "extended" ant use needs more than one jar, for example often xercesImpl.jar. If an obscure "class not found" exception is raised during testing, check first for missing jar files. For supporting uninstallation the jar field was extended by the attribute stage

The stage attribute of the jar element determines when a jar is required. If an ant uninstaller custom action is used, the uninstaller also needs the jar files. If stage is "both" or "uninstall", the contents of the referenced jar file will be packed into the uninstaller.jar. Be aware

Note that not the jar file itself, but the contents of it are required. This implies, that the paths of the contained files are unique and the information in meta-inf/Manifest.mf will be lost.

The AntActionSpec XML Struture

An ant action will be is defined in the resource with the id "AntActionsSpec.xml". Sometimes it will help to look into createpage.action?spaceKey=IZPACK&title=IzPackRoot&linkCreation=true&fromPageId=142803064antaction.dtd (4.x SVN trunk) or validate a written xml file with the dtd.In IzPack 5.0 (as of 5.0.0-beta-11), an XML-Schema is provided, which may be declared as follows:

Code Block
languagehtml/xml
<izpack:antactions version="5.0"
                   xmlns:izpack="http://izpack.org/schema/antactions"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://izpack.org/schema/antactions http://izpack.org/schema/5.0/izpack-antactions-5.0.xsd">
<!-- .... -->
</izpack:antactions>

 

Prior to processing the packs a substitution is performed using all defined IzPack variables on the spec file. This is a common way of loading spec files into custom actions.

For more information see method com.izforge.izpack.util.SpecHelper.readSpec. If you want to substitute a value in the file, simply add a variable via idatainstallData.setVariable in a custom panel before InstallPanel. The given variable name (id) should be written into the xml file in the common variable notation.

...