Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>Custom Actions</h1>

<p>(by Klaus BARTZ)</p>

<h2>Overview</h2>

<p>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.</p>

<p>In general the installation procedure is separated into several steps. The first step, let's call it the <em>data collection phase</em>, is getting specific data needed for the installation process. Typically this is done by typing all neded data into one or more panels, if a GUI is used, or automatically by reading the data from a config file. In general nothing will be changed on the system until all needed data is obtained. But mostly - depending on to the information, e.g. the destination path - different input panels are involved.</p>

<p>If all needed data is collected the second step will be perfomed, let us call it the <em>action phase</em>. During this step the state of the locale machine will be changed, e.g. files will be copied to the installation destination or some short cuts will be registered. Each of this subsequent steps are denoted as actions. There are actions intended to be reused, so called common actions, and actions for one special purpose only, so called custom actions. In IzPack there are already some common actions, for example &quot;file transfer&quot;, &quot;parse&quot; or &quot;execute&quot;.</p>

<p>The third step, the <em>reporting phase</em>, is normally represented by a panel that reports the result state of the installation (OK, or not OK) and a simple good bye message.</p>

<p>With IzPack there are two ways to implement custom actions. Firstly it is always possible to define a custom panel that perfoms the desired actions too. Secondly, and that's the new, custom actions are supported.</p>

<p>Panels still may be used for actions that are perfomed, e.g. before files are transferred or after the &quot;execute&quot; action. But if the needed action depends on the selected or already installed packages, this works also, but the implementation effort is much higher.</p>

<p>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.</p>

<h2>How It Works</h2>

<p>Custom actions are implemented as listeners. Each listener implements callback methods that will be called at well-defined points. The method <code>InstallerListener.afterFile</code> 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.</p>

<p>Each interface is implemented by a class with the prefix &quot;Simple&quot; (e.g. SimpleCompilerListener) that implements all declared interface methods with an empty body. These classes may be used as base classes for own listener implementations.</p>

<p>To apply custom actions to the installer, an entry in the apropriate install.xml file is needed. The configuration of listeners starts with the facultative ELEMENT &quot;listeners&quot; which can contain one or more ELEMENTs of &quot;listener&quot;. For a &quot;listener&quot; there are three attributes which determine the &quot;compiler&quot;, &quot;installer&quot; and &quot;uninstaller&quot; custom action pupose. Additionally it is possible to make the listener OS dependent using the &quot;os&quot; ELEMENT.</p>

<p>If file related data will be set, the facultative ELEMENT &quot;additionaldata&quot; is defined for the ELEMENTs &quot;file&quot;, &quot;singlefile&quot; and &quot;fileset&quot;. 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).</p>

<h2>Custom Action Types</h2>

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

<h4>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. <img class="confluence-embedded-image" src="/plugins/servlet/confluence/placeholder/unknown-attachment?locale=en_GB&amp;version=2" title="img12.png" data-resource-id="PHJpOmF0dGFjaG1lbnQgcmk6ZmlsZW5hbWU9ImltZzEyLnBuZyIgLz4="></h4>

