You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-commits@xmlgraphics.apache.org by me...@apache.org on 2012/02/06 16:29:13 UTC
svn commit: r1241041 - in
/xmlgraphics/fop/trunk/src/documentation/content/xdocs: dev/api-doc.xml
site.xml trunk/embedding.xml
Author: mehdi
Date: Mon Feb 6 15:29:12 2012
New Revision: 1241041
URL: http://svn.apache.org/viewvc?rev=1241041&view=rev
Log:
Bugzilla#52536: Added documentation about FOPs API and updated related documentation
Removed:
xmlgraphics/fop/trunk/src/documentation/content/xdocs/dev/api-doc.xml
Modified:
xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml
xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/embedding.xml
Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml?rev=1241041&r1=1241040&r2=1241041&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml (original)
+++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml Mon Feb 6 15:29:12 2012
@@ -211,7 +211,6 @@
</design>
<develop label="Develop" href="dev/" tab="development">
- <api-doc label="API Doc" href="api-doc.html"/>
<walkthru label="Walk-Thru" href="implement.html" tab="development"/>
<patch label="Patch Queue" href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&bugidtype=include&bug_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&product=Fop&short_desc=%5BPATCH%5D&short_desc_type=allwordssubstr&long_desc=&long_desc_type=allwordssubstr&bug_file_loc=&bug_file_loc_type=allwordssubstr&keywords=&keywords_type=anywords&field0-0-0=noop&type0-0-0=noop&value0-0-0=&namedcmd=Fop+all&newqueryname=fop+patch+queue&tofooter=1&order=Reuse+same+sort+as+last+time" tab="development"/>
<conventions label="Conventions" href="conventions.html" tab="development"/>
Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/embedding.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/embedding.xml?rev=1241041&r1=1241040&r2=1241041&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/embedding.xml (original)
+++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/embedding.xml Mon Feb 6 15:29:12 2012
@@ -37,19 +37,39 @@
org.apache.fop.apps.FopFactory instance. This object can be used to launch multiple
rendering runs. For each run, create a new org.apache.fop.apps.Fop instance through
one of the factory methods of FopFactory. In the method call you specify which output
- format (i.e. Renderer) to use and, if the selected renderer requires an 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 Renderer instance (details
- below). Finally, you retrieve a SAX DefaultHandler instance from the Fop object and
- use that as the SAXResult of your transformation.
- </p>
- <note>
- We recently changed FOP's outer API to what we consider the final API. This might require
- some changes in your application. The main reasons for these changes were performance
- improvements due to better reuse of reusable objects and reduced use of static variables
- for added flexibility in complex environments.
- </note>
+ format (i.e. MIME type) to use and, if the selected output format requires an
+ 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.
+ </p>
+ </section>
+ <section id="API">
+ <title>The API</title>
+ <p>
+ FOP has many classes which express the "public" access modifier, however, this is not
+ indicative of their inclusion into the public API. Every attempt will be made to keep the
+ public API static, to minimize regressions for existing users, however, since the API is not
+ clearly defined, the list of classes below are the generally agreed public API:
+ <source><![CDATA[
+org.apache.fop.apps.*
+org.apache.fop.fo.FOEventHandler
+org.apache.fop.fo.ElementMappingRegistry
+org.apache.fop.fonts.FontManager
+org.apache.fop.events.EventListener
+org.apache.fop.events.Event
+org.apache.fop.events.model.EventSeverity
+org.apache.fop.render.ImageHandlerRegistry
+org.apache.fop.render.RendererFactory
+org.apache.fop.render.intermediate.IFContext
+org.apache.fop.render.intermediate.IFDocumentHandler
+org.apache.fop.render.intermediate.IFException
+org.apache.fop.render.intermediate.IFParser
+org.apache.fop.render.intermediate.IFSerializer
+org.apache.fop.render.intermediate.IFUtil
+org.apache.fop.render.intermediate.util.IFConcatenator]]></source>
+ </p>
</section>
<section id="basics">
<title>Basic Usage Pattern</title>
@@ -425,11 +445,11 @@ try {
</li>
<li>
<p>
- Set <strong>your own Renderer instance</strong>. If you want to supply your own renderer or
- configure a Renderer in a special way you can give the instance to the FOUserAgent. Normally,
- the Renderer instance is created by FOP. Example:
+ Set <strong>your own Document Handler</strong>. This feature can be used for several purposes, the most likey usage of which would probably be
+ binding a MIME type when the output is Intermediate Format (see <a href="#documenthandlers">Document Handlers</a>). This also allows advanced
+ users to create their own implementation of the document handler.
</p>
- <source>userAgent.setRendererOverride(myRenderer); // myRenderer is an org.apache.fop.render.Renderer</source>
+ <source>userAgent.setDocumentHandlerOverride(documentHandler) // documentHandler is an instance of org.apache.fop.render.intermediate.IFDocumentHandler</source>
</li>
<li>
<p>
@@ -482,6 +502,28 @@ fopFactory.setUserConfig(new File("C:/Te
The layout of the configuration file is described on the <a href="configuration.html">Configuration page</a>.
</p>
</section>
+ <section id="documenthandlers">
+ <title>Document Handlers</title>
+ <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.
+ <source><![CDATA[
+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.mimicDocumentHandler(targetHandler); //Tell the IFSerializer to mimic the target format
+
+userAgent.setDocumentHandlerOverride(ifSerializer); //Make sure the prepared document handler is used
+ ]]></source>
+ The rest of the code is the same as in <a href="#basics">Basic Usage Patterns</a>.
+ </p>
+ </section>
<section id="hints">
<title>Hints</title>
<section id="object-reuse">
@@ -686,6 +728,15 @@ shows the usage of the PDF Transcoder, a
It is used to generate a PDF document from an SVG file.
</p>
</section>
+ <section id="ExampleConcat">
+ <title>ExampleConcat.java (IF Concatenation example)</title>
+ <p>
+This can be found in the <code>embedding.intermediate</code> package within the
+examples and describes how IF can be concatenated to produce a document. Because
+IF has been through FOPs layout engine, it should be visually consistent with FO
+rendered documents while allowing the user to merge numerous documents together.
+ </p>
+ </section>
<section id="example-notes">
<title>Final notes</title>
<p>
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org