root / trunk / install / IzPack / doc / izpack / html / node9.html @ 11445
History | View | Annotate | Download (29 KB)
1 | 5819 | cesar | <!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> |