<ul>
	<li><em>(constructor)</em>: 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 <code>notify</code> call.</li>
	<li><code>reviseAdditionalDataMap</code> gives the facility to add data to each <code>PackFile</code> 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 <code>CompilerListeners</code>. Each call of this method adds own key value pairs to the given <code>existenDataMap</code> because more than one listener can be used. If the given map is null, a new one will be created.</li>
	<li><code>notify</code> is called at the beginning and at the end of each &quot;add&quot; method call which is called in <code>Compiler.executeCompiler</code>. Custom Actions At Installing Time h3. <img class="confluence-embedded-image" src="/plugins/servlet/confluence/placeholder/unknown-attachment?locale=en_GB&amp;version=2" title="img13.png" data-resource-id="PHJpOmF0dGFjaG1lbnQgcmk6ZmlsZW5hbWU9ImltZzEzLnBuZyIgLz4="></li>
	<li><em>(constructor)</em>: only the default constructor will be used. It is called from <code>Unpacker.run</code> before unpacking.</li>
	<li><code>beforePacks</code> will be called each time before an unpacking call is performed.</li>
	<li><code>beforePack</code> is called before a package is installed. Pack object and the number of the pack are passed.</li>
	<li><code>isFileListener</code> determines whether the next four methods are called or not. This is a little performance optimizing.</li>
	<li><code>beforeDir</code> 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 <code>PackFile</code> object are passed.</li>
	<li><code>afterDir</code> is called directly after the directory creation.</li>
	<li><code>beforeFile</code> is called before a file is created. The file and <code>PackFile</code> object are passed as parameters.</li>
	<li><code>afterFile</code> is the best place to perform file related actions. The given <code>PackFile</code> objects contains the additional data which was set at packaging.</li>
	<li><code>afterPack</code> will be just called after the pack is closed.</li>
	<li><code>afterPacks</code> is the last step before the handler will be stopped. Custom Actions At Uninstalling Time h3. <img class="confluence-embedded-image" src="/plugins/servlet/confluence/placeholder/unknown-attachment?locale=en_GB&amp;version=2" title="img14.png" data-resource-id="PHJpOmF0dGFjaG1lbnQgcmk6ZmlsZW5hbWU9ImltZzE0LnBuZyIgLz4="></li>
	<li><em>(constructor)</em> : only the default constructor will be used. It is called from <code>Destroyer.run</code> as first call.</li>
	<li><code>beforeDeletion</code> will be called after execute files was performed. The given list contains all <em>File</em> objects which are marked for deletion.</li>
	<li><code>isFileListener</code> determines whether the next two methods are called or not.</li>
	<li><code>beforeDelete</code> is the method which, is called before a single file is deleted. The <em>File</em> object is given as parameter.</li>
	<li><code>afterDelete</code> will be invoked after the delete call for a single file.</li>
	<li><code>afterDeletion</code> is the last call before the cleanup of created data is performed.</li>
</ul>

<h2>Package Path</h2>

<p>Custom actions must always implement one of the given listener interfaces. As mentioned above, it is also possible to derive from one of the &quot;Simple&quot; 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 <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/bin/customActions</code>, may be</p>

<h2>Native Libraries for Uninstallation</h2>

<p>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 <code>stage</code> attribute to the <code>native</code> tag in the install xml file like</p>

<p>Follow the steps that are needed to create and use custom actions with the &quot;normal&quot; source environment (not standalone compiler) using Ant. Of course, it works also with the standalone compiler.</p>

<h2>Custom Actions at Packaging (CompilerListener)</h2>

<ul>
	<li>Implement <code>com.izforge.izpack.event.CompilerListener</code> or extend <code>com.izforge.izpack.event.SimpleCompilerListener</code>. Place it as <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/src/lib/</code><code><a class="confluence-link unresolved" data-content-title="MyPackagePath" data-linked-resource-default-alias="MyPackagePath" href="#">MyPackagePath</a></code><code>/MyCompilerListener.java</code>.</li>
	<li>Add a &quot;<code>build-compiler-listener</code>&quot; macro call in to the <code>build.listeners</code> target in <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/src/build.xml</code>. Note that the name attribute value in the build-instealler-listener must match <code>CompilerListener</code> implementation class name (not including the package). You should include the actual Listener implementation, as well as any other classes required by the listener.
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;build-compiler-listener
name="MyCompilerListener">
    &lt;include
    name="[MyPackagePath]/MyCompilerListener.java"/>
    &lt;include
    name="[MyPackagePath]/SomeOtherHelperClass.java"/>
&lt;/build-compiler-listener></pre></td></tr></table></li>
	<li>Run <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/src/build.xml</code>. An <code>ant</code> alone will execute the required targets.</li>
	<li>Add a &quot;listeners&quot; ELEMENT with a &quot;listener&quot; ELEMENT with a &quot;compiler&quot; attribute in to <a class="confluence-link unresolved" data-content-title="MyProjectPath" data-linked-resource-default-alias="MyProjectPath" href="#">MyProjectPath</a>/install.xml
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;listeners>
  &lt;listener compiler="MyCompilerListener" />
&lt;listeners></pre></td></tr></table></li>
	<li>Compile with the following command, or an ant task you have set up.
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>java -jar [IzPackRoot]/lib/compiler.jar -HOME [IzPackRoot]
  [MyProjectPath]/install.xml -b [MyProductPath] -o
  [MyBuildPath]/install.jar</pre></td></tr></table></li>
	<li>Test it</li>
