Mailing-List: contact fop-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: fop-dev@xml.apache.org
Message-ID: <20040815234848.54096.qmail@web60102.mail.yahoo.com>
Date: Sun, 15 Aug 2004 16:48:48 -0700 (PDT)
From: Glen Mazza <grm7793@yahoo.com>
Subject: Re: Setting up the output format
To: fop-dev@xml.apache.org
In-Reply-To: <20040815170159.BF5F.DEV.JEREMIAS@greenmail.ch>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii

--- Jeremias Maerki <dev.jeremias@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