IzPack Plugin

Overview

Integrates the generation of an IzPack installation jar into the maven build process. For more information regarding the usage of IzPack please refer to the IzPack documentation. We use this plugin in conjunction with IzPack to assemble the alakai installation jar. Hopefully it will be useful within other projects as well, i.e. non-alakai related projects.

Note that the izpack distribution used by this plugin, as configured within the example, below uses some features, e.g. packing pack files using pack200 and checksum verification of the downloaded pack files, which are not present within the IzPack distribution downloaded from the IzPack web site. These features were implemented by Bluestem Software and we intend to contribute them back to the IzPack project. Stay tuned.

Examples

Enable The Plugin

The plugin is enabled via a build execution tag associated with the build's 'verify' phase. An example configuration is included below. Note, for repeatable builds, you should 'peg' the plugin to a specific version as shown in the example below.

...
<build>
  <plugins>
    <plugin>
      <groupId>org.bluestemsoftware.open.maven.plugin</groupId>
      <artifactId>izpack-plugin</artifactId>
      <version>1.0.0.0</version>
      <executions>
        <execution>
          <id>izpack</id>
          <phase>verify</phase>
          <goals>
            <goal>izpack</goal>
          </goals>
          <configuration>
            <installationType>web</installationType>
            <installationFile>${basedir}/src/main/installer/izpack.xml</installationFile>
            <packFileExtensionType>gz</packFileExtensionType>
            <customActions>
              <customAction>
                <name>MyRegistryInstallerListener</name>
                <versionlessKey>org.bluestemsoftware.open.eoa.alakai.system.standalone:installer-utils</versionlessKey>
                <classifier>jar-with-dependencies</classifier>
              </customAction>
              <customAction>
                <name>MyRegistryUninstallerListener</name>
                <versionlessKey>org.bluestemsoftware.open.eoa.alakai.system.standalone:installer-utils</versionlessKey>
                <classifier>jar-with-dependencies</classifier>
              </customAction>
              <customAction>
                <name>UninstallerConfigurator</name>
                <versionlessKey>org.bluestemsoftware.open.eoa.alakai.system.standalone:installer-utils</versionlessKey>
                <classifier>jar-with-dependencies</classifier>
              </customAction>
            </customActions>
            <installationJars>
              <installationJar>
                <name>coi-tools.jar</name>
                <versionlessKey>org.bluestemsoftware.open.maven.plugin:izpack-coi-tools</versionlessKey>
              </installationJar>
            </installationJars>
            <resources>
              <resource>
                <name>My.uninstaller</name>
                <versionlessKey>org.bluestemsoftware.open.eoa.alakai.system.standalone:alakai-standalone-uninstaller</versionlessKey>
                <classifier>jar-with-dependencies</classifier>
                <type>jar</type>
              </resource>
            </resources>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
<dependencies>
  <dependency>
    <groupId>org.bluestemsoftware.open.eoa.alakai.system.standalone</groupId>
    <artifactId>installer-utils</artifactId>
    <scope>runtime</scope>
    <classifier>jar-with-dependencies</classifier>
    <version>0.8.0.0</version>
  </dependency>
  <dependency>
    <groupId>org.bluestemsoftware.open.eoa.alakai.system.standalone</groupId>
    <artifactId>alakai-standalone-uninstaller</artifactId>
    <scope>runtime</scope>
    <classifier>jar-with-dependencies</classifier>
    <version>0.8.0.0</version>
  </dependency>
  <dependency>
    <groupId>org.bluestemsoftware.open.maven.plugin</groupId>
    <artifactId>izpack-coi-tools</artifactId>
    <version>1.0.0.0</version>
    <scope>runtime</scope>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>ant</groupId>
    <artifactId>ant</artifactId>
    <version>1.6.2</version>
  </dependency>
</dependencies>
...

IzPack Installation File