</ul>

<h2>Custom Actions at Installation Time (InstallerListener)</h2>

<p>Perform the same steps as above, replace all occurrences of &quot;CompilerListener&quot; with &quot;InstallerListener&quot; and &quot;compiler&quot; with &quot;installer&quot;.</p>

<h2>Custom Actions at Uninstallation Time (UninstallerListener)</h2>

<p>Perform the same steps as above, replace all occurrences of &quot;CompilerListener&quot; with &quot;UninstallerListener&quot;and &quot;compiler&quot; with &quot;uninstaller&quot;.</p>

<h2>Example</h2>

<p>Let us say, we want to set access rights for files and directories on Unix. The Java sources are placed in the directory <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/sample/src/com/myCompany/tools/install/listener</code>. There are the files ChmodCompilerListener.java and ChmodInstallerListener.java.</p>

<ul>
	<li>Copy the files to <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/src/lib/com/myCompany/tools/install/listener</code></li>
	<li>In <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/src/build.xml</code> there are the lines
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;!-- CUSTOM ACTION test START
CUSTOM ACTION test END --></pre></td></tr></table>
Uncomment them (activate the lines between them).</li>
	<li>Build IzPack new.</li>
	<li>Compile a test installation with
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>java -jar [IzPackRoot]/lib/compiler.jar -HOME [IzPackRoot]
  [IzPackRoot]/sample/listener/install.xml
  -b [IzPackRoot]/sample/listener -o
  [IzPackRoot]/sample/listener/install.jar</pre></td></tr></table></li>
	<li>Install it
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>java -jar install.jar</pre></td></tr></table></li>
</ul>

<h2>Ant Actions (InstallerListener and UninstallerListener)</h2>

<p>In this section the common ant task custom actions are described in detail. It is only for developers who are not acquainted with <code>IzPack</code> 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 <code>com.izforge.izpack.event</code> there are the ant related custom actions <code>AntActionInstallerListener</code> and <code>AntActionUninstallerListener</code>. As recapitulation, to add any custom action a reference in install.xml will be needed, as example:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;listeners>
    &lt;listener installer="AntActionInstallerListener"
        uninstaller="AntActionUninstallerListener" />
&lt;/listeners></pre></td></tr></table>
<p>For all referenced listeners a jar file with the same name must exist in <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/bin/customActions</code>. If compilation (packaging) fails with a &quot;not found&quot; 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 <code>pack</code> 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 <code>AntActionsSpec.xml</code> e.g.</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;jar src="jar/ant/ant.jar" stage="both" /></pre></td></tr></table>
<p>Be aware, that an &quot;extended&quot; ant use needs more than one jar, for example often <code>xercesImpl.jar</code>. If an obscure &quot;class not found&quot; exception is raised during testing, check first for missing jar files. For supporting uninstallation the jar field was extended by the attribute <code>stage</code>. If an ant uninstaller custom action is used, the uninstaller also needs the jar files. If <code>stage</code> is &quot;both&quot; or &quot;uninstall&quot;, 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 <code>meta-inf/Manifest.mf</code> will be lost.</p>

<h2>The Basic XML Struture</h2>

<p>An ant action will be defined in the resource with the id &quot;AntActionsSpec.xml&quot;. Sometimes it will help to lock into <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/src/dtd/event/antaction.dtd</code> or validate a written xml file with the dtd.</p>

<p>On this xml file a substitution will be performed using all defined <code>IzPack</code> variables. It is performed just before processing the packs. This is a common way of loading spec files into custom actions. For more information see method <code>com.izforge.izpack.util.SpecHelper.readSpec</code>. If you want to substitute some custom item, simply add a variable via idata.setVariable in a custom panel before <code>InstallPanel</code>. The given variable name (id) should be written into the xml file in the common variable notation.</p>

