Hi Jeremias/Chris, First thing first; I'll second Jeremias's suggestion and Chris in saying that this is definitely a major release. The best reason is because we're purposefully changing behaviour. FOP is currently very flexible in handling URIs, it has a lot of contingency mechanisms for falling back if a file can't be found. These are great when FOP is invoked on the commandline, however, they have to be controlled in a cloud environment and unauthorised file access cannot be allowed. If users are relying on these contingencies, then they're going to find they have issues and I think that's a compelling reason for calling it a major change.
Jeremias, as for being unconvinced about the necessity of making these API changes, I'd say it's a shame you didn't hear the conversations we had here about it. I started this body of work a while ago, and took a lot of steps to avoid changing the API for 2 reasons: 1) The reasons you gave above 2) We're changing FOPs behaviour, changing the API as well, I was afraid the community wouldn't support so many changes. I'm not sure if this is an acceptable reason or not, but it played a big part in my thought process. However, it's just not feasible to unify URI resolution to a single mechanism to be used in a highly parallelised system if there is mutability in the member variables. Mutability in FopFactory means that FOP isn't thread-safe, changing the FopFactory in one thread could have repercussions in other threads, so we had to lock this down. Because there's some set up in FopFactory that requires I/O, the base-URI and the URI resolver have to be available from the start, from initialization of FopFactory. Unfortunately it's that simple. And we thought, since we're changing the API in an incompatible way (adding parameters to FopFactory.newInstance(...), we might as well take this time to update and improve the way FopFactory is built. The biggest problem being the disparity between when FopFactory is setup using a populated fop.xconf, an empty fop.xconf and no fop.xconf. The way we've implemented it, the API isn't actually changing very much, there're about 2/3 lines of code changes depending on if you're using a fop conf or not. The only thing I have left to say is that the system just wasn't designed for what we're asking it to do now. When FopFactory was written, clouds were in the sky and SaaS was a typo. For better or worse though, that's where the industry is putting its resources and if we want FOP to remain relevant, we've got to keep up with it. I know I'm preaching to the choir here, but we feel these changes are an improvement and they are a necessary part of the task. When we push up the changes to the temp branch, hopefully you'll be much more convinced that what we've done is a) an improvement and b) necessary. Mehdi On 2 April 2012 13:46, Chris Bowditch <bowditch_ch...@hotmail.com> wrote: > On 01/04/2012 15:47, Jeremias Maerki wrote: > > Hi Jeremias, > > Thanks for your feedback. I'm answering in place of Peter who is on > holiday this week. > > 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<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. >> > > I see your point. I don't think FOP would suffer from the same issue as we > only tend to release every other year or so :-) I do agree that we need to > minimize the changes to the public API, but in this case there is a good > reason for a small amount of change. We are making FOP suitable for a cloud > environment and to do that requires quite a few internal as well as some > minor external changes to the URI Resolvers. It's true that it could be > made to work without any change to the FOPFactory API, but the current > situation seems sub-optimal and since we would have to change the URI > Resolvers which are part of the API then why not do this at the same time > rather than delay it until later? > > > > >> 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). >> > > I agree that the URI Resolver and other minor changes to FOP Factory > should go into a major release, perhaps after the release that Glenn was > planning for Bidi support. > > Thanks, > > Chris > > > >> 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<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/ApiRequirements> >>>> http://wiki.apache.org/**xmlgraphics-fop/ApiDesign<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<http://wiki.apache.org/xmlgraphics-fop/URIResolution> >>>>> [2] >>>>> http://wiki.apache.org/**xmlgraphics-fop/**FopFactoryConfiguration<http://wiki.apache.org/xmlgraphics-fop/FopFactoryConfiguration> >>>>> >>>> >>>> >>>> >>>> Jeremias Maerki >>>> >>>> >> >> >> Jeremias Maerki >> >> >> >> >