The file below is the izpack installation file used to generate the alakai izpack installation jar. It is used in conjunction with the plugin configuration defined above. Note that POM variables within the IzPack installation file are interpolated by the IzPack plugin (with the exception of environment vars, i.e. vars prefixed with 'env' - hopefully these will make it into a future release.

<installation version="1.0">

  <info>
    <appname>alakai</appname>
    <appversion>${project.version}</appversion>
    <webdir>${webdir}</webdir>
    <uninstaller write="no" />
    <writeinstallationinformation>no</writeinstallationinformation>
  </info>

  <!-- 
    here's where we register our custom 'web' packer and unpacker. the 
    packer packs the file using pack200 and gzip according to the options 
    set below. the corresponding unpacker downloads the packs from a 
    remote location, creates a message digest from the downloaded pack and
    compares with a md5/sha1 digest value downloaded from a secure
    server using the location defined within the 'digest' tag nested
    within the 'pack' element, and compares the hash. it then uses gzip
    and unpack200 to unpack and install the packs.
  -->

  <packaging>
    <packager class="com.izforge.izpack.compiler.WebPackager">
      <options>
        <pack200>
          <property name="pack.keep.file.order" value="false" />
          <property name="pack.segment.limit" value="-1" />
          <property name="pack.effort" value="9" />
        </pack200>
      </options>
    </packager>
    <unpacker class="com.izforge.izpack.installer.WebUnpacker" />
  </packaging>

  <guiprefs width="500" height="400" resizable="no">
    <laf name="kunststoff">
      <os family="unix" />
    </laf>
    <modifier key="useHeadingPanel" value="yes" />
    <modifier key="useHeadingForSummary" value="yes" />
    <modifier key="headingLineCount" value="2" />
    <modifier key="headingFontSize" value="1.5" />
    <modifier key="headingBackgroundColor" value="0x00ffffff" />
    <modifier key="headingPanelCounter" value="text" />
    <modifier key="headingPanelCounterPos" value="inHeading" />
  </guiprefs>

  <locale>
    <langpack iso3="eng" />
  </locale>

  <!-- 
    note that the 'MyUninstaller' resource is copied by our maven izpack plugin
    to the 'res' directory. it is 'installed' by the 'UninstallerConfigurator'
    action
  -->

  <resources>
    <res id="HTMLLicencePanel.licence" src="${basedir}/src/main/assembly/license/LICENSE.html" />
    <res id="Heading.image" src="${basedir}/src/main/installer/images/alakai-logo.png" />
    <res id="Alakai.icon" src="${basedir}/src/main/installer/images/alakai.ico" />
    <res id="My.uninstaller" src="${project.build.directory}/izpack/res/My.uninstaller" />
  </resources>

  <!-- 
    defines the succession of ordered panels. note that we do not require the
    checked hello panel. the coi-tools artifact is copied to our uninstall jar
    by the uninstaller's maven assembly plugin
  -->

  <panels>
    <panel classname="HelloPanel" />
    <panel classname="HTMLLicencePanel" />
    <panel classname="TargetPanel" />
    <panel classname="PacksPanel" />
    <panel classname="InstallPanel" />
    <panel classname="SimpleFinishPanel" />
  </panels>

  <packs>

    <!-- 
      this pack defines core files required to run the system. note that if user is updating
      alakai to a new version, we update if the installed file is newer than the existing
      file EXCEPT if we're copying the 'system' directory. we never overwrite files within
      this directory. note also that this pack is not required, i.e. user may decide to
      re-run the install just to copy the sources and/or examples.
    -->
    <pack name="binaries" required="no" preselected="yes">
      <description>the alakai system</description>
      <digest>http://alakai.org/downloads/${project.build.finalName}-install.pack-binaries.jar.pack.gz.sha1</digest>
      <file src="${project.build.finalName}/alakai/bin" targetdir="$INSTALL_PATH" />
      <file src="${project.build.finalName}/alakai/lib" targetdir="$INSTALL_PATH" />
      <file src="${project.build.finalName}/alakai/license" targetdir="$INSTALL_PATH" />
      <fileset dir="${project.build.finalName}/alakai/system" targetdir="$INSTALL_PATH/system" override="false">
        <include name="readme.txt" />
        <include name="default/**" />
      </fileset>
      <fileset dir="${project.build.finalName}/alakai/repository" targetdir="$INSTALL_PATH/repository">
        <exclude name="**/*-sources.jar" />
        <exclude name="**/org/bluestemsoftware/open/eoa/example/**" />
      </fileset>
    </pack>

    <!-- 
      this pack defines all of the *-sources jars contained with the system repository.
      this is an optional pack.
    -->
    <pack name="sources" required="no" preselected="yes">
      <description>the source code</description>
      <digest>http://alakai.org/downloads/${project.build.finalName}-install.pack-sources.jar.pack.gz.md5</digest>
      <fileset dir="${project.build.finalName}/alakai/repository" targetdir="$INSTALL_PATH/repository">
        <include name="**/*-sources.jar" />
        <exclude name="**/org/bluestemsoftware/open/eoa/example/**" />
      </fileset>
    </pack>

    <!-- 
      this pack defines all of the examples each of which is contained within a separate
      alakai system instance, i.e. system sub-directory. this is an optional pack.
    -->
    <pack name="examples" required="no" preselected="yes">
      <description>the demo applications</description>
      <digest>http://alakai.org/downloads/${project.build.finalName}-install.pack-examples.jar.pack.gz.md5</digest>
      <fileset dir="${project.build.finalName}/alakai/system" targetdir="$INSTALL_PATH/system">
        <include name="samples/spring/ordermgr/**" />
        <include name="samples/spring/whsemgr/**" />
      </fileset>
      <fileset dir="${project.build.finalName}/alakai/repository" targetdir="$INSTALL_PATH/repository">
        <include name="**/org/bluestemsoftware/open/eoa/example/**" />
      </fileset>
    </pack>

  </packs>

  <!-- 
    we use our registry installer listeners instead of the the listeners provided  by
    izpack. our listeners use static constants to populate and clear the registry. the
    uninstaller configurator 'installs' our custom uninstall jar to the alakai 'bin'
    directory
  -->
  <listeners>
    <listener installer="MyRegistryInstallerListener" uninstaller="MyRegistryUninstallerListener">
      <os family="windows" />
    </listener>
    <listener installer="UninstallerConfigurator" />
  </listeners>

  <!-- 
    this dll is required for registry support on windows, i.e. it is used by the
    registry actions defined above to create and remove the registry entries
  -->
  <native type="3rdparty" name="COIOSHelper.dll" stage="both">
    <os family="windows" />
  </native>

  <!-- 
    include the following jar within the generated install jar. it is required
    by our registry actions
  -->
  <jar src="${project.build.directory}/izpack/lib/izevent.jar" />
  
  <!-- 
    izpack compiler won't include the coi classes, which are required by
    our registry actions, unless the checked hello panel is used, which
    we don't need. so ... we list coi-tools.jar artifact as a dependency
    within our project's pom.xml and within the installationJars section
    of the izpack plugin config which such that it is copied to the
    following location before izpack compile is kicked off
   -->  
  <jar src="${project.build.directory}/izpack/lib/coi-tools.jar" />

</installation>