As a developer who successfully moved our deployment from one FOP
version to the next, we had very few problems transitioning due to pages
like this:

http://xmlgraphics.apache.org/fop/trunk/upgrading.html

I don't see why this sort of alteration wouldn't be handled here.  In my
opinion, the upgrading page for each version is quite appropriately
blatant.

-Josh

-----Original Message-----
From: Jeremias Maerki [mailto:d...@jeremias-maerki.ch] 
Sent: Tuesday, April 03, 2012 3:36 PM
To: fop-dev@xmlgraphics.apache.org
Subject: Re: A proposal to change the configuration and deployment of
FOP

Thanks for the extensive explanation, Mehdi (and Chris)!

First, I'd like to stress that I'm not putting out a veto here. I'm just
trying to take the position of an advocate to the FOP users who might
not all follow the development closely.

Back on the technical side: A JAXP TransformerFactory is just as mutable
as the FopFactory, but only if it's handled wrongly by the developer of
the client code. In the application I'm currently working on, the
FopFactory is created once based on the configuration and registered as
an OSGi service. All client code using the FopFactory (service) is
written as if the FopFactory is immutable. Yes, I'm counting on the
participants to play nice although I can still proxy the FopFactory if
need be. And my application is also targeted to be deployable in the
cloud (I hate that wishy-washy term) and already works with zero access
to the local file system.

So to be frank, I still see squeeky clean, best practice design (which
is in itself nothing but good) being put before continuity (or API
stability) without an absolute need for an API break to enable
"cloud-compatibility". And I personally weigh API stability higher than
design principles. The world isn't perfect. However, I see no problem
improving the URI resolution the way you propose it as long as it is
done in a backwards-compatible way. Again, no veto, just my opinion. I
might be the only one here who sees it that way.

On 02.04.2012 16:25:21 mehdi houshmand wrote:
> 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.wikipe
> >> dia.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.ap
> >>>> ache.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://wi
> >>>>> ki.apache.org/xmlgraphics-fop/URIResolution>
> >>>>> [2] 
> >>>>> http://wiki.apache.org/**xmlgraphics-fop/**FopFactoryConfigurati
> >>>>> on<http://wiki.apache.org/xmlgraphics-fop/FopFactoryConfiguratio
> >>>>> n>
> >>>>>
> >>>>
> >>>>
> >>>>
> >>>> Jeremias Maerki
> >>>>
> >>>>
> >>
> >>
> >> Jeremias Maerki
> >>
> >>
> >>
> >>
> >




Jeremias Maerki


-----------------------------------------
The information in this message may be proprietary and/or
confidential, and protected from disclosure.  If the reader of this
message is not the intended recipient, or an employee or agent
responsible for delivering this message to the intended recipient,
you are hereby notified that any dissemination, distribution or
copying of this communication is strictly prohibited. If you have
received this communication in error, please notify First Data
immediately by replying to this message and deleting it from your
computer.

Reply via email to