svn-gvsig-desktop / branches / v2_0_0_prep / build / distribution / IzPack / doc / izpack / html / node9.html @ 23393
History | View | Annotate | Download (29.8 KB)
| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|---|---|
| 2 |
|
| 3 |
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
|
| 4 |
original version by: Nikos Drakos, CBLU, University of Leeds
|
| 5 |
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
|
| 6 |
* with significant contributions from:
|
| 7 |
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
|
| 8 |
<HTML>
|
| 9 |
<HEAD>
|
| 10 |
<TITLE>Custom Actions</TITLE> |
| 11 |
<META NAME="description" CONTENT="Custom Actions"> |
| 12 |
<META NAME="keywords" CONTENT="izpack-doc"> |
| 13 |
<META NAME="resource-type" CONTENT="document"> |
| 14 |
<META NAME="distribution" CONTENT="global"> |
| 15 |
|
| 16 |
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1"> |
| 17 |
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| 18 |
|
| 19 |
<LINK REL="STYLESHEET" HREF="izpack-doc.css"> |
| 20 |
|
| 21 |
<LINK REL="next" HREF="node10.html"> |
| 22 |
<LINK REL="previous" HREF="node8.html"> |
| 23 |
<LINK REL="up" HREF="izpack-doc.html"> |
| 24 |
<LINK REL="next" HREF="node10.html"> |
| 25 |
</HEAD>
|
| 26 |
|
| 27 |
<BODY > |
| 28 |
|
| 29 |
<DIV CLASS="navigation"><!--Navigation Panel--> |
| 30 |
<A NAME="tex2html514" |
| 31 |
HREF="node10.html"> |
| 32 |
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> |
| 33 |
<A NAME="tex2html510" |
| 34 |
HREF="izpack-doc.html"> |
| 35 |
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> |
| 36 |
<A NAME="tex2html504" |
| 37 |
HREF="node8.html"> |
| 38 |
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> |
| 39 |
<A NAME="tex2html512" |
| 40 |
HREF="node1.html"> |
| 41 |
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> |
| 42 |
<BR>
|
| 43 |
<B> Next:</B> <A NAME="tex2html515" |
| 44 |
HREF="node10.html">The GNU General Public</A> |
| 45 |
<B> Up:</B> <A NAME="tex2html511" |
| 46 |
HREF="izpack-doc.html">izpack-doc</A> |
| 47 |
<B> Previous:</B> <A NAME="tex2html505" |
| 48 |
HREF="node8.html">User Input</A> |
| 49 |
<B> <A NAME="tex2html513" |
| 50 |
HREF="node1.html">Contents</A></B> |
| 51 |
<BR>
|
| 52 |
<BR></DIV> |
| 53 |
<!--End of Navigation Panel-->
|
| 54 |
<!--Table of Child-Links-->
|
| 55 |
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A> |
| 56 |
|
| 57 |
<UL CLASS="ChildLinks"> |
| 58 |
<LI><A NAME="tex2html516" |
| 59 |
HREF="node9.html#SECTION00910000000000000000">Overview</A> |
| 60 |
<LI><A NAME="tex2html517" |
| 61 |
HREF="node9.html#SECTION00920000000000000000">How It Works</A> |
| 62 |
<UL>
|
| 63 |
<LI><A NAME="tex2html518" |
| 64 |
HREF="node9.html#SECTION00921000000000000000">Custom Action Types</A> |
| 65 |
<UL>
|
| 66 |
<LI><A NAME="tex2html519" |
| 67 |
HREF="node9.html#SECTION00921100000000000000">Custom Actions At Packaging</A> |
| 68 |
<UL>
|
| 69 |
<LI><A NAME="tex2html520" |
| 70 |
HREF="node9.html#SECTION00921110000000000000">UML Diagram</A> |
| 71 |
<LI><A NAME="tex2html521" |
| 72 |
HREF="node9.html#SECTION00921120000000000000">Description</A> |
| 73 |
</UL>
|
| 74 |
<LI><A NAME="tex2html522" |
| 75 |
HREF="node9.html#SECTION00921200000000000000">Custom Actions At Installing Time</A> |
| 76 |
<UL>
|
| 77 |
<LI><A NAME="tex2html523" |
| 78 |
HREF="node9.html#SECTION00921210000000000000">UML Diagram</A> |
| 79 |
<LI><A NAME="tex2html524" |
| 80 |
HREF="node9.html#SECTION00921220000000000000">Description</A> |
| 81 |
</UL>
|
| 82 |
<LI><A NAME="tex2html525" |
| 83 |
HREF="node9.html#SECTION00921300000000000000">Custom Actions At Uninstalling Time</A> |
| 84 |
<UL>
|
| 85 |
<LI><A NAME="tex2html526" |
| 86 |
HREF="node9.html#SECTION00921310000000000000">UML Diagram</A> |
| 87 |
<LI><A NAME="tex2html527" |
| 88 |
HREF="node9.html#SECTION00921320000000000000">Description</A> |
| 89 |
</UL>
|
| 90 |
</UL>
|
| 91 |
<LI><A NAME="tex2html528" |
| 92 |
HREF="node9.html#SECTION00922000000000000000">Package Path</A> |
| 93 |
<LI><A NAME="tex2html529" |
| 94 |
HREF="node9.html#SECTION00923000000000000000">Correlated Stuff</A> |
| 95 |
<UL>
|
| 96 |
<LI><A NAME="tex2html530" |
| 97 |
HREF="node9.html#SECTION00923100000000000000">Native Libraries for Uninstallation</A> |
| 98 |
</UL>
|
| 99 |
</UL>
|
| 100 |
<BR>
|
| 101 |
<LI><A NAME="tex2html531" |
| 102 |
HREF="node9.html#SECTION00930000000000000000">What You Have To Do</A> |
| 103 |
<UL>
|
| 104 |
<LI><A NAME="tex2html532" |
| 105 |
HREF="node9.html#SECTION00931000000000000000">Custom Actions at Packaging (CompilerListener)</A> |
| 106 |
<LI><A NAME="tex2html533" |
| 107 |
HREF="node9.html#SECTION00932000000000000000">Custom Actions at Installation Time (InstallerListener)</A> |
| 108 |
<LI><A NAME="tex2html534" |
| 109 |
HREF="node9.html#SECTION00933000000000000000">Custom Actions at Uninstallation Time |
| 110 |
(UninstallerListener)</A>
|
| 111 |
</UL>
|
| 112 |
<BR>
|
| 113 |
<LI><A NAME="tex2html535" |
| 114 |
HREF="node9.html#SECTION00940000000000000000">Example</A> |
| 115 |
<LI><A NAME="tex2html536" |
| 116 |
HREF="node9.html#SECTION00950000000000000000">Ant Actions (InstallerListener and UninstallerListener)</A> |
| 117 |
<UL>
|
| 118 |
<LI><A NAME="tex2html537" |
| 119 |
HREF="node9.html#SECTION00951000000000000000">The Basic XML Struture</A> |
| 120 |
<UL>
|
| 121 |
<LI><A NAME="tex2html538" |
| 122 |
HREF="node9.html#SECTION00951100000000000000"><TT><property></TT>: define a property</A> |
| 123 |
<LI><A NAME="tex2html539" |
| 124 |
HREF="node9.html#SECTION00951200000000000000"><TT><propertyfile></TT>: define properties in a file</A> |
| 125 |
<LI><A NAME="tex2html540" |
| 126 |
HREF="node9.html#SECTION00951300000000000000"><TT><target></TT>: target to call at installation</A> |
| 127 |
<LI><A NAME="tex2html541" |
| 128 |
HREF="node9.html#SECTION00951400000000000000"><TT><uninstall_target></TT>: target to call on uninstallation</A> |
| 129 |
</UL></UL></UL> |
| 130 |
<!--End of Table of Child-Links-->
|
| 131 |
<HR>
|
| 132 |
|
| 133 |
<H1><A NAME="SECTION00900000000000000000"></A><A NAME="cha:customactions"></A> |
| 134 |
<BR>
|
| 135 |
Custom Actions |
| 136 |
</H1> (by Klaus B<SMALL>ARTZ</SMALL>) |
| 137 |
|
| 138 |
<P>
|
| 139 |
|
| 140 |
<H1><A NAME="SECTION00910000000000000000"> |
| 141 |
Overview</A>
|
| 142 |
</H1>
|
| 143 |
|
| 144 |
<P>
|
| 145 |
In general the installation procedure is separated into several |
| 146 |
steps. The first step, let's call it the <SPAN CLASS="textit">data collection phase</SPAN>, |
| 147 |
is getting specific data needed for the installation process. |
| 148 |
Typically this is done by typing all neded data into one or more panels, |
| 149 |
if a GUI is used, or automatically by reading the data from a config file. |
| 150 |
In general nothing will be changed on the system until all needed data is |
| 151 |
obtained. But mostly - depending on to the information, e.g. the |
| 152 |
destination path - different input panels are involved. |
| 153 |
|
| 154 |
<P>
|
| 155 |
If all needed data is collected the second step will be perfomed, |
| 156 |
let us call it the <SPAN CLASS="textit">action phase</SPAN>. During this step the state of |
| 157 |
the locale machine will be changed, e.g. files will be copied to |
| 158 |
the installation destination or some short cuts will be registered. |
| 159 |
Each of this subsequent steps are denoted as actions. There are actions |
| 160 |
intended to be reused, so called common actions, and actions for one special |
| 161 |
purpose only, so called custom actions. In IzPack there are already some |
| 162 |
common actions, for example "file transfer", "parse" or "execute". |
| 163 |
|
| 164 |
<P>
|
| 165 |
The third step, the <SPAN CLASS="textit">reporting phase</SPAN>, is normally |
| 166 |
represented by a panel that reports the result state of the installation |
| 167 |
(OK, or not OK) and a simple good bye message. |
| 168 |
|
| 169 |
<P>
|
| 170 |
With IzPack there are two ways to implement custom actions. Firstly |
| 171 |
it is always possible to define a custom panel that perfoms the desired |
| 172 |
actions too. Secondly, and that's the new, custom actions are supported. |
| 173 |
|
| 174 |
<P>
|
| 175 |
Panels still may be used for actions that are perfomed, e.g. |
| 176 |
before files are transferred or after the "execute" action. |
| 177 |
But if the needed action depends on the selected or already installed |
| 178 |
packages, this works also, but the implementation effort is much higher. |
| 179 |
|
| 180 |
<P>
|
| 181 |
If the action should be performed for several amount of elements of a |
| 182 |
pack, using custom actions will be more easy than using panels. |
| 183 |
Additional custom actions may be defined for installation, but also for |
| 184 |
packaging and uninstallation purposes. If a custom action is also needed |
| 185 |
for uninstallation purposes, it'll be always a good idea to implement a |
| 186 |
corresponding installation action as custom action, but not as panel. |
| 187 |
|
| 188 |
<P>
|
| 189 |
|
| 190 |
<H1><A NAME="SECTION00920000000000000000"> |
| 191 |
How It Works</A>
|
| 192 |
</H1>
|
| 193 |
|
| 194 |
<P>
|
| 195 |
Custom actions are implemented as listeners. Each listener implements |
| 196 |
callback methods that will be called at well-defined points. The method |
| 197 |
<TT>InstallerListener.afterFile</TT> for example will be called after |
| 198 |
a file has been copied. There are different interfaces intended for being |
| 199 |
used at packaging time, at installation time and at uninstallation time. |
| 200 |
|
| 201 |
<P>
|
| 202 |
Each interface is implemented by a class with the prefix |
| 203 |
"Simple" (e.g. SimpleCompilerListener) that implements all declared interface |
| 204 |
methods with an empty body. These classes may be used as base classes |
| 205 |
for own listener implementations. |
| 206 |
|
| 207 |
<P>
|
| 208 |
To apply custom actions to the installer, an entry in the apropriate |
| 209 |
install.xml file is needed. The configuration of listeners starts with |
| 210 |
the facultative ELEMENT "listeners" which can contain one or more ELEMENTs |
| 211 |
of "listener". For a "listener" there are three attributes which determine the |
| 212 |
"compiler", "installer" and "uninstaller" custom action pupose. |
| 213 |
Additionally it is possible to make the listener OS dependent using the "os" |
| 214 |
ELEMENT. |
| 215 |
|
| 216 |
<P>
|
| 217 |
If file related data will be set, the facultative ELEMENT |
| 218 |
"additionaldata" is defined for the ELEMENTs "file", "singlefile" |
| 219 |
and "fileset". This data will be automatically moved to the |
| 220 |
corresponding PackFile objects in the install.jar. Extraction and |
| 221 |
usage should be implemented in a install custom action (see |
| 222 |
example). |
| 223 |
|
| 224 |
<P>
|
| 225 |
|
| 226 |
<H2><A NAME="SECTION00921000000000000000"> |
| 227 |
Custom Action Types</A>
|
| 228 |
</H2>
|
| 229 |
|
| 230 |
<P>
|
| 231 |
Custom actions are intended to be used at packaging time, at installation time |
| 232 |
and at uninstallation time. The interfaces are: |
| 233 |
<DIV ALIGN="CENTER"> |
| 234 |
<TABLE CELLPADDING=3 BORDER="1"> |
| 235 |
<TR><TH ALIGN="LEFT"><SPAN CLASS="textit">Custom action type</SPAN></TH> |
| 236 |
<TH ALIGN="LEFT"><SPAN CLASS="textit">Interface name</SPAN></TH> |
| 237 |
</TR>
|
| 238 |
<TR><TD ALIGN="LEFT">Packaging</TD> |
| 239 |
<TD ALIGN="LEFT">com.izforge.izpack.event.CompilerListener</TD> |
| 240 |
</TR>
|
| 241 |
<TR><TD ALIGN="LEFT">Installation</TD> |
| 242 |
<TD ALIGN="LEFT">com.izforge.izpack.event.InstallerListener</TD> |
| 243 |
</TR>
|
| 244 |
<TR><TD ALIGN="LEFT">Uninstallation</TD> |
| 245 |
<TD ALIGN="LEFT">com.izforge.izpack.event.UninstallerListener</TD> |
| 246 |
</TR>
|
| 247 |
</TABLE>
|
| 248 |
</DIV>
|
| 249 |
|
| 250 |
<P>
|
| 251 |
|
| 252 |
<H3><A NAME="SECTION00921100000000000000"> |
| 253 |
Custom Actions At Packaging</A>
|
| 254 |
</H3>
|
| 255 |
|
| 256 |
<P>
|
| 257 |
|
| 258 |
<H4><A NAME="SECTION00921110000000000000"> |
| 259 |
UML Diagram</A>
|
| 260 |
</H4>
|
| 261 |
|
| 262 |
<P>
|
| 263 |
<DIV ALIGN="CENTER"> |
| 264 |
<!-- MATH
|
| 265 |
$\fbox{\includegraphics[scale=1.0]{img/CompilerListener}}$
|
| 266 |
-->
|
| 267 |
<SPAN CLASS="MATH"><IMG |
| 268 |
WIDTH="206" HEIGHT="138" ALIGN="MIDDLE" BORDER="0" |
| 269 |
SRC="img12.png" |
| 270 |
ALT="\fbox{\includegraphics[scale=1.0]{img/CompilerListener}}"></SPAN> |
| 271 |
</DIV>
|
| 272 |
<P>
|
| 273 |
|
| 274 |
<H4><A NAME="SECTION00921120000000000000"> |
| 275 |
Description</A>
|
| 276 |
</H4>
|
| 277 |
|
| 278 |
<P>
|
| 279 |
|
| 280 |
<UL>
|
| 281 |
<LI><SPAN CLASS="textit">(constructor)</SPAN> : only the default constructor will |
| 282 |
be used. It is called from Compiler just after creating the packager. |
| 283 |
Therefore initializing will be better during in the first <TT>notify</TT> call. |
| 284 |
|
| 285 |
<P>
|
| 286 |
</LI>
|
| 287 |
<LI><TT>reviseAdditionalDataMap</TT> gives the facility to add |
| 288 |
data to each <TT>PackFile</TT> object. This is the place where |
| 289 |
file related data can be transferred from the install xml file |
| 290 |
into the install jar file. Although each key and value of the map can be any |
| 291 |
type, but the class definitions of all used types must therfore be contained |
| 292 |
in the installer jar file or in the VM's classpath. In general strings |
| 293 |
are the best choice for being used as keys or values. All keys must be |
| 294 |
unique over all registered <TT>CompilerListeners</TT>. Each call of this |
| 295 |
method adds own key value pairs to the given <TT>existenDataMap</TT> because |
| 296 |
more than one listener can be used. If the given map is null, a |
| 297 |
new one will be created. |
| 298 |
|
| 299 |
<P>
|
| 300 |
</LI>
|
| 301 |
<LI><TT>notify</TT> is called at the beginning and at the end of each |
| 302 |
"add" method call which is called in <TT>Compiler.executeCompiler</TT>. |
| 303 |
|
| 304 |
<P>
|
| 305 |
</LI>
|
| 306 |
</UL>
|
| 307 |
<P>
|
| 308 |
|
| 309 |
<H3><A NAME="SECTION00921200000000000000"> |
| 310 |
Custom Actions At Installing Time</A>
|
| 311 |
</H3>
|
| 312 |
|
| 313 |
<P>
|
| 314 |
|
| 315 |
<H4><A NAME="SECTION00921210000000000000"> |
| 316 |
UML Diagram</A>
|
| 317 |
</H4>
|
| 318 |
|
| 319 |
<P>
|
| 320 |
<DIV ALIGN="CENTER"> |
| 321 |
<!-- MATH
|
| 322 |
$\fbox{\includegraphics[scale=1.0]{img/InstallerListener}}$
|
| 323 |
-->
|
| 324 |
<SPAN CLASS="MATH"><IMG |
| 325 |
WIDTH="293" HEIGHT="278" ALIGN="MIDDLE" BORDER="0" |
| 326 |
SRC="img13.png" |
| 327 |
ALT="\fbox{\includegraphics[scale=1.0]{img/InstallerListener}}"></SPAN> |
| 328 |
</DIV>
|
| 329 |
<P>
|
| 330 |
|
| 331 |
<H4><A NAME="SECTION00921220000000000000"> |
| 332 |
Description</A>
|
| 333 |
</H4>
|
| 334 |
|
| 335 |
<P>
|
| 336 |
|
| 337 |
<UL>
|
| 338 |
<LI><SPAN CLASS="textit">(constructor)</SPAN> : only the default constructor will |
| 339 |
be used. It is called from <TT>Unpacker.run</TT> before unpacking. |
| 340 |
|
| 341 |
<P>
|
| 342 |
</LI>
|
| 343 |
<LI><TT>beforePacks</TT> will be called each time before an unpacking |
| 344 |
call is performed. |
| 345 |
|
| 346 |
<P>
|
| 347 |
</LI>
|
| 348 |
<LI><TT>beforePack</TT> is called before a package is |
| 349 |
installed. Pack object and the number of the pack are passed. |
| 350 |
|
| 351 |
<P>
|
| 352 |
</LI>
|
| 353 |
<LI><TT>isFileListener</TT> determines whether the next four |
| 354 |
methods are called or not. This is a little performance optimizing. |
| 355 |
|
| 356 |
<P>
|
| 357 |
</LI>
|
| 358 |
<LI><TT>beforeDir</TT> is called before a directory is created. |
| 359 |
In this case, when file listeners exist, directories are created |
| 360 |
recursively and the method is called at each step. The file and the |
| 361 |
current <TT>PackFile</TT> object are passed. |
| 362 |
</LI>
|
| 363 |
<LI><TT>afterDir</TT> is called directly after the directory |
| 364 |
creation. |
| 365 |
</LI>
|
| 366 |
<LI><TT>beforeFile</TT> is called before a file is created. The file |
| 367 |
and <TT>PackFile</TT> object are passed as parameters. |
| 368 |
</LI>
|
| 369 |
<LI><TT>afterFile</TT> is the best place to perform file |
| 370 |
related actions. The given <TT>PackFile</TT> objects contains |
| 371 |
the additional data which was set at packaging. |
| 372 |
</LI>
|
| 373 |
<LI><TT>afterPack</TT> will be just called after the pack is |
| 374 |
closed. |
| 375 |
</LI>
|
| 376 |
<LI><TT>afterPacks</TT> is the last step before the handler |
| 377 |
will be stopped. |
| 378 |
</LI>
|
| 379 |
</UL>
|
| 380 |
<P>
|
| 381 |
|
| 382 |
<H3><A NAME="SECTION00921300000000000000"> |
| 383 |
Custom Actions At Uninstalling Time</A>
|
| 384 |
</H3>
|
| 385 |
|
| 386 |
<P>
|
| 387 |
|
| 388 |
<H4><A NAME="SECTION00921310000000000000"> |
| 389 |
UML Diagram</A>
|
| 390 |
</H4>
|
| 391 |
|
| 392 |
<P>
|
| 393 |
<DIV ALIGN="CENTER"> |
| 394 |
<!-- MATH
|
| 395 |
$\fbox{\includegraphics[scale=1.0]{img/UninstallerListener}}$
|
| 396 |
-->
|
| 397 |
<SPAN CLASS="MATH"><IMG |
| 398 |
WIDTH="215" HEIGHT="199" ALIGN="MIDDLE" BORDER="0" |
| 399 |
SRC="img14.png" |
| 400 |
ALT="\fbox{\includegraphics[scale=1.0]{img/UninstallerListener}}"></SPAN> |
| 401 |
</DIV>
|
| 402 |
<P>
|
| 403 |
|
| 404 |
<H4><A NAME="SECTION00921320000000000000"> |
| 405 |
Description</A>
|
| 406 |
</H4>
|
| 407 |
|
| 408 |
<P>
|
| 409 |
|
| 410 |
<UL>
|
| 411 |
<LI><SPAN CLASS="textit">(constructor)</SPAN> : only the default constructor will |
| 412 |
be used. It is called from <TT>Destroyer.run</TT> as first call. |
| 413 |
</LI>
|
| 414 |
<LI><TT>beforeDeletion</TT> will be called after execute files was performed. |
| 415 |
The given list contains all <SPAN CLASS="textit">File</SPAN> objects which are marked for deletion. |
| 416 |
</LI>
|
| 417 |
<LI><TT>isFileListener</TT> determines whether the next two |
| 418 |
methods are called or not. |
| 419 |
</LI>
|
| 420 |
<LI><TT>beforeDelete</TT> is the method which, is called before |
| 421 |
a single file is deleted. The <SPAN CLASS="textit">File</SPAN> object is given as |
| 422 |
parameter. |
| 423 |
</LI>
|
| 424 |
<LI><TT>afterDelete</TT> will be invoked after the delete call |
| 425 |
for a single file. |
| 426 |
</LI>
|
| 427 |
<LI><TT>afterDeletion</TT> is the last call before the |
| 428 |
cleanup of created data is performed. |
| 429 |
</LI>
|
| 430 |
</UL>
|
| 431 |
<P>
|
| 432 |
|
| 433 |
<H2><A NAME="SECTION00922000000000000000"> |
| 434 |
Package Path</A>
|
| 435 |
</H2>
|
| 436 |
Custom actions must always implement one of the given listener |
| 437 |
interfaces. As mentioned above, it is also possible to derive from |
| 438 |
one of the "Simple" listeners. The package path is facultative, only the |
| 439 |
class name must be unique over all custom actions. The preparation of a |
| 440 |
custom action for providing it with an installation is very similar to panels. |
| 441 |
Custom actions must also be packed into a jar file with the name |
| 442 |
of the custom action class name. This jar file should be placed in |
| 443 |
<TT>[IzPackRoot]/bin/customActions</TT>, may be |
| 444 |
<PRE>
|
| 445 |
[IzPackRoot]/bin/customActions/MyCompilerListener.jar |
| 446 |
[IzPackRoot]/bin/customActions/MyInstallerListener.jar |
| 447 |
[IzPackRoot]/bin/customActions/MyUninstallerListener.jar |
| 448 |
</PRE>
|
| 449 |
In the default Ant definition file (build.xml) there are some |
| 450 |
targets for this stuff. |
| 451 |
|
| 452 |
<P>
|
| 453 |
|
| 454 |
<H2><A NAME="SECTION00923000000000000000"> |
| 455 |
Correlated Stuff</A>
|
| 456 |
</H2>
|
| 457 |
|
| 458 |
<H3><A NAME="SECTION00923100000000000000"> |
| 459 |
Native Libraries for Uninstallation</A>
|
| 460 |
</H3>
|
| 461 |
If a custom action uses JNI at installation time, often the |
| 462 |
associated uninstall custom action needs JNI too. For this |
| 463 |
situation it is possible to declare a native library for |
| 464 |
unstallation. The only work to do is to add a <TT>stage</TT> |
| 465 |
attribute to the <TT>native</TT> tag in the install xml file like |
| 466 |
<PRE>
|
| 467 |
<!-- The native section. We specify here our os dependant
|
| 468 |
libs..--> <native type="3rdparty" |
| 469 |
name="MyOSHelper.dll"stage="both" >
|
| 470 |
<os family="windows" /> |
| 471 |
</native> |
| 472 |
</PRE>
|
| 473 |
<P>
|
| 474 |
The needed additional classes are packed into |
| 475 |
lib/uninstaller-ext.jar. If a native library is defined for |
| 476 |
uninstallation, this file will also be packed into the |
| 477 |
installer.jar as IzPack.unistaller-ext and used at its right |
| 478 |
position. |
| 479 |
|
| 480 |
<P>
|
| 481 |
|
| 482 |
<H1><A NAME="SECTION00930000000000000000"> |
| 483 |
What You Have To Do</A>
|
| 484 |
</H1>
|
| 485 |
Follow the steps that are needed to create and use custom actions |
| 486 |
with the "normal" source environment (not standalone compiler) |
| 487 |
using Ant. Of course, it works also with the standalone compiler. |
| 488 |
|
| 489 |
<P>
|
| 490 |
|
| 491 |
<H2><A NAME="SECTION00931000000000000000"></A><A NAME="sec:caPackaging"></A> |
| 492 |
<BR>
|
| 493 |
Custom Actions at Packaging (CompilerListener) |
| 494 |
</H2>
|
| 495 |
|
| 496 |
<P>
|
| 497 |
|
| 498 |
<UL>
|
| 499 |
<LI>Implement <TT>com.izforge.izpack.event.CompilerListener</TT> or |
| 500 |
extend <TT>com.izforge.izpack.event.SimpleCompilerListener</TT>. |
| 501 |
Place it as <TT>[IzPackRoot]/src/lib/[MyPackagePath]/MyCompilerListener.java</TT>. |
| 502 |
|
| 503 |
<P>
|
| 504 |
</LI>
|
| 505 |
<LI>Add a "compile.simple" antcall in to <TT>[IzPackRoot]/src/build.xml</TT>. |
| 506 |
<PRE>
|
| 507 |
<antcall target="compile.listener.simple"> |
| 508 |
<param name="listener" value="MyCompilerListener"/> |
| 509 |
<param name="listener-dir" value="MyCompilerListener"/> |
| 510 |
<param name="listener-include" value="[MyPackagePath]"/> |
| 511 |
</antcall> |
| 512 |
</PRE>
|
| 513 |
<P>
|
| 514 |
</LI>
|
| 515 |
<LI>Run <TT>[IzPackRoot]/src/build.xml</TT>. |
| 516 |
|
| 517 |
<P>
|
| 518 |
</LI>
|
| 519 |
<LI>Add a "listeners" ELEMENT with a "listener" ELEMENT with
|
| 520 |
a "compiler" attribute in to [MyProjectPath]/install.xml |
| 521 |
<PRE>
|
| 522 |
<listeners> |
| 523 |
<listener compiler="MyCompilerListener" /> |
| 524 |
<listeners> |
| 525 |
</PRE>
|
| 526 |
<P>
|
| 527 |
</LI>
|
| 528 |
<LI>Compile with
|
| 529 |
<PRE>
|
| 530 |
java -jar [IzPackRoot]/lib/compiler.jar -HOME [IzPackRoot] |
| 531 |
[MyProjectPath]/install.xml -b [MyProductPath] -o |
| 532 |
[MyBuildPath]/install.jar |
| 533 |
</PRE>
|
| 534 |
<P>
|
| 535 |
</LI>
|
| 536 |
<LI>Test it
|
| 537 |
</LI>
|
| 538 |
</UL>
|
| 539 |
<P>
|
| 540 |
|
| 541 |
<H2><A NAME="SECTION00932000000000000000"> |
| 542 |
Custom Actions at Installation Time (InstallerListener)</A>
|
| 543 |
</H2>
|
| 544 |
Perform the same steps as described in <A HREF="#sec:caPackaging">7.3.1</A>, replace |
| 545 |
all occurrences of "CompilerListener" with "InstallerListener" and |
| 546 |
"compiler" with "installer". |
| 547 |
|
| 548 |
<P>
|
| 549 |
|
| 550 |
<H2><A NAME="SECTION00933000000000000000"> |
| 551 |
Custom Actions at Uninstallation Time |
| 552 |
(UninstallerListener)</A>
|
| 553 |
</H2> Perform the same steps as described in
|
| 554 |
<A HREF="#sec:caPackaging">7.3.1</A>, replace all occurrences of |
| 555 |
"CompilerListener" with "UninstallerListener"and "compiler" with |
| 556 |
"uninstaller". |
| 557 |
|
| 558 |
<P>
|
| 559 |
|
| 560 |
<H1><A NAME="SECTION00940000000000000000"> |
| 561 |
Example</A>
|
| 562 |
</H1>
|
| 563 |
Let us say, we want to set access rights for files and directories |
| 564 |
on Unix. The Java sources are placed in the directory |
| 565 |
<BR><TT>[IzPackRoot]/sample/src/com/myCompany/tools/install/listener</TT>. |
| 566 |
There are the files ChmodCompilerListener.java and |
| 567 |
ChmodInstallerListener.java. |
| 568 |
|
| 569 |
<UL>
|
| 570 |
<LI>Copy the files too
|
| 571 |
[IzPackRoot]/src/lib/com/myCompany/tools/install/listener |
| 572 |
</LI>
|
| 573 |
<LI>In [IzPackRoot]/src/build.xml there are the lines
|
| 574 |
<PRE>
|
| 575 |
<!-- CUSTOM ACTION test START
|
| 576 |
CUSTOM ACTION test END -->
|
| 577 |
</PRE>Uncomment them (activate the lines between them).
|
| 578 |
</LI>
|
| 579 |
<LI>Build IzPack new.
|
| 580 |
</LI>
|
| 581 |
<LI>Compile a test installation with
|
| 582 |
<PRE>
|
| 583 |
java -jar [IzPackRoot]/lib/compiler.jar -HOME [IzPackRoot] |
| 584 |
[IzPackRoot]/sample/listener/install.xml |
| 585 |
-b [IzPackRoot]/sample/listener -o |
| 586 |
[IzPackRoot]/sample/listener/install.jar |
| 587 |
</PRE>
|
| 588 |
</LI>
|
| 589 |
<LI>Install it
|
| 590 |
<PRE>
|
| 591 |
java -jar install.jar |
| 592 |
</PRE>
|
| 593 |
</LI>
|
| 594 |
</UL>
|
| 595 |
<P>
|
| 596 |
|
| 597 |
<H1><A NAME="SECTION00950000000000000000"> |
| 598 |
Ant Actions (InstallerListener and UninstallerListener)</A>
|
| 599 |
</H1>
|
| 600 |
In this section the common ant task custom actions are described |
| 601 |
in detail. It is only for developers who are not acquainted |
| 602 |
with <TT>IzPack</TT> or it's custom actions. In addition to the |
| 603 |
basics there are some recapitulations of the common custom |
| 604 |
action techniques and some hints for pitfalls. |
| 605 |
<BR>
|
| 606 |
In the package <TT>com.izforge.izpack.event</TT> there are the ant |
| 607 |
related custom actions <TT>AntActionInstallerListener</TT> and |
| 608 |
<TT>AntActionUninstallerListener</TT>. As recapitulation, to add |
| 609 |
any custom action a |
| 610 |
reference in install.xml will be needed, as example: |
| 611 |
<BR><PRE> |
| 612 |
<listeners> |
| 613 |
<listener installer="AntActionInstallerListener"
|
| 614 |
uninstaller="AntActionUninstallerListener" />
|
| 615 |
</listeners> |
| 616 |
</PRE>
|
| 617 |
<P>
|
| 618 |
For all referenced listeners a jar file with the same name must |
| 619 |
exist in <TT>[IzPackRoot]/bin/customActions</TT>. If compilation |
| 620 |
(packaging) fails with a "not found" error, first |
| 621 |
verify, that the jar file exists. If not, create it. |
| 622 |
<BR>
|
| 623 |
With this custom action it is possible to perform ant calls at |
| 624 |
installation and/or uninstallation time. It is not only a wrapper |
| 625 |
for a comand-line ant call, but also an intersected description file |
| 626 |
defining what target of the ant build file should be performed at |
| 627 |
what time of (un)installation and specifies which properties for what IzPack |
| 628 |
<TT>pack</TT> are to be used. The intersected description file is written as XML, |
| 629 |
the corresponding dtd is placed in |
| 630 |
src/dtd/event/antaction.dtd. The description file should be declared as a |
| 631 |
resource in the install.xml with the id <TT>AntActionsSpec.xml</TT> e.g. |
| 632 |
<BR>
|
| 633 |
<P>
|
| 634 |
<PRE>
|
| 635 |
<resorces> |
| 636 |
... |
| 637 |
<res id="AntActionsSpec.xml" src="myInstallSpecs/MyAntActionsSpec.xml" /> |
| 638 |
... |
| 639 |
</resorces> |
| 640 |
</PRE>
|
| 641 |
<P>
|
| 642 |
The precise spelling of the id is important. The base path of <TT>src</TT> |
| 643 |
is the installation project path. If you want to use ant, you have to specify it here. |
| 644 |
IzPack is designed for running without dependencies on external software or libraries. |
| 645 |
Therefore it is necessary to include everything needed, in this case ant self. |
| 646 |
The field <TT><jar></TT> in |
| 647 |
installation.xml is predestinated for such cases, e.g. |
| 648 |
<BR><PRE> |
| 649 |
<jar src="jar/ant/ant.jar" stage="both" /> |
| 650 |
</PRE>
|
| 651 |
|
| 652 |
<P>
|
| 653 |
Be aware, that an "extended" ant use needs more than one jar, for |
| 654 |
example often <TT>xercesImpl.jar</TT>. If an obscure "class not |
| 655 |
found" exception is raised during testing, check first for missing |
| 656 |
jar files. |
| 657 |
<BR>
|
| 658 |
For supporting uninstallation the jar field was extended by the |
| 659 |
attribute <TT>stage</TT>. If an ant uninstaller custom action is |
| 660 |
used, the uninstaller also needs the jar files. If <TT>stage</TT> |
| 661 |
is "both" or "uninstall", the contents of the referenced jar file |
| 662 |
will be packed into uninstaller.jar. Be aware that not the jar file |
| 663 |
itself, but the contents of it are required. This implies, that the paths of the |
| 664 |
contained files are unique and the information in |
| 665 |
<TT>meta-inf/Manifest.mf</TT> will be lost. |
| 666 |
<BR>
|
| 667 |
<H2><A NAME="SECTION00951000000000000000"> |
| 668 |
The Basic XML Struture</A>
|
| 669 |
</H2>
|
| 670 |
An ant action will be defined in the resource with the id |
| 671 |
"AntActionsSpec.xml". Sometimes it will help to lock into |
| 672 |
<TT>[IzPackRoot]/src/dtd/event/antaction.dtd</TT> or validate a |
| 673 |
written xml file with the dtd. |
| 674 |
<BR>
|
| 675 |
On this xml file a substitution will be performed using all |
| 676 |
defined <TT>IzPack</TT> variables. It is performed just before |
| 677 |
processing the packs. This is a common way of loading spec files |
| 678 |
into custom actions. For more information see method |
| 679 |
<TT>com.izforge.izpack.util.SpecHelper.readSpec</TT>. |
| 680 |
If you want to substitute some custom item, simply add a variable |
| 681 |
via idata.setVariable in a custom panel before <TT>InstallPanel</TT>. |
| 682 |
The given variable name (id) should be written into the xml file |
| 683 |
in the common variable notation. |
| 684 |
<BR>
|
| 685 |
<P>
|
| 686 |
The top level XML section is called <TT><antactions></TT>. Only |
| 687 |
one is possible. The <TT><antactions></TT> are segregated in one or more |
| 688 |
<TT><pack></TT> elements. The single attribute <TT><name></TT> of |
| 689 |
the <TT><pack></TT> corresponds to the same structure in |
| 690 |
install.xml (for more information see also installation.dtd). Only the |
| 691 |
"things" included in the <TT><pack></TT> are performed, if a |
| 692 |
pack with the same name was chosen to be installed. The "things" |
| 693 |
to be done to self are defined by the element <TT><antcall></TT> (without |
| 694 |
ssss). |
| 695 |
<BR>
|
| 696 |
The <TT><antcall></TT> takes the following attributes: |
| 697 |
|
| 698 |
<UL>
|
| 699 |
<LI><TT>order</TT>: required. Determine at what point of installation the antcalls |
| 700 |
defined by element <TT>target</TT> should be |
| 701 |
performed. Possible are |
| 702 |
<TT>beforepack</TT>, <TT>afterpack</TT>, <TT>beforepacks</TT> or <TT>afterpacks</TT>. Be aware that |
| 703 |
with beforepack(s) there are no installed files and also no installed |
| 704 |
build file. With this order only preexistent build files are |
| 705 |
useable. |
| 706 |
|
| 707 |
<P>
|
| 708 |
</LI>
|
| 709 |
<LI><TT>uninstall_order</TT>: optional. Determine at what point of uninstallation |
| 710 |
the antcalls defined by element <TT>uninstall_target</TT> |
| 711 |
should be performed. Possible are <TT>beforedeletion</TT> |
| 712 |
and <TT>afterdeletion</TT>. As opposed to the |
| 713 |
behaviour of <TT>order</TT> the referenced files |
| 714 |
are also accessible in the order |
| 715 |
<TT>afterdeletion</TT>. The |
| 716 |
uninstaller action copies the files into |
| 717 |
tempfiles before deletion which are marked as deleteOnExit. |
| 718 |
</LI>
|
| 719 |
<LI><TT>quiet</TT>: optional. To quit or not. Possible are yes or |
| 720 |
no. Default is no. |
| 721 |
</LI>
|
| 722 |
<LI><TT>verbose</TT>: optional. To output verbose information or not. Possible are yes |
| 723 |
or no. Default is no. |
| 724 |
</LI>
|
| 725 |
<LI><TT>logfile</TT>: optional. Path of the file for logging should |
| 726 |
be performed. The logfile should be not marked for |
| 727 |
uninstallation otherwise it will be deleted too. |
| 728 |
</LI>
|
| 729 |
<LI><TT>buildfile</TT>: required. Path of the file which contains the |
| 730 |
antcall. This is the file you normally use as <TT>-buildfile</TT> during an ant call via the command |
| 731 |
line. In this file variables are not substituted. For |
| 732 |
substitution there are properties in ant which can be used. |
| 733 |
Never write an <TT>IzPack</TT> variable in an ant buildfile. |
| 734 |
</LI>
|
| 735 |
<LI><TT>messageid</TT>: optional. A string ID which refers to |
| 736 |
<BR> <TT>bin/langpacks/installer/<lang>.xml</TT>. If it is defined, the message |
| 737 |
will be displayed in the InstallPanel whilst performing the ant call. |
| 738 |
</LI>
|
| 739 |
</UL>
|
| 740 |
In addition to the possible attributes there are some elements. All |
| 741 |
elements can be defined more than one time in one |
| 742 |
<TT><antcall></TT>. All are optional, but with no |
| 743 |
<TT><target></TT> element the <TT><antcall></TT> makes no sense. |
| 744 |
Do not confuse the following: "required"s are related to the |
| 745 |
attributes of the elements, not to the elements themselfs. |
| 746 |
|
| 747 |
<H3><A NAME="SECTION00951100000000000000"></A><A NAME="tag:antproperty"></A> |
| 748 |
<BR>
|
| 749 |
<TT><property></TT>: define a property |
| 750 |
</H3>
|
| 751 |
Property to be used with all <TT>target</TT>s and |
| 752 |
<TT>uninstall_target</TT>s which are defined for this antcall. |
| 753 |
|
| 754 |
<UL>
|
| 755 |
<LI><TT>name</TT>: required. The name (id) of the property. |
| 756 |
</LI>
|
| 757 |
<LI><TT>value</TT>: required. The value of the property. |
| 758 |
</LI>
|
| 759 |
</UL>
|
| 760 |
<H3><A NAME="SECTION00951200000000000000"></A><A NAME="tag:antpropertyfile"></A> |
| 761 |
<BR>
|
| 762 |
<TT><propertyfile></TT>: define properties in a file |
| 763 |
</H3>
|
| 764 |
Properties to be used with all targets and uninstall_targets which |
| 765 |
are defined for this antcall given by the path of a properties |
| 766 |
file. |
| 767 |
|
| 768 |
<UL>
|
| 769 |
<LI><TT>path</TT>: required. Path of a file which contains |
| 770 |
properties in the syntax which is used by ant. Some ant calls |
| 771 |
need properties files. For these this element is used. One |
| 772 |
way to fill specific data into it is to create a new file in |
| 773 |
a custom panel and fill it with values given by input fields. |
| 774 |
The file path can be set at installation time, if there is a |
| 775 |
variable in AntActionSpec.xml and an IzPack variable was |
| 776 |
defined before InstallPanel. That file can be only created |
| 777 |
with deleteOnExit, if no <TT><uninstall_target></TT> was defined in |
| 778 |
this <TT><antcall></TT>. This implies, that other <TT><antcall></TT>s can |
| 779 |
have a <TT><uninstall_target></TT>. |
| 780 |
</LI>
|
| 781 |
</UL>
|
| 782 |
|
| 783 |
<P>
|
| 784 |
|
| 785 |
<H3><A NAME="SECTION00951300000000000000"></A><A NAME="tag:anttarget"></A> |
| 786 |
<BR>
|
| 787 |
<TT><target></TT>: target to call at installation |
| 788 |
</H3>
|
| 789 |
Targets to perform with this antcall at installation time. The |
| 790 |
targets should be defined in the given buildfile or else an ant |
| 791 |
exception will be raised. This is that what you use, if you don't want |
| 792 |
to perform the default target. e.g. cleaning the <TT>IzPack</TT> project with |
| 793 |
<TT>ant clean</TT> |
| 794 |
|
| 795 |
<P>
|
| 796 |
|
| 797 |
<UL>
|
| 798 |
<LI><TT>name</TT>: required. The name of the target. |
| 799 |
</LI>
|
| 800 |
</UL>
|
| 801 |
|
| 802 |
<P>
|
| 803 |
|
| 804 |
<H3><A NAME="SECTION00951400000000000000"></A><A NAME="tag:antuninsttarget"></A> |
| 805 |
<BR>
|
| 806 |
<TT><uninstall_target></TT>: target to call on uninstallation |
| 807 |
</H3>
|
| 808 |
Targets to perform with this antcall at uninstallation time. The |
| 809 |
targets should be defined in the given buildfile otherwise an ant |
| 810 |
exception will be raised. With this target it will be possible |
| 811 |
to undo the things done at installation time. |
| 812 |
|
| 813 |
<UL>
|
| 814 |
<LI><TT>name</TT>: required. The name of the uninstall target. |
| 815 |
</LI>
|
| 816 |
</UL>
|
| 817 |
|
| 818 |
<P>
|
| 819 |
|
| 820 |
<P>
|
| 821 |
|
| 822 |
<DIV CLASS="navigation"><HR> |
| 823 |
<!--Navigation Panel-->
|
| 824 |
<A NAME="tex2html514" |
| 825 |
HREF="node10.html"> |
| 826 |
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> |
| 827 |
<A NAME="tex2html510" |
| 828 |
HREF="izpack-doc.html"> |
| 829 |
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> |
| 830 |
<A NAME="tex2html504" |
| 831 |
HREF="node8.html"> |
| 832 |
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> |
| 833 |
<A NAME="tex2html512" |
| 834 |
HREF="node1.html"> |
| 835 |
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> |
| 836 |
<BR>
|
| 837 |
<B> Next:</B> <A NAME="tex2html515" |
| 838 |
HREF="node10.html">The GNU General Public</A> |
| 839 |
<B> Up:</B> <A NAME="tex2html511" |
| 840 |
HREF="izpack-doc.html">izpack-doc</A> |
| 841 |
<B> Previous:</B> <A NAME="tex2html505" |
| 842 |
HREF="node8.html">User Input</A> |
| 843 |
<B> <A NAME="tex2html513" |
| 844 |
HREF="node1.html">Contents</A></B> </DIV> |
| 845 |
<!--End of Navigation Panel-->
|
| 846 |
<ADDRESS>
|
| 847 |
Julien Ponge |
| 848 |
2005-04-22 |
| 849 |
</ADDRESS>
|
| 850 |
</BODY>
|
| 851 |
</HTML>
|