You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlgraphics.apache.org by rm...@apache.org on 2013/09/09 17:11:19 UTC
svn commit: r1521153 -
/xmlgraphics/site/trunk/content/fop/trunk/embedding.mdtext
Author: rmeyer
Date: Mon Sep 9 15:11:19 2013
New Revision: 1521153
URL: http://svn.apache.org/r1521153
Log:
rmeyer - Updated the trunk embedding documentation as the code has changed since the URI resolution patch
Modified:
xmlgraphics/site/trunk/content/fop/trunk/embedding.mdtext
Modified: xmlgraphics/site/trunk/content/fop/trunk/embedding.mdtext
URL: http://svn.apache.org/viewvc/xmlgraphics/site/trunk/content/fop/trunk/embedding.mdtext?rev=1521153&r1=1521152&r2=1521153&view=diff
==============================================================================
--- xmlgraphics/site/trunk/content/fop/trunk/embedding.mdtext (original)
+++ xmlgraphics/site/trunk/content/fop/trunk/embedding.mdtext Mon Sep 9 15:11:19 2013
@@ -43,9 +43,9 @@ Here is the basic pattern to render an X
/*..*/
- // Step 1: Construct a FopFactory
+ // Step 1: Construct a FopFactory by specifying a reference to the configuration file
// (reuse if you plan to render multiple documents!)
- FopFactory fopFactory = FopFactory.newInstance();
+ FopFactory fopFactory = FopFactory.newInstance(new File("C:/Temp/fop.xconf"));
// Step 2: Set up output stream.
// Note: Using BufferedOutputStream for performance reasons (helpful with FileOutputStreams).
@@ -77,7 +77,7 @@ Here is the basic pattern to render an X
Let's discuss these 5 steps in detail:
-- **Step 1:** 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.
+- **Step 1:** 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.
- **Step 2:** 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.
@@ -175,44 +175,43 @@ Apache FOP provides two levels on which
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.
-You can set all sorts of things on the FopFactory:
-
-- The **font base URL** to use when resolving relative URLs for fonts. Example:
+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:
:::java
- fopFactory.getFontManager().setFontBaseURL("file:///C:/Temp/fonts");
+ FopFactoryBuilder builder = new FopFactoryBuilder(baseURI);
-- The **hyphenation base URL** to use when resolving relative URLs for hyphenation patterns. Example:
+A **URIResolver** 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:
:::java
- fopFactory.setHyphenBaseURL("file:///C:/Temp/hyph");
+ // myResourceResolver is a org.apache.xmlgraphics.io.ResourceResolver
+ FopFactoryBuilder builder = new FopFactoryBuilder(baseURI, myResourceResolver);
- Disable **strict validation**. When disabled FOP is less strict about the rules established by the XSL-FO specification. Example:
:::java
- fopFactory.setStrictValidation(false);
+ builder.setStrictFOValidation(false);
- Enable an **alternative set of rules for text indents** 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:
:::java
- fopFactory.setBreakIndentInheritanceOnReferenceAreaBoundary(true);
+ builder.setBreakIndentInheritanceOnReferenceAreaBoundary(true);
- Set the **source resolution** 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:
:::java
- fopFactory.setSourceResolution(96); // =96dpi (dots/pixels per Inch)
+ builder.setSourceResolution(96); // =96dpi (dots/pixels per Inch)
-- Manually add an **ElementMapping instance**. 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:
+The following example shows how a FopFactory is created using the settings specified:
:::java
- fopFactory.addElementMapping(myElementMapping); // myElementMapping is a org.apache.fop.fo.ElementMapping
+ FopFactory fopFactory = builder.build();
-- Set a **URIResolver** for custom URI resolution. By supplying a JAXP URIResolver you can add custom URI resolution functionality to FOP. For example, you can use [Apache XML Commons Resolver](http://xml.apache.org/commons/components/resolver/) to make use of XCatalogs. Example:
+Finally, there are several options which can be set on the FopFactory itself including the following example:
- :::java
- fopFactory.setURIResolver(myResolver); // myResolver is a javax.xml.transform.URIResolver
+- Manually add an **ElementMapping instance**. 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:
- <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>
+ :::java
+ fopFactory.addElementMapping(myElementMapping); // myElementMapping is a org.apache.fop.fo.ElementMapping
### Customizing the User Agent {#user-agent}
@@ -227,11 +226,6 @@ The user agent is the entity that allows
You can do all sorts of things on the user agent:
-- The **base URL** to use when resolving relative URLs. Example:
-
- :::java
- userAgent.setBaseURL("file:///C:/Temp/");
-
- Set the **producer** 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:
:::java
@@ -277,13 +271,6 @@ You can do all sorts of things on the us
:::java
userAgent.setFOEventHandlerOverride(myFOEventHandler); // myFOEventHandler is an org.apache.fop.fo.FOEventHandler
-- Set a **URIResolver** for custom URI resolution. By supplying a JAXP URIResolver you can add custom URI resolution functionality to FOP. For example, you can use [Apache XML Commons Resolver](http://xml.apache.org/commons/components/resolver/) to make use of XCatalogs. Example:
-
- :::java
- userAgent.setURIResolver(myResolver); // myResolver is a javax.xml.transform.URIResolver
-
- <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>
-
<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>
## Using a Configuration File {#config-external}
@@ -298,11 +285,7 @@ Instead of setting the parameters manual
DefaultConfigurationBuilder cfgBuilder = new DefaultConfigurationBuilder();
Configuration cfg = cfgBuilder.buildFromFile(new File("C:/Temp/mycfg.xml"));
- fopFactory.setUserConfig(cfg);
-
- /* ..or.. */
-
- fopFactory.setUserConfig(new File("C:/Temp/mycfg.xml"));
+ fopFactoryBuilder = new FopFactoryBuilder(baseURI).setConfiguration(cfg);
The layout of the configuration file is described on the [Configuration page](configuration.html).
@@ -313,8 +296,7 @@ The document handlers are classes that i
:::java
IFDocumentHandler targetHandler = userAgent.getRendererFactory().createDocumentHandler(userAgent, MimeConstants.MIME_PDF);
- IFSerializer ifSerializer = new IFSerializer(); //Create the IFSerializer to write the intermediate format
- ifSerializer.setContext(new IFContext(userAgent));
+ IFSerializer ifSerializer = new IFSerializer(new IFContext(userAgent)); //Create the IFSerializer to write the intermediate format
ifSerializer.mimicDocumentHandler(targetHandler); //Tell the IFSerializer to mimic the target format
userAgent.setDocumentHandlerOverride(ifSerializer); //Make sure the prepared document handler is used
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: commits-help@xmlgraphics.apache.org