A proposal to change the configuration and deployment of FOP

[Peter Hancock <pe...@gmail.com>]

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

RE: A proposal to change the configuration and deployment of FOP

["Marquart, Joshua D" <jo...@firstdata.com>]

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:dev@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 <bo...@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 
> >>> <de...@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<de...@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. 

Re: A proposal to change the configuration and deployment of FOP

[mehdi houshmand <me...@gmail.com>]

Hi Jeremias,

I'll add my comments inline:
<snip/>

>
> 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.
>

Yeah, I/we do appreciate your concerns, it's important for any body of work
to stand up to scrutiny. We need your (both personal and the collective
"your") experience and expertise to critique our work not only so that we
maintain the high quality of FOP, but to improve ourselves as developers.


>
> 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.
>

I ask you this; how are we defining work? The caveats we imply and
assumptions we make aren't trivial. Are we talking about just producing
plain vanilla documents with no custom fonts and no images? Sure, works
like a dream. Or are we talking about very strict I/O such that no user can
either intentionally/unintentionally access someone else's resources under
ANY circumstances? Well... No. I'm just not confident that it would be
possible to guarantee that level of security.

Having immutability in the FopFactory allows us to make assertions, it
prevents "if (x == null) { x = <default value> }" all over the shop.


>
> 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.
>
> <snip/>

Well again, we're breaking the API anyways! Because FopFactory relies on
I/O for setup (the font-cache, and the fop-conf if it is used, the latter
I'll discuss in more detail), we need both a base-URI and a URI resolver
when the FopFactory is instantiated. There's not a lot we can do about
that, we can't have FOP accessing the "user.dir" in the cloud. There is an
argument to be made that we disallow fonts-caching, but then we're not
solving the problem, we're de-scoping.

As for the fop-conf, if it is used, keeping the old mechanism, a client
would have to do the following:

FopFactory f = FopFactory.newInstance();
f.setUriResolver(...);
f.setUserConfig(...);

If they didn't set the URI resolver *before* setting the user config, then
they're going to see different behaviour. Also if the did this:

FopFactory f = FopFactory.newInstance();
f.setUriResolver(...);
f.setUserConfig(...);
f.setUriResolver(...); <-- different URIResolver used here!

then they're gonna see even more unusual behaviour, since there's a
disparity between the URIResolver used set to configure the FopFactory and
that used to configure the PrintRenderers. A friend of mine once said to me
"you can use all your wit to make things idiot-proof and an idiot will come
along and out-smart you", and I very much agree you can't protect against
every quirky use-case. But the above just doesn't seem right to me. If an
object is used for configuring and initializing a class, it should be in
the constructor.

Thanks for your patience Jeremias, it really is appreciated,

Mehdi

Re: A proposal to change the configuration and deployment of FOP

[Jeremias Maerki <de...@jeremias-maerki.ch>]

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 <bo...@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
> >>> <de...@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<de...@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
> >>
> >>
> >>
> >>
> >




Jeremias Maerki

Re: A proposal to change the configuration and deployment of FOP

[Alexios Giotis <al...@gmail.com>]

On Apr 2, 2012, at 5:25 PM, mehdi houshmand wrote:

> 
> 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


I believe that the term 'cloud' does not describe well the proposed API changes, although it describes well how you intend to use FOP. The mutability of the FopFactory is not necessarily related to whether FOP is executed on the cloud or not. You are actually proposing an improvement to FOP multi-threading support. Based on the number of concurrency issues in FOP 1.0, I consider myself one of the first people who used FOP in a real multi-threaded environment. By now we have more than 10 production installations using FOP in 2 up to 8 systems. Some systems have up to 64 cores stressed by about 100 threads. None of the issues that came up, was related to the mutable and more importantly not thread-safe FopFactory members. Of course, care should be taken during initialization and it is certainly easy to provoke such an issue.

Having said that, I am very happy that I am seeing you moving there and I welcome the changes. A decision should be taken whether it is more important to keep a stable API or make it safer. Finally, as I wrote earlier, most users would expect breaking API changes when upgrading to a major version. But they would also expect new features and complex script support is more tangible than thread safety. It would be better to include them all in a single new release, assuming that there is not a lot of work there.

Alex Giotis

Re: A proposal to change the configuration and deployment of FOP

[mehdi houshmand <me...@gmail.com>]

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 <bo...@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
>>> <de...@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<de...@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
>>
>>
>>
>>
>

Re: A proposal to change the configuration and deployment of FOP

[Chris Bowditch <bo...@hotmail.com>]

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
>
> 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
>> <de...@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<de...@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
>
>
>

Re: A proposal to change the configuration and deployment of FOP

[Jeremias Maerki <de...@jeremias-maerki.ch>]

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
> <de...@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 <de...@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

Re: A proposal to change the configuration and deployment of FOP

[Peter Hancock <pe...@gmail.com>]

Hi Jeremias,

Thanks for your feedback!

On Wed, Mar 28, 2012 at 7:08 PM, Jeremias Maerki
<de...@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 <de...@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
>

Re: A proposal to change the configuration and deployment of FOP

[Alexios Giotis <al...@gmail.com>]

Hi Peter,

The public API could be improved but I also don't see in the wiki links
a good reason to do so. It is expected to have a stable public API,
once a project reaches a 1.0 version. Backwards incompatible changes
are expected in a 2.0 version for methods/classes that have been
deprecated. 

Alex Giotis


On Mar 28, 2012, at 9:08 PM, Jeremias Maerki 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
> 

Re: A proposal to change the configuration and deployment of FOP

[Glenn Adams <gl...@skynav.com>]

On Tue, Apr 3, 2012 at 5:26 PM, Martin Edge
<Ma...@intellimail.com.au>wrote:

> Yes, if you changed IF on me I'd need to know. I embed postscript commands
> in headers and page sequences.
>
> That said - if you are talking the java side of it versus the file format
> itself that doesn't affect me (but of course it may others)
>

The recent complex scripts patch changed both the IFPainter API and the IF
schema in minor, but substantive ways. [1][2]

[1] http://www.mail-archive.com/fop-dev@xmlgraphics.apache.org/msg12614.html
[2] http://www.mail-archive.com/fop-dev@xmlgraphics.apache.org/msg14721.html

Re: A proposal to change the configuration and deployment of FOP

[Martin Edge <Ma...@intellimail.com.au>]

Yes, if you changed IF on me I'd need to know. I embed postscript commands in headers and page sequences. 

That said - if you are talking the java side of it versus the file format itself that doesn't affect me (but of course it may others) 

Thanks 
Martin



---------------
Martin Edge
---------------

On 04/04/2012, at 5:54 AM, Jeremias Maerki <de...@jeremias-maerki.ch> wrote:

> Glenn,
> I see the IF API as an advanced use case for FOP. I've realized from the
> beginning that the IF might have to mature over time and that requires
> changes. My main concern in the whole discussion is stability for the
> large majority of FOP's users who just rely directly or indirecly (in
> the case of XML editors and such) on relatively easy upgrades,
> especially if FOP can one day be released more often (with an easier
> release process).
> 
> Just a thought loosely related to this: maybe we should introduce a
> "version" attribute on the root element to indicate the version of IF
> XML format so people can deal more easily with that.
> 
> Maybe there should be a registry of FOP's APIs and the stability policy
> for each.
> 
> On 02.04.2012 17:15:58 Glenn Adams wrote:
>> On Wed, Mar 28, 2012 at 12:08 PM, Jeremias Maerki <de...@jeremias-maerki.ch>wrote:
>> 
>>> 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.
>>> 
>> 
>> Would you consider a minor, but substantive technical change to the IF
>> APIs, specifically, to IFPainter, to require a revision of the major
>> version? I ask this because one of the arguments to IFPainter.drawText()
>> has been changed from int[] to int[][] in the recent complex scripts merge.
>> 
>> In other words, are the IF public APIs to be considered part of the formal
>> public FOP API that is subject to version control rules?
>> 
>> Do we have a precise list of which APIs are (or should be) subject to such
>> rules?
> 
> 
> 
> 
> Jeremias Maerki
> 

