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.

Custom Actions

(by Klaus BARTZ)

Overview

The implementation of custom actions presume knowledge of java. Custom actions are not a good starting point for learning java. Learners can use existent custom actions but should not implement them as exercise.

...

If the action should be performed for several amount of elements of a pack, using custom actions will be more easy than using panels. Additional custom actions may be defined for installation, but also for packaging and uninstallation purposes. If a custom action is also needed for uninstallation purposes, it'll be always a good idea to implement a corresponding installation action as custom action, but not as panel.

How It Works

Custom actions are implemented as listeners. Each listener implements callback methods that will be called at well-defined points. The method InstallerListener.afterFile for example will be called after a file has been copied. There are different interfaces intended for being used at packaging time, at installation time and at uninstallation time.

...

If file related data will be set, the facultative ELEMENT "additionaldata" is defined for the ELEMENTs "file", "singlefile" and "fileset". This data will be automatically moved to the corresponding PackFile objects in the install.jar. Extraction and usage should be implemented in a install custom action (see example).

Custom Action Types

Custom actions are intended to be used at packaging time, at installation time and at uninstallation time. The interfaces are:

h4. h3. h4. h4. h4. h4. Custom action type Interface name h4. h4.h4. h4. h4. h4. Packaging com.izforge.izpack.event.CompilerListener Installation com.izforge.izpack.api.event.InstallerListener Uninstallation com.izforge.izpack.api.event.UninstallerListener h4. h4. h3. h4. h4. h4. h4. Custom Actions At Packaging h3. Image Modified

  • (constructor): only the default constructor will be used. It is called from Compiler just after creating the packager. Therefore initializing will be better during in the first notify call.
  • reviseAdditionalDataMap gives the facility to add data to each PackFile object. This is the place where file related data can be transferred from the install xml file into the install jar file. Although each key and value of the map can be any type, but the class definitions of all used types must therfore be contained in the installer jar file or in the VM's classpath. In general strings are the best choice for being used as keys or values. All keys must be unique over all registered CompilerListeners. Each call of this method adds own key value pairs to the given existenDataMap because more than one listener can be used. If the given map is null, a new one will be created.
  • notify is called at the beginning and at the end of each "add" method call which is called in Compiler.executeCompiler. Custom Actions At Installing Time h3.
  • (constructor): only the default constructor will be used. It is called from Unpacker.run before unpacking.
  • beforePacks will be called each time before an unpacking call is performed.
  • beforePack is called before a package is installed. Pack object and the number of the pack are passed.
  • isFileListener determines whether the next four methods are called or not. This is a little performance optimizing.
  • beforeDir is called before a directory is created. In this case, when file listeners exist, directories are created recursively and the method is called at each step. The file and the current PackFile object are passed.
  • afterDir is called directly after the directory creation.
  • beforeFile is called before a file is created. The file and PackFile object are passed as parameters.
  • afterFile is the best place to perform file related actions. The given PackFile objects contains the additional data which was set at packaging.
  • afterPack will be just called after the pack is closed.
  • afterPacks is the last step before the handler will be stopped. Custom Actions At Uninstalling Time h3.
  • (constructor) : only the default constructor will be used. It is called from Destroyer.run as first call.
  • beforeDeletion will be called after execute files was performed. The given list contains all File objects which are marked for deletion.
  • isFileListener determines whether the next two methods are called or not.
  • beforeDelete is the method which, is called before a single file is deleted. The File object is given as parameter.
  • afterDelete will be invoked after the delete call for a single file.
  • afterDeletion is the last call before the cleanup of created data is performed.

Package Path

Custom actions must always implement one of the given listener interfaces. As mentioned above, it is also possible to derive from one of the "Simple" listeners. The package path is facultative, only the class name must be unique over all custom actions. The preparation of a custom action for providing it with an installation is very similar to panels. Custom actions must also be packed into a jar file with the name of the custom action class name. This jar file should be placed in IzPackRoot/bin/customActions, may be

...

In the default Ant definition file (build.xml) there are some targets for this stuff.

Native Libraries for Uninstallation

If a custom action uses JNI at installation time, often the associated uninstall custom action needs JNI too. For this situation it is possible to declare a native library for unstallation. The only work to do is to add a stage attribute to the native tag in the install xml file like

