(by Klaus BARTZ)
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
reviseAdditionalDataMapgives the facility to add data to each
PackFileobject. 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
existenDataMapbecause more than one listener can be used. If the given map is null, a new one will be created.
notifyis 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
beforePackswill be called each time before an unpacking call is performed.
beforePackis called before a package is installed. Pack object and the number of the pack are passed.
isFileListenerdetermines whether the next four methods are called or not. This is a little performance optimizing.
beforeDiris 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
PackFileobject are passed.
afterDiris called directly after the directory creation.
beforeFileis called before a file is created. The file and
PackFileobject are passed as parameters.
afterFileis the best place to perform file related actions. The given
PackFileobjects contains the additional data which was set at packaging.
afterPackwill be just called after the pack is closed.
afterPacksis 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.runas first call.
beforeDeletionwill be called after execute files was performed. The given list contains all File objects which are marked for deletion.
isFileListenerdetermines whether the next two methods are called or not.
beforeDeleteis the method which, is called before a single file is deleted. The File object is given as parameter.
afterDeletewill be invoked after the delete call for a single file.
afterDeletionis the last call before the cleanup of created data is performed.
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
/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)
com.izforge.izpack.event.SimpleCompilerListener. Place it as
- Add a "
build-compiler-listener" macro call in to the
/src/build.xml. Note that the name attribute value in the build-instealler-listener must match
CompilerListenerimplementation class name (not including the package). You should include the actual Listener implementation, as well as any other classes required by the listener.
<build-compiler-listener name="MyCompilerListener"> <include name="[MyPackagePath]/MyCompilerListener.java"/> <include name="[MyPackagePath]/SomeOtherHelperClass.java"/> </build-compiler-listener>
antalone will execute the required targets.
- Add a "listeners" ELEMENT with a "listener" ELEMENT with a "compiler" attribute in to MyProjectPath/install.xml
<listeners> <listener compiler="MyCompilerListener" /> <listeners>
- Compile with the following command, or an ant task you have set up.
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".
Let us say, we want to set access rights for files and directories on Unix. The Java sources are placed in the directory
/sample/src/com/myCompany/tools/install/listener. There are the files ChmodCompilerListener.java and ChmodInstallerListener.java.
- Copy the files to
/src/build.xmlthere are the lines
Uncomment them (activate the lines between them).
<!-- CUSTOM ACTION test START CUSTOM ACTION test END -->
- Build IzPack new.
- Compile a test installation with
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
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
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
/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
/src/dtd/event/registry.dtd or validate a written xml file with the dtd.