lib/bsf.jar src/dtd/event/bsfaction.dtd src/lib/com/izforge/izpack/event/BSFAction.java src/lib/com/izforge/izpack/event/BSFInstallerListener.java src/lib/com/izforge/izpack/event/BSFUninstallerListener.java @@ -40,6 +40,15 @@ <SOURCES /> </library> </orderEntry> + <orderEntry type="module-library"> + <library> + <CLASSES> + <root url="jar://$MODULE_DIR$/lib/bsf.jar!/" /> + </CLASSES> + <JAVADOC /> + <SOURCES /> + </library> + </orderEntry> </component> </module> IzPack.iml @@ -845,11 +845,14 @@ <macrodef name="build-uninstaller-listener"> <attribute name="name"/> <attribute name="srcdir" default="${src.dir}"/> + <attribute name="classpath-ext" description="An extension of the classpath required to build the listener" + default=""/> <element name="uninstaller-fileset" implicit="yes" description="include and exclude elements indicating listener sources"/> <sequential> - <build-listener name="@{name}" srcdir="@{srcdir}" izeventExcludes="**/*Installer*"> + <build-listener name="@{name}" srcdir="@{srcdir}" izeventExcludes="**/*Installer*" + classpath-ext="@{classpath-ext}"> <uninstaller-fileset/> </build-listener> </sequential> @@ -906,6 +909,16 @@ <include name="com/coi/tools/os/izpack/COIOSHelper.java"/> </build-uninstaller-listener> + <build-installer-listener name="BSFInstallerListener" classpath-ext="$${basedir}/lib/bsf.jar"> + <include name="com/izforge/izpack/event/BSFInstallerListener.java" /> + <include name="com/izforge/izpack/event/BSFAction.java" /> + </build-installer-listener> + + <build-uninstaller-listener name="BSFUninstallerListener" classpath-ext="$${basedir}/lib/bsf.jar"> + <include name="com/izforge/izpack/event/BSFUninstallerListener.java" /> + <include name="com/izforge/izpack/event/BSFAction.java" /> + </build-uninstaller-listener> + <!-- CUSTOM ACTION test START <build-compiler-listener name="ChmodCompilerListener"> <include name="com/myCompany/tools/install/listener/ChmodCompilerListener.java"/> src/build.xml @@ -863,5 +863,455 @@ It can be changed with the subelement ``summarylogfilepath`` of the element </summarylogfilepath> </info> + +BSF (Bean Scripting Framework) Actions (InstallerListener and UninstallerListener) +------------------------------------------------------------------------------------ + +In this section the BSF 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 BSF related custom +actions ``BSFInstallerListener`` and ``BSFUninstallerListener``. +As recapitulation, to add any custom action a reference in install.xml will +be needed, as example: + + +:: + + <listeners> + <listener installer="BSFInstallerListener" + uninstaller="BSFUninstallerListener" /> + </listeners> + + +For all referenced listeners a jar file with the same name must exist in +``[IzPackRoot]/bin/customActions``. If compilation (packaging) fails with a +"not found" 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 ``pack`` 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 `` BSFActionsSpec.xml`` +e.g. + + +:: + + <resources> + ... + <res id="BSFActionsSpec.xml" + src="myInstallSpecs/MyBSFActionsSpec.xml" /> + ... + </resources> + + +The precise spelling of the id is important. The base path of ``src`` is the +installation project path. If you want to use bsf, you have to specify it +here. IzPack is designed for running without dependencies on external +software or libraries. Therefore it is necessary to include everything +needed, in this case ant self. The field ``<jar>`` in installation.xml is +predestinated for such cases, e.g. + + +:: + + <jar src="jar/bsf/bsf.jar" stage="both" /> + + +In addition, you must also include the jar file for the language which you are +going to use in your BSF scripts, including any additional language dependencies, e.g. + +:: + + <jar src="jar/groovy/groovy-all.jar" stage="both" /> + + +Finally, if you are NOT going to embed your script content in the "BSFActionsSpec.xml", but +instead will be including it in an external resource, you must also define that resource in your +installer.xml file (see below for an explanation) + +:: + + <res id="actions.groovy" src="myInstallSpecs/actions.groovy" /> + + + +The Basic XML Struture +----------------------- + +A BSF action will be defined in the resource with the id +"BSFActionsSpec.xml". Sometimes it will help to lock into +``[IzPackRoot]/src/dtd/event/bsfaction.dtd`` or validate a written xml file +with the dtd. + +On this xml file a substitution will be performed using all defined +``IzPack`` 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 ``com.izforge.izpack.util.SpecHelper.readSpec``. If +you want to substitute some custom item, simply add a variable via +idata.setVariable in a custom panel before ``InstallPanel``. The given +variable name (id) should be written into the xml file in the common variable +notation. + +The top level XML section is called ``<bsfactions>``. Only one is possible. +The ``<bsfactions>`` are segregated in one or more ``<pack>`` elements. The +single attribute ``<name>`` of the ``<pack>`` corresponds to the same +structure in install.xml (for more information see also installation.dtd). +Only the "things" included in the ``<pack>`` are performed, if a pack with +the same name was chosen to be installed. The "things" to be done to self are +defined by the element ``<script>``. + +The ``<script>`` takes the following attributes: + +- ``language``: 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 "javascript" and "groovy". + +- ``src``: 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. + +In addition to the possible attributes ``<script>`` can contain a ``CDATA`` section +which contains the script content, rather than using the "src" 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. + +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. + + +:: + + <script language="groovy" src="actions.groovy" /> + +OR + +:: + + <script language="groovy"><![CDATA[ + // Variables defined + // idata - installer data, of type AutomatedInstallerData + // npacks - # of packs selected + beforePacks = { + print "before packs"; + } + + // 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"; + } + ]]></script> + + <script language="beanshell"><![CDATA[ + void beforePacks() { + print "INSTALL_PATH=${INSTALL_PATH}"; + } + ]]></script> + + +BSF (Bean Scripting Framework) Actions (InstallerListener and UninstallerListener) +------------------------------------------------------------------------------------ + +In this section the BSF 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 BSF related custom +actions ``BSFInstallerListener`` and ``BSFUninstallerListener``. +As recapitulation, to add any custom action a reference in install.xml will +be needed, as example: + + +:: + + <listeners> + <listener installer="BSFInstallerListener" + uninstaller="BSFUninstallerListener" /> + </listeners> + + +For all referenced listeners a jar file with the same name must exist in +``[IzPackRoot]/bin/customActions``. If compilation (packaging) fails with a +"not found" 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 ``pack`` 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 `` BSFActionsSpec.xml`` +e.g. + + +:: + + <resources> + ... + <res id="BSFActionsSpec.xml" + src="myInstallSpecs/MyBSFActionsSpec.xml" /> + ... + </resources> + + +The precise spelling of the id is important. The base path of ``src`` is the +installation project path. If you want to use bsf, you have to specify it +here. IzPack is designed for running without dependencies on external +software or libraries. Therefore it is necessary to include everything +needed, in this case ant self. The field ``<jar>`` in installation.xml is +predestinated for such cases, e.g. + + +:: + + <jar src="jar/bsf/bsf.jar" stage="both" /> + + +In addition, you must also include the jar file for the language which you are +going to use in your BSF scripts, including any additional language dependencies, e.g. + +:: + + <jar src="jar/groovy/groovy-all.jar" stage="both" /> + + +Finally, if you are NOT going to embed your script content in the "BSFActionsSpec.xml", but +instead will be including it in an external resource, you must also define that resource in your +installer.xml file (see below for an explanation) + +:: + + <res id="actions.groovy" src="myInstallSpecs/actions.groovy" /> + + + +The Basic XML Struture +----------------------- + +A BSF action will be defined in the resource with the id +"BSFActionsSpec.xml". Sometimes it will help to lock into +``[IzPackRoot]/src/dtd/event/bsfaction.dtd`` or validate a written xml file +with the dtd. + +On this xml file a substitution will be performed using all defined +``IzPack`` 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 ``com.izforge.izpack.util.SpecHelper.readSpec``. If +you want to substitute some custom item, simply add a variable via +idata.setVariable in a custom panel before ``InstallPanel``. The given +variable name (id) should be written into the xml file in the common variable +notation. + +The top level XML section is called ``<bsfactions>``. Only one is possible. +The ``<bsfactions>`` are segregated in one or more ``<pack>`` elements. The +single attribute ``<name>`` of the ``<pack>`` corresponds to the same +structure in install.xml (for more information see also installation.dtd). +Only the "things" included in the ``<pack>`` are performed, if a pack with +the same name was chosen to be installed. The "things" to be done to self are +defined by the element ``<script>``. + +The ``<script>`` takes the following attributes: + +- ``language``: 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 "javascript" and "groovy". + +- ``src``: 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. + +In addition to the possible attributes ``<script>`` can contain a ``CDATA`` section +which contains the script content, rather than using the "src" 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. + +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. + + +:: + + <script language="groovy" src="actions.groovy" /> + +OR + +:: + + <script language="groovy"><![CDATA[ + // Variables defined + // idata - installer data, of type AutomatedInstallerData + // npacks - # of packs selected + beforePacks = { + print "before packs"; + } + + // 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"; + } + ]]></script> + + <script language="beanshell"><![CDATA[ + void beforePacks() { + print "INSTALL_PATH=${INSTALL_PATH}"; + } + ]]></script> + + +More detailed examples can be downloaded from http://jira.codehaus.org/secure/attachment/39246/sample.tar.gz +and http://jira.codehaus.org/secure/attachment/39379/sample2.tar.gz + .. include:: include-bottom.inc src/doc-reST/custom-actions.txt 4cefadc07d0119445e3e4a401c755666ca0f46b9 jponge jponge@7d736ef5-cfd4-0310-9c9a-b52d5c14b761 http://github.com/jponge/izpack/commit/d2c3abca8df07f36dd722bc9586a2c032f25f61b d2c3abca8df07f36dd722bc9586a2c032f25f61b 2009-01-24T06:02:42-08:00 2009-01-24T06:02:42-08:00 IZPACK-240: support of scripting languages for handling event using the Bean Scripting Framework (Apache BSF). Original patch contributed by Matthew Inger. git-svn-id: https://svn.codehaus.org/izpack/izpack-src/trunk@2505 7d736ef5-cfd4-0310-9c9a-b52d5c14b761 077a6911709132961453aa33661f875bb04ea0d2 jponge jponge@7d736ef5-cfd4-0310-9c9a-b52d5c14b761