This page describes the requirements for FOP's end-user API. The hard requirements listed and agreed to here should be met by the time the first preview release of 1.0 is published.
Content here has been mostly taken from the older FOPAvalonization page and updated.
Hard requirements
HR1 |
consistent, easy to understand, to use, to configure |
HR2 |
easy to integrate into other systems (especially Cocoon, using a passive SAX-based approach, see |
HR3 |
appeal to both novice users and expert developers |
HR4 |
well documented behaviour |
HR5 |
little overhead |
HR6 |
thread-safe |
HR7 |
logging to any logging mechanism |
HR8 |
Programmatically evaluatable feedback from the layout process per processing run (overflows, validation feedback, notifications on page creation, new page-sequences etc.). Note: This is different from the logging aspect which is used for debugging purposes and log output may not be separatable by processing run. |
HR9 |
provide for all configuration aspects (fonts, extensions etc) |
HR10 |
Support for XML Resolver and special-purpose URI Resolvers |
HR11 |
widely acceptable configuration defaults |
HR12 |
use well known design and usage patterns (example: reused elements from JAXP wherever possible) |
HR13 |
several example classes demonstrating the use of FOPs API |
HR14 |
automatic plug-in mechanism for extensions |
HR15 |
Reuse configuration and caches for multiple processing runs while supporting different configurations in one VM (differentiate between engine configuration and per-document configuration) |
Wish list
WL1 |
automatic plug-in mechanism for renderers and FO event handlers (with the ability to override an existing renderer for a given MIME type. No client code changes should be necessary. |
WL2 |
At least partial compatibility with FOP 0.20.5 to ease the migration. (Alternative: Support for a general purpose FO processing API which allows easy switching of the implementation) |
WL3 |
Serializable, modifyable intermediate format between the layout engine and the renderers (use cases: manual layout tweaking, custom modifications, imposition (n-up) etc. |
WL4 |
Concatenation of multiple input documents to a single output file |
Applications/wrappers/examples to be included
- command line application for all stream output and direct print renderers, including Swing preview
- reusable AWT/Swing panel
- Ant task
- sample servlet
- to consider: Cocoon serializer
- to consider: Web Service
Detailed notes on certain requirements
HR1
(jeremias, 2005-06-26) ATM, if you supply your own renderer instance via the FOUserAgent you still have to use a RENDER_* constant in the constructor for the Fop class. That's not very beautiful and confusing.
HR8
(jeremias, 2005-06-26) At some point we should localize the clear-text feedback from the validation and layout process. If FOP is used in an end-user application, the errors and warning must be understandable to not-so-technical people.
wL1
(jeremias, 2005-06-26) I want renderer selection by MIME type even though there's technically no MIME type for a print renderer. No problem with leaving the integer constants as long as they go into a separate constants interface which isn't mixed with private constants for FOP's internal use. The myriad of constants showing up due to auto-complete in modern IDE's when programming against the FOP API is a PITA and a source for confusion.
(jeremias, 2005-06-26) The validity of the RendererFactory class will become evident with the implementation of this point. The RendererFactory will remain a FOP-internal facility. It is simply responsible to instantiate and configure the renderers which are not provided from the outside.
WL3
(jeremias, 2005-06-26) This has been brought to my attention by a client. It goes beyond what we currently have. Currently, we only support serializing the area tree using Java serialization. The intermediate format should ideally be XML. Implications on the design and the performance would have to be determined.