[izpack-changes] r1890 - izpack-src/trunk/src/doc-reST
noreply at berlios.de
noreply at berlios.de
Wed Nov 7 09:00:43 CET 2007
Author: jponge
Date: 2007-11-07 08:59:37 +0100 (Wed, 07 Nov 2007)
New Revision: 1890
Added:
izpack-src/trunk/src/doc-reST/advanced-features.txt
izpack-src/trunk/src/doc-reST/apache-license.txt
izpack-src/trunk/src/doc-reST/build.py
izpack-src/trunk/src/doc-reST/cc-license.txt
izpack-src/trunk/src/doc-reST/cookbooks.txt
izpack-src/trunk/src/doc-reST/creating-panels.txt
izpack-src/trunk/src/doc-reST/custom-actions.txt
izpack-src/trunk/src/doc-reST/desktop-shortcuts.txt
izpack-src/trunk/src/doc-reST/getting-started.txt
izpack-src/trunk/src/doc-reST/index.txt
izpack-src/trunk/src/doc-reST/installation-files.txt
izpack-src/trunk/src/doc-reST/introduction.txt
izpack-src/trunk/src/doc-reST/pdf-version.txt
izpack-src/trunk/src/doc-reST/user-input.txt
Removed:
izpack-src/trunk/src/doc-reST/convert.py
izpack-src/trunk/src/doc-reST/node1.html.txt
izpack-src/trunk/src/doc-reST/node10.html.txt
izpack-src/trunk/src/doc-reST/node11.html.txt
izpack-src/trunk/src/doc-reST/node12.html.txt
izpack-src/trunk/src/doc-reST/node13.html.txt
izpack-src/trunk/src/doc-reST/node2.html.txt
izpack-src/trunk/src/doc-reST/node3.html.txt
izpack-src/trunk/src/doc-reST/node4.html.txt
izpack-src/trunk/src/doc-reST/node5.html.txt
izpack-src/trunk/src/doc-reST/node6.html.txt
izpack-src/trunk/src/doc-reST/node7.html.txt
izpack-src/trunk/src/doc-reST/node8.html.txt
izpack-src/trunk/src/doc-reST/node9.html.txt
Log:
- Basic build (not yet integrated with Ant)
- Basic front pages
Copied: izpack-src/trunk/src/doc-reST/advanced-features.txt (from rev 1888, izpack-src/trunk/src/doc-reST/node5.html.txt)
Copied: izpack-src/trunk/src/doc-reST/apache-license.txt (from rev 1887, izpack-src/trunk/src/doc-reST/node10.html.txt)
Copied: izpack-src/trunk/src/doc-reST/build.py (from rev 1888, izpack-src/trunk/src/doc-reST/convert.py)
===================================================================
--- izpack-src/trunk/src/doc-reST/convert.py 2007-11-07 02:38:30 UTC (rev 1888)
+++ izpack-src/trunk/src/doc-reST/build.py 2007-11-07 07:59:37 UTC (rev 1890)
@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+
+import os
+import shutil
+
+REST_FILES = [
+ 'index',
+ 'introduction',
+ 'getting-started',
+ 'installation-files',
+ 'advanced-features',
+ 'desktop-shortcuts',
+ 'creating-panels',
+ 'user-input',
+ 'custom-actions',
+ 'apache-license',
+ 'cc-license',
+ 'cookbooks'
+]
+
+DIRS = ['html', 'pdf']
+
+for d in DIRS:
+ if not os.path.exists(d):
+ os.makedirs(d)
+
+for rest_file in REST_FILES:
+ os.system('rst2html.py %s.txt html/%s.html' % (rest_file, rest_file))
+
+os.system('rst2newlatex.py pdf-version.txt pdf/manual.tex')
+
+for f in os.listdir('.'):
+ if f.endswith('.png') or f.endswith('.jpg'):
+ shutil.copyfile(f, 'html/' + f)
+ shutil.copyfile(f, 'pdf/' + f)
\ No newline at end of file
Copied: izpack-src/trunk/src/doc-reST/cc-license.txt (from rev 1887, izpack-src/trunk/src/doc-reST/node11.html.txt)
Deleted: izpack-src/trunk/src/doc-reST/convert.py
===================================================================
--- izpack-src/trunk/src/doc-reST/convert.py 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/convert.py 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,6 +0,0 @@
-#!/usr/bin/env python
-
-import os
-
-for i in xrange(1, 14):
- os.system('rst2html.py node%i.html.txt node%i.html' % (i, i))
\ No newline at end of file
Copied: izpack-src/trunk/src/doc-reST/cookbooks.txt (from rev 1888, izpack-src/trunk/src/doc-reST/node13.html.txt)
Copied: izpack-src/trunk/src/doc-reST/creating-panels.txt (from rev 1888, izpack-src/trunk/src/doc-reST/node7.html.txt)
Copied: izpack-src/trunk/src/doc-reST/custom-actions.txt (from rev 1888, izpack-src/trunk/src/doc-reST/node9.html.txt)
Copied: izpack-src/trunk/src/doc-reST/desktop-shortcuts.txt (from rev 1888, izpack-src/trunk/src/doc-reST/node6.html.txt)
Copied: izpack-src/trunk/src/doc-reST/getting-started.txt (from rev 1888, izpack-src/trunk/src/doc-reST/node3.html.txt)
Added: izpack-src/trunk/src/doc-reST/index.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/index.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/index.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -0,0 +1,32 @@
+////////////////////////
+IzPack documentation
+////////////////////////
+
+.. WARNING:: This is a work in progress and should not be used as a reference...
+
+Chapters
+========
+
+- introduction_
+- getting-started_
+- installation-files_
+- advanced-features_
+- desktop-shortcuts_
+- creating-panels_
+- user-input_
+- custom-actions_
+- apache-license_
+- cc-license_
+- cookbooks_
+
+.. _introduction: introduction.html
+.. _getting-started: getting-started.html
+.. _installation-files: installation-files.html
+.. _advanced-features: advanced-features.html
+.. _desktop-shortcuts: desktop-shortcuts.html
+.. _creating-panels: creating-panels.html
+.. _user-input: user-input.html
+.. _custom-actions: custom-actions.html
+.. _apache-license: apache-license.html
+.. _cc-license: cc-license.html
+.. _cookbooks: cookbooks.html
Copied: izpack-src/trunk/src/doc-reST/installation-files.txt (from rev 1888, izpack-src/trunk/src/doc-reST/node4.html.txt)
Copied: izpack-src/trunk/src/doc-reST/introduction.txt (from rev 1888, izpack-src/trunk/src/doc-reST/node2.html.txt)
Deleted: izpack-src/trunk/src/doc-reST/node1.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node1.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node1.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1 +0,0 @@
-(to be removed)
\ No newline at end of file
Deleted: izpack-src/trunk/src/doc-reST/node10.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node10.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node10.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,4 +0,0 @@
-Apache License, Version 2.0
---------------------------------
-
-(to be replaced with an up-to-date text)
\ No newline at end of file
Deleted: izpack-src/trunk/src/doc-reST/node11.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node11.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node11.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,4 +0,0 @@
-The Commons Creative Attribution-NonCommercial-ShareAlike License
-===================================================================
-
-(to be replaced with an up-to-date text)
\ No newline at end of file
Deleted: izpack-src/trunk/src/doc-reST/node12.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node12.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node12.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1 +0,0 @@
-(to be removed)
\ No newline at end of file
Deleted: izpack-src/trunk/src/doc-reST/node13.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node13.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node13.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,788 +0,0 @@
-CookBooks
-=========
-
-
-1. How To create an ODBC connection with IzPack (by Fabrice Mirabile)
----------------------------------------------------------------------
-
-
-a. Problem
-''''''''''
-
-ODBC can be used as a layer between app servers and databases. It is quite
-convienent to setup an ODBC connection at installation time when the
-installer can actually retrieve all info needed for such setup. How can we
-achieve that? And for which OS ?
-
-
-b. Solution
-'''''''''''
-
-After looking at many solutions, I found one that is very convenient in the
-sense that it applies to both Windows and UNIX environment.
-In fact, the Windows ODBC Manager applet offers two type of setup:
-
-
-- The system source
-- The file source
-
-Basically, the system source writes in the registry and unfortunately does
-something else that I couldn't figure out.
-However, the file source is very similar to ODBC.ini under UNIX.
-In ODBC.ini, you can define all connections into this file. For windows it's
-a bit different as you will have as many files as connections. But even
-though, there's a trick!
-
-
-A fileDSN (the name given to this type of connection) for a connection to an
-Oracle database will look like this : ::
-
- [ODBC]
- DRIVER=Oracle in OraHome92
- UID=%{UID}
- PWD=%{PWD}
- DBQ=%{DBName}
- SERVER=%{DBName}
-
-Therefore you can realize straightforwardly that by changing the UID and PWD
-you will make your connection point to any schemas you want.
-
-In my company's software, we use ODBC to make the connection between the
-application and the database. Therefore, we use a batch to launch the server
-with a bunch of parameters. One of them is the ODBC DSN. This one, using
-fileDSN, should be defined as follows: ::
-
- SET DSN=filedsn=$INSTALL_PATH\whateveryoulike.dsn
-
-A very nice trick is to put in this batch the UID and the PWD so that it's
-not needed in the file directly and therefore you make the installer create
-different batch loaders for different Schemas !
-That's very usefull when you have on the same DB many schema and you want the
-same application server to access both of them without reinstalling the whole
-thing !
-
-In the following discussion, I'll show you an example on how to prepare the
-installer for creating a file at the root of the installation path which will
-permit to connect to an Oracle DataBase.
-
-
-
-c. Discussion
-'''''''''''''
-
-**Install.xml:**
-
-<file src="dsn.dsn" targetdir="$INSTALL_PATH"/>
-<parsable type="shell" targetfile="$INSTALL_PATH/whateveryoulike.dsn"/>
-
-**UserInputSpec.xml:**
-
-::
-
- <userInput>
- <panel order="0">
- <field type="staticText" align="left" txt="Server Only:
- Enter the settings for the ODBC Connection (DSN) environment variable:"
- id="staticText3.text"/>
- <field type="divider" align="center"/>
- <field type="text" variable="UID">
- <description align="left" txt=""
- id="description2.text"/>
- <spec txt="-> Enter UID:" id="text.label"
- size="15" set=""/>
- </field>
- <field type="divider" align="center"/>
- <field type="password" variable="PWD">
- <description align="left" txt=""
- id="description3.text"/>
- <spec>
- <pwd txt="-> Type the password for the
- connection:" id="pwd.label" size="10" set=""/>
- <pwd txt="-> Retype the password for the
- connection:" id="pwd.label2" size="10" set=""/>
- </spec>
- <validator
- class="com.izforge.sample.PWDValidator" txt="Both versions of the
- password must match" id="error.label"/>
- <processor
- class="com.izforge.sample.PWDEncryptor"/>
- </field>
- <field type="space" align="center"/>
- <field type="divider" align="center"/>
- <field type="space" align="center"/>
- <field type="text" variable="DBName">
- <description align="left" txt=""
- id="description4.text"/>
- <spec txt="-> Enter the name of the Database:"
- id="text.label" size="15" set=""/>
- </field>
- <field type="text" variable="DBPortNo">
- <description align="left" txt="-> Enter the port
- number for the database connection" id="description5.text"/>
- <spec txt="(usually 1521 for oracle and 1433 for
- MS SQL Server)" id="text.label" size="15" set=""/>
- </field>
- </panel>
- </userInput>
-
-
-**BatchLoader.bat:**
-
-::
-
- SET DSN=filedsn=$INSTALL_PATH\whateveryoulike.dsn;UID=$UID;PWD=$PWD
- start $INSTALL_PATH\yourpath\yourapp
-
-
-**whateveryoulike.dsn:**
-
-::
-
- [ODBC]
- DRIVER=Oracle in OraHome92
- DBQ=%{DBName}
- SERVER=%{DBName}
-
-
-Now during the installation the user will be prompt for the parameters (UID,
-PWD...) and the file will be parsed.
-
-Pretty simple !
-
-What about SQL Server or other db you would say ? Well, there's many ways to
-do it, a simple would be to have a skeleton for kind of db and then during
-the userinput ask for the database type (DB2, SQLSERVER,ORACLE...) and switch
-to the corresponding file before parsing.
-
-Let's imagine you choose SQL Server in the userinputpanel, then instead of
-copying whateveryoulike.dsn, you can copy whateveryoulikeforMS.dsn which
-looks like this:
-
-::
-
- [ODBC]
- DRIVER=SQL Server
- WSID=%{DBName}
- APP=Microsoft Open Database Connectivity
- SERVER=%{DBName}
-
-
-In our installer, we create four packs, one for each DataBase. These packs
-copy the corresponding file and parse them. Again, pretty simple !
-
-Another remark, is that in this way if you choose more than one pack you
-could setup more than one connection at once on different DB as long as UID
-and PWD are the same. If not you'll need a little trick...
-
-I hope this helps and if anyone has a question, don't hesitate to contact me
-via `http://developer.berlios.de/sendmessage.php?touser=12462` or post into
-the user/devel list.
-
-**Done by Fabrice Mirabile on 20th of april 2005**
-
-
-2. Work around for pack and process dependence And Execution of Java Classes that runs SQL/PLSQL
-------------------------------------------------------------------------------------------------
-
-
-a. Problem
-''''''''''
-
-I've encountered in many cases the need to have a relation between job being
-executed with the processpanel and a pack. Since IzPack doesn't provide yet
-such feature I worked out something that does the job.
-
-I'll explain it using an example on how to execute a java class that runs SQL
-statements.
-
-
-b. Solution
-'''''''''''
-
-Here is what you will need:
-
-- UserInputSpec.xml
-- Install.xml
-- ProcessPanel.Spec.xml
-
-Which are at the root of the installation folder.
-
-Then you could have a folder with the SQL Stuffs, let's call it update.
-So in update you'll have:
-
-- JDBCGeneral.class, I use JDBC to make a DataBase connection
-- launchsql.bat, which runs the class with all kind of arguments
-- ojdbc14.jar, oracle JDBC drivers
-- mssqlserver.jar, msutil.jar and msbase.jar, SQL server drivers (You
- could have also drivers for other DB such as DB2 or Sybase)
-- Two folders for the SQL scripts:
-
- - sqlsms, for SQL Server scripts
- - sqlsoracle, for oracle scripts
-
-Inside those folders you can have any number of SQL scripts. The scripts can
-be written in this way for example:
-delete from task_category;
-insert into task_category values('LoadSource','Data Source
-Loading','source_loader_task.bat');
-
-Once you have this tree of files prepared you need to setup each file. The
-idea is that the install should copy on the client side the SQL scripts
-depending on the pack(s) chosen, plus the class and the batch file and then
-run the batch using the processpanel job. Therefore only the scripts for a
-specific pack would be run and there is the dependence we're looking for!
-
-
-c .Discussion
-'''''''''''''
-
-**Install.xml:**
-
-::
-
- <?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
- <installation version="1.0">
- ....
- <resources>
- <res id="ProcessPanel.Spec.xml"
- src="ProcessPanel.Spec.xml"/>
- <res id="userInputSpec.xml" src="UserInputSpec.xml"/>
- ....
- </resources>
- <panels>
- .....
- <panel classname="UserInputPanel"/>
- <panel classname="ProcessPanel"/>
- .....
- </panels>
- <packs>
- ......
- <pack name="16-12-04" preselected="no" required="no"
- os="windows">
- <description>jar and SQL</description>
- <singlefile src="updates\sqlsms\sql161204.txt"
- target="$INSTALL_PATH\updates\sqlsms\sql161204.txt"/>
- <singlefile src="updates\sqlsoracle\sql161204.txt"
- target="$INSTALL_PATH\updates\sqlsoracle\sql161204.txt"/>
- <file src="uninstaller.bat"
- targetdir="$INSTALL_PATH\Uninstaller"/>
- <file src="uninstall.ico"
- targetdir="$INSTALL_PATH\Uninstaller"/>
- <singlefile src="updates\msbase.jar"
- target="$INSTALL_PATH\updates\msbase.jar"/>
- <singlefile src="updates\mssqlserver.jar"
- target="$INSTALL_PATH\updates\mssqlserver.jar"/>
- <singlefile src="updates\msutil.jar"
- target="$INSTALL_PATH\updates\msutil.jar"/>
- <singlefile src="updates\ojdbc14.jar"
- target="$INSTALL_PATH\updates\ojdbc14.jar"/>
- <singlefile src="updates\jdbcgeneral.class"
- target="$INSTALL_PATH\updates\JDBCGeneral.class"/>
- <singlefile src="updates\class\axiom_lang.jar"
- target="$INSTALL_PATH\class2\axiom_lang.jar"/>
- <singlefile src="updates\class\axiom_lib.jar"
- target="$INSTALL_PATH\class2\axiom_lib.jar"/>
- <singlefile src="updates\launchsql.bat"
- target="$INSTALL_PATH\updates\launchsql.bat"/>
- <parsable
- targetfile="$INSTALL_PATH\updates\launchsql.bat"/>
- <parsable
- targetfile="$INSTALL_PATH\Uninstaller\uninstaller.bat"/>
- </pack>
-
- <pack name="17-12-04" preselected="no" required="no"
- os="windows">
- <description>jar and SQL</description>
- <singlefile src="updates\sqlsms\sql171204.txt"
- target="$INSTALL_PATH\updates\sqlsms\sql171204.txt"/>
- <singlefile src="updates\sqlsoracle\sql171204.txt"
- target="$INSTALL_PATH\updates\sqlsoracle\sql171204.txt"/>
- <file src="uninstaller.bat"
- targetdir="$INSTALL_PATH\Uninstaller"/>
- <file src="uninstall.ico"
- targetdir="$INSTALL_PATH\Uninstaller"/>
- <singlefile src="updates\msbase.jar"
- target="$INSTALL_PATH\updates\msbase.jar"/>
- <singlefile src="updates\mssqlserver.jar"
- target="$INSTALL_PATH\updates\mssqlserver.jar"/>
- <singlefile src="updates\msutil.jar"
- target="$INSTALL_PATH\updates\msutil.jar"/>
- <singlefile src="updates\ojdbc14.jar"
- target="$INSTALL_PATH\updates\ojdbc14.jar"/>
- <singlefile src="updates\jdbcgeneral.class"
- target="$INSTALL_PATH\updates\JDBCGeneral.class"/>
- <singlefile src="updates\launchsql.bat"
- target="$INSTALL_PATH\updates\launchsql.bat"/>
- <singlefile src="updates\class\axiom_lang.jar"
- target="$INSTALL_PATH\class2\axiom_lang.jar"/>
- <singlefile src="updates\class\axiom_lib.jar"
- target="$INSTALL_PATH\class2\axiom_lib.jar"/>
- <parsable
- targetfile="$INSTALL_PATH\updates\launchsql.bat"/>
- <parsable
- targetfile="$INSTALL_PATH\Uninstaller\uninstaller.bat"/>
- </pack>
- .....
- </packs>
- </installation>
-
-
-**UserInputSpec.xml:**
-
-::
-
- <userInput>
- <panel order="0">
- <field type="title" align="Left" txt="Database Connection
- Parameters" bold="true" size="1" id="DBParam"/>
- <field type="staticText" align="left" txt="The following
- information are needed for making the connection with the database."
- id="staticText1.text"/>
- <field type="staticText" align="left" txt="Careful These
- fields are case sensitive !" id="staticText2.text"/>
- <field type="divider" align="center"/>
- <field type="divider" align="center"/>
- <field type="combo" variable="SQLServerType">
- <spec txt="Select the type of DataBase you're using "
- id="SqlServerType.spec">
- <choice processor="" txt="Not Needed !"
- id="SQLServerType.notneeded" value="None" set="true"/>
- <choice processor="" txt="Oracle"
- id="SQLServerType.Oracle" value="Oracle"/>
- <choice processor="" txt="Microsoft SQL Server"
- id="SQLServerType.MS" value="SQLServer"/>
- </spec>
- </field>
- <field type="text" variable="ServerNameTextInput">
- <description align="left" txt="" id="description1.text"/>
- <spec txt="Enter server name " id="text.label" size="15"
- set="localhost"/>
- </field>
- <field type="divider" align="center"/>
- <field type="text" variable="PortNbTextInput">
- <description align="left" txt="-> Enter the port number
- for the database connection" id="description5.text"/>
- <spec txt="(usually 1521 for oracle and 1433 for MS SQL
- Server)" id="text.label" size="15" set="1433"/>
- </field>
- <field type="divider" align="center"/>
- <field type="text" variable="DBNameTextInput">
- <description align="left" txt="" id="description3.text"/>
- <spec txt="Enter Database name " id="text.label"
- size="15" set="axiom"/>
- </field>
- <field type="divider" align="center"/>
- <field type="text" variable="UserNameTextInput">
- <description align="left" txt="" id="description4.text"/>
- <spec txt="Enter Schema/User name for the Database "
- id="text.label" size="15" set="axiom"/>
- </field>
- <field type="text" variable="UserPwdTextInput">
- <description align="left" txt="" id="description5.text"/>
- <spec txt="Enter Schema/User name password for the
- Database " id="text.label" size="15" set="okta007"/>
- </field>
- </panel>
- </userInput>
-
-
-**ProcessPanel.Spec.xml:**
-
-::
-
- <processing>
- <job name="Executing the Needed Queries">
- <os family="windows" />
- <executefile name="$INSTALL_PATH\updates\launchsql.bat"/>
- </job>
- </processing>
-
-
-**Launchsql.bat:**
-
-::
-
- echo "Execution of SQL Queries \n"
- java -classpath $INSTALL_PATH\updates\msutil.jar;$INSTALL_PATH\update
- s\msbase.jar;$INSTALL_PATH\updates\mssqlserver.jar;$INSTALL_PATH\updates\
- ojdbc14.jar;$INSTALL_PATH\updates\
- JDBCGeneral
- $INSTALL_PATH\updates\
- $ServerNameTextInput
- $PortNbTextInput
- $DBNameTextInput
- $UserNameTextInput
- $UserPwdTextInput
- $SQLServerType
-
-
-**JDBCGeneral.java: (of course you need the compiled .class !!! but I'm
-showing the source code)**
-
-::
-
- /**
- * Parses a .sql file and runs them depending on DB settings
- * through jdbc.
- *
- * @author Fabrice Mirabile
- * @version 2.0
- */
-
-
- import java.*;
- import java.sql.*;
- import java.io.*;
- import java.util.*;
- import java.io.File;
-
-
- public class JDBCGeneral{
- private java.sql.Connection con = null;
- private final String selectMethod = "cursor";
-
- // Constructor
- public JDBCGeneral(){}
-
- public static void main(String[] argv) throws Exception
- {
- String folderpath = "";
-
- final String folderpathbase = argv[0];
- final String serverName= argv[1];
- final String portNumber = argv[2];
- final String databaseName= argv[3];
- final String userName = argv[4];
- final String password = argv[5];
- final String SQLServerType = argv[6];
-
- if (SQLServerType.equals("SQLServer")) {
- final String url = "jdbc:microsoft:sqlserver://";
- folderpath = folderpathbase.concat("sqlsms");
- String classforname =
- "com.microsoft.jdbc.sqlserver.SQLServerDriver";
- JDBCGeneral myDbTest = new JDBCGeneral();
- //myDbTest.displayDbPropertiesMS(classforname,url,ser
- verName,portNumber, databaseName, userName, password);
- String[] files =
- myDbTest.getfilenamesMS(classforname,url,folderpath, serverName,
- portNumber, databaseName, userName, password);
- }
- else if (SQLServerType.equals("Oracle")) {
- final String url = "jdbc:oracle:thin:@";
- folderpath = folderpathbase.concat("sqlsoracle");
- //test if there's no need for SQL Execution,
- //check if null value is returned from file selection
- on selecte path
- String classforname =
- "oracle.jdbc.driver.OracleDriver";
- JDBCGeneral myDbTest = new JDBCGeneral();
- //myDbTest.displayDbPropertiesOracle(classforname,url,s
- erverName,portNumber, databaseName, userName, password);
- String[] files =
- myDbTest.getfilenamesOracle(classforname,url,folderpath,
- serverName, portNumber, databaseName, userName, password);
- }
-
- }
-
- public void displayDbPropertiesOracle(String classforname,
- String url,String serverName, String portNumber, String
- databaseName, String userName, String password){
- java.sql.DatabaseMetaData dm = null;
- java.sql.ResultSet rs = null;
- try{
- con=
- this.getConnectionOracle(classforname,url,serverName,
- portNumber, databaseName, userName, password);
- if(con!=null){
- dm = con.getMetaData();
- System.out.println("Driver
- Information");
- System.out.println("\tDriver
- Name: "+ dm.getDriverName());
- System.out.println("\tDriver
- Version: "+ dm.getDriverVersion ());
- System.out.println("\nDatabase Information ");
- System.out.println("\tDatabase Name: "+
- dm.getDatabaseProductName());
- System.out.println("\tDatabase Version: "+
- dm.getDatabaseProductVersion());
- System.out.println("Avalilable Catalogs ");
- rs = dm.getCatalogs();
- while(rs.next()){
- System.out.println("\tcatalog: "+
- rs.getString(1));
- }
- rs.close();
- rs = null;
- closeConnection();
- }else System.out.println("Error: No
- active Connection");
- }catch(Exception e){
- e.printStackTrace();
- }
- dm=null;
- }
-
- public void displayDbPropertiesMS(String classforname,
- String url,String serverName, String portNumber, String
- databaseName, String userName, String password){
- java.sql.DatabaseMetaData dm = null;
- java.sql.ResultSet rs = null;
- try{
- con=
- this.getConnectionMS(classforname,url,serverName,
- portNumber, databaseName, userName, password);
- if(con!=null){
- dm = con.getMetaData();
- System.out.println("Driver
- Information");
- System.out.println("\tDriver
- Name: "+ dm.getDriverName());
- System.out.println("\tDriver
- Version: "+ dm.getDriverVersion ());
- System.out.println("\nDatabase Information ");
- System.out.println("\tDatabase Name: "+
- dm.getDatabaseProductName());
- System.out.println("\tDatabase Version: "+
- dm.getDatabaseProductVersion());
- System.out.println("Avalilable Catalogs ");
- rs = dm.getCatalogs();
- while(rs.next()){
- System.out.println("\tcatalog: "+
- rs.getString(1));
- }
- rs.close();
- rs = null;
- closeConnection();
- }else System.out.println("Error: No
- active Connection");
- }catch(Exception e){
- e.printStackTrace();
- }
- dm=null;
- }
-
- private java.sql.Connection getConnectionMS(String
- classforname, String url,String serverName, String portNumber,
- String databaseName, String userName, String password){
- try{
- Class.forName(classforname);
- con = java.sql.DriverManager.getConnect
- ion(getConnectionUrlMS(url,serverName, portNumber,
- databaseName),userName,password);
- if(con!=null)
- System.out.println("Connection Successful!");
- }catch(Exception e){
- e.printStackTrace();
- System.out.println("Error Trace in
- getConnection() : " + e.getMessage());
- }
- return con;
- }
-
- private String getConnectionUrlMS(String url,String
- serverName, String portNumber, String databaseName){
- return url+serverName+":"+portNumber+";databaseNa
- me="+databaseName+";selectMethod="+selectMethod+";";
- }
-
- private java.sql.Connection getConnectionOracle(String
- classforname, String url,String serverName, String portNumber,
- String databaseName, String userName, String password){
- try{
- Class.forName(classforname);
- con = java.sql.DriverManager.getConnect
- ion(getConnectionUrlOracle(url,serverName, portNumber,
- databaseName),userName,password);
- if(con!=null)
- System.out.println("Oracle Connection Successful!");
- }catch(Exception e){
- e.printStackTrace();
- System.out.println("Error Trace in
- getConnectionOracle() : " + e.getMessage());
- }
- return con;
- }
-
- private String getConnectionUrlOracle(String url,String
- serverName, String portNumber, String databaseName){
- return
- url+serverName+":"+portNumber+":"+databaseName;
- }
-
- private String[] getfilenamesOracle(String classforname,
- String url, String folderpath, String serverName, String portNumber,
- String databaseName, String userName, String password) throws
- FileNotFoundException,IOException{
- String newfolderpath = folderpath + "\\";
- File toto = new File(newfolderpath);
- String [] thelist = toto.list();
- for (int j=0; j<thelist.length; ++j)
- {
- //System.out.println("file n?" + j
- + " = " + thelist[j] + "\n");
- String[] StatementsSQL =
- SQLFileInput(newfolderpath + thelist[j]);
- RunSQLOracle(StatementsSQL,classforname,url,serverName,
- portNumber, databaseName, userName, password);
- }
- return thelist;
- }
-
- private String[] getfilenamesMS(String classforname, String
- url, String folderpath, String serverName, String portNumber, String
- databaseName, String userName, String password) throws
- FileNotFoundException,IOException{
- String newfolderpath = folderpath + "\\";
- File toto = new File(newfolderpath);
- String [] thelist = toto.list();
- for (int j=0; j<thelist.length; ++j)
- {
- //System.out.println("file n?" + j + " =
- " + thelist[j] + "\n");
- String[] StatementsSQL =
- SQLFileInput(newfolderpath + thelist[j]);
- RunSQLMS(StatementsSQL,classforname,url,serverName,
- portNumber, databaseName, userName, password);
- }
- return thelist;
- }
-
- /*
- public String[] addToArray(String[] array, String s)
- {
- String[] ans = new String[array.length+1];
- System.arraycopy(array, 0, ans, 0, array.length);
- ans[ans.length - 1] = s;
- return ans;
- }
- */
-
- public String[] SQLFileInput(String sqlinput) throws
- FileNotFoundException,IOException {
- BufferedReader br = new BufferedReader(new
- FileReader(sqlinput));
- List lines = new ArrayList();
- int i = 0;
- int h = 0;
- String thisLine;
- String[] SQLStatements = new String[1000];
-
- while ((thisLine = br.readLine()) != null)
- {
- //System.out.println(thisLine);
- SQLStatements[h] = thisLine;
- h++;
- }
-
- /*for(String line = br.readLine();line != null;line =
- br.readLine()) {
- // split by semi-colon
- InsertRows = line.split(";");
- i++;
- }
-
- for (int j=0; j<SQLStatements.length; ++j)
- {
- if (SQLStatements[j] != null)
- System.out.println("query n?" + j + "
- = " + SQLStatements[j]);
- }*/
-
- return SQLStatements;
- }
-
- public void RunSQLOracle(String[] StatementsSQL, String
- classforname, String url, String serverName, String portNumber,
- String databaseName, String userName, String password){
- try {
- con=
- this.getConnectionOracle(classforname,url,serverName,
- portNumber, databaseName, userName, password);
- Statement stAddUser = con.createStatement();
-
- for (int i=0; i<StatementsSQL.length; ++i)
- {
- if (StatementsSQL[i] != null)
- {
- System.out.print(StatementsSQL[i] + "...");
- int rowsAffected =
- stAddUser.executeUpdate(StatementsSQL[i]);
- if (rowsAffected == 1)
- System.out.println("OK");
- }
- }
- closeConnection();
- }
- catch(SQLException e) {
- e.printStackTrace();
- System.out.println("\nError Trace in
- RunSQLOracle(): " + e.getMessage());
- }
- }
-
- public void RunSQLMS(String[] StatementsSQL, String
- classforname, String url, String serverName, String portNumber,
- String databaseName, String userName, String password){
- try {
- con= this.getConnectionMS(classforname,
- url,serverName, portNumber, databaseName, userName,
- password);
- Statement stAddUser = con.createStatement();
-
- for (int i=0; i<StatementsSQL.length; ++i)
- {
- if (StatementsSQL[i] != null)
- {
- System.out.print(StatementsSQL[i] + "...");
- int rowsAffected =
- stAddUser.executeUpdate(StatementsSQL[i]);
- if (rowsAffected == 1)
- System.out.println("OK");
- }
- }
- closeConnection();
- }
- catch(SQLException e) {
- e.printStackTrace();
- System.out.println("\nError Trace in RunSQLMS():
- " + e.getMessage());
- }
- }
-
- private void closeConnection(){
- try{
- if(con!=null)
- con.close();
- con=null;
- }catch(Exception e){
- e.printStackTrace();
- }
- }
- }
-
-**To sum up**:
-
-The install.xml copy the files, the userinput ask for the DB connections, the
-process.xml launch the class which takes as arguments the following entries:
-
-- a folder that will contain the sql files (each file is a sequence of
- sql queries semi-colon separated). This folder contains subfolder for
- each type of DB
-- the server name of the machine hosting the DB
-- the port number of the connection (1433 for sql server and 1521 for
- oracle for example)
-- name of the DB
-- username
-- username password
-- type of DB (oracle, sqlserver...) in order to execute the sql inside
- the corresponding sub-folder
-
-Once again, i hope you'll find this useful and if anyone has a question,
-don't hesitate to contact me via
-`http://developer.berlios.de/sendmessage.php?touser=12462` or post into the
-user/devel list.
-
-**Done by Fabrice Mirabile on 20th of april 2005**
Deleted: izpack-src/trunk/src/doc-reST/node2.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node2.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node2.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,130 +0,0 @@
-Introduction
-============
-
-
-Welcome to IzPack !
--------------------
-
-IzPack is a tool that will help you to solve your software installation
-problems. It is a JavaTM based software installer builder that will run on
-any operating system coming with a *Java Virtual Machine (JVM)* that is
-compliant with the Sun JVM 1.4 or higher. Its design is very modular and you
-will be able to choose how **you** want your installer to look and you will
-also be able to customize it using a very simple *Application Programming
-Interface (API)*. Although IzPack is essentially a JavaTM only application
-(it can run on virtually any operating system), it can interact in a clean
-way with the underlying operating system. Native code can interact with it on
-a specific platform without disturbing the operation on incompatible
-operating systems. For instance, you can develop Unix-specific code that will
-be silent if run on Windows. To put it in a nutshell, whereas most of the
-other JavaTM installers force you to go their way, IzPack will let you go
-**your way**. Some respectable companies have been using it in order to
-produce customized installers for their *very* specific needs.
-
-
-*"So, if it's so good, how much is it ?"* : well, you can get it for free.
-**BUT** IzPack is not a *freeware*. It's not *free* as in *"free beer"* but
-*"free as in free speech"*. So it's neither *freeware* nor *public domain*.
-It is software covered by the Apache Software License 2.0. You have access to
-the IzPack source code and you can modify it to make it suit your needs, but
-if you publish such a modified version, you are forced to publish the
-modifications you've made.That's a fair exchange of expertise and work. To
-learn more about the Apache Software License 2.0, visit
-http://www.apache.org/licenses/LICENSE-2.0.html
-
-
-
-The Features
-------------
-
-IzPack uses XML files to describe installations. When you make an installer,
-you have a choice of panels. You can see panels as a kind of plugin that
-composes the installer. For instance, a panel can choose the installation
-path, the packs to install, prompt the user for a license agreement and so
-on. This approach is very modular. You can also create your own panels if you
-have specific needs. In some cases you even have a choice from multiple panel
-versions for the same task. You can also choose the order in which panels
-appear during the installation process. IzPack can be used in a number of
-different ways:
-
-- by writing the XML installation file "by hand" and compiling it with
- the command line compiler
-- by invoking the compiler from the great APACHE JAKARTA ANT tool (see
- http://jakarta.apache.org/) as IzPack can be used as a task for
- ANT
-
-Here is a brief (and certainly incomplete !) list of the main IzPack features
-:
-
-- XML based installation files
-- easy internationalization using XML files (10 translations are
- already available)
-- Ant integration, command-line compiler
-- easy customization with the panels and a rich API (even an XML parser
- is included !)
-- powerful variable substitution system that you can use to customize
- scripts and more generally any text-based file
-- different kinds of installers (standard, web-based, ...)
-- launching of external executables during the installation process and
- Unix executable flag support (useful for the scripts for instance)
-- layout of the installation files in packs (some can be optional)
-- native code integration facilities
-- jar files nesting support
-- ... *more things to discover and create !*.
-
-
-The Development
----------------
-
-I started writing IzPack in April 2001 and many people have helped me
-improving it since. i prefer not to mention them here as i would for sure
-forget some of them, so please check the file named ``Thanks.txt`` which i
-try to get as up-to-date as possible in order to mention everyone who helped
-me. As far as i'm concerned, i'm a french student and i rather see this as a
-fun activity in my free time where i can learn a lot of great things. The
-contributors to the project are both individuals and companies. Help can take
-any form :
-
-- translations
-- new features and various fixes
-- bug fixes
-- writing manuals
-- ... anything else you like :-)
-
-The official IzPack homepage is located at https://izpack.github.io/. The
-IzPack developer services (mailing-lists, CVS, patches manager, bugs tracker,
-...) are generously hosted by BerliOS. The IzPack BerliOS section is located
-at http://developer.berlios.de/projects/izpack/. Feel free to use
-these services. In particular, there are two mailing-lists:
-
-- ``izpack-devel``: used for the IzPack development
-- ``izpack-users``: general users lounge, great to get some help with
- IzPack.
-
-
-3rd party code used in IzPack
------------------------------
-
-IzPack uses several 3rd party libraries and i would like to mention them in
-respect for their respective authors work :
-
-- *NanoXML* by Marc DE SCHEEMAECKER : the XML parser used inside IzPack
- and released under a *zlib/png*-style license - see http://nanoxml.sourceforge.net/
-- *Kunststoff Look and Feel* by Incors Gmbh : a SwingTM Look and Feel
- that can be used for installers. It **really** looks good and is released
- under the GNU LESSER GENERAL PUBLIC LICENSE (LGPL) - see
- http://www.incors.org/
-- *Crystal-SVG Icons* : the icons used in IzPack come from the great
- work of Everaldo (http://www.everaldo.com/) that makes KDE 3.2
- look so sweet
-- *Some Apache Jakarta classes and libraries* : released under the
- *Apache License*
-- *Metouia Look and Feel* by Taoufik Romdhane : released under the
- *LGPL license* - see http://mlf.sf.net/
-- *Liquid Look and Feel* by Miroslav Lazarevic : released under the
- *LGPL license* - see liquidlnf.sf.net/
-- *JGoodies Looks* by Karsten Lentzsch : released under a *BSD-style
- license* - see http://looks.dev.java.net/
-
-So, now let's dive into understanding how IzPack works. You'll be surprised
-to see how powerful and simple it can be :-)
Deleted: izpack-src/trunk/src/doc-reST/node3.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node3.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node3.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,360 +0,0 @@
-Getting started
-================
-
-Overview
----------
-
-To begin with, you should know what IzPack is organized if you want to use it. let's go into the directory where you have installed IzPack on your machine. There are 3 text files and a set of directories. The most important for the moment are bin/ doc/ sample/. If you are reading this, you already know that doc contains this documentation :-)
-
-So let's go into bin/. The icons/ directory contains some directories for your system, in case you would like an icon to launch a component of IzPack . But the most important things you can see in bin are the compile scripts (in both unix* and windows formats). Compile is used to compile a ready-to-go xml installation file from a command-line context or from an external tool.
-
-Note : these scripts can be launched from anywhere on your system as the installer has customized these scripts so that they can inform IzPack of where it is located.
-
-Installation of IzPack
------------------------
-
-First go get the latest stable version of IzPack from: https://izpack.github.io/downloads
-
-If needed download the Latest Java Run Time from Sun's website http://java.sun.com/. You should get the JRE if you intend to ONLY run the installer and get the SDK if you're willing to compile as well.
-
-On Windows
-'''''''''''
-
-Don't forget to set up the environment variables:
-
-If using the SDK: ::
-
- set JAVA_HOME="C:\j2sdk1.4.2_04"
- set JRE_HOME=%JAVA_HOME%/jre
- set CLASSPATH=%JAVA_HOME%/bin;%CLASSPATH%
- set PATH=%JAVA_HOME%/bin;%JRE_HOME%/bin;%PATH%
-
-This is obvioulsy assuming that SDK has been installed to "C:\j2sdk1.4.2_04"
-
-If using the JRE: ::
-
- set JAVA_HOME="C:\Program Files\Java\j2re1.4.2_05"
- set CLASSPATH=%JAVA_HOME%/bin;%CLASSPATH%
- set PATH=%JAVA_HOME%/bin;%PATH%
-
-This is obviously assuming that SDK has been installed to "C:\Program Files\Java\j2re1.4.2_05"
-Once this is done, you can install IzPack using the following command: ::
-
- java -jar izpack.jar
-
-Where izpack.jar is the latest release you downloaded from IzPack website.
-
-On UNIX/Linux
-''''''''''''''
-
-If needed download the Latest Java Run Time from Sun's website http://java.sun.com/. You should get the JRE if you intend to ONLY run the installer, but you should get the SDK if you're willing to compile as well.
-
-If using the SDK: ::
-
- export JAVA_HOME=/usr/java/j2sdk1.4.2_06
- export JAVA_JAR=/usr/java/java_jar
- export JRE_HOME=/usr/java/j2sdk1.4.2_06/jre
- export CLASSPATH=/usr/java/j2sdk1.4.2_06/bin
- export PATH=/usr/java/j2sdk1.4.2_06/bin:/usr/java/j2sdk1.4.2_06/jre/bin:$PATH
-
-This is obviously assuming that java has been installed to /usr/java/j2sdk1.4.2_06
-
-If using the JRE: ::
-
- export JAVA_HOME=/usr/java/j2re1.4.2_05
- export CLASSPATH=$JAVA_HOME/bin:$CLASSPATH
- export PATH=$JAVA_HOME/bin:$PATH
-
-This is obviously assuming that SDK has been installed to "/usr/java/j2re1.4.2_05"
-You can put them into any script launched at startup if you don't want to have to do it everytime.
-For example, .bashrc of your user, so that whenever you'll start a bash console the variables will be set.
-
-To verify that the environment is correct, type SET in the command prompt and check if those variables are set before running any compilation.
-
-Then you install IzPack using the following command: ::
-
- java -jar izpack.jar
-
-By default it will be installed in /usr/local/IzPack.
-Therefore you can create two scripts, one for compiling your code and the second to execute the installer.
-
-Compile.sh: ::
-
- #!/bin/sh
- /usr/local/IzPack/bin/compile /yourpath/Install.xml -b /yourpath -o /yourpath/yourjaroutput.jar -k standard
-
-Install.sh: ::
-
- #!/bin/sh
- java -jar yourjaroutput.jar
-
-**BUGS and TROUBLESHOOTING**
-
-1. This is assuming that you're current Unix/Linux allows the use of the server X. In cas it doesn't here is a way to install IzPack using cygwin (thanks to Shrish Buradkar and Bartz Klaus for this trick):
-
- Install cygwin on a remote machine. Cygwin can be downloaded from http://www.cygwin.com/
- Firstly, start the XWindows server on your PC. This could be done by using the startxwin-multiwindow batch file or running /usr/X11R6/bin/startxwin.sh
- From the cygwin Xterm, type xhost +
- Then telnet to the remote UNIX/Linux machine and set the DISPLAY to your PC. So after you have logged into the remote machine, do export DISPLAY=pc-ip-adress:0.0 xterm & java -jar installer.jar
- This should do the job by displaying an xterm from the remote machine onto yor PC.
-
-2. Normally launching packages created by IzPack under Gnome, KDE or XFCE works fine. If when trying to launch a pack you receive this error message: ::
-
- Exception in thread "main" java.lang.InternalError: Can't connect to X11
- window server using ':0.0' as the value of the DISPLAY variable.
- at sun.awt.X11GraphicsEnvironment.initDisplay(Native Method)
- at
- sun.awt.X11GraphicsEnvironment.<clinit>(X11GraphicsEnvironment.java:134)
- at java.lang.Class.forName0(Native Method)
- at java.lang.Class.forName(Class.java:141)
- at
- java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(GraphicsEnvironment.java:62)
- at java.awt.Font.initializeFont(Font.java:308)
- at java.awt.Font.<init>(Font.java:344)
- at
- com.izforge.izpack.gui.IzPackMetalTheme.createFont(IzPackMetalTheme.java:62)
- at
- com.izforge.izpack.gui.IzPackMetalTheme.<init>(IzPackMetalTheme.java:52)
- at
- com.izforge.izpack.gui.IzPackKMetalTheme.<init>(IzPackKMetalTheme.java:59)
- at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native
- Method)
- at
- sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:39)
- at
- sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:27)
- at java.lang.reflect.Constructor.newInstance(Constructor.java:274)
- at java.lang.Class.newInstance0(Class.java:308)
- at java.lang.Class.newInstance(Class.java:261)
- at
- com.izforge.izpack.installer.GUIInstaller.loadLookAndFeel(GUIInstaller.java:297)
- at
- com.izforge.izpack.installer.GUIInstaller.<init>(GUIInstaller.java:100)
- at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native
- Method)
- at
- sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:39)
- at
- sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:27)
- at java.lang.reflect.Constructor.newInstance(Constructor.java:274)
- at java.lang.Class.newInstance0(Class.java:308)
- at java.lang.Class.newInstance(Class.java:261)
- at com.izforge.izpack.installer.Installer.main(Installer.java:47)
-
-Then, it's most probably the fact that in some distribution the console and environment variables are "erased" when switching between users. So, you can type 'su -' in order to obtain all commands. With 'su -' $DISPLAY variables is erased and all X11 connections is refused. So, a best and fast practice in this way is:
-
- 1. Log in your system by user
- 2. In shell type: '$ echo $DISPLAY'
- 3. the result seems to be ':0.0'. If the response isn't there you can type:
- 4. '$ export $DISPLAY=":0.0"'
- 5. Now type $su for a "normal" alias by root.
- 6. Run: $ java -jar "package.jar"
-
-First Compilation
-------------------
-
-Now you probably can't wait to build your first installer. So go on open a command-line shell and navigate to sample/. The following should work on both unix* and windows systems. for the latter, just change the path separator (slash '/') to a backslash. So type ($ is your shell prompt !) : ::
-
- $ ../bin/compile install.xml -b . -o install.jar -k standard
- (installer generation text output here)
- $ java -jar install.jar
-
-There you are! The first command has produced the installer and the second one did launch it.
-
-How to develop and debug IzPack using Eclipse
-----------------------------------------------
-
-(thanks to Bartz Klaus)
-
-Here are the steps needed to develop adn debug IzPack with Eclipse:
-
-1. IzPack Installation
-
- Install the latest stable release of IzPack with the sources !
- For more details see the section "IzPack Installation".
-
-2. Custom class sources and build.xml
-
- Put your custom class sources under
- %IZPACK_HOME%\src\lib
- may be
- %IZPACK_HOME%\src\lib\com\izforge\izpack\panels\MyPanel.java
- Add a create rule into %IZPACK_HOME%\src\build.xml
- under target "build.panels"
-
-3. Eclipse
-
- You can get Eclipse from http://www.eclipse.org/downloads/index.php
-
-4. Create IzPack project
-
- Select
- File > New > Project...
- Java > Java Project > next >
- give a project name like "IzPack"
- deselect "Use default" ( 2.x) or
- select "Create project at external location" (3.x)
- Browse to %IZPACK_HOME%\src\lib select it
- Next >
- In "Libraries" select "Add External JARs..."
- select ant.jar and jakarta-regexp-1.3.jar from %IZPACK_HOME%\lib
- Finish
-
-5. Debug compile (create installation)
-
- Select
- Run > Debug...
- Java Application
- New
- give a name e.g. "CompileMyInstall"
- select in "Main" the project "IzPack"
- select as "main class" "Compile" (from package com.izforge.izpack.compiler)
- As "Program arguments" put in (for %SOME_THING% use your local value)
- %SRC_ROOT%\%CONFIG_SUBPATH%\install.xml -b %SRC_ROOT% -o %INSTALLER_DEST%\install.jar
- As "VM arguments" put in
- "-DIZPACK_HOME=n:\home\bartzkau\work\xt150_forIzPack\izpack-src"
-
- No you can debug the compiling of your installation.
-
-5. Debug installation
-
- Compile your installation; now you have
- %INSTALLER_DEST%\install.jar
- Run > Debug...
- Java Application
- New
- give a name e.g. "InstallMyInstall"
- select in "Main" the project "IzPack"
- select as "main class" "Installer" (from package com.izforge.izpack.installer)
- as "VM arguments" use
- -DTRACE=true
- select the tab "Classpath"
- select "User classes" (2.x) or "User Entries" (3.x)
- select "Add External JARs..."
- select %INSTALLER_DEST%\install.jar (may be, that's the trick...)
- install.jar must be under the project entry
-
- **BUGS and TROUBLESHOOTING**
-
- If you get this error when running the application
- could not create shortcut instance ::
-
- java.lang.Exception: error loading library
- at com.izforge.izpack.util.Librarian.loadLibrary(Librarian.java:249)
- at com.izforge.izpack.util.os.ShellLink.initialize(ShellLink.java:461)
- at com.izforge.izpack.util.os.ShellLink.<init>(ShellLink.java:349)
- at com.izforge.izpack.util.os.Win_Shortcut.initialize(Win_Shortcut.java:79)
- at com.izforge.izpack.panels.ShortcutPanel.<init>(ShortcutPanel.java:473)
- at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
- at sun.reflect.NativeConstructorAccessorImpl.newInstance(Unknown Source)
- at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(Unknown Source)
- at java.lang.reflect.Constructor.newInstance(Unknown Source)
- at com.izforge.izpack.installer.InstallerFrame.loadPanels(InstallerFrame.java:203)
- at com.izforge.izpack.installer.InstallerFrame.<init>(InstallerFrame.java:160)
- at com.izforge.izpack.installer.GUIInstaller.loadGUI(GUIInstaller.java:391)
- at com.izforge.izpack.installer.GUIInstaller.<init>(GUIInstaller.java:128)
- at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
- at sun.reflect.NativeConstructorAccessorImpl.newInstance(Unknown Source)
- at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(Unknown Source)
- at java.lang.reflect.Constructor.newInstance(Unknown Source)
- at java.lang.Class.newInstance0(Unknown Source)
- at java.lang.Class.newInstance(Unknown Source)
- at com.izforge.izpack.installer.Installer.main(Installer.java:62)
-
- then it means you forgot to put the shelllink.dll into the correct source folder in that case, copy %IZPACK_HOME%\bin\native\izpack\ShellLink.dll to
- %IZPACK_HOME%\src\lib\com\izforge\izpack\util\os\ShellLink.dll
-
- Now you can debug the installation. With 2.x you can edit on demand,
- if %INSTALLER_DEST%\install.jar is shown in "Classpath" under the
- project.
- With 3.x it seems so, that always the JAR will be loaded; therefore
- the contents of install.jar and the sources should be synchron.
-
-6. Debug uninstallation
-
- Install your installation to
- %INSTALL_PATH%
- Run > Debug...
- Java Application
- New
- give a name e.g. "UninstallMyInstall"
- select in "Main" the project "IzPack"
- select as "main class" "Uninstaller" (from package com.izforge.izpack.installer)
- as "VM arguments" use
- -DTRACE=true
- select the tab "Classpath"
- select "User classes" (2.x) or "User Entries" (3.x)
- select "Add External JARs..."
- select %INSTALL_PATH%\Uninstaller\uninstall.jar
- uninstall.jar must be under the project entry
-
- Now, you can debug your uninstallation. Don't worry if you get first a NullPointerException in SelfModifier. This should be; it is a hint, that the class files of your eclipse session are used.
- If debugging not working, look whether:
- there is a fresh installation
- the uninstall.jar is in the "Classpath" tab under the project entry
-
-The IzPack architecture
-------------------------
-
-Now that you have packaged your first installer, it's time for you to understand how the whole thing works.
-
-The compilation system
-'''''''''''''''''''''''
-
-The compilation system is quite modular. Indeed, you can use the compiler in 2 ways :
-
-* from a command-line
-* from jakarta ant
-
-.. figure:: compilation-overview.png
-
- The compilation architecture.
-
-The compiler takes as its input an xml installation file that describes (at a relatively high-level) the installation. this file contains detailed information such as the application name, the authors, the files to install, the panels to use, which resources to load and much more.
-
-The compiler can generate different kinds of installers, but this information is not located inside the xml file as it is not were it should be. On the contrary, this is a compiler parameter.
-
-The compilation options for a command-line installer are the following:
-
--? Gives a list of the available options.
--b Specifies the base path, ie the one that will be used to resolve the relative paths. if your xml file contains absolute paths, specify it to an empty string (-b "").
--k Specifies the installer kind, for instance most users will want standard here.
--o Specifies the resulting installer jar file name.
-
-How an installer works
-'''''''''''''''''''''''
-
-An installer presents its panels to the end-user. for instance, there is one to select the packages, one to prompt for the license agreement, one to select the installation path and so on. You have a choice from a variety of panels to place in the installer. For example, you can choose between a plain text and a html text panel for the license agreement. also, if you don't want of the hellopanel, you just don't include it.
-
-.. figure:: installer-content.png
-
- The content of an installer.
-
-It is very important to understand that some of the panels may need extra data. for instance, the license agreement panel needs the license text. A simple approach to specify such data would have been to add as many xml tags as needed for each panel. However, this makes the xml file too specific and not easy to maintain. The approach that has been chosen is to put the data in files and we call these files resource files. They are specified with a unique xml tag. this is a much cleaner approach.
-
-You might wonder how your files are packaged. They can be grouped in packs. For instance, you can have one pack for the core files, one for the documentation, one for the source code and so on. In this way, your end-users will have the choice to install a pack or not (provided that the pack they don't want to install is not mandatory). Inside the jar file (which is a zip file), a sub directory contains the pack files. Each pack file contains the files that are part of it. Could we do it simpler ? :-)
-
-The different kinds of installers
-''''''''''''''''''''''''''''''''''
-
-There are 2 kinds of installers available :
-
-* Standard : a single-file ready-to-run installer
-* Web : a web based installer (pack data is located on an http server, and the installer retrieves it at install time (see section 3.6))
-
-Installers for older vm versions
-'''''''''''''''''''''''''''''''''
-
-By default the installer will be made for the current most used version of the java runtime environment. It is possible to create an installation that is runable with an older vm version.
-
-What version is used can be detected in the ant properties file that is used to build izpack. It is [izpackroot]/src/ant.properties. The value of the property "source" determines the vm version.
-
-If compatibility to older versions is needed, a recompilation of the jar files of the izpack system should be done. For this the sources of izpack and an ant installation are needed. the sources of izpack are selectable at installation time of izpack. Before a recompilation of all can be triggered, the version of byte code should be changed. This can be done simple by changing the "source" entry in [izpackroot]/src/ant.properties to the needed value. The recompilation should be performed with the current most used vm version because there are classes of it referenced in the izpack code. Usage of an older vm version at installation time will be possible because the classes of the newer vm version are only used after a vm version check. Of course, some features of izpack will be missing at using an old vm version. To recompile izpack go into [izpackroot]/src. Use a current jdk (not jre) for this. call ::
-
- ant clean
-
-followed by ::
-
- ant all
-
-then all jar files in [izpackroot]/lib, [izpackroot]/bin/panels and [izpackroot]/bin/customactions should be recompiled with the selected source version.
Deleted: izpack-src/trunk/src/doc-reST/node4.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node4.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node4.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,1418 +0,0 @@
-Writing Installation XML Files
-==============================
-
-
-What You Need
--------------
-
-
-Your editor
-'''''''''''
-
-In order to write your XML installation files, you just need a plain text
-editor. Of course it's always easier to work with color coded text, so you
-might rather want to work with a text editor having such a feature. Here is a
-list of free editors that work well :
-
-- Jext : http://www.jext.org/
-- JEdit : http://www.jedit.org/
-- classics like Vim and (X)Emacs.
-
-If you are a developer and tend to write your own patches, extension or
-features to IzPack sources, or, if you wish to debug your compilation,
-installation and uninstallation, we recommend these IDE:
-
-- IntelliJ IDEA : http://www.jetbrains.com/idea/
-- Eclipse : http://www.eclipse.org/
-- Netbeans : http://www.netbeans.org/
-
-For the first one, JetBrains has granted us an Open Source License. All
-project members can ask the Licence Key to one of the project manager.
-
-The other ones are well know open source projects (Just like us :-)). We provide
-a tutorial on how to develop/debug IzPack using Eclipse in the chapter
-''Getting Started > How to develop and debug IpPack using Eclipse''
-
-
-Writing XML
-'''''''''''
-
-Though you might not know much about XML, you have certainly heard about it.
-If you know XML you can skip this subsection as we will briefly present how
-to use XML.
-
-
-XML is a markup language, really close to HTML. If you've ever worked with
-HTML the transition will be fast. However there are a few little things to
-know. The markups used in XML have the following form : ``<markup>``. Each
-markup has to be closed somewhere with its ending tag : ``</markup>``. Each
-tag can contain text and other markups. If a markup does not contain
-anything, it is just reported once : ``<markup/>``. A markup can contain
-attributes like : ``<markup attr1="123" attr2="hello !"/>``. Here is a sample
-of a valid XML structure :
-
-::
-
- <chapter title="Chapter 1">
- <section name="Introduction">
- <paragraph>
- This is the text of the paragraph number 1. It is available
- for the very low
- price of <price currency="dollar">1 000 000</price>.
- </paragraph>
- </section>
- <section name="xxx">
- xxx
- </section>
- </chapter>
-
-
-You should be aware of the following common mistakes :
-
-- markups **are** case sensitive : ``<markup>`` is different from
- ``<Markup>``.
-- you **must** close the markups in the same order as you create them :
- ``<m1><m2>(...)</m2></m1>`` is right but `` <m1><m2>(...)</m1></m2>`` is
- not.
-
-Also, an XML file must start with the following header :
-``<?xml version="1.0" encoding="iso-8859-1 standalone="yes" ?>``. The only
-thing you should modify is the encoding (put here the one your text editor
-saves your files to). The `` standalone`` attribute is not very important for
-us.
-
-
-This (brief !) introduction to XML was just meant to enable you to write your
-installation specification. For a better introduction there are plenty of
-books and articles/tutorials dealing with XML on the Internet, in book
-stores, in magazines and so on.
-
-Variable Substitution
----------------------
-
-During the installation process IzPack can substitute variables in various
-places with real values. Obvious targets for variable substitution are
-resource files and launch scripts, however you will notice many more places
-where it is more powerful to use variables rather then hard coded values.
-Wherever variables can be used it will be explained in the documentation.
-
-
-There are three types of variables:
-
-- Built-In variables. These are implemented in IzPack and are all
- dynamic in nature. This means that the value of each variable depends on
- local conditions on the target system.
-- Environment variables. These are provided by the operating system the
- installer is run on.
-- Variables that you can define. You also define the value, which is
- fixed for a given installation file.
-
-You define your own variables in the installation XML file with the
-``<variable>`` tag. How to do this is explained in detail later in this
-chapter.
-
-
-**Please note** that when using variables they must always appear with a
-'``$``' sign as the first character, even though they are not defined this
-way.
-
-
-
-The Built-In Variables
-----------------------
-
-The following variables are built-in :
-
-- ``$INSTALL_PATH`` : the installation path on the target system, as
- chosen by the user
-- ``$APPLICATIONS_DEFAULT_ROOT`` : the default path for applications
-- ``$JAVA_HOME`` : the JavaTM virtual machine home path
-- ``$CLASS_PATH`` : the Class Path used mainly for Java Applications
-- ``$USER_HOME`` : the user's home directory path
-- ``$USER_name`` : the user name
-- ``$APP_name`` : the application name
-- ``$APP_URL`` : the application URL
-- ``$APP_VER`` : the application version
-- ``$ISO3_LANG`` : the ISO3 language code of the selected langpack.
-- ``$IP_ADDRESS`` : the IP Address of the local machine.
-- ``$HOST_NAME`` : the HostName of the local machine.
-- ``$FILE_SEPARATOR`` : the file separator on the installation system
-- ``$DesktopShortcutCheckboxEnabled`` : When set to true, it
- automatically checks the "Create Desktop Shortcuts" button. To see how to
- use it, go to `The Variables Element ``<variables>`` Be careful this
- variable is case sensitve !
-- ``$InstallerFrame.logfilePath`` : The path to the install log. This
- file contains the paths of all installed files. If set to "default" then
- the "$INSTALL_PATH/Uninstaller/install.log" path will be used. To see how
- to use it, go to `The Variables Element ``<variables>``. If this
- variable is not set, no install.log will be created.
-
-
-Environment Variables
----------------------
-
-Environment variables can be accessed via the syntax ``${ENV[variable]}``.
-The curly braces are mandatory. Note that variable names are case-sensitive
-and usually in UPPER CASE.
-
-Example: To get the value of the OS environment variable "CATALINA_HOME", use
-``${ENV[CATALINA_HOME]}``.
-
-
-Parse Types
------------
-
-Parse types apply only when replacing variables in text files. At places
-where it might be necessary to specify a parse type, the documentation will
-mention this. Depending on the parse type, IzPack will handle special cases
--such as escaping control characters- correctly. The following parse types
-are available:
-
-- ``plain`` - use this type for plain text files, where no special
- substitution rules apply. All variables will be replaced with their
- respective values as is.
-- ``javaprop`` - use this type if the substitution happens in a Java
- properties file. Individual variables might be modified to function
- properly within the context of Java property files.
-- ``xml`` - use this type if the substitution happens in a XML file.
- Individual variables might be modified to function properly within the
- context of XML files.
-- ``shell`` - use this type if the substitution happens in a shell
- script. Because shell scripts use ``$variable`` themselves, an
- alternative variable marker is used: ``%variable`` or ``%{variable}``.
-
-
-The IzPack Elements
--------------------
-
-*When writing your installer XML files, it's a good idea to have a look at
-the iZPACK installation DTD*.
-
-
-
-
-The Root Element ``<installation>``
-''''''''''''''''''''''''''''''''''''
-
-The root element of an installation is ``<installation>``. It takes one
-required attribute : ``version``. The attribute defines the version of the
-XML file layout and is used by the compiler to identify if it is compatible
-with the XML file. This should be set to **1.0** for the moment.
-
-
-The Information Element ``<info>``
-'''''''''''''''''''''''''''''''''''
-
-This element is used to specify some general information for the installer.
-It contains the following elements :
-
-- ``<appname>`` : the application name
-- ``<appversion>`` : the application version
-- ``<appsubpath>`` : the subpath for the default of the installation
- path. A variable substitution and a maskable slash-backslash conversion
- will be done. If this tag is not defined, the application name will be
- used instead.
-- ``<url>`` : the application official website url
-- ``<authors>`` : specifies the author(s) of the application. It must
- contain at least one ``<author>`` element whose attributes are :
-
- - ``name`` : the author's name
- - ``email`` : the author's email
-
-- ``<uninstaller>`` : specifies whether to create an uninstaller after
- installation, and which name to use for it. This tag has the ``write``
- attribute, with default value `` yes``. If this tag is not specified, the
- uninstaller will still be written. The ``name`` attribute can be used to
- change the default name of the generated uninstaller, *i.e.* ``
- uninstaller.jar``.
-- ``<javaversion>`` : specifies the minimum version of Java required to
- install your program. Values can be ``1.2``, ``1.2.2``, ``1.4``, etc. The
- test is a lexical comparison against the ``java.version`` System property
- on the install machine.
-- ``<webdir>`` : Causes a ''web installer'' to be created, and
- specifies the URL packages are retrieved from at install time. The
- content of the tag must be a properly formed URL.
-- ``<summarylogfilepath>`` : specifies the path for the logfile of the
- `SummaryLoggerInstallerListener`.
-
-Here is an example of a typical ``<info>`` section :
-
-
-::
-
- <info>
- <appname>Super extractor</appname>
- <appversion>2.1 beta 6</appversion>
- <appsubpath>myCompany/SExtractor</appsubpath>
- <url>http://www.superextractor.com/</url>
- <authors>
- <author name="John John Doo" email="jjd at jjd-mail.com"/>
- <author name="El Goyo" email="goyoman at mymail.org"/>
- </authors>
- <javaversion>1.2</javaversion>
- </info>
-
-
-The Variables Element ``<variables>``
-''''''''''''''''''''''''''''''''''''''
-
-This element allows you to define variables for the variables substitution
-system. Some variables are built-in, such as ``$INSTALL_PATH`` (which is the
-installation path chosen by the user). When you define a set of variables,
-you just have to place as many ``<variable>`` tags in the file as needed. If
-you define a variable named ``VERSION`` you need to type $VERSION in the
-files to parse. The variable substitutor will then replace it with the
-correct value. One ``<variable>`` tag take the following attributes :
-
-- ``name`` : the variable name
-- ``value`` : the variable value
-
-Here's a sample ``<variables>`` section :
-
-
-::
-
- <variables>
- <variable name="app-version" value="1.4"/>
- <variable name="released-on" value="08/03/2002"/>
- </variables>
-
-
-Here's a precise sample on how to use desktopshortcutcheckboxenabled and
-InstallerFrame.logfilePath variables:
-
-
-::
-
- <variables>
- <variable name="InstallerFrame.logfilePath" value="$INSTALL_PATH
- /My-install.log"/>
- <!-- This means that the log name will be My-install and that
- it will be stored at the root of the installation. -->
- <!-- Any path is fine. If value is set to "Default" then
- "$INSTALL_PATH/uninstall/install.log" is used. -->
- <!-- And if variable isn't defined then no log is written. -->
- <variable name="desktopshortcutcheckboxenabled" value="true"/>
- <!-- This automatically checks the "Create Desktop Shortcuts"
- button. Default value is "False". -->
- </variables>
-
-
-The GUI Preferences Element ``<guiprefs>``
-'''''''''''''''''''''''''''''''''''''''''''
-
-This element allows you to set the behavior of your installer GUI. This
-information will not have any effect on the command-line installers that will
-be available in future versions of iZPACK . The arguments to specify are :
-
-- ``resizable`` : takes ``yes`` or ``no`` and indicates whether the
- window size can be changed or not.
-- ``width`` : sets the initial window width
-- ``height`` : sets the initial window height.
-
-Here's a sample :
-
-::
-
- <guiprefs resizable="no" width="800" height="600"/>
-
-
-Starting from IzPack 3.6, the look and feel can be specified in this section
-on a per-OS basis. For instance you can use the native look and feels on
-Win32 and OS X but use a third-party one on Unix-like platforms. To do that,
-you have to add some children to the ``guiprefs`` tag:
-
-- ``laf``: the tag that specifies a look and feel. It has a ``name``
- parameter that defines the look and feel name.
-- Each ``laf`` element needs at least one ``os`` tag, specified like in
- the other parts of the specification that support this tag.
-- Like you can add ``os`` elements, you can add any number of ``param``
- elements to customize a look and feel. A ``param`` elements has two
- attribues: ``name`` and `` value``.
-
-The available look and feels are:
-
-- Kunststoff: ``kunststoff``
-- Liquid: ``liquid``
-- Metouia: ``metouia``
-- JGoodies Looks: ``looks``
-- Substance: ``substance``
-
-If you don't specify a look and feel for a particular operating system, then
-the default native one will be used: Windows on Windows, Aqua on Mac OS X and
-Metal on the Unix-like variants.
-
-
-The *Liquid Look and Feel* supports the following parameters:
-
-- ``decorate.frames``: ``yes`` means that it will render the frames in
- Liquid style
-- ``decorate.dialogs``: ``yes`` means that it will render the dialogs
- in Liquid style
-
-The *JGoodies Looks* look and feel can be specified by using the ``variant``
-parameters. The values can be one of:
-
-- ``windows``: use the Windows look
-- ``plastic``: use the basic Plastic look
-- ``plastic3D``: use the Plastic 3D look
-- ``plasticXP``: use the Plastic XP look (default).
-
-Here is a small sample:
-
-::
-
- <guiprefs height="600" resizable="yes" width="800">
- <laf name="metouia">
- <os family="unix" />
- </laf>
- <laf name="looks">
- <os family="windows" />
- <param name="variant" value="extwin" />
- </laf>
- </guiprefs>
-
-
-The *Substance* look and feel *toned-down* themes can be specified using the
-``variant`` parameter, with the value being one of: ``business, business-
-blue, business-black, creme, sahara, moderate, officesilver``. We have
-reduced the choice to the toned-down themes since they are the only ones to
-actually look decent (the other families colors are way too saturated).
-Please consult https://substance.dev.java.net/docs/skins/toneddown.html
-for a gallery of the different toned-down themes.
-
-Starting from IzPack 3.7, some characteristics can be customized with the
-``<modifier>`` tag. There is a separate description in the `Advanced
-Features` chapter paragraph `Modifying the GUI`.
-
-
-
-The Localization Element ``<locale>``
-''''''''''''''''''''''''''''''''''''''
-
-This element is used to specify the language packs (langpacks) that you want
-to use for your installer. You must set one ``<langpack>`` markup per
-language. This markup takes the `` iso3`` parameter which specifies the iso3
-language code.
-
-
-Here's a sample :
-
-
-::
-
- <locale>
- <langpack iso3="eng"/>
- <langpack iso3="fra"/>
- <langpack iso3="spa"/>
- </locale>
-
-
-The supported ISO3 codes are :
-
-========= ============================
-ISO3 code Language
-========= ============================
-cat Catalunyan
-chn Chinese
-cze Czech
-dan Danish
-deu German
-eng English
-fin Finnish
-fra French
-hun Hungarian
-ita Italian
-jpn Japanese
-mys Malaysian
-ned Nederlands
-nor Norwegian
-pol Polnish
-por Portuguese (Brazilian)
-rom Romanian
-rus Russian
-scg Serbian
-spa Spanish
-svk Slovakian
-swe Swedish
-ukr Ukrainian
-========= ============================
-
-
-
-The Resources Element ``<resources>``
-''''''''''''''''''''''''''''''''''''''
-
-Several panels, such as the license panel and the shortcut panel, require
-additional data to perform their task. This data is supplied in the form of
-resources. This section describes how to specify them. Take a look at each
-panel description to see if it might need any resources. Currently, no checks
-are made to ensure resources needed by any panel have been included. The ``
-<resources>`` element is not required, and no ``<res>`` elements are required
-within.
-The ``<resources>`` element is the only element besides the ``<packs>``
-element that is taken into consideration in referenced pack-files (see
-```<packs>`` element`_ for more info)
-
-
-You have to set one ``<res>`` markup for each resource. Here are the
-attributes to specify :
-
-- ``src`` : the path to the resource file which can be named freely of
- course (for instance ``my-picture.jpg``).
-- ``id`` : the resource id, depending on the needs of a particular
- panel
-- ``parse`` : takes ``yes`` or ``no`` (default is ``no``) - used to
- specify whether the resource must be parsed at the installer compilation
- time. For instance you could set the application version in a readme file
- used by ``InfoPanel``.
-- ``type`` : specifies the parse type. This makes sense only for a text
- resource - the default is ``plain``, other values are ``javaprop, xml``
- (Java properties file and XML files)
-- ``encoding`` : specifies the resource encoding if the receiver needs
- to know. This makes sense only for a text resource.
-
-Here's a sample :
-
-::
-
- <resources>
- <res id="InfoPanel.info" src="doc/readme.txt" parse="yes"/>
- <res id="LicencePanel.licence" src="legal/License.txt"/>
- </resources>
-
-
-The Panels Element ``<panels>``
-'''''''''''''''''''''''''''''''''
-
-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 a single attribute ``classname`` which is the
-classname of the panel.
-
-
-Here's a sample :
-
-::
-
- <panels>
- <panel classname="HelloPanel"/>
- <panel classname="LicencePanel"/>
- <panel classname="TargetPanel"/>
- <panel classname="InstallPanel"/>
- <panel classname="FinishPanel"/>
- </panels>
-
-
-The Packs Element ``<packs>``
-'''''''''''''''''''''''''''''''
-
-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>`` and
-``<refpack>`` 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.
-- ``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.
-
-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 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.
-
-Internationalization of the PacksPanel
-'''''''''''''''''''''''''''''''''''''''
-
-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``.
-
-The following sections describe the tags available for a ``<pack>`` section.
-
-
-``<description>`` - pack description
-'''''''''''''''''''''''''''''''''''''
-
-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
-''''''''''''''''''''''''''''''''''
-
-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
-'''''''''''''''''''''''''''
-
-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>``
-''''''''''''''''''
-
-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.:
-
-::
-
- <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
-'''''''''''''''''''''''''''''''''''''''
-
-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
-- ``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. 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``.
-- ``unpack``: if ``true`` and the file is an archive then its content
- will be unpacked and added as individual files
-
-
-
-``<additionaldata>``
-'''''''''''''''''''''
-
-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
-'''''''''''''''''''''''''''''''''''''
-
-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)
-- ``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
-
-A ``<additionaldata>`` tag can also be specified for customizing.
-
-
-
-``<fileset>``: add a fileset
-'''''''''''''''''''''''''''''
-
-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
-- ``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.
-
-You specify the files with ``<include>`` and ``<exclude>`` tags that take the
-``name`` parameter to specify the Ant-like pattern :
-
-- ``**`` : 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``
-- ``<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:
-
-::
-
- **/*\~{}
- **/\#*\#
- **/.\#*
- **/%*%
- **/.\_*
- **/CVS
- **/CVS/**
- **/.cvsignore
- **/SCCS
- **/SCCS/**
- **/vssver.scc
- **/.svn
- **/.svn/**
- **/.DS\_Store
-
-
-A ``<additionaldata>`` tag can also be specified for customizing.
-
-
-``<parsable>`` - parse a file after installation
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-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.
-- ``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>``
-
-
-``<executable>`` - mark file executable or execute it
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''
-
-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"``.
-
-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
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-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:
-
-- ``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 :
-
-::
-
- <packs>
- <!-- The core files -->
- <pack name="Core" required="yes">
- <description>The IzPack core files.</description>
- <file targetdir="$INSTALL_PATH" src="bin"/>
- <file targetdir="$INSTALL_PATH" src="lib"/>
- <file targetdir="$INSTALL_PATH" src="legal"/>
- <file targetdir="$INSTALL_PATH" src="Readme.txt"/>
- <file targetdir="$INSTALL_PATH" src="Versions.txt"/>
- <file targetdir="$INSTALL_PATH" src="Thanks.txt"/>
- <parsable targetfile="$INSTALL_PATH/bin/izpack-fe"/>
- <parsable targetfile="$INSTALL_PATH/bin/izpack-
- fe.bat"/>
- <parsable targetfile="$INSTALL_PATH/bin/compile"/>
- <parsable
- targetfile="$INSTALL_PATH/bin/compile.bat"/>
- <executable targetfile="$INSTALL_PATH/bin/compile"
- stage="never"/>
- <executable targetfile="$INSTALL_PATH/bin/izpack-fe"
- stage="never"/>
- </pack>
-
- <!-- The documentation (1 directory) -->
- <pack name="Documentation" required="no">
- <description>The IzPack documentation (HTML and
- PDF).</description>
- <file targetdir="$INSTALL_PATH" src="doc"/>
- </pack>
- </packs>
-
-
-The Native Element ``<native>``
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-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 useable 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)
-
-
-``<os>`` - make a library OS-dependent
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-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 :
-
-::
-
- <native type="izpack" name="ShellLink.dll"/>
-
-
-The Jar Merging Element ``<jar>``
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-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 :
-
-::
-
- <jar src="../nicelibrary.jar"/>
-
-The Available Panels
----------------------
-
-In this section i will introduce the various panels available in IzPack. The
-usage for most is pretty simple and described right here. The more elaborate
-ones are explained in more detail in the *Advanced Features* chapter or in
-their own chapter. The panels are listed by their class name. This is the
-name that must be used with the ``classname`` attribute. Please be aware that
-the classname is Case-Sensitive, meaning that if the case from the
-install.xml and the founded class file differs the installation will break.
-In this last case, the installer will Throw an IllegalArgumentException in
-the compiler if the declared class name in the xml file differs in case from
-the founded class file.
-
-
-
-HelloPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel welcomes the user by displaying the project name, the version, the
-URL as well as the authors.
-
-
-
-CheckedHelloPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel welcomes the user also by displaying the project name, the
-version, the URL as well as the authors.
-
-
-Additonal on windows the registry will be scanned for an entry which
-determines that the product is already installed. If so, a dialog will be
-shown which ask whether to install a second version of the product or not. If
-you use this panel do not forget to add the `registry feature` into your
-installation.
-
-
-InfoPanel and HTMLInfoPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This is a kind of 'README' panel. It presents text of any length. The text is
-specified by the ``(HTML)InfoPanel.info`` resource. Starting from IzPack
-3.7.0, variables substitution is allowed.
-To add an image to the HTMLInfoPanel you simply need to add a ressource to
-your install.xml with an ID decided by you, then you can call this image by
-refering it by this same ID.
-
-In install.xml:
-
-::
-
- <resources>
- <res src="logo.jpg" id="GHGHGH"/>
- .....
-
-and in file.html:
-
-::
-
- <img src="GHGHGH" />
-
-
-LicencePanel and HTMLLicencePanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-Note:* There is a mistake in the name - it should be LicensePanel. In France
-the word is Licence ... and one of my diploma is a 'Licence' so ...:* -)
-
-
-Adding images to HTMLLicencePanel works exactly the same way as with
-HTMLInfoPanel.
-
-These panels can prompt the user to acknowledge a license agreement. They
-block unless the user selects the 'agree' option. To specify the license
-agreement text you have to use the `` (HTML)LicencePanel.licence`` resource.
-
-
-
-PacksPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-Allows the user to select the packs he wants to install.
-
-
-
-ImgPacksPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This is the same as above, but for each pack a different picture is shown to
-the user. The pictures are specified using the packImgId attribute for each
-pack in the installer XML. The initial image will be the image of the first
-pack that has a packImgId. The image is updated each time the user
-(de)selects a pack that has a packImgId. Of course it's up to you to specify
-an image for each pack in your installation with a unique packImgId. For
-instance if you have 2 packs ``core`` and ``documentation`` (in this order),
-and you assign both packs a packImgId that is identical to the pack's name
-then the resource for ``core`` will be ``core`` and the resource for
-``documentation`` will be ``documentation``. The initially shown image will
-be the resource ``core``. The supported image formats depend on what your
-client's JVM supports, but starting from J2SE 1.3, *GIF*, *JPEG* and *PNG*
-are supported.
-
-
-
-TargetPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel allows the user to select the installation path. It can be
-customized with the following resources (they are text files containing the
-path) :
-
-- ``TargetPanel.dir.f`` where f stands for the family (``mac, macosx,
- windows, unix``)
-- ``TargetPanel.dir`` : the directory name, instead of the software to
- install name
-- ``TargetPanel.dir.d`` where d is a "dynamic" name, as returned by the
- JavaTM virtual machine. You should write the name in lowercase and
- replace the spaces with underscores. For instance, you might want a
- different setting for Solaris and GNU/Linux which are both Unix-like
- systems. The resources would be ``TargetPanel.dir.sunos,
- TargetPanel.dir.linux``. You should have a Unix-resource in case it
- wouldn't work though.
-
-
-InstallPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-You should always have this one as it launches the installation process !
-
-
-
-XInfoPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-A panel showing text parsed by the variable substitutor. The text can be
-specified through the ``XInfoPanel.info`` resource. This panel can be useful
-when you have to show information after the installation process is completed
-(for instance if the text contains the target path).
-
-
-
-FinishPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-A ending panel, able to write automated installer information. For details
-see the chapter on 'Advanced Features'.
-
-
-
-SimpleFinishPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-Same as ``FinishPanel``, but without the automated installer features. It is
-aimed at making the life easier for end-users who will never encounter the
-automated installer extra feature.
-
-
-
-ShortcutPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel is used to create desktop shortcuts. For details on using the
-ShortcutPanel see the chapter 'Desktop Shortcuts'.
-
-
-UserInputPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel allows you to prompt the user for data. What the user is prompted
-for is specified using an XML file which is included as a resource to the
-installer.
-
-
-CompilePanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel allows you to compile just installed Java sourcecode. The details
-for the compilation are specified using the resource
-``CompilePanel.Spec.xml``. The XML file has the following format:
-
-::
-
- <compilation>
- <global>
- <compiler>
- <choice value="$JAVA_HOME/bin/javac" />
- <choice value="jikes" />
- </compiler>
- <arguments>
- <choice value="-O -g:none" />
- <choice value="-O" />
- <choice value="-g" />
- <choice value="" />
- </arguments>
- </global>
- <jobs>
- <classpath add="$INSTALL_PATH/src/classes/" />
- <job name="optional name">
- <directory name="$INSTALL_PATH/src/classes/xyz" />
- </job>
- <job name="another job">
- <packdepency name="some package name" />
- <classpath sub="$INSTALL_PATH/" />
- <directory name="$INSTALL_PATH/src/classes/abc" />
- <file name="$INSTALL_PATH/some/file.java" />
- </job>
- </jobs>
- </compilation>
-
-
-In theory, jobs can be nested but this has not been tested at all. A change
-to the classpath within a job only affects this job and nested jobs. The
-classpath should be specified before any files or directories.
-
-The user can change the compiler to use and choose from some default
-compilation options before compilation is started.
-
-.. image:: ./compilePanel.png
- :alt: CompilePanel
-
-
-
-ProcessPanel
-''''''''''''''''''''''''''''''''''''''''''''''''''
-
-This panel allows you to execute arbitrary files after installation. The
-details for the compilation are specified using the resource
-``ProcessPanel.Spec.xml``.
-
-The XML file has the following format:
-
-::
-
- <processing>
- <job name="do xyz">
- <os family="windows" />
- <executefile name="$INSTALL_PATH/scripts/xyz.bat">
- <arg>doit</arg><arg>$variable</arg>
- </executefile>
- </job>
- <job name="do xyz">
- <os family="unix" />
- <executefile name="$INSTALL_PATH/scripts/xyz.sh">
- <arg>doit</arg><arg>$variable</arg>
- </executefile>
- </job>
- </processing>
-
-
-Each job may have an ``<os>`` attribute.
-
-
-
-``<executeclass>`` - Execute Java Classes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It is also possible to execute Java classes from this panel. Here's what this
-feature author (Alex Bradley) says:
-
-> i've been able to work around my requirements by extending the
-``ProcessPanelWorker`` functionality to run user-specified classes. i've
-extended the DTD of the `` ProcessPanel.Spec.xml`` to include a new element:
-
-::
-
- <executeclass name="classname">
- <args..../>
- </executeclass>
-
-
-> i've also added a new sub-class of ``Processable`` called ``executeclass``.
-This will run a user-specified class in the context of the installer JVM with
-a single method :
-
-::
-
- run( AbstractUIProcessHandler handler, String[] args]);
-
-
-> It can do everything i need and more. In particular, it allows me to write
-a process extension and still be able to provide feedback to the user through
-the feedback panel, and to add new functionality to the installer, after its
-been built.
-
-To use the executeclass facility, you will need to create a jar file with
-your class and then add it to the installer with the `The Jar Merging
-Element`.
-
-
-``<executeForPack>`` - Only execute the job for certain packs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This can be be used to run the job only if the pack is enabled. For example,
-the batch file will if either the ``Sources`` or ``Executables`` packs are
-selected at install time.
-
-::
-
- <processing>
- <job name="List files">
- <executeForPack name="Sources"/>
- <executeForPack name="Executables"/>
- <os family="windows" />
- <executefile name="$INSTALL_PATH\batch\ListFiles.bat" />
- </job>
- </processing>
-
-``<logfiledir>`` - Output of the processPanel saved to a log
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-New with version 3.7 is the possibility to tee output that is written to the
-ProcessPanel's textarea into an optional logfile. Using this feature is
-pretty much straightforward, you only have to add a line in
-``ProcessPanel.Spec.xml`` that will tell IzPack the location, where the
-logfile should be stored.
-
-Variable substitution is performed, so you can use ``$INSTALL_PATH`` as
-example.
-
-The name of the logfile is not (yet) configurable but should fit in most
-cases. It will be named
-
-::
-
- Install_V<$APP_VER>_<YYYY>-<MM>-<DD>_<hh>-<mm>-<ss>_<RandomId>.log
-
-
-Here's an example:
-
-::
-
- <processing>
- <logfiledir>$INSTALL_PATH</logfiledir>
- <job name="do xyz">
- <os family="windows" />
- <executefile name="$INSTALL_PATH/scripts/xyz.bat">
- <arg>doit</arg><arg>$variable</arg>
- </executefile>
- </processing>
-
-
-This will generate a logfile named e.g.
-``Install_V1.3_2004-11-08_19-22-20_43423.log`` located in ``$INSTALL_PATH``.
-
-``ProcessPanelWorker`` will write all output that is directed to ``stdout``
-and ``stderr`` to this file if ``ProcessPanel.Spec.xml`` contains the
-``logfiledir`` entry.
-
-Please note that this one file is used for storing the complete output of all
-jobs and not a file for each job that is run.
-
-
-JDKPathPanel
-'''''''''''''
-
-This panel allows the user to select a JDK path. The variable JAVA_HOME does
-not point to a JDK, else to a JRE also the environment variable points to a
-JDK. This is not a bug, this is the behavior of the VM. But some products
-needs a JDK, for that this panel can be used. There is not only a selection
-of the path else a validation. The validation will be done with the file
-JDKPath/lib/tools.jar. If JAVA_HOME points to the VM which is placed in the
-JDK, the directory will be used as default (JAVA_HOME/..). If there is the
-variable
-
-::
-
- JDKPathPanel.skipIfValid
-
-
-defined with the value "yes", the panel will be skiped if the path is valid.
-Additional it is possible to make a version control. If one or both variables
-
-::
-
- JDKPathPanel.minVersion
- JDKPathPanel.maxVersion
-
-
-are defined, only a JDK will be accepted which has a version in the range of
-it. The detection is a little bit pragmatically, therefor it is possible,
-that the detection can fail at some VMs. The values in the install.xml should
-be like
-
-::
-
- <variables>
- <variable name="JDKPathPanel.minVersion" value="1.4.1" />
- <variable name="JDKPathPanel.maxVersion" value="1.4.99" />
- <variable name="JDKPathPanel.skipIfValid" value="yes" />
- </variables>
-
-
-If all is valid, the panels isValidated method sets the variable
-
-::
-
- JDKPath
-
-
-to the chosen path. Be aware, this variable exist not until the JDKPanel was
-quitted once. At a secound activation, the default will be the last
-selection.
-
-
-SelectPrinterPanel
-''''''''''''''''''''''''''
-
-This panel will look at the local printers installed and propose a list box
-with all of them. Once chosen, the variable $SELECTED_PRINTER is set to the
-user choice.
-
-
-DataCheckPanel
-''''''''''''''''''''''''''
-
-DataCheckPanel is not for inclusion in an actuall install, but is a debugging
-resource for developers writing custom panels or code to be included in
-IzPack.
-It creates a list of all the variables in InstallData, their values and a
-list of all packs, indicating which are selected.
-This list is printed to the console and appears in a scrollable text area on
-the panel.
-Put the panel in wherever you want to see any variables in InstallData or a
-listing of the packs with a line like this in the <panels> section of
-install.xml:
-
-<panel classname="DataCheckPanel" />
-
-It will automatically give you a full list of all the variables and packs
-whenever the panel is made active.
-
-
-SummaryPanel
-'''''''''''''
-
-This panel gives a summary of all shown panels. The best place for it is just
-infront of the InstallPanel. Normaly it contains a warning that this is the
-last panel before installation. The panel contains a scrollable HTML text
-area to display the summary. The informations are collected from each panel
-by calling the methods ``getSummaryCaption`` and ``getSummaryBody``.
-``getSummaryCaption`` is implemented in ``IzPanel`` with a panel name default
-text. ``getSummaryBody`` has to be implemented in all panels which should be
-presented in the summary. If the secound method is not implemented, no
-summary of this panel will be shown.
-
-Additional it is possible to `log the contents` of the summary panel into a
-HTML file.
-
-
-InstallationGroupPanel
-''''''''''''''''''''''''''
-
-This Panel groups the pack together. A panel which displays the available
-*installGroups* found on the packs to allow the user to select a subset of
-the packs based on the pack *installGroups* attribute. This panel will be
-skipped if there are no pack elements with an *installGroups* attribute. For
-example ::
-
- <installation version="1.0">
- (...)
- <panels>
- (...)
- <panel classname="InstallationGroupPanel"/>
- <panel classname="PacksPanel"/>
- (...)
- </panels>
-
- <packs>
- <pack name="Base"
- installGroups="Group1"
- required="yes">
- (...)
- </pack>
- <pack name="Docs"
- installGroups="Group1,Group2"
- required="no">
- (...)
- </pack>
- <pack name="Sources"
- installGroups="Group3,Group2"
- required="no">
- (...)
- </pack>
- </packs>
- </installation>
-
-In above example when InstallationGroupPanel is displayed,
-it contains three radios named Group1, Group2 and Group3. Depending
-on what user selects, the respective Packs will be displayed in
-PacksPanel. InstallationGroupPanel will look for a description
-corresponding to the key
-"InstallationGroupPanel.description.Group1",
-"InstallationGroupPanel.description.Group2" etc in installation
-langpacks and variables and displays this description for each of
-the Group_i.
-
-You may also define a sortKey in the variables section of the installer.xml
-to define an alternative sorting. The default sorting is based on the Group
-Name.
-
-Here is an example for alternative sorting of groups: ::
-
- (...)
- <variables>
- (...)
- <variable
- name="InstallationGroupPanel.sortKey.Group2" value="A"/>
- <variable
- name="InstallationGroupPanel.sortKey.Group1" value="B"/>
- <variable
- name="InstallationGroupPanel.sortKey.Group3" value="C"/>
- </variables>
- (...)
Deleted: izpack-src/trunk/src/doc-reST/node5.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node5.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node5.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,374 +0,0 @@
-Advanced features
-==================
-
-Apache Ant integration
------------------------
-
-IzPack can be easily integrated inside an Ant build process. To do so you first need to tell Ant that you would like to use IzPack: ::
-
- <!-- Allows us to use the IzPack Ant task -->
- <taskdef name="IzPack" classpath="${basedir}/lib/compiler.jar"
- classname="com.izforge.IzPack.ant.IzPackTask"/>
-
-If you want to use the standalone compiler (and therefore don't need an IzPack installation for building), the task needs to be defined as follows: ::
-
- <!-- Allows us to use the IzPack Ant task -->
- <taskdef name="IzPack" classpath="${basedir}/lib/standalone-compiler.jar"
- classname="com.izforge.IzPack.ant.IzPackTask"/>
- Don't forget to add compiler.jar or standalone-compiler.jar to the classpath of the Ant process.
-
-Then you can invoke IzPack with the IzPack task which takes the following parameters:
-
-* 'input': the XML installation file. The installation can be specified as an external file, or embedded using a config child element (see section 3.2).
-* 'output': the output jar installer file
-* 'installerType': optional. standard or web. If web, the <webdir> attribute must be specified in the input file (see section 3.7). Used to force creation of a standard installer when the <webdir> attribute has been used.
-* 'baseDir': the base directory to resolve the relative paths
-* 'IzPackDir': the IzPack home directory. Only necessary if you do not use the standalone compiler.
-
-Here is a sample of the task invocation: ::
-
- <!-- We call IzPack -->
- <echo message="Makes the installer using IzPack"/>
- <IzPack input="${dist.dir}/IzPack-install.xml"
- output="${dist.dir}/IzPack-install.jar"
- installerType="standard"
- basedir="${dist.dir}"
- IzPackDir="${dist.dir}/"/>
-
-Embedding the installation file using a config element
---------------------------------------------------------
-
-Instead of using the 'install' attribute to specify an external installation document, you can embed the installation config as a child of the IzPack task using a config child element with a CDATA section. For example: ::
-
- <property name="jboss.home.url" value="http://www.jboss.com/" />
- ...
-
- <!-- Call IzPack with an embedded install using the config element -->
- <IzPack output="${dist.dir}/IzPack-install.jar"
- installerType="standard"
- basedir="${dist.dir}"
- IzPackDir="${dist.dir}/">
- <config><![CDATA[
- <installation version="1.0">
- <info>
- <appname>JBossAS</appname>
- <appversion>4.0.2</appversion>
- <appsubpath>jboss-4.0.2</appsubpath>
- <authors>
- <author name="JBoss Inc." email="sales at jboss.com"/>
- </authors>
- <url>@{jboss.home.url}</url>
- <javaversion>1.4</javaversion>
- </info>
- ...
- ]]></config>
- </IzPack>
-
-Property references of the form '@{x}' are replaced by the associated x ant property if it is defined.
-
-System properties as variables
--------------------------------
-
-All system properties are available as '$SYSTEM_<variable>' where '<variable>' is the actual name but with all separators replaced by '_'. Properties with null values are never stored.
-
-Examples:
-
-'$SYSTEM_java_version' or '$SYSTEM_os_name'
-
-Automated Installers
----------------------
-
-When you conclude your installation with a FinishPanel, the user can save the data for an automatic installation. With this data, he will be able to run the same installation on another similar machine. In an environment where many computers need to be supported this can save a lot of time.
-
-So run once the installation on a machine and save your automatic installation data in auto-install.xml (that's just a sample). Then put this file in the same directory as the installer on another machine. Run it with: ::
-
- java -jar installer.jar auto-install.xml
-
-It has reproduced the same installation :-)
-
-Picture on the Language Selection Dialog
------------------------------------------
-
-You can add a picture on the language selection dialog by adding the following resource : 'installer.langsel.img'. GIF, JPEG and PNG pictures are supported starting from J2SE 1.3.
-
-Picture in the installer
--------------------------
-
-It is possible to specify an optional picture to display on the left side of the installer. To do this, you just have to define a resource whose id is 'Installer.image'. For instance ::
-
- <res id="Installer.image" src="nice-image.png" />
-
-will do that. If the resource isn't specified, no picture will be displayed at all. GIF, JPEG and PNG pictures are supported starting from J2SE 1.3.
-
-You can also give a specific picture for a specific panel by using the 'Installer.image.n' resource names where is the panel index. For instance if you want a specific picture for the third panel, use 'Installer.image.2' since the indexes start from 0.
-
-Modifying the GUI
-------------------
-
-There are some options to modify the graphic user interface. Most of them are managed with key/value pairs of the element '<modifier>' which will be located in the element '<guiprefs>' in the installation description file.
-
-Modifying Language Selection Dialog
-''''''''''''''''''''''''''''''''''''
-
-Additional to the picture in the language selection dialog it is possible to modify flags and the type of showing the language name. Following different views (without an images to reduce space).
-
-.. figure:: stdLangSel.png
-
- Standard language selection dialog
-
-.. figure:: modLangSel.png
-
- Alternative language selection dialog
-
-* 'useFlags': possible are "yes" or "no". Default is "yes". If it is set to "no", no flag will be displayed in the language selection dialog. For "no" it is recommended to define also 'langDisplayType' other then "iso3".
-* 'langDisplayType': possible are "iso3", "native" and "default". Default is "iso3". With "iso3" the text for a language will be displayed as ISO 639-2:1998 code. With "native" the notation of the language will be used if possible, else the notation of the default locale. Using "default" will be presented the language in the notation of the default locale of the VM.
-
-Modifying IzPack Panels
-''''''''''''''''''''''''
-
-There are some graphic elements and behavior which are prefered by some people and deprecate by other. The following keys are related to the hole installation (all panels).
-
-* 'useButtonIcons': possible are "yes" or "no". Default is "yes". If it is set to "no", all buttons which are created via the ButtonFactory contains no icon also a icon id was submitted. Directly created buttons are not affected.
-
-* 'useLabelIcons': possible are "yes" or "no". Default is "yes". If it is set to "no", all labels which are created via the LabelFactory contains no icon also a icon id was submitted. Directly created labels are not affected.
-
-* 'layoutAnchor':layout anchor for IzPanels. Valid are "NORTH", "NORTHWEST", "SOUTHWEST", "SOUTH" and "CENTER". Only panels which are using the layout helper of IzPanels are supported. These are not all standard panels. At developing custom panels it is recommended to use the layout helper with an IzPanelLayout. Note: The anchor definition will be used for all panels!
-
-* Gaps: there are defined different gaps between different components of a IzPanel if using IzPanelLayout. The gaps can be set also via the element '<modifier>' of '<guiprefs>'. It is possible to declare different values for X and Y axis. This will be determined in the key word name. X Gaps are insert after Y gaps under the control for which the gap was declared. Following key words are defined:
-
- * 'labelXGap | labelYGap': gap in pixel between two labels in X or Y direction.
- * 'textXGap | textYGap': gap in pixel between two text fields.
- * 'controlXGap | controlYGap': gap in pixel between two controls other than label or textfield.
- * 'paragraphYGap': gap in pixel for a pragraph. A paragraph will be created in the panel source for controls which should be separated. paragraphXGap is declared, but not used.
- * 'labelToTextXGap | labelToTextYGap': gap in pixel between a label (left or top) and a text field (right or bottom).
- * 'labelToControlXGap | labelToControlYGap': gap in pixel between a label (left or top) and a control other than a label or a textfield.
- * 'textToLabelXGap | textToLabelYGap': gap in pixel between a text field (left or top) and a label.
- * 'controlToLabelXGap | controlToLabelYGap': gap in pixel between a control other than a label or a text field and a label.
- * 'controlToTextXGap | controlToTextYGap': gap in pixel between a control other than a label or a text field and a text field.
- * 'textToControlXGap | textToControlYGap': gap in pixel between a text field and a control other than a label or a text field .
- * 'firstYGap': gap in pixel between the top border and the first control.
- * 'filler[N]XGap | filler[N]YGap': gap in pixel created by the layout manager. Filler are used by some panels. [N] is a number between 1 and 5 to allow to use different filler e.g. filler3XGap or filler1YGap.
- * 'allXGap | allYGap': gap in pixel between all controls in X or Y direction. If this is declared all gaps for which no own declaration exists gets this value. If a gap has an own declaration this will be used instead.
-
-* 'layoutYStretchType | layoutXStretchType': the IzPanelLayout manager allows to declare stretch factors for controls. This means, that a control will be stratched if there is place in the line. The amount of stretching will be determined by the stretch factor. But what to do if the hole stretch factor for a line or column is not 1.0? To determine this these settings are exist. Valid values are "RELATIVE", "ABSOLUTE" and "NO". With "NO" no stretch will be performed. with "RELATIVE" the values are normalized, with "ABSOLUTE" the values will be used as they are (may be a part will be clipped if the sum is greater than 1.0).
-
-* 'layoutFullLineStretch | layoutFullColumnStretch': as described there are controls which should be stretched. Beside fixed values there are the symbolic values FULL_LINE_STRETCH and FULL_COLUMN_STRETCH which are computed at layouting. E.g. MultiLineLabels has this stretch factor for x direction. But what todo if a centered layout is chosen? With a control like this the lines will be stretch to the hole size. With this settings it can be changed. E.g. a factor of 0.7 creates a nice centered layout. The default is 1.0, valid are 0.0 upto 1.0.
-
-It is possible to use an alternatively frame title. Normaly the title has the aspect "IzPack - Installation of " + '$APP_NAME'. If the langpack key 'installer.reversetitle' is defined, the value of that key will be used instead of the key 'installer.title'. There is no string added, but it is possible to use IzPack variables. The third heading example contains such a alternatively frame title. It is only possible to use predefined variables like '$APP_NAME' because the title will be created before the frame will be shown. It is common to use the name of the installation toolkit in the frame title.
-
-Using a Separated Heading Panel
-''''''''''''''''''''''''''''''''
-
-Some standard panels have headings (e.g. ShortcutPanel). These headings are integrated in the IzPanel. In oposite to this following heading will be displayed in a separated panel potential for all panels with the same design. There is no need to modify existent java classes else declaration of some key/value pairs are enough.
-
-There can be one real head and zero or more info lines. The headline will be written bold, the fontsize can be changed. Info lines will be indented and written with the normal used font. The heading message has to be written into the langpack (or custom langpack) file with the key '<panel class name>.headline'. Examples can be seen in eng.xml. May be the entries for standard panels are not present in other languages. Messages for info lines have the key '<panel class name>.headinfo<info line number>'. First info line has number zero. If no or empty headline messages will be declared in the chosen language no heading panel will be shown. This behavior can be used to suppress heading for special panels.
-
-It is also possible to declare head and info lines additonal dependent on the 'panelid'. The result is, that it is possible to declare different messages for panels which are shown more than one time (e.g. the UserInputPanel. In this case the key for heading is ::
-
- <panel class name>.headline.<panelid>
-
-and for info lines ::
-
- <panel class name>.headinfo<info line number>.<panelid>
-
-Panelids are declared in 'ELEMENT %lt;panel>'. See The Panels Element '<panels>' . The standard strings are declared in the standard langpack file. For customized panels it is common to write the string into the custom langpack (see The Internationalization of custom panels. If (as example) in install.xml was following written: ::
-
- <panels>
- ...
- <panel classname="UserInputPanel" id="one"/>
- <panel classname="UserInputPanel"id="two"/>
- ...
- </panels>
-
-Then the messages can be declared in 'CustomLangpack.xml_eng' like ::
-
- <langpack>
- ...
- <str id="UserInputPanel.headline.one" txt="User Data one"/>
- <str id="UserInputPanel.headline.two" txt="User Data two"/>
- <str id="UserInputPanel.headinfo0.one" txt="Info 1 one"/>
- <str id="UserInputPanel.headinfo1.one" txt="Info 2 one"/>
- <str id="UserInputPanel.headinfo0.two" txt="Info 1 two"/>
- <str id="UserInputPanel.headinfo1.two" txt="Info 2 two"/>
- ...
- <langpack>
-
-It is possible to place an icon on the right side of the heading. To do this a simple resource entry will be needed: ::
-
- <resources>
- ...
- <res id="Heading.image" src="[my path in the source tree]"/>
- ...
- </resources>
-
-There are some guiprefs modifier keys to use and modify heading (see above). Additonal it is possible to count the general not hidden panels in the heading or navigation panel.
-
-* 'useHeadingPanel': general switch for heading. If this key does not exist or does not have the value "yes" no heading panel will be shown.
-* 'useHeadingForSummary': in the language files there are entries for the heading text ('[Panel name].headline') and the summary caption ('[Panel name].summaryCaption'). If this modifier is set to "yes", the text of the heading will be also used for the summary caption.
-* 'headingLineCount': number of heading lines. If no info lines should be shown the value should be one (not zero).
-* 'headingFontSize': a float value used as multiplier for the standard font size.
-* 'headingBackgroundColor': background color of the heading panel as integer. Often used is 0x00ffffff (white).
-* 'headingPanelCounter': draw a panel counting. Possible values are "text" or "progressbar". inHeading the progressbar will be not the best choice.
-* 'headingPanelCounterPos': declares where the counter will be shown. Possible are "inHeading" or "inNavigationPanel". If "inNavigationPanel" is chosen, the panel counter can be used also no heading was selected.
-
-.. figure:: stdTargetPanel.jpg
-
- Normal look of an IzPack frame (TargetPanel)
-
-Key/value pairs to create IzPack installation with heading, no button and label icons and a panel text counter in the heading panel. ::
-
- <guiprefs width="600" height="480" resizable="no">
- <modifier key="useButtonIcons" value="no"/>
- <modifier key="useLabelIcons" value="no"/>
- <modifier key="labelGap" value="2"/>
- <modifier key="layoutAnchor" value="NORTHWEST"/>
- <modifier key="useHeadingPanel" value="yes"/>
- <modifier key="headingLineCount" value="1"/>
- <modifier key="headingFontSize" value="1.5"/>
- <modifier key="headingBackgroundColor" value="0x00ffffff"/>
- <modifier key="headingPanelCounter" value="text"/>
- <modifier key="headingPanelCounterPos" value="inHeading"/>
- </guiprefs>
-
-.. figure:: modTargetPanel3.png
-
- IzPack frame (TargetPanel) with heading panel and a text counter in the heading panel with panel image.
-
-Changed resources and langpack keys to create IzPack installation with alternatively frame title, heading, no button and label icons and a text counter in the heading panel.
-
-In install.xml ::
-
- <installation version="1.0">
- ...
- <resources>
- ...
- <res src="border4.png" id="Installer.image.3"/> REMOVED
- ...
- </resources>
- </installation>
-
-Add in '<ISO3>.xml' or 'CustomLangpack.xml_<ISO3>' ::
-
- <langpack>
- ...
- <str id="installer.reversetitle" txt="$APP_NAME $APP_VER - IzPack Wizard "/>
- ...
- </langpack>
-
-.. figure:: modTargetPanel.png
-
- IzPack frame (TargetPanel) with heading panel and a text counter in the heading panel with alternative frame title, no panel image.
-
-Changed key/value pairs to create IzPack installation with heading, no button and label icons and a panel progressbar counter in the navigation panel.
-
-Key/value pairs for modifying IzPack GUI (references for panel images removed): ::
-
- <guiprefs width="640" height="480" resizable="no">
- <modifier key="useButtonIcons" value="no"/>
- <modifier key="useLabelIcons" value="no"/>
- <modifier key="layoutAnchor" value="NORTHWEST"/>
- <modifier key="labelGap" value="2"/>
- <modifier key="useHeadingPanel" value="yes"/>
- <modifier key="headingLineCount" value="1"/>
- <modifier key="headingFontSize" value="1.5"/>
- <modifier key="headingBackgroundColor" value="0x00ffffff"/>
- <modifier key="headingPanelCounter" value="progressbar"/>
- <modifier key="headingPanelCounterPos" value="inNavigationPanel"/>
- </guiprefs>
-
-.. figure:: modTargetPanel2.png
-
- IzPack frame (TargetPanel) with heading panel and a progressbar counter in the navigation panel without panel image.
-
-Alternative Cancel Dialog
-''''''''''''''''''''''''''
-
-The cancel dialog will be shown if the cancel button or the close button of the frame was pushed. In the standard dialog the title contains the question and the message an affirmation. In other dialogs often the title is a common heading and the question will be called in the dialog as message. The standard behavior will be modified if the messages 'installer.quit.reversemessage' and 'installer.quit.reversetitleare' declared.
-
-Add in '<ISO3>.xml' or 'CustomLangpack.xml_<ISO3>' ::
-
- <langpack>
- ...
- <str id="installer.quit.reversemessage" txt="Are you sure you want to cancel installation?"/>
- <str id="installer.quit.reversetitle" txt="$APP_NAME $APP_VER"/>
- ...
- </langpack>
-
-.. figure:: normQuitDialog.png
-
- Standard cancel dialog.
-
-.. figure:: revQuitDialog.png
-
- Alternative cancel dialog.
-
-Logging the Installation
--------------------------
-
- Logging was made as coproduct at implementing other features. There was no common design for it. Therefor there is no one way to made logging of any kind else for each group a different logging stuff exist. Not nice, but reality.
-
-1. Debug Informations
-
- There is a rudimental debug stuff in IzPack. The class 'com.izforge.IzPack.util.Debug' is used by some other classes to write debug informations on 'stdout'. The class can be used by custom panels or actions or other custom classes. To activate it, add '-DTRACE=TRUE' in front of '-jar' of the installer call.
-
-2. Summary of Panels
-
- There is a summary panel which shows some informations of previous shown panels. The same contents can be written to a summary log file.
-
-3. Logging of Installed File Set
-
- The files which are installed are logged into the uninstaller jar file to be used at uninstallation. The contents can be also duplicated into a logfile.
-
-4. Logging of the Process Panel
-
- The process panel logs informations of each performed process in a scrollable text area. The contents can be duplicated into a logfile where the used directory can be selected (but not the logfile name).
-
-5. Logging of Ant Actions
-
- It is possible to perform ant actions with the 'AntActionInstallerListener'. The grade of logging and the path of a logfile can by determined.
-
-Web Installers
----------------
-
-The web installers allow your users to download a small installer that does not contain the files to install. These files will be downloaded from an HttP server such as Apache HTTPD. If you have many optional packs, this can save people's resources. Its very easy: people download a small Jar file containing the installer, they launch it and choose their packages. Then the installer will get the required packages from individual Jar files located on a server, only downloading those required. It's that simple.
-
-To create a web installer, add the '<webdir>' element to the <info> element. The text must be a valid, fully qualified URL for a directory on the web server. ::
-
- <info>
- <appname>Super extractor</appname>
- <appversion>2.1 beta 6</appversion>
- <url>http://www.superextractor.com/</url>
- <webdir>http://www.superextractor.com/download</url>
- </info>
-
-You can force creation of a standard installer even if 'webdir' is specified, by specifically creating a standard installer from the command line invocation or ant task.
-
-When installing, if the user is behind a firewall, attempting download the jar files may fail. If this happens, the user will be prompted to enter the name host name and port of their firewall.
-
-You may password protect the files using mechanisms provided by your web server, IzPack will prompt for a password at install time, when required.
-
-More Internationalization
---------------------------
-
-Special resources
-''''''''''''''''''
-
-IzPack is available in several languages. However you might want to internationalize some additional parts of your installer. In particular you might want this for the 'InfoPanel' and 'LicencePanel'. This is actually pretty easy to do. You just have to add one resource per localization, suffixed with the ISO3 language code. At runtime these panels will try to load a localized version.
-
-For instance let's suppose that we use a 'HtmlInfoPanel'. Suppose that we have it in English, French and German. We want to have a French text for french users. Here we add a resource pointing to the French text whose name is 'HtmlInfoPanel.info_fra'. And that's it! English and German users (or anywhere other than in France) will get the default text (denoted by 'HtmlInfoPanel.info') and the French users will get the French version. Same thing for the other Licence and Info panels.
-
-To sum up: add '_<iso3 code>' to the resource name for 'InfoPanel', 'HtmlInfoPanel', 'LicencePanel' and 'HtmlLicencePanel'.
-
-Packs
-''''''
-
-Thanks to Thorsten Kamann, it is possible to translate the packs names and descriptions. To do that, you have to define a special identifier in the elements of the XML installation file and add the related entries in the suitable langpacks. For instance if you have the following XML snippet: ::
-
- <pack name="core" id="core.package" ...>
- <description/>
- </pack>
-
-then the related entries of the langpacks will look like this: ::
-
- <str id="core.package" txt="Core Package"/>
- <str id="core.package.description" txt="The core package provides
Deleted: izpack-src/trunk/src/doc-reST/node6.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node6.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node6.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,1027 +0,0 @@
-Desktop Shortcuts
-=================
-
-(by Elmar GROM and Marc EPPELMANN)
-
-Defining Shortcuts
-------------------
-
-
-Introduction
-'''''''''''''
-
-On todays GUI oriented operating systems, users are used to launching
-applications, view web sites, look at documentation and perform a variety of
-other tasks, by simply clicking on an icon on the desktop or in a menu system
-located on the desktop. Depending on the operating system these icons have
-different names. In this context we will refer to them collectively as
-shortcuts.
-
-
-Apart from actually placing an application on the target system, users
-routinely expect an installer to create the necessary shortcuts for the
-application as well. For you as application developer, this means that for a
-professional appearance of your product you should also consider creating
-shortcuts.
-
-
-In contrast to the general specification of an IzPack installer, the
-specification of shortcuts in IzPack requires a little more effort. In
-addition, some of the concepts are a bit more complex and there are some
-operating system specific issues to observe. Fortunately, you only need to
-worry about operating system specifics if you want to deploy your application
-to multiple different operating systems. In any case, it will pay off to
-spend some time to study this documentation and the example spec files before
-you start to implement your own shortcuts.
-
-
-At the time of writing this Chapter the current IzPack Version 3.7.0-M3 is
-only capable to creating shortcuts on
-
-1. Microsoft Windows, and
-2. Unix and Unix-based operating systems (like Linux), which use the
- `X11` GUI-System and ` FreeDesktop.org` based shortcut handling (such
- as `KDE` and `Gnome`).
-
-Other operating or GUI systems, such as MacOS X are not
-supported. However, there is a special UI-variant that automatically pops up
-on unsupported systems. It informs the user about the intended targets of
-your shortcuts and allows the user to save this information to a text file.
-While this is not an elegant solution, at least it aids the user in the
-manual creation of the shortcuts.
-
-
-If you would like to review what an end user would see if the target
-operating system is not supported, you can do the following. Simply place the
-tag ``<notSupported/>`` in the spec file. This tag requires no attributes or
-other data. It must be placed under ``<shortcuts>``, just like the individual
-shortcut specifications. Be sure to remove this tag before getting your
-application ready for shipment.
-
-
-We expect other operating systems to be supported in the near future and as
-always, contributions are very welcome. At present someone is actively
-working on Mac support.
-
-
-What to Add to the Installer
-'''''''''''''''''''''''''''''
-
-There are some things that you have to add to your installer to enable
-shortcut creation. Obviously you need to add the panel responsible for
-creating shortcuts. This panel is aptly enough called ShortcutPanel. However,
-in order for the ShortcutPanel to work properly a number of additional items
-are required. These must be added manually to the installer, as all other
-resourcs, since the front-end will be rewritten. In this chapter we will
-explain which of these items are required and for what reason.
-
-
-First, we would like to discuss items that are supplied with IzPack and only
-need to be added to the installer. After that, we move on to the things you
-have to prepare yourself before you can add them. The way in which shortcuts
-are created varies widely among operating systems. In some cases it is
-possible to do this with pure Java code, while other systems -such as MS-
-Windows- require native code to accomplish this task. On the other side, the
-current implementation, which creates shortcuts on Unix based systems needs
-no native library at all, since it works with 'these' pure Java code. The
-native library required for the Windows operating systems are supplied with
-IzPack is called ``ShellLink.dll``. Note: They will not be automatically
-added to your installer file. You need to list them yourself in the XML file
-for the installer. A describtion how to do this follows in the next section.
-
-
-Native libraries can be added to the installer by using the ``<native>`` tag.
-To add the ``ShellLink.dll``, you just have to add the following line to the
-installer XML file:
-``<native type="izpack" name="ShellLink.dll"/>``
-For more details about the use of the ``<native>`` tag see the chapter about
-the format of the XML file.
-
-
-You have also to add an extra specification file for each platform family to
-enable shortcut creation on these platforms. At least one (the default file)
-is required by the shortcut panel. The format of all spec files is XML and
-they must be added to the installer as a resource. The source name of this
-specification does not matter, however its resource name (also called id or
-alias) when added to the installer must be ``(prefix)+shortcutSpec.xml``.
-At this release, there are only two prefixes supported: "Win" for the
-Windows family and "Unix" for all Unixes. If the prefix is ommited the
-shortcut panel searches for a named resource: `` shortcutSpec.xml``. This is
-the default resource name. As the default resource name will be used on
-Windows platforms, the ``"Win_shortcutSpec.xml"`` can be ommited.
-Hint: If the shortcut panel does not find one of these named resources, it
-will never appears. So, do not use different resource names and do not add a
-path to these.
-
-
-**Example**
-
-
-::
-
- <res src="C:\MyDocuments\Installer\default_shortcut_specification.xml"
- id="shortcutSpec.xml"/>
- <res src="C:\MyDocuments\Installer\unix_shortcut_specification.xml"
- id="Unix_shortcutSpec.xml"/>
-
-
-Why use different shortcut spec files?
-
-
-1. The Target filenames are most different.(batch files on Windows vs.
- shell scripts on Unix.)
-2. The Icon file formats are different. ICOs on Windows-, PNGs on Unix-
- platforms.
-3. The Target locations can be different.
-
-This is the simple reason.
-
-
-
-Why Native Code to do the Job on Windows?
------------------------------------------
-
-by Elmar
-
-
-This little chapter is not strictly part of the documentation but i have been
-asked this question sufficiently often that i think it's worth explaining
-right here. It is certainly a natural question to ask. After all IzPack is an
-application completely written in Java and primarily targeted for the
-installation of Java based programs. So why wouldn't we try to keep
-everything pure Java and avoid the use of native code altogether? There must
-be some personal preference of the developer hidden behind this approach you
-might think. Well, not really, but i admit at first it seems quite feasible
-to write it all in Java. On virtually any operating system or GUI surface
-around, Shortcuts are simply files on the local file system. Files can be
-created and accessed directly from within Java, so why should there be a need
-for using native code?
-
-
-Well, it turns out that just creating a file is not good enough, it also
-needs to have the right content. Shell Links as they are called in Windows
-land are binary files. i actually managed to find documentation on the
-format. Naturally this was hacker data, you won't get this sort of thing from
-Microsoft (by the way: thanks a lot to Jesse Hager for a smash job!). Armed
-with this information i tried to create these files myself in Java. The
-problem was that the documentation was not entirely accurate and had some
-gaps as well. i tried for over a month to get this to work but finally i had
-to give up. Even if i would have succeeded, it would have been a hack, since
-a shell link requires some information that is impossible to obtain from
-within Java. Usually you can successfully create a shell link by only filling
-in the bare minimum information and then ask Windows to resolve the link.
-Windows then repairs the shell link. Unfortunately this was only the
-beginning, soon i encountered a host of other problems. For one thing, the
-installer needs to know the correct directories for placing the links and it
-turns out they are named differently in different countries. In addition,
-there are ways of manually modifying them, which some people might actually
-have done. The only way to place the shortcut files reliably is through
-accessing the Windows Registry. Naturally, this operation also required
-native code. Same thing with asking Windows to resolve the link... On the
-bottom line, at every step and turn you run into an issue where you just need
-to use native code to do the trick. So i decided that i would do it the
-proper way all the way through. That is in a nutshell the reason why i used
-native code to create shortcuts on MS-Windows.
-
-
-As i am writing this i am at work with a friend to replicate this work for
-the Mac and it looks very much like we need to take the same approach there
-as well. On the various Unix GUIs on the other hand, we are lucky that we can
-do the job without native libraries.
-
-
-
-The Shortcut Specification
---------------------------
-
-As we say above, the specification for shortcuts is provided to the
-ShortcutPanel in the XML fileformat. At the time of this writing (for IzPack
-version 3.7.0-M3) the front-end will be rewritten. Until these work is in
-progress you have to write the specification files manually. For your
-convenience, there are two annotated sample specification files in the sample
-subdirectory of your IzPack installation. At the beginning you might want to
-experiment with these files.
-
-
-Both specification files have one root element called ``<shortcuts>``. This
-root elements recognizes 3 different child elements:
-``<programGroup>``, ``<skipIfNotSupported/>`` and ``<shortcut>``.
-
-
-``<skipIfNotSupported/>`` can be used to avoid the panel to show the
-alternative UI which shows the shortcut information that would have been
-created on a system that supports it. In other words, using this tag will
-make the panel be silent on non-supported systems. The default is to show the
-alternative UI.
-
-
-The ``<programGroup>`` tag allows you to specify the name of the menu, or
-more precise, the folder in which the shortcuts will be grouped. The exact
-location and appearance of the program group depends on the specific target
-system on which the application will be installed, however you can partially
-control it. Please note that ``<programGroup>`` may only appear once in the
-specification. If more than one instance occurs, only the first one will be
-used. This tag requires two attributes: ``defaultName`` and ``location``.
-``defaultName`` specifies the name that the group menu should have on the
-target system. You should be aware that the ShortcutPanel will present this
-name to the user as a choice. The user can then edit this name or select a
-group that already exists. As a result, there is no guarantee that the actual
-name of the program group on the target system is identical with your
-specification. ``location`` specifies where the group menu should show up.
-There are two choices: ``applications`` and ``startMenu``. If you use
-``applications``, then the menu will be placed in the menu that is ordinarily
-used for application shortcuts. ``applications`` is recommended for Unix
-shortcuts. If you use ``startMenu``, the group menu will be placed at the top
-most menu level available on the target system. Depending on the target
-system, it might not be possible to honor this specification exactly. In such
-cases, the ShortcutPanel will map the choice to the location that most
-closely resembles your choice. Unix shortcuts do not need to support the
-``startMenu``, because the ``applications`` menu is already on the highest
-level. This means this has no affect on thess platform.
-
-
-For each shortcut you want to create, you have to add one ``<shortcut>`` tag.
-Most details about the shortcut are listed as attributes with this tag. The
-following sections describe what each attribute does, which attributes are
-optional and which ones are required and what the values are that are
-accepted for each of the attributes. Note that all attributes that have a
-yes/no choice can also be omitted. Doing so has the same effect as using a
-value of no. The shortcut attributes can be divided into two groups
-
-
-- attributes that describe properties of the shortcut
-- attributes that define the location(s) at which a copy of the
- shortcut should be placed.
-
-The following attributes are used to define location:
-
-- ``programGroup``
-- ``desktop``
-- ``applications``
-- ``startMenu``
-- ``startup``
-
-
-Shortcut Attributes
--------------------
-
-There are three classes of attributes. Some are required, most are completely
-optional and some are semi-optional. The set of semi-optional attributes are
-all the attributes used to define the location of a shortcut. These are semi-
-optional because for any individual one it is your choice if you want to
-include it or not. However they are not completely optional. You must specify
-at least one location. If all were omitted, the instruction would essentially
-tell the panel that a copy of this shortcut is to be placed at no location.
-In other words no copy is to be placed anywhere.
-
-**name** ``- required``
-
-
-The value of this attribute defines the name that the shortcut will have.
-This is the text that makes up the menu name if the shortcut is placed in a
-menu or the caption that is displayed with the shortcut if it is placed on
-the desktop.
-
-
-**target** ``- required``
-
-
-The value of this attribute points to the application that should be launched
-when the shortcut is clicked. The value is translated through the variable
-substitutor. Therefore variables such as ``$INSTALL_PATH`` can be used to
-describe the location. **You should be aware that the use of this tag is
-likely to change once other operating systems are supported**.
-
-
-**commandLine** ``- optional``
-
-
-The value of this attribute will be passed to the application as command
-line. i recommend to work without command line arguments, since these are not
-supported by all operating systems. As a result, your applications will not
-be portable if they depend on command line arguments. Instead, consider using
-system properties or configuration files.
-
-
-**workingDirectory** ``- optional``
-
-
-This attribute defines the working directory for the application at the time
-it is launched. i would recommend some caution in relying on this too heavily
-if your application should be portable, since this might not be supported by
-all operating systems. At this time i don't have enough information to make a
-definite statement one way or the other. The value is translated through the
-variable substitutor. Therefore variables such as ``$INSTALL_PATH`` can be
-used to describe the directory.
-
-
-**description** ``- optional``
-
-
-The value of this attribute will be visible to the user when a brief
-description about associated application is requested. The form of the
-request and the way in which this description is displayed varies between
-operating systems. On MS-Windows the description is shown as a tool tip when
-the mouse cursor hovers over the icon for a few seconds. On some operating
-systems this feature might not be supported but i think it is always a good
-idea to include a brief description.
-
-
-**iconFile** ``- optional``
-
-
-The value of this attribute points to the file that holds the icon that
-should be displayed as a symbol for this shortcut. This value is also
-translated through the variable substitutor and consequently can contain
-variables such as $INSTALL_PATH. If this attribute is omitted, no icon will
-be specified for the shortcut. Usually this causes the OS to display an OS
-supplied default icon. **The use of this attribute is also likely to change
-once other operating systems are supported. Read the Section about Icons
-below, for more information.**
-
-
-**iconIndex** ``- optional``
-
-
-If the file type for the icon supports multiple icons in one file, then this
-attribute may be used to specify the correct index for the icon. i would also
-advise against using this feature, because of operating system
-incompatibilities in this area. In file formats that do not support multiple
-icons, this values is ignored.
-
-
-**initialState** ``- optional``
-
-
-There are four values accepted for this attribute: ``noShow``, ``normal``,
-``maximized`` and ``minimized``. If the target operating system supports this
-feature, then this value will have the appropriate influence on the initial
-window state of the application. ``noShow`` is particularly useful when
-launch scripts are used that cause a command window to open, because the
-command window will not be visible with this option. For instance on MS-
-Windows starting a batch file that launches a Java application has the less
-than pretty side effect that two windows show: the DOS command prompt and the
-Java application window. Even if the shortcut is configured to show
-minimized, there are buttons for both windows in the task bar. Using
-``noShow`` will completely eliminate this effect, only the Java application
-window will be visible. *On Unix use* ``normal`` *, because this is not
-supported*.
-
-
-**programGroup** ``- semi-optional``
-
-
-The value for this attribute can be either yes or no. Any other value will be
-interpreted as no. If the value is yes, then a copy of this shortcut will be
-placed in the group menu. *On Unix (KDE) this will always be placed on the
-top level.*
-
-
-**desktop** ``- semi-optional``
-
-
-For this attribute the value should also be yes or no. If the value is yes,
-then a copy of the shortcut is placed on the desktop. *On Unix the shortcuts
-will only be placed on the (KDE-) desktop of the user, who currently runs the
-installer. For Gnome the user can simply copy the *.desktop files from*
-``/Desktop`` *to* ``/gnome-desktop``. (This is already a TODO for the Unix-
-shortcut implementation.)
-
-
-**applications** ``- semi-optional``
-
-
-This is also a yes/no attribute. If the value is yes, then a copy of the
-shortcut is placed in the applications menu (if the target operating system
-supports this). This is the same location as the applications choice for the
-program group. *This makes no sense on Unix.*
-
-
-**startMenu** ``- semi-optional``
-
-
-This is a yes/no attribute as well. If the value is yes, then a copy of the
-shortcut is placed directly in the top most menu that is available for
-placing application shortcuts. *This is not supported on Unix. see above.*
-
-
-**startup** ``- semi-optional``
-
-
-This is also a yes/no attribute. If the value is yes, then a copy of the
-shortcut is placed in a location where all applications get automatically
-started at OS launch time, if this is available on the target OS. *This is
-also not supported on Unix.*
-
-
-
-Unix specific shortcut attributes
-----------------------------------
-
-This extension was programmed by MARC EPPELMANN. This is still in development
-and may be changed in one of the next releases of IzPack.
-
-
-**type** ``- required``
-
-
-This must be one of ``Application`` or ``Link``
-
-
-- Application: To start any application, native, Java or shell-script
- based, the **type** has to be ``Application``. The GUI-System will launch
- this Application, so as is, thru their native shell or application
- launcher. In this case, note that the right ``workingDirectory`` is
- always important on Unix platforms. If the users PATH environment
- variable does not contain the path, where the application is located,
- this can never be run, until the ``workingDirectory`` does not contain
- these path. The needed current path: ".", this is the case on most
- systems, should be in the users PATH environment variable. Consult the
- Unix manuals for more details.
-- Link: If you want to open a URL in the users default Webbrowser, you
- have to set the **type** to ``Link``. Note: The ``url`` attribute must be
- set to work properly.
-- Other: There are more supported types on KDE, like FSDevice, but
- these types makes no sense for IzPack, in my opinion.
-
-Without the type the Unix shortcut does not work.
-
-
-**url** ``- semi-optional``
-
-
-If you want to create a shortcut as type *Link*, then you have to set the
-``url`` attribute. The value can be a locally installed html or another
-document, with a known MIME type, like plain text, or a WWW Url i.e.
-'https://izpack.github.io/'.
-
-
-A local document can be referenced by i.e. "$INSTALL_PATH/doc/index.html".
-
-
-The IzPack variable substitution system is supported by the **url**.
-
-
-**encoding** ``- required``
-
-
-This should always set to **UTF-8**.
-
-
-**terminal** ``- optional``
-
-
-If you want, the user can see the console output of a program (in Java
-applications "System.outs"), set the ``terminal`` attribute to **true**.
-
-
-**KdeSubstUID** ``- unused``
-
-
-This is not fully implemented by IzPack. i the future this is the sudo option
-for a shortcut.
-
-
-
-Selective Creation of Shortcuts
--------------------------------
-
-Usually all shortcuts that are listed will be created when the user clicks
-the 'Next' button. However it is possible to control to some degree if
-specific shortcuts should be created or not. This is based on install
-conditions. By including one or more ``<createForPack name=''a pack name''
-/>`` tags in the specification for a shortcut, you can direct the
-ShortcutPanel to create the shortcut only if any of the listed packs are
-actually installed. The 'name' attribute is used to define the name of one of
-the packs for which the shortcut should be created. You do not need to list
-all packs if a shortcut should always be created. In this case simply omit
-this tag altogether.
-
-
-**A word of caution**
-
-
-For any shortcut that is always created, i would recommend to omit this tag,
-since i have seen a number of problems related to changing pack names. You
-can save yourself some troubleshooting and some Aspirin by not using this
-feature if it's not required. On the other hand if you need it i would advise
-to be very careful about changing pack names.
-
-
-
-DesktopShortcutCheckboxEnabled Builtin Variable
------------------------------------------------
-
-``$DesktopShortcutCheckboxEnabled`` : When set to true, it automatically
-checks the "Create Desktop Shortcuts" button. To see how to use it, go to
-`The Variables Element ``<variables>``
-
-Be careful this variable is case sensitve !
-
-
-Summary
--------
-
-**Native Libraries**
-
-- ShellLink.dll ``- required by Microsoft Windows``
-- 'Nothing' ``- for KDE/Gnome shortcuts``
-
-**Names of the Specification Files**
-``shortcutSpec.xml`` for Windows and as default.
-``Unix_shortcutSpec.xml`` for Unix.
-
-
-**Specification File Layout - Windows**
-
-::
-
- <shortcuts>
- <skipIfNotSupported/>
- <programGroup defaultName="MyOrganization\MyApplication"
- location="applications||startMenu"/>
- <shortcut
- name="Start MyApplication"
- target="$INSTALL_PATH\Path\to\MyApplication\launcher.bat"
- commandLine=""
- workingDirectory="$INSTALL_PATH\Path\to\MyApplication"
- description="This starts MyApplication"
- iconFile="$INSTALL_PATH\Path\to\MyApplication\Icons\start.ico"
- iconIndex="0"
- initialState="noShow||normal||maximized||minimized"
- programGroup="yes||no"
- desktop="yes||no"
- applications="yes||no"
- startMenu="yes||no"
- startup="yes||no">
-
- <createForPack name="MyApplication Binaries"/>
- <createForPack name="MyApplication Batchfiles"/>
- </shortcut>
- </shortcuts>
-
-
-**A sample Specification File for Unix is at the end of this chapter**
-
-
-Shortcut Tips
--------------
-
-I wrote this section to provide additional information about issues
-surrounding the creation of shortcuts. Reading this section is not necessary
-to successfully create shortcuts, but it might help you creating an
-installation that works more smoothly. In addition, it might give you some
-knowledge about operating systems that you don't know so well. In fact most
-of the issues described in this section are focused on differences in
-operating system specifics.
-
-
-The Desktop
-'''''''''''
-
-You should recognize that the desktop is precious real estate for many
-people. They like to keep it uncluttered and keep only the things there that
-they use on a regular basis. This is not true for everybody and you might
-personally think different about this. Still, the fact remains that a lot of
-people might have different feelings about it, so you should not
-automatically assume that it is ok to place all of your shortcuts on the
-desktop proper. While your application is certainly one of the most important
-things for you, for your customers it is probably one of many applications
-they use and maybe not even the most important one. Accordingly, placing more
-shortcut icons there than they feel they will use on a regular basis and
-especially doing this without asking for permission might trigger some bad
-temper.
-
-
-Annotation: But even the experienced user should be able to organize their
-Desktop. On Linux the users desktop is the only place, which supports any
-kind of shortcuts.
-
-
-It is common practice to create a program group in the application menu
-system of the OS and place all shortcuts that go with an application in that
-program group. In addition, only one shortcut to the key access point of the
-application is placed directly on the desktop. Many installers first ask for
-permission to do so, as does the ShortcutPanel in IzPack.
-
-
-I would like to recommend that you always create a shortcut in the menu
-system, even if your application has only one access point and you are
-placing this on the desktop. Note that shortcuts can also be placed directly
-in the menu, they don't need to be in a program group. There are two reasons
-for doing so.
-
-
-- If the user elects not to create shortcuts on the desktop, they will
- end up with no access point to your application
-- Even if this works fine, occasionally people 'clean up' their
- desktop. They might later find that they accidentally deleted the only
- access point to your application. For the less technology savvy users,
- recreating the shortcut might be a rough experience.
-
-
-Icons
-''''''
-
-Icons are supplied in image files, usually in some kind of bitmap format.
-Unfortunately there is no format that is universally recognized by all
-operating systems. If you would like to create shortcuts on a variety of
-operating systems that use your own icons, you must supply each icon in a
-number of different formats. This chapter discusses icon file formats used on
-various operating systems. Fortunately there are good programs available that
-allow you to convert between these formats, so that creating the different
-files is not much of a problem once the icons themselves are created.
-
-
-**Microsoft Windows**
-
-
-Windows prefers to use its native icon file format. Files of this type
-usually use the extension .ico. These so called ICO files can hold multiple
-icons in one file, which can be useful if the same icon is to be provided in
-a number of sizes and color-depths.
-
-Windows itself selects the icon with the most matching dimensions and
-displays it. While the Start menu displays the icon with 16x16 pixel if
-available, the desktop displays the 32x32 pixel resolution of the same ICO if
-this is in.
-
-In other words, a ICO file has embedded one or more dimensions of the same
-Icon. We recommend to play with `microangelo`.
-
-Dlls and Exe files on the other side, can store, amongst other things, a
-collection of different Icons. You can select your desired Icon by its index.
-The lowest index is 0. Use the iconIndex attribute in the spec file to
-specify this index.
-
-
-As a sample look into
-
-::
-
- %SystemRoot%\system32\shell32.dll
-
-
-These contains a lot of Windows own icons. You can use the `PE Explorer` or
-another Resource Editor to extract or modify Icons in dlls or exe files. But
-be warned. You can also destroy a working application with these kind of
-tools.
-
-At least Windows also supports the use of bitmap files in the .bmp format as
-icons. Note that this format does not support multiple icons.
-
-
-We might have overlooked other file formats that are supported by Windows.
-However, we suggest to test other formats for compatibility as they might not
-work all the way back to Windows 95 or on the NT/non-NT strain. Sticking with
-one of these two formats should keep you out of trouble.
-
-
-**Apple**
-
-
-Apple Macintosh systems use the Macintosh PICT format, extension .pct. If
-you are working with an apple system you know a whole lot more about this
-format than i do. If you don't but would like to be able to install your
-application on a Mac, simply start with any bitmap format that you feel
-comfortable to work with. Then find an application that is capable of
-converting this format into a .pct file. i like to use Paint Shop Pro (PC
-based), because it provides conversion capabilities among several dozen
-different file formats.
-
-
-**UNIX flavors**
-
-
-by Marc Eppelmann
-
-
-As my knowledge, all X based Unix Window systems supports the (ASCII-) XBM
-(X-Bitmap ) and the better XPM (X-PixMap) format. The modern GUI systems like
-KDE and Gnome can display additionally a lot of other ImageIcon formats, such
-as GIF, JPG, and PNG.
-
-
-i suggest to use PNG, because this can lossless compress like the GIF format,
-however this format is absolutely free. And not least, this can store true
-transparency informations (It has an alpha channel).
-
-
-Targets
-''''''''
-
-So, you thought you could escape the ugly mess of operating system
-dependencies at least with the way how your Java application is started?
-Sorry but i have just another bad message. The one positive thing is that
-here you have a way of escaping, even if doing so has a few less pretty side
-effects. At first, i would like to discuss various launching options you have
-available on different operating systems. At the end of the chapter i write
-about a way to make launching your application OS independent.
-
-
-**Microsoft Windows**
-
-
-On Microsoft Windows you have a variety of options for launching your
-application. Probably the most simple case is directly starting the Java VM
-from the command line and typing out all parameters, such as class path, the
-class name etc. In principle, this can be placed right in a shortcut and
-should work.
-
-
-A little more elegant solution is to place this in a batch file and have the
-shortcut point to this batch file. This will also make it more likely that
-users can repair or recreate shortcuts. Recreating shortcuts with
-sophisticated command lines is practically impossible.
-
-
-Another method is less commonly used but just as possible. Implement a native
-executable that launches the VM with your Java application. The VM comes as
-DLL and is used by java.exe in just the same way. As a sample look at the
-exlipse.exe provided by the `Eclipse-IDE`
-
-
-Clearly, even though the first option is a bit ugly and has some
-restrictionss, it is the most portable solution among the three.
-
-
-**Apple**
-
-
-We hope, there is a IzPack developer currently researching for the details
-for the Mac environment. We expect an updated chapter in one of the next
-releases.
-
-
-**UNIX**
-
-
-UNIX provides essentially the same options as Windows. You can simply use the
-command line option, you can write a shell script and you can write a native
-launcher. Naturally this stuff is in no way compatible with the equivalent
-Windows implementations. The native option is even more problematic in this
-environment, since the code can not even be moved from one UNIX platform to
-another, without recompilation.
-
-
-**OS Independent Launching**
-
-
-So, after all this rather discouraging news, there is actually a portable way
-to launch Java applications? You bet! although i have to admit that it is not
-necessarily the most pretty way of doing things.
-
-
-This approach is currently used by IzPack. Package your application in a
-.jar file if you don't already do so and make it executable by including the
-necessary metaINF/MANIFEST.MF information file. i am not going into all the
-details on how exactly to do this, the Java documentation will have to do.
-You might have noticed that even though the instructions to install IzPack
-say to type :
-
-::
-
- java -jar IzPack-install.jar
-
-
-You can just as well double click on IzPack-install.jar and it will start up.
-This procedure will work on all GUI based Java supported operating systems
--though you might have to replace double clicking with dropping the file on
-the VM. In just the same way, you can make the .jar file itself the target
-of a shortcut. Note: This works only, if jars are registered as files, which
-have to launch by the installed JRE (with: javaw.exe -jar)
-
-
-The one restriction with this approach is that a .jar file can only have one
-main file. So, if you have multiple targets, they need to be packaged each
-into a different .jar file. They can be in one .jar file but then you have
-to start them explicitly, which gets you back to the problems that i
-mentioned before. This brings me to the ugly part. If you have just one
-target, then you are all set. If you have multiple targets, you need to
-create a .jar file for each of them. In addition, you have a much harder
-time setting the classpath, because each of the .jar files that contain
-supporting code must be listed. In fact, at present there is no way of
-setting this during the installation, because IzPack does not yet (version
-3.0) support the setting and modification of environment variables.
-
-
-
-Command Line
-------------
-
-Before i start to write a lot about the use of command line arguments let me
-state this: If you can avoid using them, do it! Not that there is anything
-wrong with command line arguments as such. The issue is simply that if you
-want your application to be usable cross platform (the big Java promise) you
-should shy away from using command line arguments. The problem here is that
-not all operating systems actually support command line arguments. To be more
-precise, to my knowledge only Apple operating systems do not support command
-line parameters. If you don't care for running your application on a Mac,
-then you might not worry about his at all. If you are interested to support
-the Mac as well, read on.
-
-
-In fact the Mac lower than MacOSX supports command line parameters in a way.
-More to the point, it supports a single parameter that your application
-should interpret as the name of a data file to open. You have no way of
-supplying this to your application through the command line attribute. The
-operating system generates this when the user drops the file on your
-application and then passes it as command line argument. That's it. This same
-behavior will probably fly well on pretty much any system and should
-therefore be an ok implementation.
-
-
-So what to do if you want to modify program behavior based on runtime
-switches? For one thing, you could set system properties accordingly. The
-disadvantage here is the same as with the command line parameters: the way of
-setting these might vary between operating systems. The best way seems to be
-using a property file that contains the configuration data.
-
-
-
-Trouble Shooting
------------------
-
-by Elmar
-
-It has been some time since i wrote this chapter during which a good number
-of users had a chance to gather experience. Unfortunately i never know how
-many have used it successfully without much difficulty. i only hear from
-those that have encountered one problem or another. The type of problems that
-i have seen prompted me to write this section, because i think it will help
-you in locating most problems that you might encounter or at least give you
-some idea where the problem might be located.
-
-
-
-Problems You Can Solve
-'''''''''''''''''''''''
-
-If you see an exception that essentially says that a library can not be
-loaded (ShellLink.dll) you have an easy problem to deal with. Your installer
-file is probably missing the native tag that adds the Windows dll to the
-installer or something with this tag is no quite right. Read 'What to Add to
-the Installer' for all details on this topic.
-
-
-Most other problems cause the ShortcutPanel not to show at all during the
-installation process. The reason is simply that the ShortcutPanel skips if it
-does not know what to do or if it has nothing to do (no point showing then
-and confusing the user). The problem is that this is not always what you
-intended. The most simple but not so uncommon case is, that the ShortcutPanel
-cannot find their spec file. This can be caused by a number of reasons. The
-associated resource tag might be missing in the installer specification file,
-the target file name might be misspelled (the name you specify for the ``id``
-attribute) or the target file name has a path or package name pre-pended. You
-have only to use ``shortcutSpec.xml`` or ``Unix_shortcutSpec.xml`` and
-nothing else, just as described in 'What to Add to the Installer'. You can
-always verify if this part is ok by inspecting the content of the installer
-.jar file. The file shortcutSpec.xml should be located in the directory
-``res``. This inspection can be performed with any zip tool. If the file is
-not there, first correct this before proceeding.
-
-
-If the file is there and the panel does not appear, you have a problem within
-the specification file. In most cases that i have seen, it comes down to a
-spelling mistake of an attribute or tag name. You just have to carefully make
-sure that everything is spelled correctly. Don't forget that all names are
-case sensitive! In a few cases it is also happend, that required or semi-
-optional attributes are omitted, so you might want to verify if all
-attributes that you need are actually supplied.
-
-
-If everything is correct up to this point the problem becomes more elusive.
-Most likely the panel will not be displayed, because it is instructed not to
-show. There are be several reasons for this. The simple case is that no
-location has been specified for the shortcuts in your installation. This can
-happen if all five location attributes are omitted or if all the ones that
-are listed are set to ``no``. Remember, you have to specify at least one
-location for every shortcut. If this is also correct, you might have used the
-``<createForPack>`` tag. Review the details in 'Selective Creation of
-Shortcuts'. One possibility for the panel not to show is that based on the
-packs that are currently selected for installation no shortcut qualifies for
-creation. In this case the panel will not show, this is perfectly normal
-behavior. More likely this condition is true because of some accident and not
-because it's intended. Make sure the packs that you list for the shortcut are
-actually defined in your installation and verify that they are all spelled
-correctly. Remember: case matters! Did the ShortcutPanel use to work in your
-installation and all of a sudden stopped working? Very likely you are dealing
-with the last problem. A package name might have been modified and the
-shortcut spec was not adjusted to stay in sync.
-
-
-
-Problems That Have No Solution (yet)
-'''''''''''''''''''''''''''''''''''''''
-
-Unfortunately one problem has been very persistent and only recently one user
-found the reason. The problem occurs when installing on some target systems
-where non-English characters are used in the storage path for the shortcuts.
-The problem is that these characters don't seem to be properly translated
-across the Java Native Interface. This leads to a situation where the proper
-path can not be located and the shortcut creation fails. i write 'some target
-systems' because it does not fail everywhere. After much agonizing over this
-problem, one user found the solution: The shortcut creation works fine if a
-Sun virtual machine is installed, but fails if a version from IBM happens to
-be installed. So far i have no solution for this problem but i am trying to
-find a workaround the problem.
-
-
-
-A sample shortcut specification file for Unix
-----------------------------------------------
-
-::
-
- <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
-
- <shortcuts>
-
- <programGroup defaultName="IzForge/IzPack"
- location="applications"/>
-
- <!-- Disabled since there is no Frontend
- shortcut
- name="IzPack"
- programGroup="yes"
- desktop="yes"
- applications="no"
- startMenu="yes"
- startup="no"
- target="$INSTALL_PATH/bin/izpack-fe.sh"
- commandLine=""
- workingDirectory="$INSTALL_PATH/bin"
- description="Front-End for IzPack installation tool"
- iconFile="$INSTALL_PATH/bin/icons/izpack.png"
- iconIndex="0"
- type="Application"
- encoding="UTF-8"
- terminal="true"
- KdeSubstUID="false"
- initialState="normal">
- <createForPack name="Core"/>
- </shortcut -->
-
- <shortcut
- name="IzPack Documentation"
- programGroup="yes"
- desktop="yes"
- applications="no"
- startMenu="yes"
- startup="no"
- target="konqueror"
- workingDirectory=""
- commandLine=""
- initialState="noShow"
- iconFile="help"
- iconIndex="0"
- url="$INSTALL_PATH/doc/izpack/html/izpack-doc.html"
- type="Link"
- encoding="UTF-8"
- description="IzPack user documentation (html format)">
-
- <createForPack name="Documentation-html"/>
- </shortcut>
-
- <shortcut
- name="Documentation"
- programGroup="yes"
- desktop="yes"
- applications="no"
- startMenu="yes"
- startup="no"
- target="acroread"
- workingDirectory=""
- commandLine="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf"
- initialState="noShow"
- iconFile="acroread"
- iconIndex="0"
- url="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf"
- type="Application"
- encoding="UTF-8"
- description="IzPack user documentation (PDF format)">
-
- <createForPack name="Documentation-PDF"/>
- </shortcut>
-
- <shortcut
- name="Uninstaller"
- programGroup="yes"
- desktop="yes"
- applications="no"
- startMenu="no"
- startup="no"
- target="/usr/lib/java/bin/java"
- commandLine="-jar
- "$INSTALL_PATH/Uninstaller/uninstaller.jar""
- initialState="noShow"
- iconFile="trashcan_full"
- iconIndex="0"
- workingDirectory=""
- type="Application"
- encoding="UTF-8"
- description="IzPack uninstaller">
- <createForPack name="Core" />
- </shortcut>
-
- </shortcuts>
Deleted: izpack-src/trunk/src/doc-reST/node7.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node7.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node7.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,274 +0,0 @@
-Creating Your Own Panels
-========================
-
-In IzPack all of the actual work of installing an application is done in
-panels. The IzPack framework is primarily there to support the operation of
-the panels and to manage the navigation through the installation process.
-This enables a user to decide which operations are carried out during an
-installation and the order in which they are carried out, simply by listing
-the appropriate panels in the desired order.
-
-
-As far as extending the functionality of IzPack is concerned, the result of
-this design is that new functionality can be integrated by adding new panels
-to the framework and then listing them in the install spec. Because the
-existing panels all have a visible GUI and because the term panel hints at
-something visible, it is not obvious that a panel does not have to contain
-any visible GUI to function in this framework. There are more details on this
-subject later on in this chapter.
-
-
-
-How to get started
---------------------
-
-To get started with writing your own panels, it is best to place all the
-IzPack code into a separate working directory, from where you can compile it.
-Then try to compile the code as is and get that to work.
-
-
-The next step would be to have a look at another panel implementation, so you
-can see how things are done. Make sure you look at the less complicated
-panels, as the panels with advanced features will only be confusing. All the
-code for building UI and such, only detracts from the essentials of what a
-panel needs to do. This means that you shouldn't start with ``
-UserInputPanel`` or ``ShortcutPanel``. ``HelloPanel`` is probably a much
-better choice at this stage. The source code for panels is located at:
-``/src/lib/com/izforge/izpack/panels``.
-
-
-You will find that all panels are derived from ``IzPanel``; do the same thing
-with your new panel. Please note that the ``IzPanel`` class itself is located
-in the `` com.izforge.izpack.installer`` package but your panels need to
-belong to ``com.izforge.izpack.panels``. Perhaps you can just copy the code
-of a panel, remove all the functional stuff and then start filling in your
-own code. Start with something very simple to begin with, just to see how it
-works. The implementation is really quite straight forward.
-
-
-
-Next Steps
---------------------
-
-Once you have a successful compilation, you must place the compiled result of
-your panel code at a special place, so that the installer compiler can fetch
-it when building an installer that uses your panel. Go to: ``/bin/panels``
-
-
-You will see that there is a subdirectory for each panel. Make a subdirectory
-for your new panel with the exact same name as your panel and place your
-compiled panel code there.
-
-
-Once this is accomplished, you are ready to use your panel in an installer.
-Just list it in the spec file like any other panel, compile and in theory it
-will show up when running the installer. Once you made it this far, you can
-dig deeper and get going with your specific needs.
-
-
-Oh, and one other thing: If you think the your code might be useful for a
-larger audience, please think about a contribution to IzPack.
-
-
-Access to the Variable Substitution System
-------------------------------------------------------------
-
-One thing many developers ask about is how to get access to the variable
-substitution system. This is not surprising, because customizing an
-installation for a particular target environment is one of the most important
-functions of an installer and the variable substitution system plays a big
-part in this operation.
-
-
-You can get access to the variable substitution system through the protected
-variable ``idata`` in ``IzPanel``. This variable is of the type
-``InstallData``, which is in turn subclassed from ``AutomatedInstallData``.
-The Javadoc documentation will give you more details on these classes. Of
-particular interest in this context are the methods `` getVariable()``,
-``setVariable()`` and ``getVariableValueMap()`` in ``AutomatedInstallData``.
-
-
-
-Controlling Flow
---------------------
-
-Some of the interesting methods in ``com.izforge.izpack.InstallerFrame`` that
-you might want to explore are ``lockPrevButton()`` and ``lockNextButton()``.
-They allow you to block the use of the button to move back to the previous
-panel and the button that moves to the next panel respectively. Being able to
-control the availability of these buttons to the user is important if one of
-your panels performs a task where the effects cannot be undone. If the user
-would navigate back to the previous panel your installation might get into an
-unknown or even unstable state. On the other hand, if the operations in one
-panel vitally depend that a task in the previous panel is completed, then you
-should block the use of the next button until that task is completed.
-
-
-
-Reading XML
---------------------
-
-If you need configuration files for your panel you would want to use XML for
-that purpose. To read XML files you should use NanoXML, as it is guaranteed
-to be available at installation time. In fact, all of the IzPack
-infrastructure uses NanoXML to read XML files. First you should read the
-NanoXML documentation. The documentation is included as PDF file with the
-IzPack distribution, have a look in ``/doc/nanoxml``. In addition to that,
-the Javadoc-generated class documentation is an excellent resource to get
-help on NanoXML. And then, there is always the code of other panels to see
-practical examples. Generally, it is a much simpler matter to use NanoXML
-then to use the DOM included with the Java distribution, so don't hesitate to
-explore NanoXML.
-
-
-Supporting Classes
---------------------
-
-If your panel requires any supporting classes that are part of the panels
-package, then you must place the .class files into the same directory with
-your panel .class file.
-
-
-It is also possible to have supporting classes that are not part of the
-panels package. In fact, these classes don't even have to be in the
-``com.izpack...`` tree. You simply have to ensure that the .class files are
-located in the proper directory structure inside ``/lib/installer.jar``. If
-this is done, they will be available at install time. For your first
-experiments you can simply compile your classes and add them to the .jar
-file using the jar tool or a zip utility. However, ultimately it is much
-easier to use Ant and the IzPack build script to accomplish this task.
-
-
-
-Panels that are not visible
-----------------------------------------
-
-If you have a task that needs to be performed at a particular step in the
-installation process, but that does not need any user interaction, you can
-implement a panel that is not visible. To implement this, you should first
-familiarize yourself with the Javadoc documentation of
-``com.izforge.izpack.InstallerFrame``. In your panel code you get access to
-the right instance of ``InstallerFrame`` through the protected variable
-``parent`` in ``IzFrame``.
-
-
-To begin with, do not configure any UI. In other words, do not set a layout
-and do not place any GUI elements on your panel. In this context the method
-``skipPanel()`` is what gets the job done. In your ``panelActivate()`` method
-you simply perform your task and then call ``parent.skipPanel()``. This gets
-the job done without the user being aware that there was another panel in the
-flow.
-
-
-
-A word about building IzPack
-----------------------------------------
-
-If you don't already use Jakarta Ant to support your development work, i
-highly recommend you have a look at it. It is a great help in organizing
-practically all routine tasks connected with building and packaging your
-application. For example, building and getting IzPack ready for distribution
-is not a straight forward process but with Ant this all comes down to
-starting a single command. In addition, IzPack provides its own Ant task,
-which supports the integration of building a complete installer into your
-regular build scripts. You can find more details about this in the chapter
-about advanced features. To get a look at Ant you can visit the following
-link: http://ant.apache.org/index.html.
-
-
-You can find the Ant build script for IzPack itself at: ``/src/build.xml``
-
-The ``IzPanel`` Class
-----------------------
-
-
-.. image:: izpanel-uml-diag.png
-
-
-The two data members are : the install data (refer to the ``InstallData``
-Javadoc reference) and a reference to the parent installer frame.
-
-
-The methods have the following functionality :
-
-
-- *(constructor)* : called just after the language selection dialog.
- All the panels are constructed at this time and then the installer is
- shown. So be aware of the fact that the installer window is **not** yet
- visible when the panel is created. If you need to do some work when the
- window is created, it is in most cases better do it in ``panelActivate``.
-
-- ``isValidated`` returns ``true`` if the user is allowed to go a step
- further in the installation process. Returning ``false`` will lock it.
- For instance the LicencePanel returns ``true`` only if the user has
- agreed with the license agreement. The default is to return ``true``.
-
-- ``panelActivate`` is called when the panel becomes active. This is
- the best place for most initialization tasks. The default is to do
- nothing.
-
-- ``makeXMLData`` is called to build the automated installer data. The
- default is to do nothing. ``panelRoot`` refers to the node in the XML
- tree where you can save your data. Each panel is given a node. You can
- organize it as you want with the markups you want starting from
- ``panelRoot``. It's that simple.
-
-- ``runAutomated`` is called by an automated-mode installation. Each
- panel is called and can do its job by picking the data collected during a
- previous installation as saved in `` panelRoot`` by ``makeXMLData``.
-
-- ``setInitialFocus`` with this method it is possible to set a hint
- which component should be get the focus at activation of the panel. It is
- only a hint. Not all components are supported. For more information see
- java.awt.Component.requestFocusInWindow or
- java.awt.Component.requestFocus if the VM version is less than 1.4.
-
-- ``getInitialFocus`` returns the component which should be get the
- focos at activation of the panel. If no component was set, null returns.
-
-- ``getSummaryBody`` this method will be called from the SummaryPanel
- to get the summary of this class which should be placed in the
- SummaryPanel. The returned text should not contain a caption of this
- item. The caption will be requested from the method getCaption. If null
- returns, no summary for this panel will be enerated. Default behaviour is
- to return null.
-
-- ``getSummaryCaption`` this method will be called from the
- SummaryPanel to get the caption for this class which should be placed in
- the SummaryPanel. Default behaviour is to return the string given by
- langpack for the key ClassName.summaryCaption.
-
-
-Additionally, there are some helper methods to simplify grid bag layout
-handling and creation of some common used components.
-
-
-The ``Internationalization`` of custom panels
-------------------------------------------------------------
-
-A common way to define language dependant messages for custom panels is to
-add entries into the common langpacks which are stored in the directory
-
-::
-
- [IzPackRoot]/bin/langpacks/installer
-
-
-New with version 3.8 is the possibility to define a resource for custom
-langpacks. Define e.g.
-
-::
-
- <resources>
- ...
- <res id="CustomLangpack.xml_deu"
- src="myConfigSubPath/CustomLangpack_deu.xml"/>
- ...
- </resources>
-
-
-in the install.xml file.The id should be written as shown, the file sub path
-and name can be other than in the example. This file should be using the same
-DTD as the common langpack. For each language a separate file with the ISO3
-extension in the id should be used.
-
Deleted: izpack-src/trunk/src/doc-reST/node8.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node8.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node8.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,908 +0,0 @@
-User Input
-======================
-
-(by Elmar GROM)
-
-
-Most of the panels that come with IzPack take user input in some form. In
-some panels this is through a simple user acknowledgment in others the user
-can enter text or select a directory through a file open dialog. In all of
-those cases the user input is used for the specific purpose needed by the
-panel that takes the input. However, if you need user input during
-installation that will later on be available to your application then you
-need to use the user input panel.
-
-
-To use this panel, list it in the install file with the class name
-``UserInputPanel``. In addition, you must write a XML specification and add
-it to the install resources. The name of this resource must be
-``userInputSpec.xml``.
-
-
-The user input panel is a blank panel that can be populated with UI elements
-through a XML specification file. The specification supports text labels,
-input elements, explanatory text and some minor formatting options.
-
-
-The following types of user input elements are supported:
-
-- Text
-- Combo Box
-- Radio Buttons
-- Check Box
-- Rule Input Field
-- Search Field
-
-The way in which this panel conveys the user input to your application is
-through the variable substitution system. User input is not directly inserted
-into your configuration files but the variables that you specify for this
-panel are set in the variable substitution system. After this operation has
-taken place the variables and associated values are available for all
-substitutions made. This way of operation has a number of implications that
-you should be aware of.
-
-
-First, not only can you set additional variables in this way but you can also
-modify variables that are defined elsewhere -even built in variables. For
-this reason you should be careful to avoid overlaps when choosing variable
-names. Although there might be cases when it seems useful to modify the value
-of other variables, it is generally not a good idea to do so. Because you
-might not exactly know when other variables are set and when and where they
-are used throughout the installation process, there might be unintended side
-effects.
-
-
-Second, the panel must be shown at a point during the installation process
-before the variables are used. In most cases you will use the values to
-substitute variables in launch and configuration files that you supply with
-your installation. For this to work you place this panel before the install
-panel, because the install panel uses the variable substitutor to replace all
-such variables. Although using this panel any later in the process will
-correctly set the variables internally, there won't be any affect on the
-files written to disk. You can also use variables set in this way in other
-panels that you have written yourself. There is a section in the chapter on
-writing your own panel that explains how to do this. Also in this case it is
-important to place the associated input panel in the process before the
-variables are used.
-
-
-At this point i would also like to mention that it is possible to hide select
-elements on the panel or the panel altogether if certain packs are not
-selected. For this to work you must place this panel after the packs panel.
-One side effect of using this feature is that it is not possible to step back
-once the user input panel is displayed. This is because the user might make
-changes in the packs selection that would require a complete rebuild of the
-UI. Unfortunately, building the UI is an irreversible process, therefore the
-user can not be allowed to go back to the packs panel.
-
-
-
-The Basic XML Structure
-----------------------------------------
-
-The top level XML section is called ``<userInput>``. For most panels it does
-not make sense to present them more than once, however you might want to
-present multiple user input panels -with different content of course.
-Therefore the ``<userInput>`` section can contain multiple tags that each
-specify the details for one panel instance. The tag name for this is
-``<panel>``.
-
-
-The ``<panel>`` tag uses the following attributes:
-
-
-**order** ``- required``
-
-
-This is the order number of the user input panel for which this specification
-should be used. Counting starts at 0 and increments by 1 for each instance of
-the user input panel. So if a spec should be used for the second occurrence
-of the user input panel use ``order="1"``.
-
-
-**layout** ``- optional``
-
-
-There are three general layout rules this panel uses, they are ``left``,
-``center`` and ``right``. While i think left is most commonly used, you might
-want to experiment with this attribute and see which you like best. The
-default is ``left``.
-
-
-
-Concepts and XML Elements Common to All Fields
-------------------------------------------------------------
-
-Before i dive into the details of defining the various UI elements i would
-like to present XML elements and general concepts that apply throughout. This
-saves me a lot of work in writing and you a lot of repetitive reading and
-maybe a tree or two.
-
-
-The UI elements are generally laid out top to bottom in the order they appear
-in the XML file. The only exception to this rule is the title, which always
-appears at the very top. The layout pattern for the input fields is as
-follows: If a description is defined, it appears first, using the full
-available layout width. The input field is placed beneath the description.
-With fields such as the text field or the combo box, the label is placed to
-the left and the input field to the right. Fields such as radio buttons and
-check boxes are somewhat indented and have the label text appear to their
-right.
-
-
-Each UI element is specified with a ``<field>`` tag. The ``type`` attribute
-is used to specify what kind of field you want to place. Obviously, the
-``type`` attribute is not optional.
-
-
-Each field that takes user input must also specify the variable that should
-be substituted. This is done with the ``variable`` attribute.
-
-
-Almost all fields allow a description. When a description is allowed it is
-always added in the same way. The description is part of the data within the
-field tag. There can only be one description per field. If you add more than
-one, the first one is used and the others ignored. There are three attributes
-used with this tag. The text is specified through the ``txt`` or the ``id``
-attribute. The details on using them are described below. The attributes are
-all optional but you must specify text to use, either directly or through the
-``id`` attribute. In addition, you can set the text justification to
-``left``, ``center`` and ``right`` with the ``align`` attribute.
-
-
-The following example illustrates the general pattern for field
-specification:
-
-
-::
-
- <field type="text" variable="myFirstVariable">
- <description align="left" txt="A description" id="description1"/>
- .
- .
- .
- </field>
-
-
-A very frequently used pattern is for the definition of text. Where ever text
-is needed (labels, descriptions, static text, choices etc.) it can be
-specified in place using the ``txt`` attribute. This is convenient if you are
-only supporting a single language. However, if you would like to separate
-your text definitions from the panel specification or if you need to support
-multiple languages you might want to use the ``id`` attribute instead to only
-specify an identifier. You can then add multiple XML files with the same name
-as this spec file (userInputSpec.xml) appended with an unserscore '_' and the
-the appropriate three letter ISO3 language code. The content of those files
-must conform to the specification for IzPack language packages. For more
-details on this topic see the chapter on language packages under advanced
-features. ``id`` defines an identifier that is also defined in the language
-package, together with the localized text to use. It is possible to use both
-the ``txt`` and the ``id`` attribute. In this case the text from the language
-package is used. If for some reason the language package is not available or
-the ``id`` is not defined there, the text specified with ``txt`` is used as
-default.
-
-
-All input fields can be pre-set with a value of your choice. Although the
-details vary a bit from field type to field type, the ``set`` attribute is
-always used to accomplish this. The ``set`` attribute is of course optional.
-
-
-All fields that take user input use a ``<spec>`` tag to define the details of
-the input field. In the some cases the content of this tag is rather simple.
-Input fields with a more complex nature tend to have accordingly complex
-content in this tag. Since the details vary widely, they are explained with
-each input field.
-
-
-Any number of ``<createForPack name=''a pack name'' />`` tags can be added to
-the ``<panel>`` and ``<field>`` sections. This tag has only one attribute and
-no data. The attribute is ``name`` and specifies the name of one of the
-installation packs that you have defined. Here is how it works: if no
-``<createForPack ...>`` tag exists in a section, the entity is always
-created. However, if the tag exists, the entity is only created if one or
-more of the listed packs are selected for installation. As mentioned before,
-if you are using this feature, make sure the user input panel shows up after
-the packs panel.
-
-
-Also, any number of ``<createForUnselectedPack name=''a pack name'' />`` tags
-can be added to the ``<panel>`` and ``<field>`` sections. This tag has only
-one attribute and no data. It works exactly like createForPack except that
-once added userinputpanel will appear for only NOT Selected packs. As
-mentioned earlier, you need to make sure that the user input panel shows up
-after the packs panel for this feature to work.
-
-
-
-Internationalization
---------------------
-
-To provide internationalization you can create a file named
-``userInputLang.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.
-
-
-Example:
-
-
-If you have the following userInputSpec.xml and you want to internationalize
-``input.comment``, ``input.proxy``, ``input.port`` for english and french you
-have to create two files named userInputLang.xml_eng and
-userInputLang.xml_fra:
-
-::
-
- <userInput>
- <panel order="0">
- <field type="staticText" align="left" txt="My comment is here."
- id="input.comment"/>
- <field type="text" variable="proxyaddress">
- <spec txt="Proxy Host:" id="input.proxy" size="25"
- set=""/>
- </field>
- <field type="text" variable="proxyPort">
- <spec txt="Proxy Port:" id="input.port" size="6"
- set=""/>
- </field>
- </panel>
- </userInput>
-
-
-userInputLang.xml_eng file contains:
-
-::
-
- <langpack>
- <str id="input.comment" txt="English:My comment is here."/>
- <str id="input.proxy" txt="English:Proxy Host:"/>
- <str id="input.port" txt="English:Proxy Port:"/>
- </langpack>
-
-
-userInputLang.xml_fra file contains:
-
-::
-
- <langpack>
- <str id="input.comment" txt="French:My comment is here."/>
- <str id="input.proxy" txt="French:Proxy Host:"/>
- <str id="input.port" txt="French:Proxy Port:"/>
- </langpack>
-
-
-you will also have to add the following to the install.xml file
-
-::
-
- <resources>
- ...
- <res id="userInputSpec.xml" src="userInputSpec.xml"/>
- <res id="userInputLang.xml_eng" src="userInputLang.xml_eng" />
- <res id="userInputLang.xml_fra" src="userInputLang.xml_fra" />
- ...
- </resources>
-
-Panel Title
---------------------
-
-You can place an optional title at the top of the panel. Though it is not
-possible to select a font for the title that is different form the one used
-on the rest of the panel, it is possible to modify the font to some extent.
-To specify the title create a ``<field>`` tag and use the ``type`` attribute
-with the value ``title``. In addition to the ``txt`` and ``id`` attributes,
-the following attributes are supported:
-
-
-**italic** ``- optional``
-
-
-With a value of ``true`` specifies that the title font should be in italics.
-
-
-**bold** ``- optional``
-
-
-With a value of ``true`` specifies that the title font should be bold.
-
-
-**size** ``- optional``
-
-
-This attribute specifies the size of the title font. Please note that the
-size is not specified in points but as a relative size multiplier compared to
-the body font on the panel. The default value is 2.
-
-
-
-Static Text
---------------------
-
-Static text is simply text that is placed on the panel without direct
-connection to any of the input elements. It is laid out to use the entire
-layout width available on the panel and is broken into multiple lines if
-necessary. To specify static text create a ``<field>`` tag and use the
-``type`` attribute with a value of ``staticText``. In addition to the ``
-txt`` and ``id`` attributes, the text can be justified ``left``, ``center``
-or ``right`` with the ``align`` attribute. It is not possible to format this
-text in any way.
-
-
-**Example**
-
-
-The following example inserts some static text in the panel.
-
-::
-
- <field type="staticText" align="left"
- txt="This is just some simple static text."
- id="staticText.text"/>
-
-Visual Separation
---------------------
-
-Sometimes it is desirable to separate different entities visually. This can
-be accomplished by inserting a space or a divider. A space simply inserts a
-vertical separation of the average height of a single line entity, such as a
-line of text or a an input field. A divider inserts the same amount of space
-but also draws a division line which can be either aligned at the top or
-bottom of the separation.
-
-``<field type="divider" />``
-``<field type="space" />``
-
-
-Text Input
---------------------
-
-A text input field allows the user to enter and edit a single line of text,
-without length restriction. The input field can have a label, which will show
-to the left of the input field and a description, which can span multiple
-lines. The description is placed above the input field and uses the entire
-available layout width. The width of the input field must be explicitly set,
-otherwise it will only accommodate a single character. To specify a text
-input field create a ``<field>`` tag and use the ``type`` attribute with a
-value of ``text``. The ``txt`` and ``id`` attributes are not supported here.
-The ``variable`` attribute specifies the variable that should be replaced
-with the text taken from the input field.
-
-
-**The Data**
-
-
-The data consists of two items, a description and the spec. The ``<spec>``
-tag uses four attributes. The label text is specified with ``txt`` and/or
-``id`` as described above. In addition, the width of the input field as it
-appears on the panel can be set with the ``size`` attribute. The value must
-be an integer and sets the field width based on the average character width
-of the active font. If this is not specified, then you will end up with a
-very narrow field that is practically unusable.
-
-
-The fourth attribute ``set`` is optional. It takes a text string to pre-fill
-the input field.
-
-
-**Example**
-
-
-The following example creates a text input field with a label and
-description. The width of the input field will be enough to accommodate 15
-characters. The field will be pre-set with the text 'some text' when the UI
-is first presented.
-
-
-::
-
- <field type="text" variable="textInput">
- <description align="left" txt="A description for a text input
- field"
- id="description.text"/>
- <spec txt="Enter some text:" id="text.label" size="15" set="some
- text"/>
- </field>
-
-Radio Buttons
---------------------
-
-The radio buttons are useful when the user needs to select a specific option
-out of a pre-defined list of choices. This field offers an arbitrary number
-of mutually exclusive buttons, each with its own label. The placement of the
-buttons and labels is different form other fields. First, the button is
-placed to the left and the label text to the right. Second, the buttons are
-not lined up all the way to the left as other labels are but they are
-indented from that location. As with other fields, the description is placed
-above the list of radio buttons and uses the entire available layout width.
-To specify a set of radio buttons create a ``<field>`` tag and use the
-``type`` attribute with a value of ``radio``. The ``txt`` and `` id``
-attributes are **not** supported here. As with all other input fields, the
-``variable`` attribute specifies that variable that should be replaced with
-the user selection.
-
-
-**The Data**
-
-
-The data consists of two items, a description and the spec. The ``<spec>``
-tag has no attributes, instead the specification details are entered as data
-within the `` <spec>`` tag. The ``<spec>`` data consists of one or more
-``<choice>`` tags. One ``<choice>`` tag is required for each radio button.
-The `` <choice>`` tag accepts the usual ``txt`` and ``id`` attributes, which
-are used to specify the label text. In addition the following attributes are
-supported:
-
-
-**value** ``- required``
-
-
-The ``value`` attribute is used to specify which value to insert if this
-associated radio button is selected. In other words, the label text has
-nothing to do with the value that is actually substituted for the variable.
-For this reason there is never an issue if multiple languages are used, the
-value is always the same for a given selection.
-
-
-**set** ``- optional``
-
-
-The ``set`` attribute accepts the values ``true`` and ``false``. Since the
-attribute is optional it can also be omitted, which is interpreted as
-``false``. If a value of ``true`` is used, the associated radio button will
-be selected when the UI is first presented. Obviously, only one of the
-buttons in a set should be set to ``true``.
-
-
-**Example**
-
-
-The following example creates a set of four radio buttons with description.
-The second button will be selected when the UI is first presented.
-
-
-::
-
- <field type="radio" variable="radioSelection">
- <description align="left" txt="This is a description for radio
- buttons" id="description.radio"/>
- <spec>
- <choice txt="the first choice" id="radio.label.1" value="1 selected" />
- <choice txt="the second choice" id="radio.label.2" value="2 selected" set="true" />
- <choice txt="the third choice" id="radio.label.3" value="3 selected" />
- <choice txt="the fourth choice" id="radio.label.4" value="4 selected" />
- </spec>
- </field>
-
-Combo Box
---------------------
-
-The combo box provides essentially the same functionality as do the radio
-buttons, just in a different presentation stile. The advantage of the combo
-box is that it is easier to deal with a long list of choices.
-
-
-
-Check Box
---------------------
-
-If there are a number of choices and any combination of them could be
-selected, not just a single one, then radio buttons are not the way to go.
-You might be better off using a number of check boxes. The layout for a check
-box works in the same way as for radio buttons. The check box is placed
-indented from the left most edge and the label text is placed to the right of
-it. Other than with radio buttons, you cannot define any number of check
-boxes. This field allows the definition of only one check box, which is
-associated with one variable. If you need multiple check boxes you need to
-define one field for each of them. To make it look like a cohesive group you
-simply provide a description only for the first check box. All of the check
-boxes will be positioned in such a way that they look like a group, even
-though they are separate entities and their selections are conveyed to
-different variables. The description is placed above the check box and uses
-the entire available layout width. To specify a check box create a
-``<field>`` tag and use the ``type`` attribute with a value of ``check``. As
-with all other input fields, the ``variable`` attribute specifies the
-variable that should be replaced with the user input.
-
-
-**The Data**
-
-
-The data consists of two items, a description and the spec. The ``<spec>``
-tag accepts the usual ``txt`` and ``id`` attributes, which are used to
-specify the label text. In addition, the following attributes are supported:
-
-
-**true** ``- required``
-
-
-The ``true`` attribute specifies the value to use for substitution when the
-box is selected.
-
-
-**false** ``- required``
-
-
-The ``false`` attribute specifies the value to use for substitution when the
-box is not selected.
-
-
-**set** ``- optional``
-
-
-The ``set`` attribute accepts the values ``true`` and ``false``. Since the
-attribute is optional it can also be omitted, which is interpreted as
-``false``. If a value of ``true`` is used, the check box will be selected
-when the UI is first presented.
-
-
-**Example**
-
-
-The following example creates a check box with description. The check box
-will not be selected when the UI is first presented. This could also be
-accomplished by omitting the ``set`` attribute.
-
-
-::
-
- <field type="check" variable="chekSelection.1">
- <description align="left" txt="This is a description for a check
- box"
- id="description.check.1"/>
- <spec txt="check box 1" id="check.label.1" true="on" false="off"
- set="false"/>
- </field>
-
-Rule Input
---------------------
-
-The rule input field is the most powerful and complex one of all the input
-fields offered by this panel. In its most simple incarnation it looks and
-works like a regular text input field. There is also only an incremental
-increase of the complexity in the specification for this case. However, it is
-unlikely that you would use it for such a purpose. The real power of this
-input field comes from the fact that rules can be applied to it that control
-many aspects of its look as well as overt and covert operation.
-
-
-
-Layout and Input Rules
-----------------------------------------
-
-The basic nature of this input field is that of a text input field and as
-mentioned before, in its most simple incarnation that is what it looks like
-and how it operates. However, the layout of the field can be defined in such
-a way that there are multiple logically interconnected text input fields,
-adorned with multiple labels. Further more, each of these fields can be
-instructed to restrict the type of input that will be accepted. Now you might
-ask what this could be useful for. As an answer, let me present a few
-examples that show how this feature can be used. Before i do this however, i
-would like to describe the specification syntax, so that the examples can be
-presented together with the specifications that make them work in a
-meaningful way.
-
-
-The actual specification of the layout, the labels and the type of input each
-field accepts all happens in a single string with the ``layout`` attribute.
-First let us have a look at the specification format for a single field. This
-format consists of a triplet of information, separated by two colons ':'. A
-typical field spec would look like this: ``N:4:4``, where the first item is a
-key that specifies the type of input this particular field will accept -
-numeric input in the example. The second item is an integer number that
-specifies the physical width of the field, this is the same as in the with of
-any regular text field. Therefore the field in the example will provide space
-to display four characters. The third item specifies the editing length of
-the string or in other words, the maximum length of the string that will be
-accepted by the field. In the ``layout`` string you can list as may fields as
-you need, each with its own set of limitations. In addition you can add text
-at the front, the end and in between the fields. The various entities must be
-separated by white space. The behavior of this field is such that when the
-editing length of a field has been reached, the cursor automatically moves on
-to the next field. Also, when the backspace key is used to delete characters
-and the beginning of a field has been reached, the cursor automatically moves
-on to the previous field. So let us have a look a some examples.
-
-
-**Phone Number**
-
-The following specification will produce a pre formatted input field to
-accept a US phone number with in-house extension. Even though the pattern is
-formatted into number groups as customary, complete with parentheses '(' and
-dash '-', entering the number is as simple as typing all the digits. There is
-no need to advance using the tab key or to enter formatting characters.
-Because the fields only allow numeric entry, there is a much reduced chance
-for entering erroneous information. ``"( N:3:3 ) N:3:3 - N:4:4 x N:5:5"``.
-Each of the fields uses the 'N' key, indicating that only numerals will be
-accepted. Also, each of the fields only accepts strings of the same length as
-the physical width of the field.
-
-
-.. image:: img7.png
-
-
-**E-Mail address**
-
-This specification creates a pattern that is useful for entering an e-mail
-address ``"AN:15:U @ AN:10:40 . A:4:4"``. Even though the first field is only
-fifteen characters wide it will accept a string of unlimited length, because
-the 'U' identifier is used for the edit length. The second field is a bit
-more restrictive by only accepting a string up to forty characters long.
-
-
-.. image:: img8.png
-
-
-**IP address**
-
-It might not be uncommon to require entering of an IP address. The following
-simple specification will produce the necessary input field. All fields are
-the same, allowing just three digits of numerical entry. ``"N:3:3 . N:3:3 .
-N:3:3 . N:3:3"``
-
-
-.. image:: img9.png
-
-
-**Serial Number or Key Code**
-
-If you ship your product with a CD key code or serial number and require this
-information for registration, you might want to ask the customer to
-transcribe that number from the CD label, so that it is later on accessible
-to your application. As this is always an error prone operation, the
-predefined pattern with the easy editing support and restriction of accepted
-data helps to reduce transcription errors ``"H:4:4 - N:6:6 - N:3:3"``. This
-particular specification will produce three fields, the first accepting four
-hexadecimal, the second six numerical and the third three numerical digits.
-
-
-.. image:: img10.png
-
-
-**Limitations**
-
-Even though the above examples all use single character labels between
-fields, there is no restriction on the length of these labels. In addition,
-it is possible to place label text in front of the first field and after the
-last field and the text can even contain spaces. The only limitation in this
-regard is the fact that all white space in the text will be reduced to a
-single space on the display. This means that it is not possible to use
-multiple spaces or tabs in the text.
-
-
-The following table lists and describes all the keys that can be used in the
-specification string.
-
-
-==== =============== ================================================================================================================================================
-Key Meaning Description
-==== =============== ================================================================================================================================================
-N numeric The field will accept only numerals.
-H hexadecimal The field will accept only hexadecimal numerals, that is all numbers from 0-F.
-A alphabetic The field will accept only alphabetic characters. Numerals and punctuation marks will not be accepted.
-AN alpha-numeric The field will accept alphabetic characters and numerals but no punctuation marks.
-O open The filed will accept any input, without restriction.
-U unlimited This key is only legal for specifying the editing length of a fields. If used, the field imposes no length restriction on the text entered.
-==== =============== ================================================================================================================================================
-
-
-Setting Field Content
-----------------------
-
-Like all other input fields the rule input field can also be pre-filled with
-data and as usual, this is accomplished thought the ``set`` attribute. As you
-might expect, the details of setting this field are rather on the complicated
-side. In fact you can set each sub field individually and you can leave some
-of the fields blank in the process. The ``set`` specification for all sub
-fields is given in a single string. Each field is addressed by its index
-number, with the count starting at 0. The index is followed by a colon ':'
-and then by the content of the field. The string "0:1234 1:af415 3:awer"
-would fill the first subfield with ``1234``, the second one with ``af415``
-and the fourth with ``awer``. The third subfield would stay blank and so
-would any additional fields that might follow.
-
-
-The individual field specs must be separated with spaces. Spaces within the
-pre-fill values are not allowed, otherwise the result is undefined.
-
-
-
-The Output Format
-----------------------
-
-The user input from all subfields is combined into one single value and used
-to replace the variable associated with the field. You can make a number of
-choices when it comes to the way how the subfield content is combined. This
-is done with the ``resultFormat`` and ``separator`` attributes. The
-``resultFormat`` attribute can take the following values:
-
-
-===================== ======================================================================================================================================================
-Value Meaning
-===================== ======================================================================================================================================================
-``plainString`` The content of all subfields is simply concatenated into one long string.
-``displayFormat`` The content of all subfields and all labels (as displayed) is concatenated into one long string.
-``specialSeparator`` The content of all subfields is concatenated into one string, using the string specified with the ``separator`` attribute to separate the content of the subfields.
-``processed`` The content is processed by Java code that you supply before replacing the variable. How to do this is described below.
-===================== ======================================================================================================================================================
-
-Validating the Field Content
---------------------------------------------
-
-You can provide runtime validation for user input into a rule field via the
-``validator`` element (which is a child of the ``field`` element. There are
-two types of built-in validators already provided: a ``NotEmptyValidator``
-and a ``RegularExpressionValidator``. You can also easily create your own
-validator. In all cases, if the chosen validator returns ``false``, a
-messagebox will display the contents of the ``txt`` attribute and the user
-will be unable to continue to the next panel.
-
-
-You can specify a processor for a combobox:
-
-::
-
- <choice processor="fully.qualified.class.name"
- set="selectedValue"/>
-
-
-so that you can fill a combobox with data on a simple way.
-
-
-NotEmptyValidator
-''''''''''''''''''
-
-The ``NotEmptyValidator`` simply checks that the user entered a non-null
-value into each subfield, and returns ``false`` otherwise.
-
-
-
-RegularExpressionValidator
-'''''''''''''''''''''''''''
-
-The ``RegularExpressionValidator`` checks that the user entered a value which
-matches a specified regular expression, as accepted by the Jakarta Regexp
-library (http://jakarta.apache.org/regexp/). The syntax of this
-implementation is described in the javadoc of the ``RE`` class
-(http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html).
-
-You can specify the regular expression to be tested by passing a parameter
-with a name of ``pattern`` to the validator (via the ``param`` element), with
-the regular expression as the ``value`` attribute. For example, the following
-would validate an e-mail address:
-
-
-::
-
- <field type="rule" variable="EMAILaddress">
- <spec
- txt="Your Email address:" layout="O:12:U @ O:8:40 .
- A:4:4"
- set="0: 1:domain 2:com" resultFormat="displayFormat"
- />
- <validator
- class="com.izforge.izpack.util.RegularExpressionValidator"
- txt="Invalid email address!">
- <param
- name="pattern"
- value="[a-zA-Z0-9._-]{3,}@[a-zA-Z0-9._-]+([.][a-zA-Z0
- -9_-]+)*[.][a-zA-Z0-9._-]{2,4}"
- />
- </validator>
- </field>
-
-
-You can test your own regular expressions using the handy applet at
-http://jakarta.apache.org/regexp/applet.html.
-
-
-
-Creation Your Own Custom Validator
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can create your own custom Validator implementation simply by creating a
-new class which implements the ``com.izforge.izpack.panels.Validator``
-interface. This interface specifies a single method:
-``validate(ProcessingClient client)`` , which returns a ``boolean`` value.
-You can retrieve the value entered by the user by casting the input
-ProcessingClient as a ``RuleInputField`` and calling the
-``RuleInputField.getText()`` method. You can also retrieve any parameters to
-your custom ``Validator`` by calling the
-``RuleInputField.getValidatorParams()`` which returns a ``java.util.Map``
-object containing parameter names mapped to parameter values. For an example,
-take a look at
-``com.izforge.izpack.util.RegularExpressionValidator``.
-
-
-Set values in the RuleInputField can be preprocessed. At now you can specify
-a processor class to pre process a value to be set at initial value of a
-RuleInputField. Syntax:
-
-::
-
- <spec set="0:defaultVal:classname" .../>
-
-
-The class name is an optional value. The class must implement the
-``Processor`` interface.
-
-
-
-Processing the Field Content
---------------------------------------------
-
-This feature needs to be documented.
-
-
-Summary Example
-----------------------
-
-::
-
- <field type="rule" variable="test1">
- <description align="left" txt="A description for a rule input
- field."
- id="description.rule.1"/>
- <spec txt="Please enter your phone number:"
- layout="( N:3:3 ) N:3:3 - N:4:4 x N:5:5"
- resultFormat="specialSeparator" separator="."/>
- <validator class="com.izforge.izpack.util.NotEmptyValidator"
- txt="The phone number is mandatory!" />
- <!--processor class=""/-->
- </field>
-
-Search
-----------------------
-
-The search input field allows the user to choose the location of files or
-directories. It also supports auto-detection of the location using a list of
-suggestions. The field is basically a combobox with an extra button to
-trigger auto-detection (again).
-
-.. image:: img11.png
-
-
-
-Specification
-----------------------
-
-The ``<description>`` tag is the same as with other fields
-
-The ``<spec>`` tag supports the following attributes:
-
-- ``filename`` - the name of the file or directory to search for
-- ``type`` - what to search for
-
- - ``file`` - search for a file
- - ``directory`` - search for a directory
-
-- ``result`` - what to return as the search result
-
- - ``file`` - result of search is whole pathname of file or directory found
- - ``directory`` - only return directory where the file was found (this is the same as ``file`` when searching for directories)
- - ``parentdir`` - return the full path of the parent directory where the file was found
-
-- ``checkfilename`` - the name of a file or directory to check for
- existence (this can be used to validate the user's selection)
-
-
-Example
--------
-
-::
-
- <field type="search" variable="java_sdk_home">
- <description align="left"
- txt="This is a description for a search
- input field."
- id="description.java_sdk_home"/>
- <spec txt="Path to Java SDK:" checkfilename="lib/tools.jar"
- type="file" result="directory">
- <choice value="/usr/lib/java/" os="unix" />
- <choice value="/opt/java" os="unix" />
- <choice value="C:\Program Files\Java" os="windows" />
- <choice value="C:\Java" os="windows" />
- </spec>
- </field>
-
Deleted: izpack-src/trunk/src/doc-reST/node9.html.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/node9.html.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/node9.html.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -1,842 +0,0 @@
-Custom Actions
-==========================
-
-(by Klaus BARTZ)
-
-
-Overview
-----------------------
-
-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.
-
-In general the installation procedure is separated into several steps. The
-first step, let's call it the *data collection phase*, 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.
-
-If all needed data is collected the second step will be perfomed, let us call
-it the *action phase*. 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 "file transfer", "parse"
-or "execute".
-
-The third step, the *reporting phase*, is normally represented by a panel
-that reports the result state of the installation (OK, or not OK) and a
-simple good bye message.
-
-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.
-
-Panels still may be used for actions that are perfomed, e.g. before files are
-transferred or after the "execute" action. But if the needed action depends
-on the selected or already installed packages, this works also, but the
-implementation effort is much higher.
-
-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.
-
-
-How It Works
-----------------------
-
-Custom actions are implemented as listeners. Each listener implements
-callback methods that will be called at well-defined points. The method
-``InstallerListener.afterFile`` 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.
-
-Each interface is implemented by a class with the prefix "Simple" (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.
-
-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 "listeners" which can contain one or more ELEMENTs of
-"listener". For a "listener" there are three attributes which determine the
-"compiler", "installer" and "uninstaller" custom action pupose. Additionally
-it is possible to make the listener OS dependent using the "os" ELEMENT.
-
-If file related data will be set, the facultative ELEMENT "additionaldata" is
-defined for the ELEMENTs "file", "singlefile" and "fileset". 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).
-
-
-Custom Action Types
-----------------------
-
-Custom actions are intended to be used at packaging time, at installation
-time and at uninstallation time. The interfaces are:
-
-=================== =============================================
-Custom action type Interface name
-=================== =============================================
-Packaging com.izforge.izpack.event.CompilerListener
-Installation com.izforge.izpack.event.InstallerListener
-Uninstallation com.izforge.izpack.event.UninstallerListener
-=================== =============================================
-
-
-Custom Actions At Packaging
-''''''''''''''''''''''''''''
-
-.. image:: img12.png
-
-- *(constructor)*: 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 ``notify`` call.
-- ``reviseAdditionalDataMap`` gives the facility to add data to each
- ``PackFile`` 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
- ``CompilerListeners``. Each call of this method adds own key value pairs
- to the given ``existenDataMap`` because more than one listener can be
- used. If the given map is null, a new one will be created.
-- ``notify`` is called at the beginning and at the end of each "add"
- method call which is called in ``Compiler.executeCompiler``.
-
-
-Custom Actions At Installing Time
-''''''''''''''''''''''''''''''''''
-
-
-.. image:: img13.png
-
-- *(constructor)*: only the default constructor will be used. It is
- called from ``Unpacker.run`` before unpacking.
-- ``beforePacks`` will be called each time before an unpacking call is
- performed.
-- ``beforePack`` is called before a package is installed. Pack object
- and the number of the pack are passed.
-- ``isFileListener`` determines whether the next four methods are
- called or not. This is a little performance optimizing.
-- ``beforeDir`` 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 ``PackFile``
- object are passed.
-- ``afterDir`` is called directly after the directory creation.
-- ``beforeFile`` is called before a file is created. The file and
- ``PackFile`` object are passed as parameters.
-- ``afterFile`` is the best place to perform file related actions. The
- given ``PackFile`` objects contains the additional data which was set at
- packaging.
-- ``afterPack`` will be just called after the pack is closed.
-- ``afterPacks`` is the last step before the handler will be stopped.
-
-
-Custom Actions At Uninstalling Time
-'''''''''''''''''''''''''''''''''''''
-
-.. image:: img14.png
-
-- *(constructor)* : only the default constructor will be used. It is
- called from ``Destroyer.run`` as first call.
-- ``beforeDeletion`` will be called after execute files was performed.
- The given list contains all *File* objects which are marked for deletion.
-- ``isFileListener`` determines whether the next two methods are called
- or not.
-- ``beforeDelete`` is the method which, is called before a single file
- is deleted. The *File* object is given as parameter.
-- ``afterDelete`` will be invoked after the delete call for a single
- file.
-- ``afterDeletion`` is the last call before the cleanup of created data
- is performed.
-
-
-Package Path
-----------------------
-
-Custom actions must always implement one of the given listener interfaces. As
-mentioned above, it is also possible to derive from one of the "Simple"
-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 ``[IzPackRoot]/bin/customActions``,
-may be
-
-::
-
- [IzPackRoot]/bin/customActions/MyCompilerListener.jar
- [IzPackRoot]/bin/customActions/MyInstallerListener.jar
- [IzPackRoot]/bin/customActions/MyUninstallerListener.jar
-
-
-In the default Ant definition file (build.xml) there are some targets for
-this stuff.
-
-Native Libraries for Uninstallation
---------------------------------------------
-
-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
-``stage`` attribute to the ``native`` tag in the install xml file like
-
-::
-
- <!-- The native section. We specify here our os dependant
- libs..--> <native type="3rdparty"
- name="MyOSHelper.dll"stage="both" >
- <os family="windows" />
- </native>
-
-
-The needed additional classes are packed into lib/uninstaller-ext.jar. If a
-native library is defined for uninstallation, this file will also be packed
-into the installer.jar as IzPack.unistaller-ext and used at its right
-position.
-
-
-What You Have To Do
-----------------------
-
-Follow the steps that are needed to create and use custom actions with the
-"normal" source environment (not standalone compiler) using Ant. Of course,
-it works also with the standalone compiler.
-
-
-
-Custom Actions at Packaging (CompilerListener)
-----------------------------------------------------------
-
-- Implement ``com.izforge.izpack.event.CompilerListener`` or extend
- ``com.izforge.izpack.event.SimpleCompilerListener``. Place it as ``
- [IzPackRoot]/src/lib/[MyPackagePath]/MyCompilerListener.java``.
-- Add a "``build-compiler-listener``" macro call in to the
- ``build.listeners`` target in ``[IzPackRoot]/src/build.xml``. Note that
- the name attribute value in the build-instealler-listener must match
- ``CompilerListener`` implementation class name (not including the
- package). You should include the actual Listener implementation, as well
- as any other classes required by the listener.
-
- ::
-
- <build-compiler-listener
- name="MyCompilerListener">
- <include
- name="[MyPackagePath]/MyCompilerListener.java"/>
- <include
- name="[MyPackagePath]/SomeOtherHelperClass.java"/>
- </build-compiler-listener>
-
-- Run ``[IzPackRoot]/src/build.xml``. An ``ant`` alone will execute the
- required targets.
-- Add a "listeners" ELEMENT with a "listener" ELEMENT with a "compiler"
- attribute in to [MyProjectPath]/install.xml
-
- ::
-
- <listeners>
- <listener compiler="MyCompilerListener" />
- <listeners>
-
-- Compile with the following command, or an ant task you have set up.
-
- ::
-
- java -jar [IzPackRoot]/lib/compiler.jar -HOME [IzPackRoot]
- [MyProjectPath]/install.xml -b [MyProductPath] -o
- [MyBuildPath]/install.jar
-
-- Test it
-
-
-Custom Actions at Installation Time (InstallerListener)
-------------------------------------------------------------------
-
-Perform the same steps as above, replace all occurrences of
-"CompilerListener" with "InstallerListener" and "compiler" with "installer".
-
-
-Custom Actions at Uninstallation Time (UninstallerListener)
-------------------------------------------------------------------
-
-Perform the same steps as above, replace all occurrences of
-"CompilerListener" with "UninstallerListener"and "compiler" with
-"uninstaller".
-
-
-Example
-----------------------
-
-Let us say, we want to set access rights for files and directories on Unix.
-The Java sources are placed in the directory
-``[IzPackRoot]/sample/src/com/myCompany/tools/install/listener``. There are
-the files ChmodCompilerListener.java and ChmodInstallerListener.java.
-
-- Copy the files to ``[IzPackRoot]/src/lib/com/myCompany/tools/install/listener``
-- In ``[IzPackRoot]/src/build.xml`` there are the lines
-
- ::
-
- <!-- CUSTOM ACTION test START
- CUSTOM ACTION test END -->
-
- Uncomment them (activate the lines between them).
-- Build IzPack new.
-- Compile a test installation with
-
- ::
-
- java -jar [IzPackRoot]/lib/compiler.jar -HOME [IzPackRoot]
- [IzPackRoot]/sample/listener/install.xml
- -b [IzPackRoot]/sample/listener -o
- [IzPackRoot]/sample/listener/install.jar
-
-- Install it
-
- ::
-
- java -jar install.jar
-
-
-
-Ant Actions (InstallerListener and UninstallerListener)
-------------------------------------------------------------------
-
-In this section the common ant task 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 ant related custom
-actions ``AntActionInstallerListener`` and ``AntActionUninstallerListener``.
-As recapitulation, to add any custom action a reference in install.xml will
-be needed, as example:
-
-
-::
-
- <listeners>
- <listener installer="AntActionInstallerListener"
- uninstaller="AntActionUninstallerListener" />
- </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 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 ``pack`` 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 `` AntActionsSpec.xml``
-e.g.
-
-
-::
-
- <resorces>
- ...
- <res id="AntActionsSpec.xml"
- src="myInstallSpecs/MyAntActionsSpec.xml" />
- ...
- </resorces>
-
-
-The precise spelling of the id is important. The base path of ``src`` is the
-installation project path. If you want to use ant, 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/ant/ant.jar" stage="both" />
-
-
-Be aware, that an "extended" ant use needs more than one jar, for example
-often ``xercesImpl.jar``. If an obscure "class not found" exception is raised
-during testing, check first for missing jar files.
-For supporting uninstallation the jar field was extended by the attribute
-``stage``. If an ant uninstaller custom action is used, the uninstaller also
-needs the jar files. If `` stage`` is "both" or "uninstall", 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
-``meta-inf/Manifest.mf`` will be lost.
-
-
-
-The Basic XML Struture
-----------------------
-
-An ant action will be defined in the resource with the id
-"AntActionsSpec.xml". Sometimes it will help to lock into
-``[IzPackRoot]/src/dtd/event/antaction.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 ``<antactions>``. Only one is possible.
-The ``<antactions>`` 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 ``<antcall>`` (without ssss).
-
-The ``<antcall>`` takes the following attributes:
-
-- ``order``: required. Determine at what point of installation the
- antcalls defined by element ``target`` should be performed. Possible are
- ``beforepack``, ``afterpack``, ``beforepacks`` or ``afterpacks``. 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.
-- ``uninstall_order``: optional. Determine at what point of
- uninstallation the antcalls defined by element ``uninstall_target``
- should be performed. Possible are ``beforedeletion`` and
- ``afterdeletion``. As opposed to the behaviour of ``order`` the
- referenced files are also accessible in the order ``afterdeletion``. The
- uninstaller action copies the files into tempfiles before deletion which
- are marked as deleteOnExit.
-- ``quiet``: optional. To quit or not. Possible are yes or no. Default
- is no.
-- ``verbose``: optional. To output verbose information or not. Possible
- are yes or no. Default is no.
-- ``logfile``: optional. Path of the file for logging should be
- performed. The logfile should be not marked for uninstallation otherwise
- it will be deleted too.
-- ``buildfile``: required. Path of the file which contains the antcall.
- This is the file you normally use as ``-buildfile`` 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 ``IzPack`` variable in an ant buildfile.
-- ``messageid``: optional. A string ID which refers to
- ``bin/langpacks/installer/<lang>.xml``. If it is defined, the message
- will be displayed in the InstallPanel whilst performing the ant call.
-
-In addition to the possible attributes there are some elements. All elements
-can be defined more than one time in one ``<antcall>``. All are optional, but
-with no ``<target>`` element the ``<antcall>`` makes no sense. Do not confuse
-the following: "required"s are related to the attributes of the elements, not
-to the elements themselfs.
-
-
-
-``<property>``: define a property
-'''''''''''''''''''''''''''''''''''
-
-Property to be used with all ``target`` and ``uninstall_target`` which are
-defined for this antcall.
-
-- ``name``: required. The name (id) of the property.
-- ``value``: required. The value of the property.
-
-
-
-``<propertyfile>``: define properties in a file
-''''''''''''''''''''''''''''''''''''''''''''''''
-
-Properties to be used with all targets and uninstall_targets which are
-defined for this antcall given by the path of a properties file.
-
-- ``path``: 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
- ``<uninstall_target>`` was defined in this `` <antcall>``. This implies,
- that other ``<antcall>``s can have a ``<uninstall_target>``.
-
-
-
-``<target>``: target to call at installation
-''''''''''''''''''''''''''''''''''''''''''''''''
-
-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 ``IzPack`` project with ``ant clean``
-
-- ``name``: required. The name of the target.
-
-
-
-``<uninstall_target>``: target to call on uninstallation
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
-
-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.
-
-- ``name``: required. The name of the uninstall target.
-
-
-Registry access (InstallerListener and UninstallerListener)
-------------------------------------------------------------
-
-The event package of ``IzPack`` contains an installer and an uninstaller
-listener for Windows registry access. The listeners uses the separated pack
-*com.coi.tools* which is also available as source under the src subtree of
-``IzPack``. The registry will be called by JNI.
-
-The registry stuff was implemented in all conscience, but certainly WITHOUT
-WARRANTIES OR CONDITIONS OF ANY KIND
-
-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.
-
-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:
-
-::
-
- <listeners>
- <listener installer="RegistryInstallerListener"
- uninstaller="RegistryUninstallerListener" >
- <os family="windows"/>
- </listener>
- </listeners>
-
-
-It is also recomanded to add the uninstaller listener because it is usual to
-cleanup the registry at uninstallation. The listeners are only used on
-Windows, therefore we declare it.
-
-As with other listeners a jar file with the same name has to exist in
-``[IzPackRoot]/bin/customActions``. If compilation (packaging) fails with an
-"not found" error, verify, that the jar file exists. If not, create it. The
-jar files are ``RegistryInstallerListener.jar`` and
-``RegistryUninstallerListener.jar``.
-
-As second change in ``install.xml`` we have to declare the native part JNI
-needs the dll
-
-::
-
- <native type="3rdparty" name="COIOSHelper.dll" stage="both">
- <os family="windows"/>
- </native>
-
-
-The dll should be placed in ``[IzPackRoot]/bin/native/3rdparty``. The stage
-"both" marks this dll not only to be put into the installation jar file but
-also to be put into the uninstallation jar file. This will automatically be
-performed by the packager and installation.
-
-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.:
-
-::
-
- IzPack 4.6.8 (build 2007.02.15)
-
-
-The variables will be defined from the entries <appname> and <appversion> in
-the <info> element of the installation definition file.
-
-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 ``install.xml`` as
-resource:
-
-::
-
- <resources>
- ...
- <res src="mySubPath/MyRegistrySpec.xml"
- id="RegistrySpec.xml"/>
- </resources>
-
-
-The id has to be ``RegistrySpec.xml``. The real file name is not of any
-importance but should be written the same as in your source tree. It will be
-securer if you do not use special chars like blanks or umlauts. Be aware! If
-you forget to refer to ``registrySpec.xml`` in your ``install.xml`` no
-exception will be made because this is a facultative file
-
-
-The Basic XML Struture
---------------------------
-
-The specification file for registry entries will be defined in the resource
-with the id "ReigstrySpec.xml". Sometimes it will help to lock into
-``[IzPackRoot]/src/dtd/event/registry.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 ``<registry>``. Only one is possible. The
-``<registry>`` is 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. Valid "things" are <key> <value>.
-
-The registry stuff self allows to create keys and values directly under a
-registry root. But Windows self allows this not on "real" 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 "wrong parameter", not "permission denied".
-
-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_MACHINE\Software\Classes. Why not write directly
-there?Reading is in opposite to writing no problem.
-
-
-``<key>``: define a key
-''''''''''''''''''''''''
-
-Key to be set at installation time into the Windows registry.
-
-- ``keypath`` : 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.
-- ``root`` : required. The root of the key as symbol. Valid is one of
- HKCR HKCU HKLM HKU HKPD HKCC HKDDS.
-
-
-``<value>``: define a value
-''''''''''''''''''''''''''''
-
-Value to be set at installation time into the Windows registry.
-
-- ``name`` : required. The name of the value to be set or modified
- without a path.
- The default value will be written as the empty string "".
-- ``keypath`` : 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 "".
-- ``root`` : required. The root of the key as symbol. Valid is one of
- HKCR HKCU HKLM HKU HKPD HKCC HKDDS.
-- ``override`` : optional. Override an existent value or not. Valid is
- "true" or "false", default is "true".
-- ``Contents part``: accurately one of the following content elements
- should be defined. It implicit defines the type of the value.
-
- - ``string`` : contents for value to be set if it is a string.
- - ``dword`` : contents for value to be set if it is an integer
- (Windows DWORD). Only digits are valid. "48" is valid, "0x30" will be
- raise an NumberFormatException from ``java.lang.Long.parseLong``.
- - ``<bin>`` : element to handle one "line" of binary data.
-
- - ``data`` : contents for value of type BINARY written as
- comma separated list of hex. Only hex-digits are valid. "48, f4" is
- valid, "0x48, 0xf4" will be raise an NumberFormatException from
- ``java.lang.Integer.parseInt``.
-
- - ``<multi>``: element to handle one contents string for
- MULTI_STRINGs.
-
- - ``data`` : the contents for the element <multi>.
-
-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:
-
-::
-
- <registry>
- ...
- <pack name="Core">
- <value name="Path"
- keypath="SOFTWARE\IzForge\IzPack\$APP_VER"
- root="HKLM"
- string="$INSTALL_PATH"/>
- <value name="DWORD"
- keypath="SOFTWARE\IzForge\IzPack\$APP_VER"
- root="HKLM"
- dword="42"/>
- <value name="BIN"
- keypath="SOFTWARE\IzForge\IzPack\$APP_VER"
- root="HKLM" >
- <bin data="42, 49, 4e, 20, 54, 45, 53, 54" />
- <bin data="42, 49, 4e, 20, 54, 45, 53, 54" />
- </value>
- <value name="MULTI"
- keypath="SOFTWARE\IzForge\IzPack\$APP_VER"
- root="HKLM" >
- <multi data="A multi string with three elements" />
- <multi data="Element two"/>
- <multi data="Element three"/>
- </value>
- </pack>
- </registry>
-
-Extended Uninstall Key
-----------------------
-
-There is a special pack named ``UninstallStuff``. If a pack will be declared
-like ::
-
- <name="UninstallStuff">
-
-the incorporated elements will be used for creating the uninstall key and
-values instead of the build-in behavior. This pack name should be not used at
-an other point of the installation. It is a virtual and should be used only
-in ``RegistrySpec.xml``.
-
-The registry handler self cannot ensure the uniqueness of an uninstaller key.
-There is the special panel ``CheckedHelloPanel`` which does it. If no pack
-``UninstallStuff`` will be used, this will be performed full automatically.
-If the pack was declared, **all** keypaths under it should be written as
-following:
-
-::
-
- ...
- <value name="DisplayName"
- keypath="SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\$UNI
- NSTALL_NAME"
- root="HKLM"
- string="$UNINSTALL_NAME"/>
- ...
-
-
-The IzPack variable ``$UNINSTALL_NAME`` will be defined in the
-``CheckedHelloPanel``. With the "normal" ``HelloPanel`` it is undefined and
-the uninstall key catches the name "$UNINSTALL_NAME".
-
-
-Uninstall Behavior
-------------------
-
-During uninstallation the deletion or modification of written keys or values
-will be performed depending to the following rules:
-
-- A review of the registry will be performed only on supported
- operating systems (current only on Windows).
-- A review of the registry will be performed only if the registry stuff
- was bound for uninstallation.
-- Keys: Keys can only be deleted, a modification is not possible.
-
- - A previous existent key will be NOT deleted.
- - A newly created key will be deleted, if...
-
- - no new values or subkeys are added after installation.
- - no changes are made at the contents of values after
- installation.
-
- With other words: if under the key something was changed
- between installation and uninstallation, the key will be persist.
-
-- Values:
-
- - A newly created value will be deleted, if the contents at
- uninstall time is the same as after installation.
- - 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.
-
- 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).
-
-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
---------
-
-There are the files
-
-::
-
- [IzPackRoot]/src/dist-files/IzPack-install-reg.xml
- [IzPackRoot]/src/dist-files/RegistrySpec.xml
-
-
-``IzPack-install-reg.xml`` contains additional to the normal definition the
-stuff needed to create an ``IzPack`` installer which sets on Windows an
-extended uninstall key and some keys and values under a "private" key.
-Compare with the "normal" installation definition of IzPack.
-
-``RegistrySpec.xml`` will be referred by ``IzPack-install-reg.xml`` as
-resource. It contains the special pack named ``UninstallStuff`` for Izpack
-and defines some additional keys and values.
-
-
-Summary Logger (InstallerListener)
-------------------------------------------------------------
-
-The listener ``SummaryLoggerInstallerListener`` 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.
-
-::
-
- <listeners>
- <listener installer="SummaryLoggerInstallerListener"
- uninstaller="SummaryLoggerInstallerListener" >
- <os family="windows"/>
- </listener>
- </listeners>
-
-
-The default path is
-
-::
-
- $INSTALL_PATH/Uninstaller/InstallSummary.htm
-
-It can be changed with the subelement ``summarylogfilepath`` of the element
-``info`` of the installation description file. As example:
-
-::
-
- <info>
- ...
- <summarylogfilepath>
- $INSTALL_PATH/Uninstaller/MySummary.htm
- </summarylogfilepath>
- </info>
-
Added: izpack-src/trunk/src/doc-reST/pdf-version.txt
===================================================================
--- izpack-src/trunk/src/doc-reST/pdf-version.txt 2007-11-07 06:54:18 UTC (rev 1889)
+++ izpack-src/trunk/src/doc-reST/pdf-version.txt 2007-11-07 07:59:37 UTC (rev 1890)
@@ -0,0 +1,19 @@
+////////////////////////
+IzPack documentation
+////////////////////////
+
+.. WARNING:: This is a work in progress and should not be used as a reference...
+
+.. contents::
+
+.. include:: introduction.txt
+.. include:: getting-started.txt
+.. include:: installation-files.txt
+.. include:: advanced-features.txt
+.. include:: desktop-shortcuts.txt
+.. include:: creating-panels.txt
+.. include:: user-input.txt
+.. include:: custom-actions.txt
+.. include:: apache-license.txt
+.. include:: cc-license.txt
+.. include:: cookbooks.txt
Copied: izpack-src/trunk/src/doc-reST/user-input.txt (from rev 1888, izpack-src/trunk/src/doc-reST/node8.html.txt)
More information about the izpack-changes
mailing list