diff options
| author | Mehdi Houshmand <mehdi@apache.org> | 2012-02-06 15:29:12 +0000 |
|---|---|---|
| committer | Mehdi Houshmand <mehdi@apache.org> | 2012-02-06 15:29:12 +0000 |
| commit | 098ac1879ef71df08ee43eb263f5efac77d4e352 (patch) | |
| tree | 2e0737595db895bdc08f63e8ffa85f51c2d43f67 /src/documentation/content | |
| parent | 49c7697650720db1bd8afa88046b6cecd7206f00 (diff) | |
| download | xmlgraphics-fop-098ac1879ef71df08ee43eb263f5efac77d4e352.tar.gz xmlgraphics-fop-098ac1879ef71df08ee43eb263f5efac77d4e352.zip | |
Bugzilla#52536: Added documentation about FOPs API and updated related documentation
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@1241041 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src/documentation/content')
| -rw-r--r-- | src/documentation/content/xdocs/dev/api-doc.xml | 42 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/site.xml | 1 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/trunk/embedding.xml | 83 |
3 files changed, 67 insertions, 59 deletions
diff --git a/src/documentation/content/xdocs/dev/api-doc.xml b/src/documentation/content/xdocs/dev/api-doc.xml deleted file mode 100644 index 94a671953..000000000 --- a/src/documentation/content/xdocs/dev/api-doc.xml +++ /dev/null @@ -1,42 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> -<document> - <header> - <title>FOP Development: API Documentation (javadocs)</title> - <version>$Revision$</version> - </header> - <body> - <section id="gump"> - <title>On-line Access (through Gump)</title> - <p>FOP (and many other Apache projects) use <link href="http://gump.apache.org/">Apache Gump</link> to do a test build several times each day. One of the useful byproducts of this process is that javadocs can be created and made available.</p> - <p>First, determine which line of development code you wish to see. If you don't know, you probably want the "Maintenance Branch", which is the line that currently produces FOP releases. See <link href="index.html#lines">Development Lines</link> for more details.</p> - <warning>Javadocs for both development lines are made from current SVN code, and are not tied to any particular release. Both the documentation and the API may be different, even if you are working with the correct branch. Currently, the only way to obtain API documentation for a specific release is to <link href="#self-built">build it yourself</link>.</warning> - <ul> - <li><link href="http://gump.apache.org/javadoc/xml-fop-maintenance/build/javadocs/index.html">Javadocs for Maintenance Branch</link></li> - <li><link href="http://gump.apache.org/javadoc/xml-fop/build/javadocs/index.html">Javadocs for Trunk (Redesign)</link></li> - </ul> - <note>If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the <link href="../maillist.html#fop-user">FOP User Mailing List</link> so that any problems can be fixed before the next build.</note> - </section> - <section id="self-built"> - <title>Building them Yourself</title> - <p>See <link href="../download.html#source">Source Download</link> for instructions on obtaining the source code. Then see <link href="../trunk/compiling.html">Building FOP</link> for instructions on running the build process. The Ant build target that you will use to generate the API documentation is "javadocs", and the results will be stored in xml-fop/build/javadocs.</p> - </section> - </body> -</document> diff --git a/src/documentation/content/xdocs/site.xml b/src/documentation/content/xdocs/site.xml index 2d55ae3f2..8a13a45c0 100644 --- a/src/documentation/content/xdocs/site.xml +++ b/src/documentation/content/xdocs/site.xml @@ -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"/> diff --git a/src/documentation/content/xdocs/trunk/embedding.xml b/src/documentation/content/xdocs/trunk/embedding.xml index 3289e68c7..3881c4599 100644 --- a/src/documentation/content/xdocs/trunk/embedding.xml +++ b/src/documentation/content/xdocs/trunk/embedding.xml @@ -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. + 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> - <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> </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:/Temp/mycfg.xml"));]]></source> 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 sub-application within FOP. 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> |