<p>The top level XML section is called <code>&lt;antactions&gt;</code>. Only one is possible. The <code>&lt;antactions&gt;</code> are segregated in one or more <code>&lt;pack&gt;</code> elements. The single attribute <code>&lt;name&gt;</code> of the <code>&lt;pack&gt;</code> corresponds to the same structure in install.xml (for more information see also installation.dtd). Only the &quot;things&quot; included in the <code>&lt;pack&gt;</code> are performed, if a pack with the same name was chosen to be installed. The &quot;things&quot; to be done to self are defined by the element <code>&lt;antcall&gt;</code> (without ssss).</p>

<p>The <code>&lt;antcall&gt;</code> takes the following attributes:</p>

<ul>
	<li><code>order</code>: required. Determine at what point of installation the antcalls defined by element <code>target</code> should be performed. Possible are <code>beforepack</code>, <code>afterpack</code>, <code>beforepacks</code> or <code>afterpacks</code>. Be aware that with beforepack(s) there are no installed files and also no installed build file. With this order only preexistent build files are useable.</li>
	<li><code>uninstall_order</code>: optional. Determine at what point of uninstallation the antcalls defined by element <code>uninstall_target</code> should be performed. Possible are <code>beforedeletion</code> and <code>afterdeletion</code>. As opposed to the behaviour of <code>order</code> the referenced files are also accessible in the order <code>afterdeletion</code>. The uninstaller action copies the files into tempfiles before deletion which are marked as deleteOnExit.</li>
	<li><code>quiet</code>: optional. To quit or not. Possible are yes or no. Default is no.</li>
	<li><code>verbose</code>: optional. To output verbose information or not. Possible are yes or no. Default is no.</li>
	<li><code>logfile</code>: optional. Path of the file for logging should be performed. The logfile should be not marked for uninstallation otherwise it will be deleted too.</li>
	<li><code>buildfile</code>: either <code>buildfile</code> or <code>buildresource</code> is required but not both. Path of the file which contains the antcall. This is the file you normally use as <code>-buildfile</code> during an ant call via the command line. In this file variables are not substituted. For substitution there are properties in ant which can be used. Never write an <code>IzPack</code> variable in an ant buildfile.</li>
	<li><code>buildresource</code>: either <code>buildresource</code> or <code>buildfile</code> is required but not both. The value is the id of the resource which contains the antcall. This resource will be extracted out into a temporary file and the path to this file will be passed as if <code>-buildfile</code> were specified during the ant call via the command line. The temporary file is removed after the ant call. In this file variables are not substituted. For substitution there are properties in ant which can be used. Never write an <code>IzPack</code> variable in an ant buildfile.</li>
	<li><code>messageid</code>: optional. A string ID which refers to <code>bin/langpacks/installer/&lt;lang&gt;.xml</code>. If it is defined, the message will be displayed in the InstallPanel whilst performing the ant call.</li>
</ul>

<p>In addition to the possible attributes there are some elements. All elements can be defined more than one time in one <code>&lt;antcall&gt;</code>. All are optional, but with no <code>&lt;target&gt;</code> element the <code>&lt;antcall&gt;</code> makes no sense. Do not confuse the following: &quot;required&quot;s are related to the attributes of the elements, not to the elements themselfs. <code>&lt;property&gt;</code>: define a property h3. Property to be used with all <code>target</code> and <code>uninstall_target</code> which are defined for this antcall.</p>

<ul>
	<li><code>name</code>: required. The name (id) of the property.</li>
	<li><code>value</code>: required. The value of the property. <code>&lt;propertyfile&gt;</code>: define properties in a file h3. Properties to be used with all targets and uninstall_targets which are defined for this antcall given by the path of a properties file.</li>
</ul>

