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
<d...@jeremias-maerki.ch> wrote:
> Hi Peter,
>
> can you please explain what problem you're trying to solve? From the
> Wiki pages I cannot derive that. And what do you mean by the separation
> of configuration and deployment? I'm particularly clueless as to how an
> API affects deployment here.
By configuration I refer to the process of configuring the Fopfactory;
both through direct programmatic means and via the parsing of the fop.xconf.
By deployment I refer to the creation of the FOUserAgent and Fop object.
The problems we wish to solve are ones of maintainability and
simplicity, and modest in scope: We think that having an unmodifiable
FopFactory would allow developers to make certain assertions with
absolute confidence about the state of the system; from the point when
the Fop object is created (what I was unhelpfully referring to as
deployment) to the closing of the render output stream. Currently,
classes that contribute to the FOP process have access to the FopFactory
and can conceivably modify it. Although this does not actually occur in
the code-base, extension code with access to the FopFactory could,
causing non-trivial bugs to emerge.
> There must be a really, really good reason to change the frontmost
> public API of FOP in a backwards-incompatible way. Changing the API will
> cause considerable work for all users when they upgrade. We must not do
> that on a whim.
>
Absolutely. We are trying to make minimal API changes to achieve our
objectives. The updates we are making to allow the external control of
all IO will require more substantial changes to the API, and therefore
we considered this a good time to make further changes. Assuming that
breaking changes are inevitable during FOP's lifetime, I suppose we have
to judge the impact of frequent minor breaks against infrequent major
breaks and the associated development costs. I think that the designed
public API (which has been previously discussed) of FOP and the actual
public API (classes/members with visible access modifiers) are generally
not close enough; and the wider the API, the harder we all have to work
maintain backwards compatibility.
> The current API is the product of long discussions and a positive vote
> back in 2005/2006. It was roughly modelled after the JAXP pattern with
> TransformerFactory and Transformer. I'd say that the API has proven to
> be solid over the years.
We do not propose a big change to this API and I am confident that they
will are faithful to the ambitions of the API requirements [1].
Referring to the hard requirements HR1-15:
HR1
Our proposal should make it configuration more consistent, there were
disparities between how FOP was configured (an empty fop.xconf would
configure FOP differently to the case when none was supplied!)
HR3
I think we have simplified API by making the distinction between config
and deployment explicit.
HR4
We will fully document.
HR6
Immutability configuration help to reduce concurrency related issues.
HR10
This is addressed as part of the wider URI resolution work.
HR13
All examples will be updated.
The remaining requirements have not affected by the proposal.
If we do proceed with these changes as part of the wider URI resolution
work, we would expect them to be included into trunk as part of a later
major revision.
[1] http://wiki.apache.org/xmlgraphics-fop/ApiRequirements
On Wed, Mar 28, 2012 at 7:08 PM, Jeremias Maerki<d...@jeremias-maerki.ch>
wrote:
Hi Peter,
can you please explain what problem you're trying to solve? From the
Wiki pages I cannot derive that. And what do you mean by the separation
of configuration and deployment? I'm particularly clueless as to how an
API affects deployment here.
There must be a really, really good reason to change the frontmost
public API of FOP in a backwards-incompatible way. Changing the API will
cause considerable work for all users when they upgrade. We must not do
that on a whim.
The current API is the product of long discussions and a positive vote
back in 2005/2006. It was roughly modelled after the JAXP pattern with
TransformerFactory and Transformer. I'd say that the API has proven to
be solid over the years.
For reference:
http://wiki.apache.org/xmlgraphics-fop/ApiRequirements
http://wiki.apache.org/xmlgraphics-fop/ApiDesign
On 28.03.2012 12:02:27 Peter Hancock wrote:
Hello,
As part of our work addressing URI resolution in FOP [1], Mehdi and
myself have been considering making changes to the configuration and
deployment of FOP. Our proposal will introduce breaking changes to
the public API that will affect code that embeds FOP. Please review
our proposal [2] and provide feedback.
Thanks,
Peter
[1] http://wiki.apache.org/xmlgraphics-fop/URIResolution
[2] http://wiki.apache.org/xmlgraphics-fop/FopFactoryConfiguration
Jeremias Maerki
Jeremias Maerki