Re: A proposal to change the configuration and deployment of FOP

[Glenn Adams <gl...@skynav.com>]

On Tue, Apr 3, 2012 at 1:54 PM, Jeremias Maerki <de...@jeremias-maerki.ch>wrote:

> Glenn,
> I see the IF API as an advanced use case for FOP. I've realized from the
> beginning that the IF might have to mature over time and that requires
> changes. My main concern in the whole discussion is stability for the
> large majority of FOP's users who just rely directly or indirecly (in
> the case of XML editors and such) on relatively easy upgrades,
> especially if FOP can one day be released more often (with an easier
> release process).
>
> Just a thought loosely related to this: maybe we should introduce a
> "version" attribute on the root element to indicate the version of IF
> XML format so people can deal more easily with that.
>

good idea; i will add


>
> Maybe there should be a registry of FOP's APIs and the stability policy
> for each.
>

ditto


>
> On 02.04.2012 17:15:58 Glenn Adams wrote:
> > On Wed, Mar 28, 2012 at 12:08 PM, Jeremias Maerki <
> dev@jeremias-maerki.ch>wrote:
> >
> > > 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.
> > >
> >
> > Would you consider a minor, but substantive technical change to the IF
> > APIs, specifically, to IFPainter, to require a revision of the major
> > version? I ask this because one of the arguments to IFPainter.drawText()
> > has been changed from int[] to int[][] in the recent complex scripts
> merge.
> >
> > In other words, are the IF public APIs to be considered part of the
> formal
> > public FOP API that is subject to version control rules?
> >
> > Do we have a precise list of which APIs are (or should be) subject to
> such
> > rules?
>
>
>
>
> Jeremias Maerki
>
>

Re: A proposal to change the configuration and deployment of FOP

[Jeremias Maerki <de...@jeremias-maerki.ch>]

