You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-dev@xmlgraphics.apache.org by Jeremias Maerki <de...@jeremias-maerki.ch> on 2006/02/07 10:09:38 UTC
Finally finalizing the FOP API
As part of my upcoming optimization work I want to finalize the FOP API.
I've written down a proposal in the Wiki:
http://wiki.apache.org/xmlgraphics-fop/ApiDesign
If possible, I'd like to have that finished by the end of the week.
Please post your feedback ASAP.
Jeremias Maerki
Re: Finally finalizing the FOP API
Posted by Jess Holle <je...@ptc.com>.
The Fop API is fine -- as long as it remains stable to the minimal level
I'm using it.
I'm just doing:
final Class fopClass = Class.forName( "org.apache.fop.apps.Fop" );
final Object fop = fopClass.getConstructor( String.class ).newInstance( "application/pdf" ); // new Fop( "application/pdf" )
fopClass.getMethod( "setOutputStream", OutputStream.class ).invoke( fop, a_outputStream ); // fop.setOutputStream( a_outputStream )
final DefaultHandler defaultHandler = (DefaultHandler) fopClass.getMethod( "getDefaultHandler" ).invoke( fop ); // fop.getDefaultHandler()
That's it (catch block omitted, of course).
It's always good to keep the simple stuff simple, but in this case
having to load just one class and call only 1 constructor and 2 methods
makes this approach quite reasonable whereas I'd hate to have a whole
lot more of such code to do the same thing. [Note the 0.20.5 code is
just slightly longer so 0.91 is a good step in this respect.]
--
Jess Holle
Jeremias Maerki wrote:
> Noted, but the fact that the API is not stable has been documented in [1].
> We've been pushing finalizing the API before us for a long time. The old
> 0.20.5 API sadly doesn't fit all the requirements that we have today.
>
> Another idea for your situation is a wrapper API that shields you from
> the actualy API of the FO implementation you use. I've written such a
> wrapper API [2] although the published version is now a little behind
> and would need to be updated. Furthermore, I got negative feedback from
> Sun about my choice of name. But if there is sufficient demand and a
> little help I can always revive it. I'm actively using it in my private
> projects.
>
> [1] http://xmlgraphics.apache.org/fop/0.91/upgrading.html
> [2] http://www.jeremias-maerki.ch/dev/jaxg/index.html
>
> On 07.02.2006 10:46:48 Jess Holle wrote:
>
>> Having just added reflection code to make my code work with 0.20.5 and
>> 0.91 beta, I'd like to see the existing Fop() constructor continue to
>> work as per 0.91 beta.
>>
>> Overall having to use reflection to maintain use of the current stable
>> while being ready for the future is at once understandable and
>> obnoxious. The simpler the new API is for simple cases (I'm *not*
>> re-using anything from one execution to the next due to the infrequency
>> of the calls, etc) and the sooner it stabilizes for these, the better.
>> I had kind of assumed that "beta" meant "API is stable for simple cases" :-)
>>
>> --
>> Jess Holle
>>
>> Jeremias Maerki wrote:
>>
>>> As part of my upcoming optimization work I want to finalize the FOP API.
>>> I've written down a proposal in the Wiki:
>>> http://wiki.apache.org/xmlgraphics-fop/ApiDesign
>>>
>>> If possible, I'd like to have that finished by the end of the week.
>>> Please post your feedback ASAP.
>>>
>>> Jeremias Maerki
>>>
>>>
>>>
>
>
>
> Jeremias Maerki
>
>
Re: Finally finalizing the FOP API
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
Noted, but the fact that the API is not stable has been documented in [1].
We've been pushing finalizing the API before us for a long time. The old
0.20.5 API sadly doesn't fit all the requirements that we have today.
Another idea for your situation is a wrapper API that shields you from
the actualy API of the FO implementation you use. I've written such a
wrapper API [2] although the published version is now a little behind
and would need to be updated. Furthermore, I got negative feedback from
Sun about my choice of name. But if there is sufficient demand and a
little help I can always revive it. I'm actively using it in my private
projects.
[1] http://xmlgraphics.apache.org/fop/0.91/upgrading.html
[2] http://www.jeremias-maerki.ch/dev/jaxg/index.html
On 07.02.2006 10:46:48 Jess Holle wrote:
> Having just added reflection code to make my code work with 0.20.5 and
> 0.91 beta, I'd like to see the existing Fop() constructor continue to
> work as per 0.91 beta.
>
> Overall having to use reflection to maintain use of the current stable
> while being ready for the future is at once understandable and
> obnoxious. The simpler the new API is for simple cases (I'm *not*
> re-using anything from one execution to the next due to the infrequency
> of the calls, etc) and the sooner it stabilizes for these, the better.
> I had kind of assumed that "beta" meant "API is stable for simple cases" :-)
>
> --
> Jess Holle
>
> Jeremias Maerki wrote:
> > As part of my upcoming optimization work I want to finalize the FOP API.
> > I've written down a proposal in the Wiki:
> > http://wiki.apache.org/xmlgraphics-fop/ApiDesign
> >
> > If possible, I'd like to have that finished by the end of the week.
> > Please post your feedback ASAP.
> >
> > Jeremias Maerki
> >
> >
Jeremias Maerki
Re: Finally finalizing the FOP API
Posted by Jess Holle <je...@ptc.com>.
Having just added reflection code to make my code work with 0.20.5 and
0.91 beta, I'd like to see the existing Fop() constructor continue to
work as per 0.91 beta.
Overall having to use reflection to maintain use of the current stable
while being ready for the future is at once understandable and
obnoxious. The simpler the new API is for simple cases (I'm *not*
re-using anything from one execution to the next due to the infrequency
of the calls, etc) and the sooner it stabilizes for these, the better.
I had kind of assumed that "beta" meant "API is stable for simple cases" :-)
--
Jess Holle
Jeremias Maerki wrote:
> As part of my upcoming optimization work I want to finalize the FOP API.
> I've written down a proposal in the Wiki:
> http://wiki.apache.org/xmlgraphics-fop/ApiDesign
>
> If possible, I'd like to have that finished by the end of the week.
> Please post your feedback ASAP.
>
> Jeremias Maerki
>
>
Re: Finally finalizing the FOP API
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
On 08.02.2006 22:03:30 Simon Pepping wrote:
> Jeremias,
>
> On Tue, Feb 07, 2006 at 10:09:38AM +0100, Jeremias Maerki wrote:
> > As part of my upcoming optimization work I want to finalize the FOP API.
> > I've written down a proposal in the Wiki:
> > http://wiki.apache.org/xmlgraphics-fop/ApiDesign
> >
> > If possible, I'd like to have that finished by the end of the week.
> > Please post your feedback ASAP.
>
> Some remarks and questions.
>
> 1. D11, D12: FopEnvironment should be FopFactory?
Yes, of course. I had FopEnvironment at first and then decided to more
closely follow the JAXP pattern.
> 2. How does FOUserAgent differ from FopFactory? What is rendering run
> dependent in FOUserAgent, now and in the future?
FOUserAgent is the object which acts as an agent for the user in a
transaction (i.e. rendering run). It's the central interaction point in
both directions. The user gives settings for the document currently
being created. FOP, on the other side, can communicate with the user
through the user agent by telling him about layout problems, for example
(user feedback mechanism I want to propose later).
FopFactory on the other side is the place where things are configured
that will be used for multiple rendering runs. Take font configuration,
for example. That won't likely change between rendering runs. You set it
up once and you also want FOP to initialize the font setup only once and
reuse it for every rendering run for performance reason. Font
initialization is a rather expensive operation. Similarly, the image
cache will also be attached to the FopFactory.
Rendering run dependent is stuff that is specific to a single document
and may potentially be different for the next document, i.e. metadata,
specially set up renderers, PDF encryption parameters etc. Granted,
there is no hard line here. It may well up subject for discussion what
ends up where. I tried to do a good division.
> 3. Is FopFactory's main role being a factory, or being a configuration
> holding object across rendering runs? I am not charmed by the name
> FopFactory; it does not seem to describe its role, only a side
> effect of its role, viz. spawning rendering runs.
I agree with you that FopFactory may not be ideal. If there's a better
choice, I'm open to suggestions. I've tried to model everything as close
as possible to the JAXP Transformer API because that's what people
already know. And even the TransformerFactory has a double-function:
It's a factory in the pattern sense and it holds configuration values
that will affect the instances created through the factory methods.
> 4. You write about XML configuration. Can the configuration on a fop
> factory also be set using an Avalon Configuration object?
ATM, configuration is exclusively set using an Avalon Configuration
object. That will remain but I'd like to add one or two additional
methods where people can simply specify an URL or a java.io.File and FOP
does the config file loading.
> 5. Do I understand correctly that the main alternatives to start a
> rendering run are:
>
> A.
> Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF);
>
> B.
> FOUserAgent userAgent = fopFactory.newFOUserAgent();
> userAgent.setTitle("My document");
> Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, userAgent);
>
> The difference being that in method B one can set properties that
> are specific to this rendering run?
That kind of pattern is already used today. Only the way the user agent
and the Fop instance are instantiated is different. People who are happy
to convert using the default settings can omit specifying the user agent.
Fop uses a default user agent in this case. No change to the current
behaviour at all.
> 6. D5 (The FOUserAgent can return the FopFactory instance. (needed
> internally by FOP)): Why? Because FOUserAgent is the programmed way
> to get at configuration settings? Could it be better to implement
> get methods on the user agent which get the settings from the
> factory object (factory object not exposed)? Or even pass the
> factory object instead of the user agent (Cf. question 2)?
We're already passing down the FOUserAgent in a number of places and
it's a good place to access central resources. If it is preferred I have
no objections to access the FopFactory values directly through method on
the FOUserAgent although I expect additions to the FOUserAgent in the
future and separating certain things to the FopFactory will clean it up
a little and make it clear on what level the values/services are
available. And yes, we could pass down the factory instance instead of
the user agent. That is certainly a possibility, one that may make sense
in certain places. Again, I'm open to suggestions. I haven't fully made
up my mind and I've asked for feedback to get additional eye-pairs on
the proposal.
> 7. What is the difference between these to instantiation methods:
>
> FOUserAgent userAgent = fopFactory.newFOUserAgent(); (D6)
> FOUserAgent userAgent = new FOUserAgent(fopFactory); (D3)
D3 is intended for use by the FopFactory. The user is not really
supposed to call the constructor directly. With the current proposal
there's no harm if someone uses the FOUserAgent constructor directly,
but we could of course hide it by making the FOUserAgent into an
interface. But I don't think it's really necessary. It's probably a
similar argument as Jesse Holle's on the Fop constructor.
Thanks for the feedback!!!!
Jeremias Maerki
Re: Finally finalizing the FOP API
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
Ok, the necessary changes except for the deprecations are done in the
branch.
On 13.02.2006 10:16:25 Jeremias Maerki wrote:
<snip/>
> I decided that I will implement my proposal in
> a new branch. There, everyone can have a look at the real thing and
> we'll adjust as necessary to make everyone happy.
<snip/>
Jeremias Maerki
Re: Finally finalizing the FOP API
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
On 12.02.2006 21:18:56 Andreas L Delmelle wrote:
> On Feb 8, 2006, at 22:03, Simon Pepping wrote:
>
> Simon / Jeremias,
>
> >
> > 6. D5 (The FOUserAgent can return the FopFactory instance. (needed
> > internally by FOP)): Why? Because FOUserAgent is the programmed way
> > to get at configuration settings? Could it be better to implement
> > get methods on the user agent which get the settings from the
> > factory object (factory object not exposed)? Or even pass the
> > factory object instead of the user agent (Cf. question 2)?
>
> I agree with this comment in particular. I'd prefer to not expose the
> Factory, but implement accessors for the persistent settings. It even
> allows for a sort of flexibility where it comes to the so-called
> persistent data across multiple rendering runs...?
> A bit unclear maybe, so some further explanation: I'm also thinking
> in terms of on-demand loading of certain data, if requested so by the
> user agent. Once it's loaded, it will be readily available for
> another user agent. If no user agent ever requests it, it will never
> be loaded into memory.
Uhm, I can't follow you here. I understand that you prefer that all
rendering-run-level and environment-level info is accessed directly
by methods on the FOUserAgent, whereas I proposed to access the
environment-level data only on the factory to have a clear distinction
between the two levels. But: What data is loaded on-demand and requested
by the user agent?
> If the factory would be exposed, and a lot of classes access it
> directly, the implied amount of checks whether certain features have
> already been loaded would be enormous. If this is centralized in the
> user agent, it becomes a lot easier to maintain.
I don't see any of that. I decided that I will implement my proposal in
a new branch. There, everyone can have a look at the real thing and
we'll adjust as necessary to make everyone happy. You'll see that the
whole thing is much less complicated than you might think. When
everybody's happy, we can merge back or, in the worst case, discard the
branch.
Jeremias Maerki
Re: Finally finalizing the FOP API
Posted by Andreas L Delmelle <a_...@pandora.be>.
On Feb 8, 2006, at 22:03, Simon Pepping wrote:
Simon / Jeremias,
>
> 6. D5 (The FOUserAgent can return the FopFactory instance. (needed
> internally by FOP)): Why? Because FOUserAgent is the programmed way
> to get at configuration settings? Could it be better to implement
> get methods on the user agent which get the settings from the
> factory object (factory object not exposed)? Or even pass the
> factory object instead of the user agent (Cf. question 2)?
I agree with this comment in particular. I'd prefer to not expose the
Factory, but implement accessors for the persistent settings. It even
allows for a sort of flexibility where it comes to the so-called
persistent data across multiple rendering runs...?
A bit unclear maybe, so some further explanation: I'm also thinking
in terms of on-demand loading of certain data, if requested so by the
user agent. Once it's loaded, it will be readily available for
another user agent. If no user agent ever requests it, it will never
be loaded into memory.
If the factory would be exposed, and a lot of classes access it
directly, the implied amount of checks whether certain features have
already been loaded would be enormous. If this is centralized in the
user agent, it becomes a lot easier to maintain.
Cheers,
Andreas
Re: Finally finalizing the FOP API
Posted by Simon Pepping <sp...@leverkruid.nl>.
Jeremias,
On Tue, Feb 07, 2006 at 10:09:38AM +0100, Jeremias Maerki wrote:
> As part of my upcoming optimization work I want to finalize the FOP API.
> I've written down a proposal in the Wiki:
> http://wiki.apache.org/xmlgraphics-fop/ApiDesign
>
> If possible, I'd like to have that finished by the end of the week.
> Please post your feedback ASAP.
Some remarks and questions.
1. D11, D12: FopEnvironment should be FopFactory?
2. How does FOUserAgent differ from FopFactory? What is rendering run
dependent in FOUserAgent, now and in the future?
3. Is FopFactory's main role being a factory, or being a configuration
holding object across rendering runs? I am not charmed by the name
FopFactory; it does not seem to describe its role, only a side
effect of its role, viz. spawning rendering runs.
4. You write about XML configuration. Can the configuration on a fop
factory also be set using an Avalon Configuration object?
5. Do I understand correctly that the main alternatives to start a
rendering run are:
A.
Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF);
B.
FOUserAgent userAgent = fopFactory.newFOUserAgent();
userAgent.setTitle("My document");
Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, userAgent);
The difference being that in method B one can set properties that
are specific to this rendering run?
6. D5 (The FOUserAgent can return the FopFactory instance. (needed
internally by FOP)): Why? Because FOUserAgent is the programmed way
to get at configuration settings? Could it be better to implement
get methods on the user agent which get the settings from the
factory object (factory object not exposed)? Or even pass the
factory object instead of the user agent (Cf. question 2)?
7. What is the difference between these to instantiation methods:
FOUserAgent userAgent = fopFactory.newFOUserAgent(); (D6)
FOUserAgent userAgent = new FOUserAgent(fopFactory); (D3)
Regards, Simon
--
Simon Pepping
home page: http://www.leverkruid.nl
Re: Finally finalizing the FOP API
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
On 10.02.2006 18:39:15 Clay Leeds wrote:
> Looks good to me. I don't have much to add.
>
> I was wondering if the FOP API should include hooks to PostScript-
> style page-reference orientation information (or anything else
> PostScript-specific that may be missing). Is that something relevant
> to consider here?
I don't think so. This is probably more about configuring the renderer
which can be done directly. I'm currently more interested in finalizing
the overall design of the top-level API. If later certain specialities
are added it doesn't change the structure of the API.
> On Feb 10, 2006, at 7:43 AM, Jeremias Maerki wrote:
> > I understand that some of you may not have a lot of time. I still hope
> > to get some more feedback on this. I can give another task priority
> > over
> > this if anyone would like some more time to review. So, I'll probably
> > start with work on PDF/A-1 support on Monday.
> >
> > So far I've incorporated the feedback from Jess and Simon.
> >
> > On 07.02.2006 10:09:38 Jeremias Maerki wrote:
> >> As part of my upcoming optimization work I want to finalize the
> >> FOP API.
> >> I've written down a proposal in the Wiki:
> >> http://wiki.apache.org/xmlgraphics-fop/ApiDesign
> >>
> >> If possible, I'd like to have that finished by the end of the week.
> >> Please post your feedback ASAP.
> >>
> >> Jeremias Maerki
> >
> > Thanks,
> > Jeremias Maerki
>
>
> Clay Leeds
> webmaestro@mac.com
>
> My religion is simple. My religion is kindness.
> -- HH Dalai Lama of Tibet
>
Jeremias Maerki
Re: Finally finalizing the FOP API
Posted by Clay Leeds <we...@mac.com>.
Looks good to me. I don't have much to add.
I was wondering if the FOP API should include hooks to PostScript-
style page-reference orientation information (or anything else
PostScript-specific that may be missing). Is that something relevant
to consider here?
On Feb 10, 2006, at 7:43 AM, Jeremias Maerki wrote:
> I understand that some of you may not have a lot of time. I still hope
> to get some more feedback on this. I can give another task priority
> over
> this if anyone would like some more time to review. So, I'll probably
> start with work on PDF/A-1 support on Monday.
>
> So far I've incorporated the feedback from Jess and Simon.
>
> On 07.02.2006 10:09:38 Jeremias Maerki wrote:
>> As part of my upcoming optimization work I want to finalize the
>> FOP API.
>> I've written down a proposal in the Wiki:
>> http://wiki.apache.org/xmlgraphics-fop/ApiDesign
>>
>> If possible, I'd like to have that finished by the end of the week.
>> Please post your feedback ASAP.
>>
>> Jeremias Maerki
>
> Thanks,
> Jeremias Maerki
Clay Leeds
webmaestro@mac.com
My religion is simple. My religion is kindness.
-- HH Dalai Lama of Tibet
Re: Finally finalizing the FOP API
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
I understand that some of you may not have a lot of time. I still hope
to get some more feedback on this. I can give another task priority over
this if anyone would like some more time to review. So, I'll probably
start with work on PDF/A-1 support on Monday.
So far I've incorporated the feedback from Jess and Simon.
On 07.02.2006 10:09:38 Jeremias Maerki wrote:
> As part of my upcoming optimization work I want to finalize the FOP API.
> I've written down a proposal in the Wiki:
> http://wiki.apache.org/xmlgraphics-fop/ApiDesign
>
> If possible, I'd like to have that finished by the end of the week.
> Please post your feedback ASAP.
>
> Jeremias Maerki
Thanks,
Jeremias Maerki