<ul>
	<li><code>path</code>: required. Path of a file which contains properties in the syntax which is used by ant. Some ant calls need properties files. For these this element is used. One way to fill specific data into it is to create a new file in a custom panel and fill it with values given by input fields. The file path can be set at installation time, if there is a variable in AntActionSpec.xml and an IzPack variable was defined before InstallPanel. That file can be only created with deleteOnExit, if no <code>&lt;uninstall_target&gt;</code> was defined in this <code>&lt;antcall&gt;</code>. This implies, that other <code>&lt;antcall&gt;}}s can have a {{&lt;uninstall_target&gt;</code>. <code>&lt;target&gt;</code>: target to call at installation h3. Targets to perform with this antcall at installation time. The targets should be defined in the given buildfile or else an ant exception will be raised. This is that what you use, if you don't want to perform the default target. e.g. cleaning the <code>IzPack</code> project with <code>ant clean</code></li>
</ul>

<ul>
	<li><code>name</code>: required. The name of the target. <code>&lt;uninstall_target&gt;</code>: target to call on uninstallation h3. Targets to perform with this antcall at uninstallation time. The targets should be defined in the given buildfile otherwise an ant exception will be raised. With this target it will be possible to undo the things done at installation time.</li>
</ul>

<ul>
	<li><code>name</code>: required. The name of the uninstall target.</li>
</ul>

<h2>Registry access (InstallerListener and UninstallerListener)</h2>

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

<p>There is no support from the IzPack project of this feature for Windows 95, Windows 98 and Windows ME. Please check the patches at <a href="http://jira.codehaus.org/browse/IZPACK-58">http://jira.codehaus.org/browse/IZPACK-58</a> if you need to support those platforms.</p>

<p>The registry stuff was implemented in all conscience, but certainly WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND</p>

<p>The listeners themselves are only able to write into the Windows registry at installation and delet the writing at uninstall time. But it is also possible to use the registry handler as a registry reader in custom panels or costum actions. The `CheckedHelloPanel` reads the registry and can be used as example for it.</p>

<p>To add registry support to an installation some changes in the installation definition file (often called{{install.xml}}) are to be made. First the declaration of the listener themselves:</p>

<p>As with other listeners a jar file with the same name has to exist in <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/bin/customActions</code>. If compilation (packaging) fails with an &quot;not found&quot; error, verify, that the jar file exists. If not, create it. The jar files are <code>RegistryInstallerListener.jar</code> and <code>RegistryUninstallerListener.jar</code>.</p>

<p>As second change in <code>install.xml</code> we have to declare the native part JNI needs the dll</p>

<p>With these two changes the registry support will be incorporated into your installation. Without any more actions an uninstall key will be crated in the registry at the installation. If you open the software manager of Windows, there will be an entry with the variables $APP_NAME $APP_VER, e.g.:</p>

<p>If you would like to have more informations in the uninstaller key or to create other keys or values in the registry, you should create a specification file. The file should be then refered to in <code>install.xml</code> as resource:</p>

<h2>The Basic XML Struture</h2>

<p>The specification file for registry entries will be defined in the resource with the id &quot;ReigstrySpec.xml&quot;. Sometimes it will help to lock into <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/src/dtd/event/registry.dtd</code> or validate a written xml file with the dtd.</p>

<p>The top level XML section is called <code>&lt;registry&gt;</code>. Only one is possible. The <code>&lt;registry&gt;</code> is segregated in one or more <code>&lt;pack&gt;</code> elements. The single attribute <code>&lt;name&gt;</code> of the <code>&lt;pack&gt;</code> corresponds to the same structure in install.xml (for more information see also installation.dtd). <code>&lt;pack&gt;</code> elements can have a condition attribute to express that a certain pack shall only be performed if the condition is fulfilled. Only the &quot;things&quot; included in the <code>&lt;pack&gt;</code> are performed, if a pack with the same name was chosen to be installed. Valid &quot;things&quot; are &lt;key&gt; &lt;value&gt;.</p>

<p>The registry stuff self allows to create keys and values directly under a registry root. But Windows self allows this not on &quot;real&quot; roots like HKEY_LOCAL_MACHINE or HKEY_USERS. Only link like roots as HKEY_CLASSES_ROOT are writeable. A try e.g. on HKLM will be cause an exception and the installation fails. The error number in this case normally will be 87 with the meaning &quot;wrong parameter&quot;, not &quot;permission denied&quot;.</p>

<p>We do NOT recommend to create a key or a value directly on a registry root. IzPack allows it now as a result of some user requests about it. Most it is not needed. E.g. an extension entry under HKEY_CLASSES_ROOT is really an entry on HKEY_LOCAL_MACHINESoftwareClasses. Why not write directly there?Reading is in opposite to writing no problem. <code>&lt;key&gt;</code>: define a key h3. Key to be set at installation time into the Windows registry.</p>

<ul>
	<li><code>keypath</code> : required. The path of the key in Windows syntax without the root. If the key should be placed directly under a registry root (`not recommended; often not possible)`) write the key name without any backslash.</li>
	<li><code>root</code> : required. The root of the key as symbol. Valid is one of HKCR HKCU HKLM HKU HKPD HKCC HKDDS. <code>&lt;value&gt;</code>: define a value h2. =</li>
</ul>

<p>Value to be set at installation time into the Windows registry.</p>

<ul>
	<li><code>condition</code>`: optional. The id of condition which has to be fulfilled to write this value into the registry.</li>
	<li><code>name</code> : required. The name of the value to be set or modified without a path. The default value will be written as the empty string &quot;&quot;.</li>
	<li><code>keypath</code> : required. The key path under which the value should be placed in Windows syntax without the root and value name. If the key of the value should be placed directly under a registry root (if not exist, `not recommended; often not possible)`) write the key name without any backslash. If the value should be placed directly under a registry root (also not recommended and often not possible) write as keypath the empty string &quot;&quot;.</li>
	<li><code>root</code> : required. The root of the key as symbol. Valid is one of HKCR HKCU HKLM HKU HKPD HKCC HKDDS.</li>
	<li><code>override</code> : optional. Override an existent value or not. Valid is &quot;true&quot; or &quot;false&quot;, default is &quot;true&quot;.</li>
	<li><code>saveprevious</code> : optional. Save the previous value or not. Valid is &quot;true&quot; or &quot;false&quot;, default is &quot;true&quot;. Setting to &quot;false&quot; can result in better uninstall behavior when an install is performed on top of an existing installation.</li>
	<li><code>Contents part</code>: accurately one of the following content elements should be defined. It implicit defines the type of the value.
	<ul>
		<li><code>string</code> : contents for value to be set if it is a string (REG_SZ).</li>
		<li><code>string</code> : if the string value starts with `%`, then the string is considered as an expandable string (REG_EXPAND_SZ) which is useful to reference Windows environment variables (e.g., in paths, etc).</li>
		<li><code>dword</code> : contents for value to be set if it is an integer (Windows DWORD). Only digits are valid. &quot;48&quot; is valid, &quot;0x30&quot; will be raise an NumberFormatException from <code>java.lang.Long.parseLong</code>.</li>
		<li><code>&lt;bin&gt;</code> : element to handle one &quot;line&quot; of binary data.
		<ul>
			<li><code>data</code> : contents for value of type BINARY written as comma separated list of hex. Only hex-digits are valid. &quot;48, f4&quot; is valid, &quot;0x48, 0xf4&quot; will be raise an NumberFormatException from <code>java.lang.Integer.parseInt</code>.</li>
		</ul>
		</li>
	</ul>
	</li>
</ul>

<ul>
	<li>
	<ul>
		<li><code>&lt;multi&gt;</code>: element to handle one contents string for MULTI_STRINGs.
		<ul>
			<li><code>data</code> : the contents for the element &lt;multi&gt;.</li>
		</ul>
		</li>
	</ul>
	</li>
</ul>

<p>In the case of string values being updated, it is possible to reuse the old value and have it for substitution through the <code>OLD_KEY_VALUE</code> variable, like in the following example:</p>

<p>Maybe the descriptions for type BINARY and MULTI_STRING are not fully descriptive. Therefore as example the test entries in the registry specification file of IzPack:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;registry>
  ...
  &lt;pack name="Core" condition="izpack.windowsinstall.vista">
    &lt;value name="Path"
      keypath="SOFTWARE\IzForge\IzPack\$APP_VER"
      root="HKLM"
      string="$INSTALL_PATH"/>
    &lt;value name="DWORD"
      keypath="SOFTWARE\IzForge\IzPack\$APP_VER"
      root="HKLM"
      dword="42"/>
    &lt;value name="BIN"
      keypath="SOFTWARE\IzForge\IzPack\$APP_VER"
      root="HKLM" >
      &lt;bin data="42, 49, 4e, 20, 54, 45, 53, 54" />
      &lt;bin data="42, 49, 4e, 20, 54, 45, 53, 54" />
    &lt;/value>
    &lt;value name="MULTI"
      keypath="SOFTWARE\IzForge\IzPack\$APP_VER"
      root="HKLM" >
      &lt;multi data="A multi string with three elements" />
      &lt;multi data="Element two"/>
      &lt;multi data="Element three"/>
    &lt;/value>
  &lt;/pack>
&lt;/registry></pre></td></tr></table>
<p> Extended Uninstall Key h2. There is a special pack named <code>UninstallStuff</code>. If a pack will be declared like</p>

<p>The registry handler self cannot ensure the uniqueness of an uninstaller key. There is the special panel <code>CheckedHelloPanel</code> which does it. If no pack <code>UninstallStuff</code> will be used, this will be performed full automatically. If the pack was declared, <strong>all</strong> keypaths under it should be written as following:</p>

<ul>
	<li>A review of the registry will be performed only on supported operating systems (current only on Windows).</li>
	<li>A review of the registry will be performed only if the registry stuff was bound for uninstallation.</li>
	<li>Keys: Keys can only be deleted, a modification is not possible.
	<ul>
		<li>A previous existent key will be NOT deleted.</li>
		<li>A newly created key will be deleted, if...
		<ul>
			<li>no new values or subkeys are added after installation.</li>
			<li>no changes are made at the contents of values after installation.<br />
With other words: if under the key something was changed between installation and uninstallation, the key will be persist.</li>
		</ul>
		</li>
	</ul>
	</li>
	<li>Values:
	<ul>
		<li>A newly created value will be deleted, if the contents at uninstall time is the same as after installation.</li>
		<li>The contents of a previos existent value will be changed to the previous contents (the contents before installation) if the contents at uninstall time is the same as after installation.<br />
In other words: if the contents of a value was changed between installation and uninstallation this contents will be persist. There is no handling of parts of the contents (important for type MULTI_STRING).</li>
	</ul>
	</li>
</ul>

<p>This conservative behavior cannot be changed to a user dependant voting because there is no user interface for custom actions at uninstall time. Additional the registry handler to not support voting. Examples h2. There are the files</p>

<p><code>RegistrySpec.xml</code> will be referred by <code>IzPack-install-reg.xml</code> as resource. It contains the special pack named <code>UninstallStuff</code> for Izpack and defines some additional keys and values. Summary Logger (InstallerListener) h2. The listener <code>SummaryLoggerInstallerListener</code> can be used to log the `summary of panels` into a file. To use it, add following element to the listener section of your installation config file.</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;info>
    ...
    &lt;summarylogfilepath>
        $INSTALL_PATH/Uninstaller/MySummary.htm
    &lt;/summarylogfilepath>
&lt;/info></pre></td></tr></table>
<p> BSF (Bean Scripting Framework) Actions (InstallerListener and UninstallerListener) h2. In this section the BSF custom actions are described in detail. It is only for developers who are not acquainted with <code>IzPack</code> 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 <code>com.izforge.izpack.event</code> there are the BSF related custom actions <code>BSFInstallerListener</code> and <code>BSFUninstallerListener</code>. As recapitulation, to add any custom action a reference in install.xml will be needed, as example:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;listeners>
    &lt;listener installer="BSFInstallerListener"
        uninstaller="BSFUninstallerListener" />
&lt;/listeners></pre></td></tr></table>
<p>For all referenced listeners a jar file with the same name must exist in <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/bin/customActions</code>. If compilation (packaging) fails with a &quot;not found&quot; error, first verify, that the jar file exists. If not, create it. With this custom action it is possible to perform BSF 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 BSF script should be performed at what time of (un)installation and specifies which properties for what IzPack <code>pack</code> are to be used. The intersected description file is written as XML, the corresponding dtd is placed in src/dtd/event/bsfaction.dtd. The description file should be declared as a resource in the install.xml with the id <code>BSFActionsSpec.xml</code> e.g.</p>

<p>A BSF action will be defined in the resource with the id &quot;BSFActionsSpec.xml&quot;. Sometimes it will help to lock into <code><a class="confluence-link unresolved" data-content-title="IzPackRoot" data-linked-resource-default-alias="IzPackRoot" href="#">IzPackRoot</a></code><code>/src/dtd/event/bsfaction.dtd</code> or validate a written xml file with the dtd.</p>

<p>The top level XML section is called <code>&lt;bsfactions&gt;</code>. Only one is possible. The <code>&lt;bsfactions&gt;</code> are segregated in one or more <code>&lt;pack&gt;</code> elements. The single attribute <code>&lt;name&gt;</code> of the <code>&lt;pack&gt;</code> corresponds to the same structure in install.xml (for more information see also installation.dtd). Only the &quot;things&quot; included in the <code>&lt;pack&gt;</code> are performed, if a pack with the same name was chosen to be installed. The &quot;things&quot; to be done to self are defined by the element <code>&lt;script&gt;</code>.</p>

<p>The <code>&lt;script&gt;</code> takes the following attributes:</p>

<ul>
	<li><code>language</code>: required. The name of the BSF language which is being used. The exact name of the language is dependent upon the BSF engine integration of that particular language. Some example values are &quot;javascript&quot; and &quot;groovy&quot;.</li>
	<li><code>src</code>: optional. The name of a resource, defined in your installer.xml, which contains the script contents. This may be used in lieu of embeddeding the script contents in the BSFActionsSpec.xml file itself.</li>
</ul>

<p>In addition to the possible attributes <code>&lt;script&gt;</code> can contain a <code>CDATA</code> section which contains the script content, rather than using the &quot;src&quot; attibute. The different installer/uninstaller phases are scripted by creating a symbol definition for that particular phase. The symbol will then be called by the listener (if present), and the appropriate phase variables defined. If a particular phase is not defined, it will be skipped.</p>

<p>NOTE: In some languages, such as groovy and jython, you must create the function as a closure, so that the symbol is globally defined. In other languages (such as beanshell), you can create the function normally.</p>

// Variables defined
  //   idata - installer data, of type AutomatedInstallerData
  afterPacks = {
    print "after packs";
  }

// Variables defined
  //   pack - pack information, of type Pack
  //   i - the package index
  beforePack = {
    print "before pack " + pack.name;
  }

// Variables defined
  //   pack - pack information, of type Pack
  //   i - the package index
  afterPack = {
    print "before pack " + pack.name;
  }

// Variables defined
  //   pack - pack information, of type Pack
  //   file - the dir which is to be created, of type File
  beforeDir = {
    print "before dir " + file.absolutePath;
  }

// Variables defined
  //   pack - pack information, of type Pack
  //   file - the dir which was created, of type File
  afterDir = {
    print "after dir " + file.absolutePath;
  }

// Variables defined
  //   pack - pack information, of type Pack
  //   file - the file which is to be installed, of type File
  beforeFile = {
    print "before file " + file.absolutePath;
  }

// Variables defined
  //   pack - pack information, of type Pack
  //   file - the file which was installed, of type File
  afterFile = {
    print "after file " + file.absolutePath;
  }

// Variables defined
  //   files - pack information, of type Pack
  //   variables - the variables which were used during the original install, of type Properties
  beforeDeletion = {
    print "before deletion";
  }

// Variables defined
  //   files - pack information, of type Pack
  //   variables - the variables which were used during the original install, of type Properties
  afterDeletion = {
    print "after deletion";
  }

// Variables defined
  //   file - the file which is to be deleted, of type File
  //   variables - the variables which were used during the original install, of type Properties
  beforeDelete = {
    print "before delete";
  }

// Variables defined
  //   file - the file which was to be deleted, of type File
  //   variables - the variables which were used during the original install, of type Properties
  afterDelete = {
    print "after delete";
  }
]]&gt;&lt;/script>

&lt;script language="beanshell">&lt;![CDATA[
void beforePacks() {
    print "INSTALL_PATH=${INSTALL_PATH}";
}
]]&gt;&lt;/script></pre></td></tr></table>
<p>More detailed examples can be downloaded from <a href="http://jira.codehaus.org/secure/attachment/39246/sample.tar.gz">http://jira.codehaus.org/secure/attachment/39246/sample.tar.gz</a> and <a href="http://jira.codehaus.org/secure/attachment/39379/sample2.tar.gz">http://jira.codehaus.org/secure/attachment/39379/sample2.tar.gz</a></p>