Setting up the output format

[Jeremias Maerki <de...@greenmail.ch>]

Today, I've had some quality time with FOP again. A lot of it was just
looking around what was changed while I wan't looking. :-) I still have
66 CVS messages unread.

One thing I didn't really like was the fact the Fop class implements
Constants. From a user's POV this renders the code completion (in
Eclipse, for example) virtually useless as there are simply too many
(unused) items.

Do the RENDER_* constants need to be in Constants? Or even better, would
anybody mind if I wrote a simple facility to create the renderers and
FOInputHandlers from using MIME types instead of hard-coded constants?
It would have the advantage to add additional output formats on-the-fly
and made it possible to selectively replace renderers if you have a
special one, for example. It could considerably ease the live of Pete
Townsend when he tries to integrate his AFP renderer as there's no
Fop/Driver.setRenderer(Renderer) anymore. API-wise this would mean that
you wrote:
Fop fop = new Fop("application/pdf");
instead of
Fop fop = new Fop(Constants.RENDER_PDF);

Jeremias Maerki

Re: Setting up the output format

[Glen Mazza <gr...@yahoo.com>]

--- Simon Pepping <sp...@leverkruid.nl> wrote:
> Indeed, it is -:) It is also a nice report of what
> you have been doing
> and the direction you have been working in. 
> Are you
> going to write
> this down more in extenso?
> 

Yes, hopefully soon.

Glen

Re: Setting up the output format

[Simon Pepping <sp...@leverkruid.nl>]

On Sun, Aug 15, 2004 at 04:48:48PM -0700, Glen Mazza wrote:
> --- Jeremias Maerki <de...@greenmail.ch> wrote:
> 
> > Today, I've had some quality time with FOP again. 
> 
> Good.  I think you finding quality time, however, at
> this date is not completely coincidental--I think the
> dropping of several classes and refactoring of a ton
> of code in that package has made it very simple to
> start looking at and quickly (re-)understanding the
> code base.  (<pat self on back/>)

Indeed, it is -:) It is also a nice report of what you have been doing
and the direction you have been working in. Are you going to write
this down more in extenso?

Regards, Simon

-- 
Simon Pepping
home page: http://www.leverkruid.nl

Re: Setting up the output format

[Glen Mazza <gr...@yahoo.com>]

--- Simon Pepping <sp...@leverkruid.nl> wrote:

> I like the way all constants are collected in one
> class. 

Me too.

> I do not like
> the fact that many classes implement this interface.
> The jdee debugger
> is much hindered by it, because it makes each object
> very large, with
> so many constants. Why is Constants not just
> imported?
> 

Matter of preference--because typing Constants. for
everything seemed cumbersome.  However, importing
Constants is a perfectly acceptable solution and
purists may consider it a better style anyway--if you
would like to do this, I wouldn't have a problem with
switching to this method.  (Except for the apps.Fop
class, I would rather embedded users type in
Fop.RENDER_PDF than Constants.RENDER_PDF.)

Matter of fact, it may be best to do this for
LayoutManager and Renderer classes, because that is
where the bulk of the work is done, and I wouldn't
want layout workers to be burdened by this.  OTOH, we
will be typing in "Constants." frequently, because
that code does/will query a lot of properties.

Another option, if we pull it out for Layout and
Renderers but keep it for the FOTree, we can still use
fObj.PR_WHATEVER in those packages.  Again, though,
anything is fine for me here--if desired we can switch
to "Constants." for all three areas.  

Glen

Re: Setting up the output format

[Simon Pepping <sp...@leverkruid.nl>]

I like the way all constants are collected in one class. I do not like
the fact that many classes implement this interface. The jdee debugger
is much hindered by it, because it makes each object very large, with
so many constants. Why is Constants not just imported?

Regards, Simon

On Sun, Aug 15, 2004 at 04:48:48PM -0700, Glen Mazza wrote:
> --- Jeremias Maerki <de...@greenmail.ch> wrote:
> 
> > One thing I didn't really like was the fact the Fop
> > class implements
> > Constants. 
> 
> Well, the render constants used to be redundantly
> defined in both CommandLineOptions.java and
> Driver.java.  I centralized them, and defined them in
> one place, fo.Constants, where we keep our other
> system-only constants--for properties, FO's, etc. 
> (fo.Constants was originally created from Finn's work
> with the properties--I just added these constants to
> it.)
> 
> > From a user's POV this renders the code
> > completion (in
> > Eclipse, for example) virtually useless as there are
> > simply too many
> > (unused) items.
> > 
> 
> Yes, the Constants class is somewhat large--it has
> render types, fo and properties constants.  But it's
> not unmanageable, and the issue of Eclipse showing too
> many constants is going to be relevant in most of the
> application.  It is implemented both by the FO's and
> the LM's, and every class needs just a little bit of
> that file--a few FO's or a few properties, etc.
> 
> But it has not been a problem to me, I work on the
> code rather heavily.  Neither have Finn, Simon or
> Chris mentioned this--and by virtue of working in
> Layout and FOTree, they would presumably come across
> this problem much more often.  

-- 
Simon Pepping
home page: http://www.leverkruid.nl

Re: Setting up the output format

[Glen Mazza <gr...@yahoo.com>]

--- Jeremias Maerki <de...@greenmail.ch> wrote:

> Today, I've had some quality time with FOP again. 

Good.  I think you finding quality time, however, at
this date is not completely coincidental--I think the
dropping of several classes and refactoring of a ton
of code in that package has made it very simple to
start looking at and quickly (re-)understanding the
code base.  (<pat self on back/>)

> A
> lot of it was just
> looking around what was changed while I wan't
> looking. :-) 

Indeed, a lot has changed over the past twelve months.
 ;) 

