Versions Compared

Old Version 13

changes.mady.by.user Former user

Saved on

compared with

New Version 14

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

</variables> ... <resources> <

...

!--

...

bundle

...

1

...

--

...

>

...

-- bundle 2 -> <bundle id="bundle2"> <res id="Heading.image" src="path2/HeadingImage.png" /> <res id="installer.langsel.img" src="path2/langselImage.png" /> </bundle> <!- common resources --> <res id="resource.id" src="path.to.resource" /> ...

Resources will be then be loaded in the following order:

Code Block
/res/<bundleName>/<resourceName>_<iso3>
/res/<bundleName>/<resourceName>
/res/<resourceName>_<iso3>
/res/<resourceName>

The Panels Element <panels> h3. Here you tell the compiler which panels you want to use. They will appear in the installer in the order in which they are listed in your XML installation file. Take a look at the different panels in order to find the ones you need. The <panel> markup takes the following attributes:

  • classname: which is the classname of the panel.
  • id: an identifier for a panel which can be used e.g. for referencing in userinput panel definitions.
  • condition: an id of a condition which has to be fullfilled to show this panel
  • jar: jar file where the classes for this panel can be found. This attribute is optional. If it is empty (jar="") the classes for this panel must be murged using the <jar> tag.

Here is a sample :

Code Block
<panels>
    <panel classname="HelloPanel"/>
    <panel classname="LicencePanel"/>
    <panel classname="TargetPanel"/>
    <panel classname="InstallPanel"/>
    <panel classname="UserInputPanel" id="myuserinput" condition="pack2selected" />
    <panel classname="FinishPanel" jar="MyFinishPanel.jar"/>
</panels>

The following sections describe the tags available for a <panel> section. <help> - optional file for a help h3. The content of the help file is shown in a small window on the panel, when User clicks on the help button. The button is only shown, when a help in the language exists.

The <help> takes the following attributes :

  • iso3: iso3 representation of the language the help is written
  • src: path to the help file to display

Here's a sample :

Code Block
<panel classname="HelloPanel">
  <help iso3="deu" src="HelloPanelHelp_deu.html" />
  <help iso3="eng" src="HelloPanelHelp_eng.html" />
</panel>

<validator> - optional validation on idata h3. This validation is done, when going on for the next panel. It is also done in case of an automatic installation. The class must implement the interface com.izforge.izpack.api.installer.DataValidator.

The <validator> takes the following attributes :

  • classname: The class implementing com.izforge.izpack.api.installer.DataValidator

Here's a sample :

Code Block
<panel classname="UserInputPanel" id="jdbc.connection.parameters">
  <validator classname="JdbcConnectionValidator" />
</panel>

<actions> - optional actions for the panel h3. Here you can define multiple actions that are done during the lifetime of the panel. The class must implement the interface com.izforge.izpack.installer.PanelAction. The actions are also called during an automated installation.

The <actions> tag has no attributes but has <action> markups with the following attributes :

  • stage: The stage when the action should be triggered. Possible values are preconstruct, preactivate, prevalidate or postvalidate.
  • classname: The class implementing com.izforge.izpack.installer.PanelAction

Here's a sample :

Code Block
<panel classname="UserInputPanel" id="jdbc.connection.parameters">
  <actions>
    <action stage="preconstruct" classname="ConnectionPreConstructAction" />
    <action stage="preactivate" classname="ConnectionPreActivateAction" />
    <action stage="prevalidate" classname="ConnectionPreVAlidateAction" />
    <action stage="postvalidate" classname="ConnectionPostValidateAction" />
  </actions>
</panel>

The Packs Element <packs> h3. This is a crucial section as it is used to specify the files that need to be installed. The <packs> section consists of several <pack>, <refpack> and <refpackset> tags.

