source: trunk/Distribution/SW/FOP/build/site/embedding.html

Last change on this file was 2, checked in by jkacer, 18 years ago

Added all DocBook Framework stuff:

  • DocBook DTD
  • Transformation software FOP 0.20.5 and Saxon 6
  • XSL styles
  • Rexx scripts

Also added some WarpIN-related stuff for creation of WarpIN installation packages.
This state corresponds to version 1.0.0 from November 2005, just slightly modified to carry versioning information (Rexx scripts).
File size: 33.8 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<head>
4<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5<title>Embedding FOP</title>
6<link type="text/css" href="skin/page.css" rel="stylesheet">
7</head>
8<body text="#000000" bgcolor="#FFFFFF">
9<!--================= start Navigation Path ==================-->
10<table summary="navigation path" width="100%" border="0" cellpadding="0" cellspacing="0">
11<tr>
12<td nowrap="nowrap" valign="middle" bgcolor="#CFDCED" height="20"><img height="1" width="5" alt="" border="0" src="skin/images/spacer.gif"><!--===== breadcrumb trail (javascript-generated) ====--><font size="2" face="Arial, Helvetica, Sans-serif"><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script></font></td>
13</tr>
14<tr>
15<td bgcolor="#4C6C8F" height="2"><img height="2" width="2" alt="" border="0" src="skin/images/spacer.gif"></td>
16</tr>
17</table>
18<!--================= end Navigation Path ==================-->
19<!--================= start Banner ==================-->
20<table summary="header with logos" width="100%" border="0" cellpadding="0" cellspacing="0">
21<tr>
22<!--================= start Group Logo ==================-->
23<td bgcolor="#294563"><a href="http://xml.apache.org/"><img border="0" class="logoImage" alt="Apache XML" src="images/group-logo.gif"></a></td>
24<!--================= end Group Logo ==================-->
25<!--================= start Project Logo ==================--><td width="100%" align="center" bgcolor="#294563"><a href="http://xml.apache.org/fop/"><img border="0" class="logoImage" alt="FOP" src="images/logo.jpg"></a></td>
26<!--================= end Project Logo ==================-->
27<!--================= start Search ==================--><td valign="top" rowspan="2" bgcolor="#294563">
28<form target="_blank" action="http://www.google.com/search" method="get">
29<table summary="search" border="0" cellspacing="0" cellpadding="0" bgcolor="#4C6C8F">
30<tr>
31<td colspan="3"><img height="10" width="1" alt="" src="skin/images/spacer.gif"></td>
32</tr>
33<tr>
34<td><img height="1" width="1" alt="" src="skin/images/spacer.gif"></td><td nowrap="nowrap"><input value="xml.apache.org" name="sitesearch" type="hidden"><input size="15" name="q" id="query" type="text"><img height="1" width="5" alt="" src="skin/images/spacer.gif"><input name="Search" value="Search" type="submit">
35<br>
36<font face="Arial, Helvetica, Sans-serif" size="2" color="white">
37 the Apache XML site
38
39
40 </font></td><td><img height="1" width="1" alt="" src="skin/images/spacer.gif"></td>
41</tr>
42<tr>
43<td><img alt="" border="0" height="10" width="9" src="skin/images/search-left.gif"></td><td><img height="1" width="1" alt="" src="skin/images/spacer.gif"></td><td><img alt="" border="0" height="10" width="9" src="skin/images/search-right.gif"></td>
44</tr>
45</table>
46</form>
47</td>
48<!--================= start Search ==================--><td bgcolor="#294563"><img height="10" width="10" alt="" src="skin/images/spacer.gif"></td>
49</tr>
50<tr>
51<td valign="bottom" bgcolor="#294563" colspan="2">
52<!--================= start Tabs ==================-->
53<div class="tab">
54<table summary="tab bar" border="0" cellpadding="0" cellspacing="0">
55<tr>
56<td width="8"><img alt="" height="8" width="8" src="skin/images/spacer.gif"></td><td valign="bottom">
57<table summary="selected tab" style="height: 1.7em" border="0" cellpadding="0" cellspacing="0">
58<tr>
59<td valign="top" width="5" bgcolor="#4C6C8F"><img height="5" width="5" alt="" src="skin/images/tabSel-left.gif"></td><td valign="middle" bgcolor="#4C6C8F"><font color="#ffffff" size="2" face="Arial, Helvetica, Sans-serif"><b><a href="index.html"><font color="#000000">Home</font></a></b></font></td><td valign="top" width="5" bgcolor="#4C6C8F"><img height="5" width="5" alt="" src="skin/images/tabSel-right.gif"></td>
60</tr>
61</table>
62</td><td width="8"><img alt="" height="8" width="8" src="skin/images/spacer.gif"></td><td valign="bottom">
63<table summary="non selected tab" style="height: 1.6em" border="0" cellpadding="0" cellspacing="0">
64<tr>
65<td valign="top" width="5" bgcolor="#B2C4E0"><img height="5" width="5" alt="" src="skin/images/tab-left.gif"></td><td valign="middle" bgcolor="#B2C4E0"><a href="dev/index.html"><font face="Arial, Helvetica, Sans-serif">Development</font></a></td><td valign="top" width="5" bgcolor="#B2C4E0"><img height="5" width="5" alt="" src="skin/images/tab-right.gif"></td>
66</tr>
67</table>
68</td>
69</tr>
70</table>
71</div>
72<!--================= end Tabs ==================-->
73</td><td bgcolor="#294563"><img alt="" width="1" height="1" src="skin/images/spacer.gif"></td>
74</tr>
75<tr>
76<td bgcolor="#4C6C8F" colspan="4"><img width="1" height="10" alt="" src="skin/images/spacer.gif"></td>
77</tr>
78</table>
79<!--================= end Banner ==================-->
80<!--================= start Menu, NavBar, Content ==================-->
81<table summary="page content" bgcolor="#ffffff" width="100%" border="0" cellpadding="0" cellspacing="0">
82<tr>
83<td valign="top">
84<table summary="menu" border="0" cellspacing="0" cellpadding="0">
85<tr>
86<!--================= start left top NavBar ==================-->
87<td rowspan="3" valign="top">
88<table summary="blue line" border="0" cellpadding="0" cellspacing="0">
89<tr>
90<td bgcolor="#294563"><img width="10" height="1" alt="" src="skin/images/spacer.gif"></td>
91</tr>
92<tr>
93<td bgcolor="#CFDCED"><font color="#4C6C8F" size="4" face="Arial, Helvetica, Sans-serif">&nbsp;</font></td>
94</tr>
95<tr>
96<td bgcolor="#294563"><img width="10" height="1" alt="" src="skin/images/spacer.gif"></td>
97</tr>
98</table>
99</td>
100<!--================= end left top NavBar ==================--><td bgcolor="#294563"><img width="1" height="1" alt="" src="skin/images/spacer.gif"></td><td valign="bottom" bgcolor="#4C6C8F"><img width="10" height="10" alt="" src="skin/images/spacer.gif"></td><td nowrap="nowrap" valign="top" bgcolor="#4C6C8F">
101<!--================= start Menu items ==================-->
102<div class="menu">
103<ul>
104<li>
105<font color="#CFDCED">Home</font>
106<ul>
107
108<li>
109<a href="index.html">Introduction</a>
110</li>
111
112</ul>
113</li>
114<li>
115<font color="#CFDCED">Using FOP</font>
116<ul>
117
118<li>
119<a href="relnotes.html">Release Notes</a>
120</li>
121
122<li>
123<a href="download.html">Download</a>
124</li>
125
126<li>
127<a href="compiling.html">Build</a>
128</li>
129
130<li>
131<a href="configuration.html">Configure</a>
132</li>
133
134<li>
135<a href="running.html">Run</a>
136</li>
137
138<li>
139<span class="sel"><font color="#ffcc00">Embed</font></span>
140</li>
141
142<li>
143<a href="servlets.html">Servlets</a>
144</li>
145
146<li>
147<a href="anttask.html">Ant task</a>
148</li>
149
150</ul>
151</li>
152<li>
153<font color="#CFDCED">Features</font>
154<ul>
155
156<li>
157<a href="compliance.html">Compliance</a>
158</li>
159
160<li>
161<a href="output.html">Output Targets</a>
162</li>
163
164<li>
165<a href="pdfencryption.html">PDF encryption</a>
166</li>
167
168<li>
169<a href="graphics.html">Graphics</a>
170</li>
171
172<li>
173<a href="fonts.html">Fonts</a>
174</li>
175
176<li>
177<a href="hyphenation.html">Hyphenation</a>
178</li>
179
180<li>
181<a href="extensions.html">Extensions</a>
182</li>
183
184</ul>
185</li>
186<li>
187<font color="#CFDCED">Resources</font>
188<ul>
189
190<li>
191<a href="gethelp.html">Getting Help</a>
192</li>
193
194<li>
195<a href="faq.html">FAQs</a>
196</li>
197
198<li>
199<a href="fo.html">XSL-FO</a>
200</li>
201
202<li>
203<a href="examples.html">Examples</a>
204</li>
205
206<li>
207<a href="maillist.html">Mailing Lists</a>
208</li>
209
210<li>
211<a href="bugs.html">Bugs</a>
212</li>
213
214<li>
215<a href="license.html">License</a>
216</li>
217
218<li>
219<a href="resources.html">Other</a>
220</li>
221
222</ul>
223</li>
224<li>
225<font color="#CFDCED">Project</font>
226<ul>
227
228<li>
229<a href="news.html">News</a>
230</li>
231
232<li>
233<a href="logocontest.html">Logo contest</a>
234</li>
235
236<li>
237<a href="status.html">Status</a>
238</li>
239
240
241<li>
242<a href="team.html">Team</a>
243</li>
244
245</ul>
246</li>
247</ul>
248</div>
249<!--================= end Menu items ==================-->
250</td><td valign="bottom" bgcolor="#4C6C8F"><img width="10" height="10" alt="" src="skin/images/spacer.gif"></td><td bgcolor="#294563"><img width="1" height="1" alt="" src="skin/images/spacer.gif"></td>
251</tr>
252<tr>
253<td valign="bottom" align="left" colspan="2" rowspan="2" bgcolor="#4C6C8F"><img height="10" width="10" border="0" alt="" src="skin/images/menu-left.gif"></td><td bgcolor="#4C6C8F"><img height="10" width="10" border="0" alt="" src="skin/images/spacer.gif"></td><td valign="bottom" align="right" colspan="2" rowspan="2" bgcolor="#4C6C8F"><img height="10" width="10" border="0" alt="" src="skin/images/menu-right.gif"></td>
254</tr>
255<tr>
256<td height="1" bgcolor="#294563"><img width="1" height="1" alt="" src="skin/images/spacer.gif"></td>
257</tr>
258</table>
259</td><td valign="top" width="100%">
260<table summary="content" width="100%" border="0" cellpadding="0" cellspacing="0">
261<!--================= start middle NavBar ==================-->
262<tr>
263<td colspan="4" bgcolor="#294563"><img width="10" height="1" alt="" src="skin/images/spacer.gif"></td>
264</tr>
265<tr>
266<td align="left" width="10" bgcolor="#CFDCED"><img width="10" height="1" alt="" src="skin/images/spacer.gif"></td><td align="left" width="50%" bgcolor="#CFDCED"><font color="#4C6C8F" size="3" face="Arial, Helvetica, Sans-serif">
267 &nbsp;
268
269 </font><img width="10" height="8" alt="" src="skin/images/spacer.gif"></td><td align="right" width="50%" bgcolor="#CFDCED"><font color="#4C6C8F" size="3" face="Arial, Helvetica, Sans-serif">
270 &nbsp;
271
272 </font><img width="10" height="8" alt="" src="skin/images/spacer.gif"></td><td width="10" bgcolor="#CFDCED"><img width="10" height="1" alt="" src="skin/images/spacer.gif"></td>
273</tr>
274<tr>
275<td colspan="4" bgcolor="#294563"><img width="10" height="1" alt="" src="skin/images/spacer.gif"></td>
276</tr>
277<!--================= end middle NavBar ==================-->
278<!--================= start Content==================-->
279<tr>
280<td align="left" width="10"><img width="10" height="1" alt="" src="skin/images/spacer.gif"></td><td align="left" width="100%">
281<div class="content">
282<table class="title" summary="">
283<tr>
284<td valign="middle">
285<h1>Embedding FOP</h1>
286</td><td nowrap="nowrap" width="80" align="center"><a class="dida" href="embedding.pdf"><img alt="printer" src="skin/images/printer.gif" border="0"><br>
287 print-friendly<br>
288 PDF</a></td>
289</tr>
290</table>
291<h3>How to Embed FOP in a Java application</h3>
292<ul class="minitoc">
293<li>
294<a href="#overview">Overview</a>
295</li>
296<li>
297<a href="#basics">Basics</a>
298<ul class="minitoc">
299<li>
300<a href="#basic-logging">Logging</a>
301</li>
302<li>
303<a href="#render">Processing XSL-FO</a>
304</li>
305<li>
306<a href="#render-with-xslt">Processing XSL-FO generated from XML+XSLT</a>
307</li>
308</ul>
309</li>
310<li>
311<a href="#logging">Controlling logging</a>
312</li>
313<li>
314<a href="#input">Input Sources</a>
315</li>
316<li>
317<a href="#config-external">Using a Configuration File</a>
318</li>
319<li>
320<a href="#config-internal">Setting the Configuration Programmatically</a>
321</li>
322<li>
323<a href="#hints">Hints</a>
324<ul class="minitoc">
325<li>
326<a href="#object-reuse">Object reuse</a>
327</li>
328<li>
329<a href="#awt">AWT issues</a>
330</li>
331<li>
332<a href="#render-info">Getting information on the rendering process</a>
333</li>
334</ul>
335</li>
336<li>
337<a href="#performance">Improving performance</a>
338</li>
339<li>
340<a href="#multithreading">Multithreading FOP</a>
341</li>
342<li>
343<a href="#examples">Examples</a>
344<ul class="minitoc">
345<li>
346<a href="#ExampleFO2PDF">ExampleFO2PDF.java</a>
347</li>
348<li>
349<a href="#ExampleXML2FO">ExampleXML2FO.java</a>
350</li>
351<li>
352<a href="#ExampleXML2PDF">ExampleXML2PDF.java</a>
353</li>
354<li>
355<a href="#ExampleObj2XML">ExampleObj2XML.java</a>
356</li>
357<li>
358<a href="#ExampleObj2PDF">ExampleObj2PDF.java</a>
359</li>
360<li>
361<a href="#example-notes">Final notes</a>
362</li>
363</ul>
364</li>
365</ul>
366
367<a name="N101C2"></a><a name="overview"></a>
368<h3>Overview</h3>
369<div style="margin-left: 0 ; border: 2px">
370<p>Review <a href="running.html">Running FOP</a> for important information that applies to embedded applications as well as command-line use, such as options and performance.
371 </p>
372<p>To embed FOP in your application, instantiate org.apache.fop.apps.Driver.
373 Once this class is
374 instantiated, methods are called to set the
375 Renderer to use
376 and the OutputStream to use to output the results of the
377 rendering (where applicable). In the case of the Renderer and
378 ElementMapping(s), the Driver may be supplied either with the
379 object itself, or the name of the class, in which case Driver will
380 instantiate the class itself. The advantage of the latter is it
381 enables runtime determination of Renderer and ElementMapping(s).
382 </p>
383</div>
384
385<a name="N101D3"></a><a name="basics"></a>
386<h3>Basics</h3>
387<div style="margin-left: 0 ; border: 2px">
388<p>The simplest way to use Driver is to instantiate it with the
389 InputSource and OutputStream, then set the renderer desired and
390 call the run method.
391 </p>
392<p>Here is an example use of Driver which outputs PDF:
393 </p>
394<pre class="code">
395import org.apache.fop.apps.Driver;
396
397/*..*/
398
399Driver driver = new Driver(new InputSource(args[0]),
400 new FileOutputStream(args[1]));
401driver.setRenderer(Driver.RENDER_PDF);
402driver.run();</pre>
403<p>
404In the example above, args[0] contains the path to an XSL-FO file, while
405args[1] contains a path for the target PDF file.
406 </p>
407<a name="N101E6"></a><a name="basic-logging"></a>
408<h4>Logging</h4>
409<div style="margin-left: 0 ; border: 2px">
410<p>
411 You also need to set up logging. Global logging for all FOP
412 processes is managed by MessageHandler. Per-instance logging
413 is handled by Driver. You want to set both using an implementation
414 of org.apache.avalon.framework.logger.Logger. See
415 <a target="_top" href="#logging">below</a> for more information.
416 </p>
417<p>
418 Call <span class="codefrag">setLogger(Logger)</span> always immediately after
419 instantiating the Driver object. See here:
420 </p>
421<pre class="code">
422import org.apache.avalon.framework.logger.Logger;
423import org.apache.avalon.framework.logger.ConsoleLogger;
424
425/*..*/
426
427Driver driver = new Driver();
428Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO);
429MessageHandler.setScreenLogger(logger);
430driver.setLogger(logger);</pre>
431</div>
432<a name="N101FE"></a><a name="render"></a>
433<h4>Processing XSL-FO</h4>
434<div style="margin-left: 0 ; border: 2px">
435<p>
436 Once the Driver is set up, one of the <span class="codefrag">render()</span> methods
437 is called. Depending on whether DOM or an InputSource is being used, the
438 invocation of the method is either <span class="codefrag">render(Document)</span> or
439 <span class="codefrag">render(Parser, InputSource)</span> respectively.
440 </p>
441<p>
442
443<strong>Another possibility may be used to build the FO Tree: You can
444 call <span class="codefrag">getContentHandler()</span> and fire the SAX events yourself.
445 </strong>
446 You don't have to call <span class="codefrag">run()</span> or <span class="codefrag">render()</span> on the
447 Driver object if you use <span class="codefrag">getContentHandler()</span>.
448 </p>
449<p>Here is an example use of Driver:</p>
450<pre class="code">
451Driver driver = new Driver();
452//Setup logging here: driver.setLogger(...
453driver.setRenderer(Driver.RENDER_PDF);
454driver.setInputSource(new FileInputSource(args[0]));
455driver.setOutputStream(new FileOutputStream(args[1]));
456driver.run();</pre>
457</div>
458<a name="N1022A"></a><a name="render-with-xslt"></a>
459<h4>Processing XSL-FO generated from XML+XSLT</h4>
460<div style="margin-left: 0 ; border: 2px">
461<p>
462 If you want to process XSL-FO generated from XML using XSLT we recommend
463 using standard JAXP to do the XSLT part and piping the generated SAX
464 events directly through to FOP. Here's how this would look like:
465 </p>
466<pre class="code">
467Driver driver = new Driver();
468//Setup logging here: driver.setLogger(...
469driver.setRenderer(Driver.RENDER_PDF);
470
471//Setup the OutputStream for FOP
472driver.setOutputStream(new java.io.FileOutputStream(outFile));
473
474//Make sure the XSL transformation's result is piped through to FOP
475Result res = new SAXResult(driver.getContentHandler());
476
477//Setup XML input
478Source src = new StreamSource(xmlFile);
479
480//Setup Transformer
481Source xsltSrc = new StreamSource(xslFile);
482TransformerFactory transformerFactory = TransformerFactory.newInstance();
483Transformer transformer = transformerFactory.newTransformer(xsltSrc);
484
485//Start the transformation and rendering process
486transformer.transform(src, res);</pre>
487<div class="frame note">
488<div class="label">Note</div>
489<div class="content">There's no need to call <span class="codefrag">run()</span> or <span class="codefrag">render()</span>.</div>
490</div>
491<p>
492 This may look complicated at first, but it's really just the combination of an
493 XSL transformation and a FOP run. It's also easy to comment out the FOP part
494 for debugging purposes, for example when you're tracking down a bug in your
495 stylesheet. You can easily write the XSL-FO output from the XSL transformation
496 to a file to check if that part generates the expected output.
497 </p>
498<p>
499 For fully working examples of the above and hints to some interesting
500 possibilities, see the <a href="#examples">examples section</a> below.
501 </p>
502</div>
503</div>
504
505<a name="N1024C"></a><a name="logging"></a>
506<h3>Controlling logging</h3>
507<div style="margin-left: 0 ; border: 2px">
508<p>
509 FOP uses the
510 <a target="_blank" href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/logger/package-summary.html">Logger package</a>
511 from Apache Avalon Framework to do logging. See the
512 <a target="_blank" href="http://avalon.apache.org/framework/">Apache Avalon Framework</a>
513 for more information.
514 </p>
515<p>
516 Per default FOP uses the ConsoleLogger which logs to System.out. If you want to do logging using a
517 logging framework (such as LogKit, Log4J or JDK 1.4 Logging) you can set a
518 different Logger implementation on the Driver object. Here's an example how you would use LogKit:
519 </p>
520<pre class="code">
521Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
522PatternFormatter formatter = new PatternFormatter(
523 "[%{priority}]: %{message}\n%{throwable}" );
524
525LogTarget target = null;
526target = new StreamTarget(System.out, formatter);
527
528hierarchy.setDefaultLogTarget(target);
529log = hierarchy.getLoggerFor("fop");
530log.setPriority(Priority.INFO);
531
532driver.setLogger(new org.apache.avalon.framework.logger.LogKitLogger(log));</pre>
533<p>
534 The LogKitLogger class implements the Logger interface so all logging calls are being redirected to LogKit.
535 More information on Jakarta LogKit can be found <a target="_blank" href="http://jakarta.apache.org/avalon/logkit/index.html">here</a>.
536 </p>
537<p>
538 Similar implementations exist for Log4J (org.apache.avalon.framework.logger.Log4JLogger) and
539 JDK 1.4 logging (org.apache.avalon.framework.logger.Jdk14Logger).
540 </p>
541<p>
542 If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.
543 </p>
544<p>
545 If you want to use yet another logging facility you simply have to create a class that
546 implements org.apache.avalon.framework.logging.Logger and set it on the Driver object.
547 See the existing implementations in Avalon Framework for examples.
548 </p>
549</div>
550
551<a name="N10275"></a><a name="input"></a>
552<h3>Input Sources</h3>
553<div style="margin-left: 0 ; border: 2px">
554<p>
555 The input XSL-FO document is always handled internally as SAX (see the
556 <a href="http://xml.apache.org/fop/design/parsing.html">Parsing Design Document</a> for the rationale).
557 However, the input itself can be provided in a variety of ways to FOP,
558 which normalizes the input (if necessary) into SAX events:
559 </p>
560<ul>
561
562<li>
563<strong>SAX Events through SAX Handler</strong>: <span class="codefrag">FOTreeBuilder</span> is the SAX Handler which is obtained through <span class="codefrag">getContentHandler</span> on <span class="codefrag">Driver</span>.</li>
564
565<li>
566<strong>DOM (which is converted into SAX Events)</strong>: The conversion of a DOM tree is done via the <span class="codefrag">render(Document)</span> method on <span class="codefrag">Driver</span>.</li>
567
568<li>
569<strong>Data Source (which is parsed and converted into SAX Events)</strong>: The <span class="codefrag">Driver</span> can take an <span class="codefrag">InputSource</span> as input.
570This can use a <span class="codefrag">Stream</span>, <span class="codefrag">String</span> etc.</li>
571
572<li>
573<strong>XML+XSLT Transformation</strong> (which is transformed using an XSLT Processor and the result is fired as SAX Events: <span class="codefrag">XSLTInputHandler</span> is used as an <span class="codefrag">InputSource</span> in the render(<span class="codefrag">XMLReader</span>, <span class="codefrag">InputSource</span>) method on <span class="codefrag">Driver</span>.</li>
574
575</ul>
576<p>
577 There are a variety of upstream data manipulations possible.
578 For example, you may have a DOM and an XSL stylesheet; or you may want to
579 set variables in the stylesheet. Interface documentation and some cookbook
580 solutions to these situations are provided in
581 <a target="_blank" href="http://xml.apache.org/xalan-j/usagepatterns.html">Xalan Basic Usage Patterns</a>.
582 </p>
583<p>
584 See the <a href="#examples">Examples</a> for some variations on input.
585 </p>
586</div>
587
588<a name="N102D2"></a><a name="config-external"></a>
589<h3>Using a Configuration File</h3>
590<div style="margin-left: 0 ; border: 2px">
591<p>
592 To access an external configuration:
593 </p>
594<pre class="code">
595import org.apache.fop.apps.Options;
596
597/*..*/
598
599userConfigFile = new File(userConfig);
600options = new Options(userConfigFile);</pre>
601<div class="frame note">
602<div class="label">Note</div>
603<div class="content">
604 This is all you need to do, it sets up a static configuration class.
605 </div>
606</div>
607<p>
608 No further reference to the <span class="codefrag">options</span> variable is necessary.
609 The "options = " is actually not even necessary.
610 </p>
611<p>
612 See <a href="#multithreading">Multithreading FOP</a> for issues related to changing configuration in a multithreaded environment.
613 </p>
614</div>
615
616<a name="N102F0"></a><a name="config-internal"></a>
617<h3>Setting the Configuration Programmatically</h3>
618<div style="margin-left: 0 ; border: 2px">
619<p>
620 If you wish to set configuration options from within your embedded application, use the <span class="codefrag">Configuration.put</span> method. Here is an example that sets the "baseDir" configuration in a Unix environment:
621 </p>
622<pre class="code">org.apache.fop.configuration.Configuration.put("baseDir","/my/base/dir");</pre>
623<p>
624 Here is another that sets baseDir in a Windows environment:
625 </p>
626<pre class="code">org.apache.fop.configuration.Configuration.put("baseDir","C:\my\base\dir");</pre>
627<p>
628 See <a href="#multithreading">Multithreading FOP</a> for issues related to changing configuration in a multithreaded environment.
629 </p>
630</div>
631
632<a name="N1030F"></a><a name="hints"></a>
633<h3>Hints</h3>
634<div style="margin-left: 0 ; border: 2px">
635<a name="N10315"></a><a name="object-reuse"></a>
636<h4>Object reuse</h4>
637<div style="margin-left: 0 ; border: 2px">
638<p>
639If FOP is going to be used multiple times within your application
640it may be useful to reuse certain objects to save time.
641 </p>
642<p>
643The renderers and the driver can both be reused. A renderer is reusable
644once the previous render has been completed. The driver is reuseable
645after the rendering is complete and the <span class="codefrag">reset()</span> method is called.
646You will need to setup the driver again with a new OutputStream,
647IntputStream and renderer.
648 </p>
649</div>
650<a name="N10325"></a><a name="awt"></a>
651<h4>AWT issues</h4>
652<div style="margin-left: 0 ; border: 2px">
653<p>
654 If your XSL-FO files contain SVG then Batik will be used. When Batik is
655 initialised it uses certain classes in <span class="codefrag">java.awt</span> that
656 intialises the java AWT classes. This means that a daemon thread
657 is created by the JVM and on Unix it will need to connect to a
658 DISPLAY.
659 </p>
660<p>
661 The thread means that the Java application may not automatically quit
662 when finished, you will need to call <span class="codefrag">System.exit()</span>. These
663 issues should be fixed in the upcoming JDK 1.4.
664 </p>
665<p>
666 If you run into trouble running FOP on a head-less server, please see the
667 <a href="graphics.html#batik">notes on Batik</a>.
668 </p>
669</div>
670<a name="N1033F"></a><a name="render-info"></a>
671<h4>Getting information on the rendering process</h4>
672<div style="margin-left: 0 ; border: 2px">
673<p>
674To get the number of pages that were rendered by FOP you can call
675<span class="codefrag">Driver.getResults()</span>. This returns a FormattingResults object
676where you can lookup the number of pages produced. It also gives you the
677page-sequences that were produced along with their id attribute and their
678number of pages. This is particularly useful if you render multiple
679documents (each enclosed by a page-sequence) and have to know the number of
680pages of each document.
681 </p>
682</div>
683</div>
684
685<a name="N1034D"></a><a name="performance"></a>
686<h3>Improving performance</h3>
687<div style="margin-left: 0 ; border: 2px">
688<p>
689 There are several options to consider:
690 </p>
691<ul>
692
693<li>
694 Whenever possible, try to use SAX to couple the individual components involved
695 (parser, XSL transformer, SQL datasource etc.).
696 </li>
697
698<li>
699 Depending on the target OutputStream (in case of an FileOutputStream, but not
700 for a ByteArrayOutputStream, for example) it may improve performance considerably
701 if you buffer the OutputStream using a BufferedOutputStream:
702 <span class="codefrag">driver.setOutputStream(new java.io.BufferedOutputStream(out));</span>
703
704<br>
705 Make sure you properly close the OutputStream when FOP is finished.
706 </li>
707
708<li>
709 Cache the stylesheet. If you use the same stylesheet multiple times
710 you can setup a JAXP <span class="codefrag">Templates</span> object and reuse it each time you do
711 the XSL transformation.
712 </li>
713
714<li>
715 Use an XSLT compiler like XSLTC that comes with Xalan-J.
716 </li>
717
718</ul>
719</div>
720
721<a name="N1036E"></a><a name="multithreading"></a>
722<h3>Multithreading FOP</h3>
723<div style="margin-left: 0 ; border: 2px">
724<p>
725 FOP is not currently completely thread safe.
726Although the relevant methods of the Driver object are synchronized, FOP uses static
727variables for configuration data and loading images.
728Here are some tips to mitigate these problems:
729 </p>
730<ul>
731
732<li>
733 To avoid having your threads blocked, create a Driver object for each thread.
734 </li>
735
736<li>
737 If possible, do not change the configuration data while there is a Driver object rendering.
738 Setup the configuration only once, preferably in the <span class="codefrag">init()</span> method of the servlet.
739 </li>
740
741<li>
742 If you must change the configuration data more often, or if you have multiple
743 servlets within the same webapp using FOP, consider implementing a singleton
744 class to encapsulate the configuration settings and to run FOP in synchronized methods.
745 </li>
746
747</ul>
748<p>There is also a known issue with fonts being jumbled between threads when using the AWT renderer (which is used by the -awt and -print output options).
749In general, you cannot safely run multiple threads through the AWT renderer.</p>
750</div>
751
752<a name="N1038A"></a><a name="examples"></a>
753<h3>Examples</h3>
754<div style="margin-left: 0 ; border: 2px">
755<p>
756The directory "{fop-fir}/examples/embedding" contains several working examples.
757In contrast of the examples above the examples here primarily use JAXP for
758XML access. This may be easier to understand for people familiar with JAXP.
759 </p>
760<a name="N10393"></a><a name="ExampleFO2PDF"></a>
761<h4>ExampleFO2PDF.java</h4>
762<div style="margin-left: 0 ; border: 2px">
763<p>
764This example demonstrates the basic usage pattern to transform an XSL-FO
765file to PDF using FOP.
766 </p>
767<div align="center">
768<img class="figure" alt="Example XSL-FO to PDF" src="images/EmbeddingExampleFO2PDF.png"></div>
769</div>
770<a name="N103A1"></a><a name="ExampleXML2FO"></a>
771<h4>ExampleXML2FO.java</h4>
772<div style="margin-left: 0 ; border: 2px">
773<p>
774This example has nothing to do with FOP. It is there to show you how an XML
775file can be converted to XSL-FO using XSLT. The JAXP API is used to do the
776transformation. Make sure you've got a JAXP-compliant XSLT processor in your
777classpath (ex. <a target="_blank" href="http://xml.apache.org/xalan-j">Xalan</a>).
778 </p>
779<div align="center">
780<img class="figure" alt="Example XML to XSL-FO" src="images/EmbeddingExampleXML2FO.png"></div>
781</div>
782<a name="N103B3"></a><a name="ExampleXML2PDF"></a>
783<h4>ExampleXML2PDF.java</h4>
784<div style="margin-left: 0 ; border: 2px">
785<p>
786This example demonstrates how you can convert an arbitrary XML file to PDF
787using XSLT and XSL-FO/FOP. It is a combination of the first two examples
788above. The example uses JAXP to transform the XML file to XSL-FO and FOP to
789transform the XSL-FO to PDF.
790 </p>
791<div align="center">
792<img class="figure" alt="Example XML to PDF (via XSL-FO)" src="images/EmbeddingExampleXML2PDF.png"></div>
793<p>
794The output (XSL-FO) from the XSL transformation is piped through to FOP using
795SAX events. This is the most efficient way to do this because the
796intermediate result doesn't have to be saved somewhere. Often, novice users
797save the intermediate result in a file, a byte array or a DOM tree. We
798strongly discourage you to do this if it isn't absolutely necessary. The
799performance is significantly higher with SAX.
800 </p>
801</div>
802<a name="N103C4"></a><a name="ExampleObj2XML"></a>
803<h4>ExampleObj2XML.java</h4>
804<div style="margin-left: 0 ; border: 2px">
805<p>
806This example is a preparatory example for the next one. It's an example that
807shows how an arbitrary Java object can be converted to XML. It's an often
808needed task to do this. Often people create a DOM tree from a Java object and
809use that. This is pretty straightforward. The example here however shows how
810to do this using SAX which will probably be faster and not even more
811complicated once you know how this works.
812 </p>
813<div align="center">
814<img class="figure" alt="Example Java object to XML" src="images/EmbeddingExampleObj2XML.png"></div>
815<p>
816For this example we've created two classes: ProjectTeam and ProjectMember
817(found in xml-fop/examples/embedding/java/embedding/model). They represent
818the same data structure found in
819xml-fop/examples/embedding/xml/xml/projectteam.xml. We want to serialize a
820project team with several members which exist as Java objects to XML.
821Therefore we created the two classes: ProjectTeamInputSource and
822ProjectTeamXMLReader (in the same place as ProjectTeam above).
823 </p>
824<p>
825The XMLReader implementation (regard it as a special kind of XML parser)is
826responsible for creating SAX events from the Java object. The InputSource
827class is only used to hold the ProjectTeam object to be used.
828 </p>
829<p>
830Have a look at the source of ExampleObj2XML.java to find out how this is
831used. For more detailed information see other resources on JAXP (ex.
832<a target="_blank" href="http://java.sun.com/xml/jaxp/dist/1.1/docs/tutorial/xslt/3_generate.html">An older JAXP tutorial</a>).
833 </p>
834</div>
835<a name="N103DF"></a><a name="ExampleObj2PDF"></a>
836<h4>ExampleObj2PDF.java</h4>
837<div style="margin-left: 0 ; border: 2px">
838<p>
839The last example here combines the previous and the third to demonstrate
840how you can transform a Java object to a PDF directly in one smooth run
841by generating SAX events from the Java object that get fed to an XSL
842transformation. The result of the transformation is then converted to PDF
843using FOP as before.
844 </p>
845<div align="center">
846<img class="figure" alt="Example Java object to PDF (via XML and XSL-FO)" src="images/EmbeddingExampleObj2PDF.png"></div>
847</div>
848<a name="N103ED"></a><a name="example-notes"></a>
849<h4>Final notes</h4>
850<div style="margin-left: 0 ; border: 2px">
851<p>
852These examples should give you an idea of what's possible. It should be easy
853to adjust these examples to your needs. For examples, you can use a DOMSource
854instead of a StreamSource to feed a DOM tree as input for an XSL
855transformation.
856 </p>
857<p>
858If you think you have a decent example that should be here, contact us via
859one of the mailing lists and we'll see to it that it gets added. Also, if
860you can't find the solution to your particular problem drop us a message on
861the fop-user mailing list.
862 </p>
863</div>
864</div>
865
866</div>
867</td><td width="10"><img width="10" height="1" alt="" src="skin/images/spacer.gif"></td>
868</tr>
869<!--================= end Content==================-->
870</table>
871</td>
872</tr>
873</table>
874<!--================= end Menu, NavBar, Content ==================-->
875<!--================= start Footer ==================-->
876<table summary="footer" cellspacing="0" cellpadding="0" width="100%" border="0">
877<tr>
878<td colspan="2" height="1" bgcolor="#4C6C8F"><img height="1" width="1" alt="" src="skin/images/spacer.gif"><a href="skin/images/label.gif"></a><a href="skin/images/page.gif"></a><a href="skin/images/chapter.gif"></a><a href="skin/images/chapter_open.gif"></a><a href="skin/images/current.gif"></a><a href="/favicon.ico"></a></td>
879</tr>
880<tr>
881<td colspan="2" bgcolor="#CFDCED" class="copyright" align="center"><font size="2" face="Arial, Helvetica, Sans-Serif">Copyright &copy;
882 1999-2003&nbsp;The Apache Software Foundation. All rights reserved.<script type="text/javascript" language="JavaScript"><!--
883 document.write(" - "+"Last Published: " + document.lastModified);
884 // --></script></font></td>
885</tr>
886<tr>
887<td colspan="2" align="left" bgcolor="#CFDCED" class="logos"></td>
888</tr>
889</table>
890<!--================= end Footer ==================-->
891</body>
892</html>
Note: See TracBrowser for help on using the repository browser.