Thanks for elaborating, Peter. Your use of the term "deployment" is indeed rather unorthodox. When I read "deployment", I instantly think: http://en.wikipedia.org/wiki/Software_deployment
I'm afraid you still haven't convinced me of the necessity to break the public API even if, as you say, it's only a minimal change. It's the difference between being able to upgrade FOP with a replacement of a JAR and the process of adjusting glue code to the changes, testing and re-releasing them. Obviously, you'll still have to test your documents with a release change. However, integrators such as OxygenXML, XMLSpy, Stylus Studio, XMLmind, XSLfast, Apache Cocoon and many others have to change their products again to be able to use the new FOP version. Their clients cannot just switch JARs. I can tell tales about how many hours I've spent porting/duplicating the Barcode4J extension for Saxon many times because the plug-in API changed even within minor revisions. Ultimately, I stopped trying to keep up. I'm sure you get the drift. If there was a case of: "if we don't break the public API, then we can't do X", I would understand the desire for such a step, but I'm not seeing that here, even with the new approach on URI resolution which I'm pretty sure can be fitted in a backwards-compatible way. And if it gets decided to change the public API in a backwards-incompatible way, then I second Alexios' call for the necessity of a major version jump (2.0). On 30.03.2012 16:53:37 Peter Hancock wrote: > Hi Jeremias, > > Thanks for your feedback! > > On Wed, Mar 28, 2012 at 7:08 PM, Jeremias Maerki > <d...@jeremias-maerki.ch> wrote: > > Hi Peter, > > > > can you please explain what problem you're trying to solve? From the > > Wiki pages I cannot derive that. And what do you mean by the separation > > of configuration and deployment? I'm particularly clueless as to how an > > API affects deployment here. > > By configuration I refer to the process of configuring the Fopfactory; > both through direct programmatic means and via the parsing of the fop.xconf. > > By deployment I refer to the creation of the FOUserAgent and Fop object. > > The problems we wish to solve are ones of maintainability and > simplicity, and modest in scope: We think that having an unmodifiable > FopFactory would allow developers to make certain assertions with > absolute confidence about the state of the system; from the point when > the Fop object is created (what I was unhelpfully referring to as > deployment) to the closing of the render output stream. Currently, > classes that contribute to the FOP process have access to the FopFactory > and can conceivably modify it. Although this does not actually occur in > the code-base, extension code with access to the FopFactory could, > causing non-trivial bugs to emerge. > > > There must be a really, really good reason to change the frontmost > > public API of FOP in a backwards-incompatible way. Changing the API will > > cause considerable work for all users when they upgrade. We must not do > > that on a whim. > > > > Absolutely. We are trying to make minimal API changes to achieve our > objectives. The updates we are making to allow the external control of > all IO will require more substantial changes to the API, and therefore > we considered this a good time to make further changes. Assuming that > breaking changes are inevitable during FOP's lifetime, I suppose we have > to judge the impact of frequent minor breaks against infrequent major > breaks and the associated development costs. I think that the designed > public API (which has been previously discussed) of FOP and the actual > public API (classes/members with visible access modifiers) are generally > not close enough; and the wider the API, the harder we all have to work > maintain backwards compatibility. > > > The current API is the product of long discussions and a positive vote > > back in 2005/2006. It was roughly modelled after the JAXP pattern with > > TransformerFactory and Transformer. I'd say that the API has proven to > > be solid over the years. > > We do not propose a big change to this API and I am confident that they > will are faithful to the ambitions of the API requirements [1]. > > Referring to the hard requirements HR1-15: > > HR1 > Our proposal should make it configuration more consistent, there were > disparities between how FOP was configured (an empty fop.xconf would > configure FOP differently to the case when none was supplied!) > > HR3 > I think we have simplified API by making the distinction between config > and deployment explicit. > > HR4 > We will fully document. > > HR6 > Immutability configuration help to reduce concurrency related issues. > > HR10 > This is addressed as part of the wider URI resolution work. > > HR13 > All examples will be updated. > > The remaining requirements have not affected by the proposal. > > If we do proceed with these changes as part of the wider URI resolution > work, we would expect them to be included into trunk as part of a later > major revision. > > [1] http://wiki.apache.org/xmlgraphics-fop/ApiRequirements > > > > On Wed, Mar 28, 2012 at 7:08 PM, Jeremias Maerki <d...@jeremias-maerki.ch> > wrote: > > Hi Peter, > > > > can you please explain what problem you're trying to solve? From the > > Wiki pages I cannot derive that. And what do you mean by the separation > > of configuration and deployment? I'm particularly clueless as to how an > > API affects deployment here. > > > > There must be a really, really good reason to change the frontmost > > public API of FOP in a backwards-incompatible way. Changing the API will > > cause considerable work for all users when they upgrade. We must not do > > that on a whim. > > > > The current API is the product of long discussions and a positive vote > > back in 2005/2006. It was roughly modelled after the JAXP pattern with > > TransformerFactory and Transformer. I'd say that the API has proven to > > be solid over the years. > > > > For reference: > > http://wiki.apache.org/xmlgraphics-fop/ApiRequirements > > http://wiki.apache.org/xmlgraphics-fop/ApiDesign > > > > On 28.03.2012 12:02:27 Peter Hancock wrote: > >> Hello, > >> > >> As part of our work addressing URI resolution in FOP [1], Mehdi and > >> myself have been considering making changes to the configuration and > >> deployment of FOP. Our proposal will introduce breaking changes to > >> the public API that will affect code that embeds FOP. Please review > >> our proposal [2] and provide feedback. > >> > >> Thanks, > >> > >> Peter > >> > >> [1] http://wiki.apache.org/xmlgraphics-fop/URIResolution > >> [2] http://wiki.apache.org/xmlgraphics-fop/FopFactoryConfiguration > > > > > > > > > > Jeremias Maerki > > Jeremias Maerki