The <pack> takes the following attributes :

  • name: the pack name
  • required: takes yes or no and specifies whether the pack is optional or not.
  • os: optional attribute that lets you make the pack targeted to a specific operating system, for instance unix, mac and so on.
  • preselected: optional attribute that lets you choose whether the pack is by default selected for installation or not. Possible values are yes and no. A pack which is not preselected needs to be explicitly selected by the user during installation to get installed.
  • loose: can be used so that the files are not located in the installer Jar. The possible values are true or false, the default beeing false. The author of this feature needed to put his application on a CD so that the users could run it directly from this media. However, he also wanted to offer them the possibility to install the software localy. Enabling this feature will make IzPack take the files on disk instead of from the installer. Please make sure that your relative files paths are correct !
  • id: this attribute is used to give a unique id to the pack to be used for internationalization via packsLang.xml file.
  • packImgId: this attribute is used to reference a unique resource that represents the pack's image for the ImgPacksPanel. The resource should be defined in the <resources> element of the installation XML using the same value for the id attribute of the <res> element.
  • condition: an id of a condition which has to be fullfilled to install this package.
  • hidden: takes true or false and specifies whether the pack shall be shown in the packs panel. The bytes of such a hidden pack will be used to calculate the required space, but the pack itself won't be shown. A hidden pack can be selected conditionally. So you have to specify a condition to enable it for installation. The default for this attribute is false

The <refpack> takes only one attribute file, which contains the relative path (from the installation compiler) to an externally defined packs-definition. This external packs definition is a regular IzPack installation XML. However the only elements that are used from that XML file are the <packs> and the <resources> elements. This enables a model in which a single developer is responsible for maintaining the packs and resources (e.g. separate packsLang.xml_xyz files providing internationalization; see `Internationalization of the PacksPanel`) related to the development-package assigned to him. The main install XML references these xml-files to avoid synchronization efforts between the central installation XML and the developer-maintained installer XMLs.

The <refpackset> tag can be used in situations were there is no predefined set of <refpack> files, but a given directory should be scanned for <refpack> files to be included instead. This element takes the following parameters:

  • dir: the base directory for the refpackset (relative path)
  • includes: a pattern of files in <refpack> format that must be included

An example:

Code Block
<refpackset dir="" includes="**/refpack.xml" />

Internationalization of the PacksPanel h3. In order to provide internationalization for the PacksPanel, so that your users can be presented with a different name and description for each language you support, you have to create a file named packsLang.xml_xyz where xyz is the ISO3 code of the language in lowercase. Please be aware that case is significant. This file has to be inserted in the resources section of install.xml with the id and src attributes set at the name of the file. The format of these files is identical with the distribution langpack files located at $IZPACK_HOME/bin/langpacks/installer. For the name of the panel you just use the pack id as the txt id. For the description you use the pack id suffixed with .description.

An example:

Code Block
<resources>
    <res id="packsLang.xml_eng" src="i18n/myPacksLang.xml_eng"/>
</resources>

The packsLang.xml_eng file: file:

Code Block
<langpack>
    <str id="myApplication" txt="Main Application"/>
    <str id="myApplication.description" txt="A description of my main application"/>
    [...]
</langpack>

The following sections describe the tags available for a <pack> section. <description> - pack description h3. The contents of the <description> tag describe the pack contents. This description is displayed if the user highlights the pack during installation. <depends> - pack dependencies h3. This can be used to make this pack selectable only to be installed only if some other is selected to be installed. The pack can depend on more than one by specifying more than one <depends> elements. Circular depedencies are not supported and the compiler reports an error if one occurs.

This tag takes the following attribute:

  • packname: The name of the pack that it depends on <os> - OS restrictions h3. It is possible to restrict a panel to a certain list of operating systems. This tag takes the following attributes:
  • family: unix, windows or mac
  • name: the exact OS name (ie Windows, Linux, ...)
  • version: the exact OS version (see the JVM os.version property)
  • arch: the machine architecture (see the JVM os.arch property). <updatecheck> h3. This feature can update an already installed package, therefore removing superfluous files after installation. Here's how this feature author (Tino Schwarze) described it on the IzPack development mailing-list:

> Each pack can now specify an <updatecheck> tag. It supports a subset of ant fileset syntax, e.g.:

Code Block
<updatecheck>
  <include name="lib/**" />
  <exclude name="config/local/** />
</updatecheck>