...

The needed additional classes are packed into lib/uninstaller-ext.jar. If a native library is defined for uninstallation, this file will also be packed into the installer.jar as IzPack.unistaller-ext and used at its right position.

What You Have To Do

Follow the steps that are needed to create and use custom actions with the "normal" source environment (not standalone compiler) using Ant. Of course, it works also with the standalone compiler.

Custom Actions at Packaging (CompilerListener)

  • Implement com.izforge.izpack.event.CompilerListener or extend com.izforge.izpack.event.SimpleCompilerListener. Place it as IzPackRoot/src/lib/MyPackagePath/MyCompilerListener.java.
  • Add a "build-compiler-listener" macro call in to the build.listeners target in IzPackRoot/src/build.xml. Note that the name attribute value in the build-instealler-listener must match CompilerListener implementation class name (not including the package). You should include the actual Listener implementation, as well as any other classes required by the listener.
    Code Block
    <build-compiler-listener
    name="MyCompilerListener">
        <include
        name="[MyPackagePath]/MyCompilerListener.java"/>
        <include
        name="[MyPackagePath]/SomeOtherHelperClass.java"/>
    </build-compiler-listener>
  • Run IzPackRoot/src/build.xml. An ant alone will execute the required targets.
  • Add a "listeners" ELEMENT with a "listener" ELEMENT with a "compiler" attribute in to MyProjectPath/install.xml
    Code Block
    <listeners>
      <listener compiler="MyCompilerListener" />
    <listeners>
  • Compile with the following command, or an ant task you have set up.
    Code Block
    java -jar [IzPackRoot]/lib/compiler.jar -HOME [IzPackRoot]
      [MyProjectPath]/install.xml -b [MyProductPath] -o
      [MyBuildPath]/install.jar
  • Test it

Custom Actions at Installation Time (InstallerListener)

Perform the same steps as above, replace all occurrences of "CompilerListener" with "InstallerListener" and "compiler" with "installer".

Custom Actions at Uninstallation Time (UninstallerListener)

Perform the same steps as above, replace all occurrences of "CompilerListener" with "UninstallerListener"and "compiler" with "uninstaller".

Example

Let us say, we want to set access rights for files and directories on Unix. The Java sources are placed in the directory IzPackRoot/sample/src/com/myCompany/tools/install/listener. There are the files ChmodCompilerListener.java and ChmodInstallerListener.java.

  • Copy the files to IzPackRoot/src/lib/com/myCompany/tools/install/listener
  • In IzPackRoot/src/build.xml there are the lines
    Code Block
    <!-- CUSTOM ACTION test START
    CUSTOM ACTION test END -->
    Uncomment them (activate the lines between them).
  • Build IzPack new.
  • Compile a test installation with
    Code Block
    java -jar [IzPackRoot]/lib/compiler.jar -HOME [IzPackRoot]
      [IzPackRoot]/sample/listener/install.xml
      -b [IzPackRoot]/sample/listener -o
      [IzPackRoot]/sample/listener/install.jar
  • Install it
    Code Block
    java -jar install.jar

Ant Actions (InstallerListener and UninstallerListener)

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 example:

...

Be aware, 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. 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 uninstaller.jar. Be aware 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 Basic XML Struture

An ant action will be defined in the resource with the id "AntActionsSpec.xml". Sometimes it will help to lock into IzPackRoot/src/dtd/event/antaction.dtd or validate a written xml file with the dtd.

...

  • name: required. The name of the uninstall target.

Registry access (InstallerListener and UninstallerListener)

The event package of IzPack contains an installer and an uninstaller listener for Windows registry access. The listeners uses the separated pack com.coi.tools which is also available as source under the src subtree of IzPack. The registry will be called by JNI.

...

The id has to be RegistrySpec.xml. The real file name is not of any importance but should be written the same as in your source tree. It will be securer if you do not use special chars like blanks or umlauts. Be aware! If you forget to refer to registrySpec.xml in your install.xml no exception will be made because this is a facultative file

The Basic XML Struture

The specification file for registry entries will be defined in the resource with the id "ReigstrySpec.xml". Sometimes it will help to lock into IzPackRoot/src/dtd/event/registry.dtd or validate a written xml file with the dtd.

...