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 getDefaultHandler())

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

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.

ApiRequirements (last edited 2009-09-20 23:52:24 by localhost)