> If the paths are relative, they will be matched relative to $INSTALL_PATH. Update checks are only enabled if at least one <include> is specified. See com.izforge.izpack.installer.Unpacker for details. <file> - add files or directories h3. The <file> tag specifies a file (a directory is a file too) to include into the pack. It takes the following attributes:

  • src: the file location (relative path) - if this is a directory its content will be added recursively. It may contain previously defined static variables (see <variables>).
  • targetdir: the destination directory, could be something like $INSTALL_PATH/subdirX
  • os: can optionally specify a target operating system (unix, windows, mac) - this means that the file will only be installed on its target operating system
  • override: if true then if the file is already installed, it will be overwritten (use false otherwise). Alternative values: asktrue and askfalse -ask the user what to do and supply default value for non-interactive use. Another possible values is update. It means that the new file is only installed if it's modification time is newer than the modification time of the already existing file (note that this is not a reliable mechanism for updates - you cannot detect whether a file was altered after installation this way.) By default it is set to update.
  • blockable : Defines whether and how blocked target files on Windows should be recognized. This might result in pending file operations which require a system reboot. The reboot behavior at the end of an installation for pending file operations can be set using the nested rebootaction_ in the infoelement. See above for possible reboot options. Possible values:
    • none (default): No recognition of blocked target files will be done at all, this is the default behavior of previous IzPack versions.
    • auto: Automatic recognition of a blocked target file by the operating system, resulting in leaving a pending file operation to be finished after system reboot. Using auto this applies only for files that are really blocked, the other files are copied normally, which can result in mixed, old and new target files at the end of the installation, unless the system won't be really rebooted.
    • force: Forces target file to be always assumed a blocked, resulting in leaving a pending file operation to be finished after system reboot. Using force this applies for each file, regardless whether it is really blocked during installation. This makes sense if you don't want to mix files old and new files at the end of the installation to not disturbing a running process, but having the complete set of target files installed after system reboot.
      Notes:
    1. Using blockable does not necessarily force you to limit such files on Windows systems. For multi-platform installations there is a compiler warning thrown that blockable will be ignored on non-Windows systems.
    2. The native library WinSetupAPI must be explicitely included using this feature.
      For setting up the according reboot behaviour see the rebootaction_ element.
      For getting more information see the chapter Advanced features.
  • unpack: if true and the file is an archive then its content will be unpacked and added as individual files
  • condition: an id of a condition which has to be fullfilled to install this file <additionaldata> h3. This tag can also be specified in order to pass additional data related to a file tag for customizing.
  • <key>: key to identify the data
  • <value>: value which can be used by a custom action <singlefile> - add a single file h3. Specifies a single file to include. The difference to <file> is that this tag allows the file to be renamed, therefore it has a target attribute instead of targetdir.
  • src: the file location (relative path). It may contain previously defined static variables (see <variables>).
  • target: the destination file name, could be something like $INSTALL_PATH/subdirX/fileY
  • os: can optionally specify a target operating system (unix, windows, mac) - this means that the file will only be installed on its target operating system
  • override: see <file> for description
  • blockable: see <file> for description
  • condition: an id of a condition which has to be fullfilled to install this file

A <additionaldata> tag can also be specified for customizing. <fileset>: add a fileset h3. The <fileset> tag allows files to be specified using the powerful Jakarta Ant set syntax. It takes the following parameters:

  • dir: the base directory for the fileset (relative path)
  • targetdir: the destination path, works like for <file>
  • casesensitive: optionally lets you specify if the names are case-sensitive or not - takes yes or no
  • defaultexcludes: optionally lets you specify if the default excludes will be used - takes yes or no.
  • os: specifies the operating system, works like for <file>
  • override: see <file> for description
  • blockable: see <file> for description (applied for all files in the fileset)
  • includes: comma- or space-separated list of patterns of files that must be included; all files are included when omitted. This is an alternative for multiple include tags.
  • excludes: comma- or space-separated list of patterns of files that must be excluded; no files (except default excludes) are excluded when omitted. This is an alternative for multiple exclude tags.
  • condition: an id of a condition which has to be fullfilled to install the files in this fileset

You specify the files with <include> and <exclude> tags that take the name parameter to specify the Ant-like pattern :

Panel

* : means any subdirectory

    • : used as a wildcard.

Here are some examples of Ant patterns :

  • <include name="lib"/> : will include lib and the subdirectories of lib

    Panel

    <exclude name="/.java"/> : will exclude any file in any directory starting from the base path ending by .java
    <include name="lib/.jar"/> : will include all the files ending by .jar in lib
    <exclude name="lib/*/FOO"/> : will exclude any file in any subdirectory starting from lib whose name contains FOO.

There area set of definitions that are excluded by default file-sets, just as in Ant. IzPack defaults to the Ant list of default excludes. There is currently no equivalent to the <defaultexcludes> task. Default excludes are:

Code Block
**/*\~{}
**/\#*\#
**/.\#*
**/%*%
**/.\_*
**/CVS
**/CVS/**
**/.cvsignore
**/SCCS
**/SCCS/**
**/vssver.scc
**/.svn
**/.svn/**
**/.DS\_Store

A <additionaldata> tag can also be specified for customizing. <parsable> - parse file(s) after installation h3. Files specified by <parsable> are parsed after installation and may have variables substituted.

  • targetfile : the file to parse, could be something like $INSTALL_PATH/bin/launch-script.sh A slash will be changed to the system dependant path separator (e.g. to a backslash on Windows) only if no backslash masks the slash. No longer mandatory as a fileset of files can be used.
  • type : specifies the type (same as for the resources) - the default is plain
  • encoding : specifies the file encoding
  • os: specifies the operating system, works like for <file>
  • condition: an id of a condition which has to be fullfilled to parse this file

One or more fileset tags can be used inside parsable to specify multiple files at once. <executable> - mark file executable or execute it h3. The <executable> tag is a very useful thing if you need to execute something during the installation process. It can also be used to set the executable flag on Unix-like systems. Here are the attributes :

  • targetfile : the file to run, could be something like $INSTALL_PATH/bin/launch-script.sh Slashes are handled special (see attribute targetfile of tag <parsable>).
  • class : If the executable is a jar file, this is the class to run for a JavaTM program
  • type : bin or jar (the default is bin)
  • stage : specifies when to launch : postinstall is just after the installation is done, never will never launch it (useful to set the +x flag on Unix). uninstall will launch the executable when the application is uninstalled. The executable is executed before any files are deleted. never is the default value.
  • failure : specifies what to do when an error occurs : abort will abort the installation process, ask (default) will ask the user what to do and warn will just tell the user that something is wrong
  • os: specifies the operating system, works like for <file>
  • keep : specifies whether the file will be kept after execution. The default is to delete the file after is has been executed. This can be changed by specifying keep="true".
  • condition: an id of a condition which has to be fullfilled to execute this file