Glenn,
I see the IF API as an advanced use case for FOP. I've realized from the
beginning that the IF might have to mature over time and that requires
changes. My main concern in the whole discussion is stability for the
large majority of FOP's users who just rely directly or indirecly (in
the case of XML editors and such) on relatively easy upgrades,
especially if FOP can one day be released more often (with an easier
release process).

Just a thought loosely related to this: maybe we should introduce a
"version" attribute on the root element to indicate the version of IF
XML format so people can deal more easily with that.

Maybe there should be a registry of FOP's APIs and the stability policy
for each.

On 02.04.2012 17:15:58 Glenn Adams wrote:
> On Wed, Mar 28, 2012 at 12:08 PM, Jeremias Maerki <de...@jeremias-maerki.ch>wrote:
> 
> > 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.
> >
> 
> Would you consider a minor, but substantive technical change to the IF
> APIs, specifically, to IFPainter, to require a revision of the major
> version? I ask this because one of the arguments to IFPainter.drawText()
> has been changed from int[] to int[][] in the recent complex scripts merge.
> 
> In other words, are the IF public APIs to be considered part of the formal
> public FOP API that is subject to version control rules?
> 
> Do we have a precise list of which APIs are (or should be) subject to such
> rules?




Jeremias Maerki

Re: A proposal to change the configuration and deployment of FOP

[mehdi houshmand <me...@gmail.com>]

Hi Glenn,

Firstly, although this is loosely related, can you try to keep the emails
in the thread relevant, this is going to be a verbose thread so we don't
want to add to the confusion. As for the public API, I don't believe
IFPainter is part of the public API, but I'm not sure who does and doesn't
agree. I wrote that wiki page in hope that we'd come to some consensus, but
it just moved from the fore of conversation, looks like we're back there.

Mehdi

On 2 April 2012 16:24, Glenn Adams <gl...@skynav.com> wrote:

>
> On Mon, Apr 2, 2012 at 9:15 AM, Glenn Adams <gl...@skynav.com> wrote:
>
>> On Wed, Mar 28, 2012 at 12:08 PM, Jeremias Maerki <dev@jeremias-maerki.ch
>> > wrote:
>>
>>> 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.
>>>
>>
>> Would you consider a minor, but substantive technical change to the IF
>> APIs, specifically, to IFPainter, to require a revision of the major
>> version? I ask this because one of the arguments to IFPainter.drawText()
>> has been changed from int[] to int[][] in the recent complex scripts merge.
>>
>> In other words, are the IF public APIs to be considered part of the
>> formal public FOP API that is subject to version control rules?
>>
>> Do we have a precise list of which APIs are (or should be) subject to
>> such rules?
>>
>
> I found http://xmlgraphics.apache.org/fop/trunk/embedding.html#API
>
> But I see this doesn't list IFPainter, even though
> IFDocumentHandler.startPageContent() returns an IFPainter.
>
> Also, I should mention that the CS patch made two minor, but substantive
> changes to the IF schema (and thus output format). Should changes to the IF
> schema also be subject to public version control rules?
>
>

Re: A proposal to change the configuration and deployment of FOP

[Glenn Adams <gl...@skynav.com>]

On Mon, Apr 2, 2012 at 9:15 AM, Glenn Adams <gl...@skynav.com> wrote:

> On Wed, Mar 28, 2012 at 12:08 PM, Jeremias Maerki <de...@jeremias-maerki.ch>wrote:
>
>> 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.
>>
>
> Would you consider a minor, but substantive technical change to the IF
> APIs, specifically, to IFPainter, to require a revision of the major
> version? I ask this because one of the arguments to IFPainter.drawText()
> has been changed from int[] to int[][] in the recent complex scripts merge.
>
> In other words, are the IF public APIs to be considered part of the formal
> public FOP API that is subject to version control rules?
>
> Do we have a precise list of which APIs are (or should be) subject to such
> rules?
>

I found http://xmlgraphics.apache.org/fop/trunk/embedding.html#API

But I see this doesn't list IFPainter, even though
IFDocumentHandler.startPageContent() returns an IFPainter.

Also, I should mention that the CS patch made two minor, but substantive
changes to the IF schema (and thus output format). Should changes to the IF
schema also be subject to public version control rules?

Re: A proposal to change the configuration and deployment of FOP

[Glenn Adams <gl...@skynav.com>]

On Wed, Mar 28, 2012 at 12:08 PM, Jeremias Maerki <de...@jeremias-maerki.ch>wrote:

> 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.
>

Would you consider a minor, but substantive technical change to the IF
APIs, specifically, to IFPainter, to require a revision of the major
version? I ask this because one of the arguments to IFPainter.drawText()
has been changed from int[] to int[][] in the recent complex scripts merge.

In other words, are the IF public APIs to be considered part of the formal
public FOP API that is subject to version control rules?

Do we have a precise list of which APIs are (or should be) subject to such
rules?

Re: A proposal to change the configuration and deployment of FOP

[Jeremias Maerki <de...@jeremias-maerki.ch>]

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