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
>

Reply via email to