A <args> tag can also be specified in order to pass arguments to the executable:

  • <arg>: passes the argument specified in the value attribute. Slashes are handled special (see attribute targetfile of tag <parsable>. <os> - make a file OS-dependent h3. The <os> tag can be used inside the <file>, <fileset>, <singlefile>, <parsable>, <executable> tags to restrict it's effect to a specific operating system family, architecture or version using the following attributes:
  • family: unix, windows, mac to specify the operating system family
  • name: the operating system name
  • version: the operating system version
  • arch: the operating system architecture (for instance the Linux kernel can run on i386, sparc, and so on)

Here's an example installation file fragment:

Code Block
<packs>

(...)

    <pack name="Core" required="yes">

    (...)

        <executable targetfile="$INSTALL_PATH/bin/compile" stage="never">
            <os family="unix"/>
        </executable>

    (...)

    </pack>

(...)

</packs>

The Native Element <native> h3. Use this if you want to use a feature that requires a native library. The native libraries are placed under bin/native/... There are 2 kinds of native libraries : the iZPACK libraries and the third-party ones. The IzPack libraries are located at bin/native/izpack, you can place your own libraries at bin/native/3rdparty. It is possible to place a native library also into the uninstaller.

It is usable from CustomActions. If one or more are referenced for it, the needed support classes are automatically placed into the uninstaller. To place it only on operating systems for which they are build, it is possible to define an OS restriction. This restriction will only be performed for the uninstaller. The markup takes the following attributes :

  • type : izpack or 3rdparty
  • name : the library filename
  • stage: stage where to use the library (install|uninstall|both)
  • src : source directory where to find the library to build the installer

Note for developers: com.izforge.izpack.util.Librarian.loadLibrary() must be used to load custom native libraries, as it performs some housekeeping. <os> - make a library OS-dependent h3. The <os> tag can be used to restrict the inclusion into the uninstaller to a specific operating system family, architecture or version. The inclusion into the installer will be always done.

Here's a sample :

Code Block
<native type="izpack" name="ShellLink.dll">
    <os family="windows"/>
</native>

The Jar Merging Element <jar> h3. If you adapt iZPACK for your own needs, you might need to merge the content of another jar file into the jar installer. For instance, this could be a library that you need to merge. The <jar> markup allows you to merge the raw content of another jar file into the installer and the uninstaller. It is necessary that the paths in the jars are unique because only the contained files of the jar are added to the installer jar, not the jar file self. The attributes are:

  • src : the path at compile time
  • stage: stage where to use the contents of the additional jar file (install|uninstall|both)

A sample :

Code Block
<jar src="../nicelibrary.jar"/>

XInclude-style constructs

The xi:include element is used to include xml or text documents in your configuration files.

The xi:include element can be used anywhere in pretty much any of the xml files used by IzPack. It is supported by the javax DocumentBuilder. It follows the XInclude recommandation produced by the W3C (http://www.w3.org/TR/xinclude/) and should be able to be used as decribed in that document.

To use the xi:include, you have to specify the namespace xmlns:xi="http://www.w3.org/2001/XInclude" in your xml.

If a logical error appear in an included file, the line number shown will indicate the xinclude element in the main xml file.

The xi:include element has the following attributes:

  • href
    The location of the file to include. If this is a relative path (e.g. href='../bob.xml') then the file is resolved relative to the document that includes the xinclude element. The href element can be a remote url (e.g. href='http://example.com/file.txt') but this is not recommended.
  • parse
    Indicates that the included file should be treated as xml, forcing the included file to be parsed (which results in all xinclude elements in the included file to also be included), or as text which includes the specified file as a text node. It can have a value of 'xml' or 'text' and defaults to 'xml' if ommitted.
  • xpointer
    In case in parse="xml", you can use xpointer to get a part of the included xml. The details of the xpointer framework can be found http://www.w3.org/TR/2003/REC-xptr-framework-20030325/.
  • encoding
    This is used when the parse attribute is 'text' to specify the character encoding of the included text document. It has no effect if parse is 'xml'.
  • accept
    Used if the href attribute specifies a url accessible via HTTP. The value of this attribute will be added as the accpet header on the HTTP request. The fallback element h3. The xi:fallback element is used to provide a fallback if the xi:include element fails. It can be empty or can contain a valid xml. If it is empty then a failure to include the specified document is supressed. If it contains a xml then a failure to include the specified document causes the xml specified in the fallback is parsed (evaluating nested xinclude elements) and inserted into the document in its place.

For example the following use of xi:include

Code Block
<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<aaa xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="does-not-exist.xml">
      <xi:fallback>
          <bbb/>
      </xi:fallback>
  </xi:include>
</aaa>

will result in

Code Block
<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<aaa>
  <bbb/>
</aaa>

if the file 'does-not-exist.xml' does indeed not exist. The xfragment element h1.

The xfragment element allows document fragments (xml documents without a single top level element) to be included. Simply use the xfragment as the top level element in the included document. It will be removed when the document is included.

e.g. If I want to use xi:include to include a file containing the following fragments:

Code Block
<ffff>
    <gggg>hello</gggg>
</ffff>
<hhhh>
    <iiii>there</iiii>
</hhhh>

I could use the xfragment element to enable it

Code Block
<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<xfragment>
    <ffff>
        <gggg>hello</gggg>
    </ffff>
    <hhhh>
        <iiii>there</iiii>
    </hhhh>
</xfragment>

For replacing Maven properties in attributes to xi:include in the standard notation of IzPack you need to prepare your POM as follows:

Example: Packaging type pom is used in the POM:

Code Block
languagehtml/xml
<build>
 
  <plugins>

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-resources-plugin</artifactId>
      <executions>
        <execution>
          <id>filter-izpack-descriptors</id>
          <phase>process-resources</phase>
          <goals>
            <goal>copy-resources</goal>
          </goals>
          <configuration>
            <useDefaultDelimiters>false</useDefaultDelimiters>
            <resources>          
              <resource>
                <directory>${basedir}/src/main/izpack</directory>
                <filtering>true</filtering>
              </resource>
            </resources>              
            <delimiters>
              <delimiter>@{*}</delimiter>
            </delimiters>
            <outputDirectory>${project.build.outputDirectory}/izpack-resources</outputDirectory>
          </configuration> 
        </execution>
      </executions>
    </plugin>
 
    ...
 
  </plugins>
 
...


</build>

and compile the installer from ${project.build.outputDirectory}/izpack-resources instead of src/main/izpack/.