You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlgraphics.apache.org by bu...@apache.org on 2013/09/09 17:11:34 UTC
svn commit: r877808 - in /websites/staging/xmlgraphics/trunk/content: ./
fop/trunk/embedding.html
Author: buildbot
Date: Mon Sep 9 15:11:34 2013
New Revision: 877808
Log:
Staging update by buildbot for xmlgraphics
Modified:
websites/staging/xmlgraphics/trunk/content/ (props changed)
websites/staging/xmlgraphics/trunk/content/fop/trunk/embedding.html
Propchange: websites/staging/xmlgraphics/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Sep 9 15:11:34 2013
@@ -1 +1 @@
-1516092
+1521153
Modified: websites/staging/xmlgraphics/trunk/content/fop/trunk/embedding.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/fop/trunk/embedding.html (original)
+++ websites/staging/xmlgraphics/trunk/content/fop/trunk/embedding.html Mon Sep 9 15:11:34 2013
@@ -350,7 +350,7 @@ $(document).ready(function () {
<div id="items">
</div>
<!-- <div id="breadcrumb"><a href="/">Home</a> » <a href="/fop/">Fop</a> » <a href="/fop/trunk/">Trunk</a></div> -->
- <div class="section-content"><h1 id="apachewzxhzdk30-fop-embedding">Apache™ FOP: Embedding</h1>
+ <div class="section-content"><h1 id="apachewzxhzdk28-fop-embedding">Apache™ FOP: Embedding</h1>
<p><subtitle>How to Embed FOP in a Java application</subtitle></p>
<h2 id="overview">Overview</h2>
<p>Review <a href="running.html">Running Apache™ FOP</a> for important information that applies to embedded applications as well as command-line use, such as options and performance.</p>
@@ -384,9 +384,9 @@ $(document).ready(function () {
<span class="cm">/*..*/</span>
-<span class="c1">// Step 1: Construct a FopFactory</span>
+<span class="c1">// Step 1: Construct a FopFactory by specifying a reference to the configuration file</span>
<span class="c1">// (reuse if you plan to render multiple documents!)</span>
-<span class="n">FopFactory</span> <span class="n">fopFactory</span> <span class="o">=</span> <span class="n">FopFactory</span><span class="o">.</span><span class="na">newInstance</span><span class="o">();</span>
+<span class="n">FopFactory</span> <span class="n">fopFactory</span> <span class="o">=</span> <span class="n">FopFactory</span><span class="o">.</span><span class="na">newInstance</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"C:/Temp/fop.xconf"</span><span class="o">));</span>
<span class="c1">// Step 2: Set up output stream.</span>
<span class="c1">// Note: Using BufferedOutputStream for performance reasons (helpful with FileOutputStreams).</span>
@@ -420,7 +420,7 @@ $(document).ready(function () {
<p>Let's discuss these 5 steps in detail:</p>
<ul>
<li>
-<p><strong>Step 1:</strong> You create a new FopFactory instance. The FopFactory instance holds references to configuration information and cached data. It's important to reuse this instance if you plan to render multiple documents during a JVM's lifetime.</p>
+<p><strong>Step 1:</strong> You create a new FopFactory instance. The FopFactory is created and holds references to configuration information and cached data. It's important to reuse this instance if you plan to render multiple documents during a JVM's lifetime.</p>
</li>
<li>
<p><strong>Step 2:</strong> You set up an OutputStream that the generated document will be written to. It's a good idea to buffer the OutputStream as demonstrated to improve performance.</p>
@@ -522,57 +522,56 @@ $(document).ready(function () {
<p>Apache FOP provides two levels on which you can customize FOP's behaviour: the FopFactory and the user agent.</p>
<h3 id="fop-factory">Customizing the FopFactory</h3>
<p>The FopFactory holds configuration data and references to objects which are reusable over multiple rendering runs. It's important to instantiate it only once (except in special environments) and reuse it every time to create new FOUserAgent and Fop instances.</p>
-<p>You can set all sorts of things on the FopFactory:</p>
-<ul>
-<li>
-<p>The <strong>font base URL</strong> to use when resolving relative URLs for fonts. Example:</p>
-<div class="codehilite"><pre><span class="n">fopFactory</span><span class="o">.</span><span class="na">getFontManager</span><span class="o">().</span><span class="na">setFontBaseURL</span><span class="o">(</span><span class="s">"file:///C:/Temp/fonts"</span><span class="o">);</span>
+<p>The FopFactoryBuilder is used to construct a FopFactory object. This builder can be used to set configuration values which will determine the behaviour of the FopFactory object. To create the FopFactoryBuilder the following line can be used as a precursor for the following examples:</p>
+<div class="codehilite"><pre> <span class="p">:::</span><span class="n">java</span>
+ <span class="n">FopFactoryBuilder</span> <span class="n">builder</span> <span class="p">=</span> <span class="n">new</span> <span class="n">FopFactoryBuilder</span><span class="p">(</span><span class="n">baseURI</span><span class="p">);</span>
</pre></div>
-</li>
-<li>
-<p>The <strong>hyphenation base URL</strong> to use when resolving relative URLs for hyphenation patterns. Example:</p>
-<div class="codehilite"><pre><span class="n">fopFactory</span><span class="o">.</span><span class="na">setHyphenBaseURL</span><span class="o">(</span><span class="s">"file:///C:/Temp/hyph"</span><span class="o">);</span>
+<p>A <strong>URIResolver</strong> for custom URI resolution can be set against the FopFactoryBuilder. By supplying a JAXP URIResolver you can add custom URI resolution functionality to FOP. For example:</p>
+<div class="codehilite"><pre> <span class="p">:::</span><span class="n">java</span>
+ <span class="o">//</span> <span class="n">myResourceResolver</span> <span class="n">is</span> <span class="n">a</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">xmlgraphics</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="n">ResourceResolver</span>
+ <span class="n">FopFactoryBuilder</span> <span class="n">builder</span> <span class="p">=</span> <span class="n">new</span> <span class="n">FopFactoryBuilder</span><span class="p">(</span><span class="n">baseURI</span><span class="p">,</span> <span class="n">myResourceResolver</span><span class="p">);</span>
</pre></div>
-</li>
+<ul>
<li>
<p>Disable <strong>strict validation</strong>. When disabled FOP is less strict about the rules established by the XSL-FO specification. Example:</p>
-<div class="codehilite"><pre><span class="n">fopFactory</span><span class="o">.</span><span class="na">setStrictValidation</span><span class="o">(</span><span class="kc">false</span><span class="o">);</span>
+<div class="codehilite"><pre><span class="n">builder</span><span class="o">.</span><span class="na">setStrictFOValidation</span><span class="o">(</span><span class="kc">false</span><span class="o">);</span>
</pre></div>
</li>
<li>
<p>Enable an <strong>alternative set of rules for text indents</strong> that tries to mimic the behaviour of many commercial FO implementations, that chose to break the specification in this respect. The default of this option is 'false', which causes Apache FOP to behave exactly as described in the specification. To enable the alternative behaviour, call:</p>
-<div class="codehilite"><pre><span class="n">fopFactory</span><span class="o">.</span><span class="na">setBreakIndentInheritanceOnReferenceAreaBoundary</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>
+<div class="codehilite"><pre><span class="n">builder</span><span class="o">.</span><span class="na">setBreakIndentInheritanceOnReferenceAreaBoundary</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>
</pre></div>
</li>
<li>
<p>Set the <strong>source resolution</strong> for the document. This is used internally to determine the pixel size for SVG images and bitmap images without resolution information. Default: 72 dpi. Example:</p>
-<div class="codehilite"><pre><span class="n">fopFactory</span><span class="o">.</span><span class="na">setSourceResolution</span><span class="o">(</span><span class="mi">96</span><span class="o">);</span> <span class="c1">// =96dpi (dots/pixels per Inch)</span>
+<div class="codehilite"><pre><span class="n">builder</span><span class="o">.</span><span class="na">setSourceResolution</span><span class="o">(</span><span class="mi">96</span><span class="o">);</span> <span class="c1">// =96dpi (dots/pixels per Inch)</span>
</pre></div>
</li>
-<li>
-<p>Manually add an <strong>ElementMapping instance</strong>. If you want to supply a special FOP extension you can give the instance to the FOUserAgent. Normally, the FOP extensions can be automatically detected (see the documentation on extension for more info). Example:</p>
-<div class="codehilite"><pre><span class="n">fopFactory</span><span class="o">.</span><span class="na">addElementMapping</span><span class="o">(</span><span class="n">myElementMapping</span><span class="o">);</span> <span class="c1">// myElementMapping is a org.apache.fop.fo.ElementMapping</span>
+</ul>
+<p>The following example shows how a FopFactory is created using the settings specified:</p>
+<div class="codehilite"><pre> <span class="p">:::</span><span class="n">java</span>
+ <span class="n">FopFactory</span> <span class="n">fopFactory</span> <span class="p">=</span> <span class="n">builder</span><span class="p">.</span><span class="n">build</span><span class="p">();</span>
</pre></div>
-</li>
+<p>Finally, there are several options which can be set on the FopFactory itself including the following example:</p>
+<ul>
<li>
-<p>Set a <strong>URIResolver</strong> for custom URI resolution. By supplying a JAXP URIResolver you can add custom URI resolution functionality to FOP. For example, you can use <a href="http://xml.apache.org/commons/components/resolver/">Apache XML Commons Resolver</a> to make use of XCatalogs. Example:</p>
-<div class="codehilite"><pre><span class="n">fopFactory</span><span class="o">.</span><span class="na">setURIResolver</span><span class="o">(</span><span class="n">myResolver</span><span class="o">);</span> <span class="c1">// myResolver is a javax.xml.transform.URIResolver</span>
+<p>Manually add an <strong>ElementMapping instance</strong>. If you want to supply a special FOP extension you can give the instance to the FOUserAgent. Normally, the FOP extensions can be automatically detected (see the documentation on extension for more info). Example:</p>
+<div class="codehilite"><pre><span class="n">fopFactory</span><span class="o">.</span><span class="na">addElementMapping</span><span class="o">(</span><span class="n">myElementMapping</span><span class="o">);</span> <span class="c1">// myElementMapping is a org.apache.fop.fo.ElementMapping</span>
</pre></div>
-<p><note>Both the FopFactory and the FOUserAgent have a method to set a URIResolver. The URIResolver on the FopFactory is primarily used to resolve URIs on factory-level (hyphenation patterns, for example) and it is always used if no other URIResolver (for example on the FOUserAgent) resolved the URI first.</note></p>
</li>
</ul>
<h3 id="user-agent">Customizing the User Agent</h3>
@@ -588,13 +587,6 @@ $(document).ready(function () {
<p>You can do all sorts of things on the user agent:</p>
<ul>
<li>
-<p>The <strong>base URL</strong> to use when resolving relative URLs. Example:</p>
-<div class="codehilite"><pre><span class="n">userAgent</span><span class="o">.</span><span class="na">setBaseURL</span><span class="o">(</span><span class="s">"file:///C:/Temp/"</span><span class="o">);</span>
-</pre></div>
-
-
-</li>
-<li>
<p>Set the <strong>producer</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. The default producer is "Apache FOP". Example:</p>
<div class="codehilite"><pre><span class="n">userAgent</span><span class="o">.</span><span class="na">setProducer</span><span class="o">(</span><span class="s">"MyKillerApplication"</span><span class="o">);</span>
</pre></div>
@@ -657,14 +649,6 @@ $(document).ready(function () {
</li>
-<li>
-<p>Set a <strong>URIResolver</strong> for custom URI resolution. By supplying a JAXP URIResolver you can add custom URI resolution functionality to FOP. For example, you can use <a href="http://xml.apache.org/commons/components/resolver/">Apache XML Commons Resolver</a> to make use of XCatalogs. Example:</p>
-<div class="codehilite"><pre><span class="n">userAgent</span><span class="o">.</span><span class="na">setURIResolver</span><span class="o">(</span><span class="n">myResolver</span><span class="o">);</span> <span class="c1">// myResolver is a javax.xml.transform.URIResolver</span>
-</pre></div>
-
-
-<p><note>Both the FopFactory and the FOUserAgent have a method to set a URIResolver. The URIResolver on the FOUserAgent is used for resolving URIs which are document-related. If it's not set or cannot resolve a URI, the URIResolver from the FopFactory is used.</note></p>
-</li>
</ul>
<p><note>You should not reuse an FOUserAgent instance between FOP rendering runs although you can. Especially in multi-threaded environment, this is a bad idea.</note></p>
<h2 id="config-external">Using a Configuration File</h2>
@@ -676,11 +660,7 @@ $(document).ready(function () {
<span class="n">DefaultConfigurationBuilder</span> <span class="n">cfgBuilder</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultConfigurationBuilder</span><span class="o">();</span>
<span class="n">Configuration</span> <span class="n">cfg</span> <span class="o">=</span> <span class="n">cfgBuilder</span><span class="o">.</span><span class="na">buildFromFile</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"C:/Temp/mycfg.xml"</span><span class="o">));</span>
-<span class="n">fopFactory</span><span class="o">.</span><span class="na">setUserConfig</span><span class="o">(</span><span class="n">cfg</span><span class="o">);</span>
-
-<span class="cm">/* ..or.. */</span>
-
-<span class="n">fopFactory</span><span class="o">.</span><span class="na">setUserConfig</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"C:/Temp/mycfg.xml"</span><span class="o">));</span>
+<span class="n">fopFactoryBuilder</span> <span class="o">=</span> <span class="k">new</span> <span class="n">FopFactoryBuilder</span><span class="o">(</span><span class="n">baseURI</span><span class="o">).</span><span class="na">setConfiguration</span><span class="o">(</span><span class="n">cfg</span><span class="o">);</span>
</pre></div>
@@ -689,8 +669,7 @@ $(document).ready(function () {
<p>The document handlers are classes that inherit from <code>org.apache.fop.render.intermediate.IFDocumentHandler</code>. This is an interface for which a MIME type specific implementation can be created. This same handler is used either when XSL-FO is used as the input or when Intermediate Format is used. Since IF is output format agnostic, if custom fonts or other configuration information that affect layout (specific to a particular MIME type) are given then FOP needs that contextual information. The document handler provides that context so that when the IF is rendered, it is more visually consistent with FO rendering. The code below shows an example of how a document handler can be used to provide PDF configuration data to the IFSerializer.</p>
<div class="codehilite"><pre><span class="n">IFDocumentHandler</span> <span class="n">targetHandler</span> <span class="o">=</span> <span class="n">userAgent</span><span class="o">.</span><span class="na">getRendererFactory</span><span class="o">().</span><span class="na">createDocumentHandler</span><span class="o">(</span><span class="n">userAgent</span><span class="o">,</span> <span class="n">MimeConstants</span><span class="o">.</span><span class="na">MIME_PDF</span><span class="o">);</span>
-<span class="n">IFSerializer</span> <span class="n">ifSerializer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">IFSerializer</span><span class="o">();</span> <span class="c1">//Create the IFSerializer to write the intermediate format</span>
-<span class="n">ifSerializer</span><span class="o">.</span><span class="na">setContext</span><span class="o">(</span><span class="k">new</span> <span class="n">IFContext</span><span class="o">(</span><span class="n">userAgent</span><span class="o">));</span>
+<span class="n">IFSerializer</span> <span class="n">ifSerializer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">IFSerializer</span><span class="o">(</span><span class="k">new</span> <span class="n">IFContext</span><span class="o">(</span><span class="n">userAgent</span><span class="o">));</span> <span class="c1">//Create the IFSerializer to write the intermediate format</span>
<span class="n">ifSerializer</span><span class="o">.</span><span class="na">mimicDocumentHandler</span><span class="o">(</span><span class="n">targetHandler</span><span class="o">);</span> <span class="c1">//Tell the IFSerializer to mimic the target format</span>
<span class="n">userAgent</span><span class="o">.</span><span class="na">setDocumentHandlerOverride</span><span class="o">(</span><span class="n">ifSerializer</span><span class="o">);</span> <span class="c1">//Make sure the prepared document handler is used</span>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: commits-help@xmlgraphics.apache.org