6 Feb 16:29
svn commit: r1241041 - in /xmlgraphics/fop/trunk/src/documentation/content/xdocs: dev/api-doc.xml site.xml trunk/embedding.xml
<mehdi <at> apache.org>
2012-02-06 15:29:13 GMT
2012-02-06 15:29:13 GMT
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>
RSS Feed