Date: Thu, 28 Mar 2024 14:28:34 +0000 (UTC) Message-ID: <473327135.27.1711636114571@679a8d557b11> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_26_268662387.1711636114571" ------=_Part_26_268662387.1711636114571 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Dynamic variables behave like static variables, except th= at they are evaluated on each panel change and have additional features.
Dynamic variables, like other variables can be used within ${ and } for = substitution.
Dynamic variables can get their values from the following sources:
They can be filtered using regular expressions. A particular dynamic var= iable can be evaluated based on a certain condition.
Attributes common to all types of dynamic variables are:
As dynamic variables almost completely integrate with static = IzPack variables, which means they are mapped to a normal IzPack variab= le, they can be used as direct variables in user input fields. Take care to= have stable evaluation conditions after the user entered a value or use ch= eckonce=3D"true" for this purpose to not override the user value after leav= ing the panel.
The easiest way to assign a value to a dynamic variable is a plain value= .
Using a plain dynamic variable assignment is recognized by using the att= ribute value in the variable definition.
Specific attributes:
Example:
<dyna= micvariables> <variable name=3D"previous.version" value=3D"4.3.3"/> </dynamicvariable>
The above example is functionally equivalent to
<vari= ables> <variable name=3D"previous.version" value=3D"4.3.3"/> </variable>
since there are no replacements used which might be refreshed on a panel= change.
In another addition to normal variables, the value of a variable can be = also defined using a nested value element embeddi= ng plain text
Example:
To comment out something in a xml file if a certain pack with the ID "my= coolfeature" is not activated, you might alternate between one and the same= variable name, which gets assigned different values in different condition= s.
<dyna= micvariables> <variable name=3D"XML_Comment_Start" condition=3D"\!izpack.selected.= mycoolfeature"> <value><\!\[CDATA[<!--]\]></value> </variable> <variable name=3D"XML_Comment_End" condition=3D"\!izpack.selected.my= coolfeature"> <value><\!\[CDATA[-->]\]></value> </variable> <variable name=3D"XML_Comment_Start" value=3D"" condition=3D"izpack.= selected.mycoolfeature" /> <variable name=3D"XML_Comment_End" value=3D"" condition=3D"izpack.se= lected.mycoolfeature" /> </dynamicvariables>
The condition "izpack.selected.mycoolfeature" is generated automatically= when a pack with the ID "mycoolfeature" was specified. You could now use $= {XML_Comment_Start} and ${XML_Comment_End} in a file which should be parsed= .
For example, there might be an input file test.xml installed to ${INSTAL= L_PATH}:
<?xml= version=3D"1.0"?> <test> =09<a></a> =09${XmlCommentStart}<b></b>${XmlCommentEnd} </test>
parsed like this in install.xml:
<pars= able targetfile=3D"$INSTALL_PATH/test.xml" encoding=3D"UTF-8"/>
If the pack mycoolfeature would be enabled during the installation, the = file would look like this at the end:
<?xml= version=3D"1.0"?> <test> =09<a></a> =09<b></b> </test>
otherwise the <b></b> element would be commented out:
<?xml= version=3D"1.0"?> <test> =09<a></a> =09<!--<b></b>--> </test>
In the <parsable>
tag don't use the type=3D"xml=
"
for this example, because it would replace the characters '<=
;' and '>' in your comment XML elements by '<=
em>' and '>' in the resulting output.
Using a dynamic variable assignment from an environment variable i= s recognized by using the attribute environment in the variable de= finition.
Specific attributes:
<dyna= micvariables> <variable name=3D"search.path" environment=3D"PATH"/> </dynamicvariables>
The above example is functionally equivalent to
<dyna= micvariables> <variable name=3D"search.path" value=3D"${ENV[PATH]}"/> </dynamicvariable>
since there are no replacements used which might be refreshed on a panel= change and the environment variable PATH won't change during the runtime o= f an installation process.
There is one import difference:
Using a dynamic variable assignment from an system property is rec= ognized by using the value ${SYSTEM[property]} in the variable def= inition. For example the following definition will give you the java.io.tmp= dir:
<dyna= micvariables> <variable name=3D"tmpdir" value=3D"${SYSTEM[java.io.tmpdir]}"/> </dynamicvariable>
Dynamic variables can be also assigned from a value in configuration fil= es with key-value pairs, as property files.
Using a dynamic variable assignment from a certain option or prope= rty of an option or property file is recognized by using the attribute = file in the variable definition along with the attribute type= set to "options" (default if omitted).
Specific attributes:
options
" | "ini=
" | "xml
" (optional, defaults to "options
"=
)options
" to read options or propertie=
s.true
" | "fals=
e
" (optional: defaults to "true
")false
" especially if you want to read values with backsla=
shes where backslashes are not assumed to introduce escape sequences, like =
Windows paths.The attribute type=3D"options"
is to be used to make this f=
ile parsed as an option file. Separators between the key and value might be=
for instance '=3D', ':' including their escaped variants '\=3D', '\:', whe=
re leading and trailing whitespaces are trimmed off.
Example:
<dyna= micvariables> <variable name=3D"option.1" checkonce=3D"true" file=3D"${INSTALL_PATH}/../old_installation/test.properties" = type=3D"options" key=3D"first.setting"/> <variable name=3D"option.2" checkonce=3D"true" file=3D"${INSTALL_PATH}/../old_installation/test.conf" key=3D"work.dir"/> </dynamicvariables>
It's also possible to assign Windows INI file values to IzPack dynamic v= ariables. INI files are 3-dimensional configuration files with key-value pa= irs which are divided into several sections, following a certain syntax.
Using a dynamic variable assignment from a certain entry of an INI file = is recognized by using the attribute file in the variable definiti= on along with the attribute type set to "ini".
Specific attributes:
options
" | "ini=
" | "xml
" (optional, defaults to "options
"=
)ini
" to read INI keys.true
" | "false
" (optional: defaults to "true
")false
" especially if you want to read values with backsla=
shes where backslashes are not assumed to introduce escape sequences, like =
Windows paths.Example:
<dyna= micvariables> <variable name=3D"ini.1" checkonce=3D"true" file=3D"C:/Program Files/freesshd/FreeSSHDService.ini" type= =3D"ini" section=3D"SSH server" key=3D"SSHCMD"/> </dynamicvariables>
Another facility of dynamic variable assignments is reading values from = XML files using XPath queries. For the syntax of XPath see XML Path Language (XPath) for mor= e information.
Using a dynamic variable assignment from a certain XML entry in a XML fi= le is recognized by using the attribute file in the variable defin= ition along with the attribute type set to "xml".
Specific attributes:
options
" | "xml
" (optional, defaults to "options")
The file type, must be "xml
" to read a XML file.
Example:
<dyna= micvariables> <variable name=3D"XMLReadTest.1" checkonce=3D"true" ignorefailure=3D= "false" file=3D"${INSTALL_PATH}/../old_installation/test.xml" type=3D= "xml" key=3D"/installations/installation[path=3D'/usr/local']/title= [@lang=3D'en']/text()"/> <variable name=3D"XMLReadTest.2" checkonce=3D"true" ignorefailure=3D= "false" file=3D"${INSTALL_PATH}/../old_installation/test.xml" type=3D= "xml" key=3D"//title[@lang=3D'en']/text()"/> </dynamicvariables>
All of the above variants of reading a dynamic variable value from a con= figuration file can be also applied if that configuration files is packaged= as an entry into a ZIP or JAR file.
Using a dynamic variable assignment from a certain entry of a configurat= ion file packed into an archive is recognized by using the attributes j= arfile or zipfile in the variable definition.
Specific attributes:
options
" | "ini=
" | "xml
" (optional, defaults to "options
"=
)true
" | "false
" (optional: defaults to "true
")false
" especially if you want to read values with backsla=
shes where backslashes are not assumed to introduce escape sequences, like =
Windows paths.Example:
<dyna= micvariables> <variable name=3D"previous.version" jarfile=3D"${INSTALL_PATH}/${INS= TALL_SUBPATH}/libs/config.jar" entry=3D"release.properties" type=3D"options" key=3D"release.version" checkonce=3D"false" ignorefailure=3D"true"> </variable> <variable name=3D"other.stuff" zipfile=3D"${INSTALL_PATH}/${INSTALL_= SUBPATH}/libs/misc.zip" entry=3D"app.ini" type=3D"ini" section=3D"Global Settings" key=3D"AUTOSTART" checkonce=3D"true" ignorefailure=3D"true"> </variable> </dynamicvariables>
Dynamic variable values can be also gathered from Windows registry data.=
Using a dynamic variable assignment from a registry entry is recognized = by using the attribute regkey in the variable definition.
Specific attributes:
Example:
<dyna= micvariables> <variable name=3D"RegistryReadTest" checkonce=3D"true" regkey=3D"HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control= \Session Manager\Environment" regvalue=3D"Path"/> </dynamicvariables>
Last but not least, a dynamic variable value can be assigned from the ou= tput of an external command execution.
Using a dynamic variable assignment from command output is recognized by= using the attribute executable in the variable definition.
Specific attributes:
Example 1:
<dyna= micvariables> <variable name=3D"hostname" checkonce=3D"true" executable=3D"hostname" type=3D"process"/> <variable name=3D"result.value" checkonce=3D"true" executable=3D"${INSTALL_PATH}/bin/init.sh" type=3D"shell"/> </dynamicvariables>
Example 2:
<dyna= micvariables> <variable name=3D"previous.java.version" checkonce=3D"true" dir=3D"${INSTALL_PATH}" executable=3D"jre/bin/java" stderr=3D"true" type=3D"process" ignorefailure=3D"true" condition=3D"haveInstallPath+isUpgrade"> <arg>-version</arg> <filters> <regex regexp=3D"java version[^\d]+([\d\._]+)" select=3D"\1"/>= ; </filters> </variable> </dynamicvariables>
After straight evaluation, each dynamic variable value can be filtered u= sing predefined filters. Each filter might have a number of attributes to c= onfigure its behavior.
Multiple nested filters can be used. The filters will be applied in the = order in which they are defined.
Filters are evaluated on each panel change, regardless whether <dynam= icvariable checkonce=3D"true"/>, because several variables that might ch= anged are also resolved in a filter.
Filters are embedded in the nested filters element like this:
<= ;dynamicvariables> <variable ... <!-- other nested arguments might go here --> <filters> <filter1 .../> <filter2 .../> ... <!-- more filters might go here --> </filters> </variable> </dynamicvariable>
After straight evaluation, each dynamic variable's value can be filtered= using a Java regular expression. This is done by the nested re= gex element.
Attributes:
Example:
<dyna= micvariables> =09<!-- Read the property value of release.version in the resource release.pr= operties from the root of the config.jar file. =09 Filter just the version string from the result, if there is one, other= wise return 'none'. --> <variable name=3D"previous.version" jarfile=3D"${INSTALL_PATH}/${INS= TALL_SUBPATH}/libs/config.jar" entry=3D"release.properties" type=3D"options" key=3D"release.version" checkonce=3D"false" ignorefailure=3D"true" condition=3D"upgra= decheck"> <filters> <regex regexp=3D"([0-9]+(\.[0-9]+){2})" select=3D"\1" defaultval= ue=3D"none"/> </filters> </variable> =09<!-- Read the value of the Windows system environment variable %PATH% dire= ctly from the Windows registry (can done smarter by ${SYSTEM[PATH]}). Filter just the first single path (if there are more separated by the= ';' character). If there was a valid value, otherwise return '(unmatched)'= . --> <variable name=3D"RegExTest.Select.Windows" checkonce=3D"true" regkey=3D"HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control= \Session Manager\Environment" regvalue=3D"Path"> <filters> <regex regexp=3D"([^;]*)(.*)" select=3D"\1" defaultvalue=3D"(unmatched)" casesensitive=3D"false"/> </filters> </variable> =09<!-- Read the value of the Windows system environment variable %PATH% dire= ctly from the Windows registry (can done smarter by ${SYSTEM[PATH]}). Filter just the first single path (if there are more separated by the= ';' character). =09 Prepend and append three plus signs to the resulting value, if there w= as a valid value, otherwise return '(unmatched)'. --> <variable name=3D"RegExTest.ReplaceFirst.Windows" checkonce=3D"true" regkey=3D"HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control= \Session Manager\Environment" regvalue=3D"Path"> <filters> <regex regexp=3D"([^;]*)" replace=3D"+++ \1 +++" defaultvalue=3D"(unmatched)" casesensitive=3D"false" global=3D"false"/> </filters> </variable> </dynamicvariables>
After straight evaluation, each dynamic variable value can be filtered t= o be canonicalized like a filename. This is done by the nested location element. Operating system-specific path co= nventions are considered when assembling the result.
This means especially the file separator will be converted to that of th= e target operating system. On Windows, an absolute path is assumed to start= with a drive letter followed by a colon, on Unix or MacOSX by a slash.
Furthermore all path parts containing /./ are replaced by the f= ile separator and /dir/../ by the parent directory of dir= .
Attributes:
Example:= u>
Assuming all defined conditions are met, the following definition conver=
ts all ${previous.wrapper.java.home.canonical}/bin/java
&n=
bsp;not being an absolute path to a canonical path of the form
${INSTALL_PATH}/${previous.wrapper.java.home.canonical}/bin/java
on Unix or
${INSTALL_PATH}\${previous.wrapper.java.home.canonical}\bin\java
on Windows.
<= ;dynamicvariables> <variable name=3D"previous.wrapper.java.command.canonical" value=3D"$= {previous.wrapper.java.home.canonical}/bin/java" condition=3D"haveInstallPath+isCompatibleUpgrade+haveWrapperJa= vaCmd+isSetCanonicalJavaHome"> <filters> <location basedir=3D"${INSTALL_PATH}"/> </filters> </variable> </dynamicvariables>
Sometimes you need a variable value with all lowercase or all uppercase.= This filter has been introduced in version 5.0.0-rc5.
Attributes:
Example:= u>
<dyn= amicvariables> <variable name=3D"var1" value=3D"Some Text" > <filters> <case style=3D"lower"/> </filters> </variable> <variable name=3D"var2" value=3D"${var1}" > <filters> <case style=3D"upper"/> </filters> </variable> </dynamicvariables>
will set var1
to "some text" and var2
to =
"SOME TEXT".