<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!--
  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: embedding.xml 1298724 2012-03-09 07:55:31Z cbowditch $ -->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">

<document>
  <header>
    <title>Apache™ FOP Design: Embedding Apache� FOP in Other Applications</title>
    <version>$Revision: 1298724 $</version>
    <authors>
      <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
    </authors>
  </header>

    <body>
<section id="intro">
  <title>Introduction</title>
<p>
This is the design for the external interface when Apache™ FOP is to be embedded
inside another java application.
  </p>
  <p>
Common places where FOP is embedded is in a report production application
of a server side application such as <jump href="http://xml.apache.org/cocoon/index.html">Cocoon</jump>.
   </p>
  </section>
<section>
  <title>Settings</title>
<section>
  <title>User Agent</title>
<p>
Possible meanings for a user agent:
</p>
<ul>
<li>something that makes decisions where the specifiction indicates
that the user agent should decide</li>
<li>FOP as the user agent, represented by a class that handles
various setup and decision values</li>
<li>an class that handles context for a particular FOP conversion
that can be configured/overridden when embedding</li>
</ul>

<p>
The user agent is responsible for supplying user or context
specific information. The list of user agent values can be found on the
<jump href="useragent.html">User Agent</jump> page.
   </p>
  </section>
<section>
  <title>Logging</title>
<ul>
<li>logging level</li>
<li>logging messages of various levels</li>
<li>error handling</li>
<li>Logging setup (LogKit, Log4J, JDK14Logging)</li>
</ul>
  </section>
<section>
  <title>XML input</title>
<ul>
<li>various ways to supply FOP with the xsl:fo file, fo, xml+xsl</li>
<li>sax handler</li>
</ul>
  </section>
<section>
  <title>general options</title>
<ul>
<li>base url</li>
<li>uri resolvers</li>
<li>which implementation of a particular LayoutManager to use</li>
</ul>
  </section>
<section>
  <title>Rendering Options</title>
<ul>
<li>embedding fonts</li>
<li>compression in pdf</li>
<li>image embedding</li>
</ul>
<p>
for the PS renderer (eventually):
</p>
<ul>
<li>PostScript Level</li>
<li>PPD to use</li>
<li>binary/ascii switch</li>
</ul>
  </section>
<section>
  <title>Render Results</title>
<p>
Generate Output statistics from FOP:
   </p>
<ul>
<li>Number of pages total</li>
<li>Number of pages of each page-sequence</li>
<li>page-master used for each page (could be used to control
the paper bin to get paper from, important for me in conjunction
with PS Renderer)</li>
<li>recoverable errors such as overflow</li>
</ul>
  </section>
<section>
  <title>Setting Up</title>
<p>
The Driver handles the XML input.
The user agent information is through the FOUserAgent.
Handle logging through the user agent.
Options could also be handled through the user agent, using mime type
selection for renderer options.
</p>
  </section>
<section>
  <title>Others</title>
<p>
Render to more than one renderer at once (maybe not from the command line).
For example you could generate a PDF for the archive
and the PS for the printer in one run. It would probably be faster than
converting the PDF to PostScript afterwards.
Make the fo tree reuseable.
If the fonts are the same then use the
same area tree to output to different renderers.
</p>
<p>
Several code pieces for resolving URLs and/or
file locations are scattered all over FOP and Batik. These should
be replaced with an URIResolver invocation to unify behaviour and
remove redundancies.
   </p>
  </section>
</section>

    </body>
</document>