From: Mehdi Houshmand Date: Thu, 5 Jul 2012 08:45:45 +0000 (+0000) Subject: Updated documentation with new API changes X-Git-Tag: fop-2_0~336 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=01d68aa91e5d8af58c44f4185f75f958e87c5b3e;p=xmlgraphics-fop.git Updated documentation with new API changes git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@1357490 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/documentation/content/xdocs/trunk/embedding.xml b/src/documentation/content/xdocs/trunk/embedding.xml index 24c74f970..abdce8843 100644 --- a/src/documentation/content/xdocs/trunk/embedding.xml +++ b/src/documentation/content/xdocs/trunk/embedding.xml @@ -41,8 +41,10 @@ OutputStream, which OutputStream to use for the results of the rendering. You can customize FOP's behaviour in a rendering run by supplying your own FOUserAgent instance. The FOUserAgent can, for example, be used to set your own document handler - instance (details below). Finally, you retrieve a SAX DefaultHandler instance from - the Fop object and use that as the SAXResult of your transformation. + instance (details below). Because the FOUserAgent holds FOP-run-specific configuration + data, it should only be used for a single run and not over multiple FOP invocations. + Finally, you retrieve a SAX DefaultHandler instance from the Fop object and use that + as the SAXResult of your transformation.

@@ -54,6 +56,7 @@ clearly defined, the list of classes below are the generally agreed public API:
  • 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. + references to configuration information and cached data. It is important to reuse this + instance if you plan to render multiple documents during a JVM's lifetime. URIs used within + FOP runs (images in the FO, fonts in the fop conf etc...) will be resolved against the base + URI given here.
  • Step 2: You set up an OutputStream that the generated document @@ -302,38 +308,33 @@ try { Configuring Apache FOP Programmatically

    Apache FOP provides two levels on which you can customize FOP's - behaviour: the FopFactory and the user agent. + behaviour: the FopFactoryBuilder and the user agent.

    Customizing the FopFactory

    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. + multiple rendering runs. The FopFactoryBuilder allows users to set configuration and then + build the FopFactory so that the FopFactory doesn't change between runs. The FopFactory performs + some performance expensive operations (i.e. detecting system fonts), as such it only needs to be + built once and cane be reused every time to create new FOUserAgent and Fop instances.

    - You can set all sorts of things on the FopFactory: + The FopFactoryBuilder can be instantiated with three objects; the base URI, the ResourceResolver + and the EnvironmentProfile. The base URI and the ResourceResolver are used for resolving resource + URIs throughout the FOP invocation. The EnvironmentProfile will be discussed further below but, in + short, it gives users more control over FOPs system dependent services. +

    +

    + You can set all sorts of things on the FopFactoryBuilder:

      -
    • -

      - The font base URL to use when resolving relative URLs for fonts. Example: -

      - fopFactory.getFontManager().setFontBaseURL("file:///C:/Temp/fonts"); -
      • -
    • -

      - The hyphenation base URL to use when resolving relative URLs for - hyphenation patterns. Example: -

      - fopFactory.setHyphenBaseURL("file:///C:/Temp/hyph"); -

    • Disable strict validation. When disabled FOP is less strict about the rules established by the XSL-FO specification. Example:

      - fopFactory.setStrictValidation(false); + fopFactoryBuilder.setStrictFOValidation(false);

    • @@ -342,14 +343,14 @@ try { 'false', which causes Apache FOP to behave exactly as described in the specification. To enable the alternative behaviour, call:

      - fopFactory.setBreakIndentInheritanceOnReferenceAreaBoundary(true); + fopFactoryBuilder.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:

      - fopFactory.setSourceResolution(96); // =96dpi (dots/pixels per Inch) + fopFactoryBuilder.setSourceResolution(96); // =96dpi (dots/pixels per Inch)

    • @@ -357,22 +358,21 @@ try { 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:

      - fopFactory.addElementMapping(myElementMapping); // myElementMapping is a org.apache.fop.fo.ElementMapping -
      • -
    • -

      - 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 to make use of XCatalogs. Example: -

      - fopFactory.setURIResolver(myResolver); // myResolver is a javax.xml.transform.URIResolver - - 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. - + fopFactoryBuilder.addElementMapping(myElementMapping); // myElementMapping is a org.apache.fop.fo.ElementMapping
    +

    + Once the settings on the FopFactoryBuilder had been set, you can create a FopFactory by invoking the build method: +

    + FopFactory factory = fopFactoryBuilder.build(); +
    +
    + Environment Profile +

    + The EnvironmentProfile can be used to define the limitations and restrictions of FOPs access to system resources. FOP, for example, + can auto-detect system fonts which users may want control over. This environment profile also holds the base URI and the + ResourceResolver discussed previously, since they are intrinsically bound to the environment inwhich FOP is invoked. +

    Customizing the User Agent @@ -383,7 +383,7 @@ try { to the factory method that will create a new Fop instance:

      -
    • -

      - The base URL to use when resolving relative URLs. Example: -

      - 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: @@ -459,19 +453,6 @@ try {

      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 to make use of XCatalogs. Example: -

      - userAgent.setURIResolver(myResolver); // myResolver is a javax.xml.transform.URIResolver - - 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. - -
    You should not reuse an FOUserAgent instance between FOP rendering runs although you can. Especially @@ -486,18 +467,20 @@ try { many values from an XML configuration file:

    +FopFactory fopFactory = FopFactory.newInstance(new File("C:/Temp/mycfg.xml"));]]> +

    + If however, you wish to override some of the configuration settings within the fop conf programmatically + then you can do so by using the FopConfParser. This allows the FopFactory to remain immutable and consistent + across multiple threads/invocations while still keeping the API flexible for the user. +

    +

    The layout of the configuration file is described on the Configuration page.

    @@ -749,4 +732,4 @@ mailing list.
    • - \ No newline at end of file +