Dear Wiki user, You have subscribed to a wiki page or wiki category on "Xmlgraphics-fop Wiki" for change notification.
The "FopFactoryConfiguration" page has been changed by Peter Hancock: http://wiki.apache.org/xmlgraphics-fop/FopFactoryConfiguration New page: = Proposed changes to Fop configuration and deployment (the o.a.f.apps API) = '''''The following is a proposal to modify some parts of the FOP API that are used for configuring and executing the FOP process (e.g fo -> pdf). The change is designed to make the separation of configuration and deployment both explicit and enforceable.''''' == Current API == The FOP process is executed using an instance of o.a.f.apps.Fop, and typically triggered from an XSLT transform: {{{transformer.transform(new StreamSource(inputFoFile), fop.getDefaultHandler())}}} Many configurable options are available to customize the process. e.g. enabling accessibility in PDF output. Configuration can be shared amongst different instances of FOP, and this is coordinated with a FopFactory and a FOUserAgent. To describe how these classes collaborate, lets consider a fairly general use case 1. {{{FopFactory fopFactory = FopFactory.newInstance();}}} 1. {{{fopFactory.setX(x);}}} 1. {{{fopFactory.setUserConfig(fopConfFile);}}} 1. {{{//Triggers a parse of the fop conf file and the setting of properties on the fopFactory}}} 1. {{{FOUserAgent foUserAgent = fopFactory.newFOUserAgent();}}} 1. {{{foUserAgent.set...}}} 1. {{{fopFactory.set... //!!!}}} 1. {{{Fop fop = fopFactory.newFop(outputFormat, foUserAgent, mimeType);}}} 1. {{{// trigger FOP process}}} The Fop object has access to the FOUserAgent and the FopFactory (exposed by FOUserAgent) >From line 4 we see that the is a one-to-many relationship between FopFactory >and FOUserAgent; The intended use of this API is to create one FOUserAgent >for each Fop instance, however there is no restriction in place to ensure >this, neither intent to change this behaviour in the near future. The code demonstrates that the configuration of the FopFactory can be interleaved with the construction of the Fop instance, and furthermore, the internal FOP process can change properties of the FopFactory (and FOUserAgent) and making assertions about the state of Fop is made difficult. == Proposed changes == We propose a change to the API to impose that the configuration and creation of Fop is done in a strict sequential order. To orchestrate this we have introduced a few new classes, notably FopConfParser and FopFactoryBuilder (plus others explained below). An example best demonstrates this: 1. {{{// Parse the fopConf, setting properties on the FopFactoryBuilder}}} 1. {{{FopFactoryBuilder fopFactoryBuilder = new FopConfParser(userConfigFile).getFopFactoryBuilder()}}} 1. {{{fopFactoryBuilder.setX(x);}}} 1. {{{FopFactory fopFactory = fopFactoryBuilder.build();}}} 1. {{{fopFactoryBuilder.setX(x) // ! throws an IllegalStateException !}}} Note that now, once built, the FopFactory properties cannot be reassigned (although they may be references to mutable data, of course). The FOUserAgent no longer provides access to the FopFactory, but instead provides the read-only properties directly ( FOUserAgent.getFopFactory().getX() becomes FOUserAgent.getX(). Further more, for backwards compatibility the static members newFop(String) and newFop(String, OutputStream) have been added (these are required by o.a.f.cli.InputHandler). Other than than the removal of getFopFactory(), changes to FOUserAgent will have no impact upon Fop client code. At this stage, other than the FopFactory (and possible URI resolution related ones)), access to properties that are exclusive to the FOUserAgent will not change. The FopConfParser replaces FopFactoryConfigurator: it delegates to the Avalon framework to parse the XML configuration and sets properties on it's FopFactoryBuilder. FopFactory still exposes static factory methods to create instances when no programmatic configuration of a FopFactoryBuilder is required. These are: * {{{public static FopFactory newInstance(String fopConfFile);}}} * {{{public static FopFactory newInstance(URI baseURI);}}} The last method is introduced as part of URIResolution == Going forward == The FopFactoryConfig should become an internal of FopFactoryBuilder which directly creates immutable FopFactory instances == Questions == Is there a use case for setting properties on the FopFactoryBuilder before parsing the fopConf? - this is a trivial change left out to simplify the API: we would just need to implement new FopConfParser(args..., FopFactoryBuilder) --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