By removing the old pre-JAXP code, and reducing the
apps package to its mathematical essence,
(approximately) from here[1] to here[2], I am also
able to significantly minimize the learning curve for
newbie committers.  Becoming a committer, I had to
spend about a lot of time wading through the old apps
package just to figure out what was happening.  A lot
of that code is gone now--future committers will not
have to waste time on obsolete code in order to get to
the main portions of the application--FO Tree, layout,
renderers, etc.


> One thing I didn't really like was the fact the Fop
> class implements
> Constants. 

Well, the render constants used to be redundantly
defined in both CommandLineOptions.java and
Driver.java.  I centralized them, and defined them in
one place, fo.Constants, where we keep our other
system-only constants--for properties, FO's, etc. 
(fo.Constants was originally created from Finn's work
with the properties--I just added these constants to
it.)

> From a user's POV this renders the code
> completion (in
> Eclipse, for example) virtually useless as there are
> simply too many
> (unused) items.
> 

Yes, the Constants class is somewhat large--it has
render types, fo and properties constants.  But it's
not unmanageable, and the issue of Eclipse showing too
many constants is going to be relevant in most of the
application.  It is implemented both by the FO's and
the LM's, and every class needs just a little bit of
that file--a few FO's or a few properties, etc.

But it has not been a problem to me, I work on the
code rather heavily.  Neither have Finn, Simon or
Chris mentioned this--and by virtue of working in
Layout and FOTree, they would presumably come across
this problem much more often.  

There's not much to change in apps.Fop anyway--it's
barely 200 lines of code as it is.  Even though it is
not the "embellished" API that some would prefer,
apps.Fop is in a sufficient state to replace the
0.20.5 version with. (The output renderers, OTOH, are
*not* in that state--that's where the future effort
needs to go.)

> Do the RENDER_* constants need to be in Constants?

I deemed that preferable to keeping them duplicated in
two places.  Also, a lot of business logic, throughout
the application, is based on the Render type. 
Generally speaking, it's better to work with constants
than strings.  (They're excellent for array index
values, for example.)

> Or even better, would
> anybody mind if I wrote a simple facility to create
> the renderers and
> FOInputHandlers from using MIME types instead of
> hard-coded constants?

Yes.  These reasons:

1.) FOInputHandlers don't exist in the apps package,
they are are present for FOTreeBuilder onwards.  (Apps
just accumulates parameters in order to activate the
FOTreeBuilder.)  The FOTreeBuilder determines the
proper FOInputHandler to route messages to based on
the input render type.

2.) Not all output types have a MIME type.  It is very
possible to write a FOInputHandler subclass that just
takes statistics on FONodes coming in, their count,
etc., perhaps displaying them on a screen: type,
parameter, etc.   No MIME type here.  So there isn't a
guaranteed mapping between an FOInputHandler and a
MIME type.  (Furthermore, you could have multiple
renderers for a single MIME type:  RENDER_PDF,
RENDER_PDF_NEW, etc.)

3.) Certain architectural reasons--I'm trying to make
the packages somewhat more standalone.  To create a
more modular design, I disconnected the apps package
from just about everything down the pipeline.  In the
old code, the apps package needed to import maybe 75
classes from non-apps packages.   It got its hands in
everything, even the fonts.  Now, it imports only one
class: FOTreeBuilder--and only references it for one
line of code, namely line 128 of Fop.java [3], to
activate it. 

Furthermore, of the approximately 580 FOP classes
outside the apps package, perhaps 400 of them could
not compile/function without the apps package, they
had to keep bouncing back to Driver or Document for
business logic, they had to make private methods
public for that purpose, etc., etc.  That's down now
to maybe 40-50 classes and still declining a bit. 
(We'll need some connection still for FOUserAgent, and
reentrant renderers like AWT, also the servlets, etc.)
 The result is that once FOTreeBuilder is activated,
it  doesn't really need the apps package again.

By making the code more modular, this will also help
you better componentize the application.  You can't
pull out various packages if much of their business
logic is shoved in the apps package because, say, "SVG
doesn't need to know about this or a font doesn't need
to know about that", etc., etc.

> It would have the advantage to add additional output
> formats on-the-fly
> and made it possible to selectively replace
> renderers if you have a
> special one, for example. 

Don't worry--we already have that
function--setRendererOverride() in the FOUserAgent
class.  Doesn't even need a FOP constant.  Also,
rather than taking a specific Renderer object--the
shape of which may change in the future--it takes a
String giving the name of the class instead.  This
will help us down the road with backwards
compatibility--setRendererOverride() always takes a
string, but the class it represents can change.

> It could considerably ease
> the live of Pete
> Townsend when he tries to integrate his AFP renderer
> as there's no
> Fop/Driver.setRenderer(Renderer) anymore. 

We still have it, it's just now setRendererOverride().
 (It is also trivial to add RENDER_AFP to the
constants package, if the Renderer is absorbed within
FOP.)

Of course, if you *really* want to help Mr. Townsend,
study the old renderers, study the new, and start
importing the old into the new, making changes to the
1.0 renderer architecture as need be.  Be in a
position to help him with any Renderer questions he
may have.  (I'm not there yet myself--but I did
"graduate" recently from the apps package to the fo
package!)  This is where the greatest help for him
would be--but this of course will take a lot of time.

Sorry for the long post.

Thanks,
Glen

[1] (0.20.5)
http://cvs.apache.org/viewcvs.cgi/xml-fop/src/org/apache/fop/apps/Attic/?only_with_tag=fop-0_20_5rc3a

[2] (1.0 - new)
http://cvs.apache.org/viewcvs.cgi/xml-fop/src/java/org/apache/fop/apps/

[3]
http://cvs.apache.org/viewcvs.cgi/xml-fop/src/java/org/apache/fop/apps/Fop.java?annotate=1.19#128