Mailing-List: contact fop-dev-help@xmlgraphics.apache.org; run by ezmlm
Precedence: bulk
Reply-To: fop-dev@xmlgraphics.apache.org
Received-SPF: neutral (asf.osuosl.org: local policy)
Date: Wed, 03 Aug 2005 09:42:08 +0200
From: Jeremias Maerki <dev.jeremias@greenmail.ch>
To: fop-dev@xmlgraphics.apache.org
Subject: Re: API discussion
In-Reply-To: <f86f5cb2eae24da1257a24a985fa5bf8@pandora.be>
References: <20050802105735.23BA.DEV.JEREMIAS@greenmail.ch>
 <f86f5cb2eae24da1257a24a985fa5bf8@pandora.be>
Message-Id: <20050803090811.3CB0.DEV.JEREMIAS@greenmail.ch>
MIME-Version: 1.0
Content-Type: text/plain; charset="US-ASCII"
Content-Transfer-Encoding: 7bit


On 03.08.2005 02:20:39 Andreas L Delmelle wrote:
> On Aug 2, 2005, at 11:14, Jeremias Maerki wrote:
> >
> > On 01.08.2005 18:31:35 Andreas L Delmelle wrote:
<snip/>
> > I'm not fully happy either, especially, after I put in the classloader
> > stuff. My proposal would be to do the same I did in Barcode4J: Let's
> > create a "cli" package with the whole command-line stuff in there. See:
> > http://cvs.sourceforge.net/viewcvs.py/barcode4j/barcode4j/src/java/ 
> > org/krysalis/barcode4j/cli/
> 
> Funny, right before I read your reply and without having looked at  
> Barcode4J, that was EXACTLY what I was thinking about. That way, it  
> becomes possible to build a JAR without the CLI classes, for people  
> that hardly ever use FOP from a console. Those that need only  
> occasional runs via CLI need simply an additional jar on their  
> classpath that contains only FOP's CLI classes. It's not that there are  
> many, but still, for the purists this means that they don't need to  
> contaminate their environment with those classes (that are not  
> re-usable in other contexts: see Joerg's remark earlier on).
> Plus: separating the CLI means that we're more at liberty to add  
> dependencies there without forcing our API-users to drag them in as  
> well.

Uhm, you know how much space the CLI part currently takes up in fop.jar?
12KB out of 1400KB (two and a half files ATM). And the classes don't
even get loaded if fop.jar is used "embedded only". I can understand if
people want a stand-alone RTF library or if they want SVG support to be
optional, but this. Hmmmm.

> (Ideas? Still a wild one ATM, but Jakarta Commons' Launcher  
> seemed interesting: IIC, it can be used to handle the tasks we now deal  
> with in our startup scripts --which would mean that we have to maintain  
> that stuff only in one place--, offers fine-grained control over the  
> class-loading.)

This would add more complexity and an additional dependency, where the
dynamic class loading for the CLI is already solved with a few lines. I
don't see the benefit, sorry. I'd rather have a Win32 executable for
people who don't know a thing about Java. I was thinking about doing
this many times now.

> <snip />
> > As a side note: Keep in mind that I've written a general API which
> > easily handles calling FOP 0.20.5, FOP Trunk, JFOR, FOray and even  
> > Batik
> > for the conversion of XSL-FO or SVG to PDF, PS, Print etc.
> 
> Yes, I remember. Of course, that is one side: a matter of conforming to  
> a set of interfaces.
> How we implement them and map the general API to our own is another.  

So far, I was able to map all the FOP-specifics into the JAXG
implementation without polluting the interface itself. There might be a
few very special use cases that won't be supported but I don't think
that's a problem.

> One thing's for sure: such mapping will be much easier if our specific  
> API is neatly designed, regardless of what the general interfaces look  
> like.

Actually, handling FOP Trunk was very easy in JAXG already. There's only
the little flaw in the Fop constructor when you actually use a
custom-configured Renderer.

> I'm very much in favor of the idea, and my preference in that area is  
> towards a *very* abstract and stringent general API, even if that would  
> mean that for all of the above apps someone still needs to code  
> API-to-API (specific-to-general) bridges. Evidently, there can be  
> absolutely no references whatsoever to any of those particular  
> applications in the general API --ideally it should be designed by  
> someone who knows nothing about those particular apps' usage patterns,  
> but who understands what a FO or SVG processor is/does (besides being  
> very proficient in Java interface-design, of course :-))

I think I already managed to do all that. There will certainly be a few
details to attend to but I'm already using the API in all my code and
for almost everything.

> > It is designed to provide for the various XSL-FO implementations what  
> > JAXP is
> > for Xerces, Crimson, Xalan, SAXON etc.
> 
> After all, I'm currently wondering if Xalan or SAXON ever started out  
> as an attempt to write an implementation for JAXP, or if their initial  
> concern was to code a decent XSLT processor and they added the JAXP  
> conformance further on. (I'd guess it lies more in the direction of the  
> latter, but I'm not sure at all)

The latter was indeed the case.

> And, now that JAXP is mentioned: of course, it's beneficial to expose  
> that API's functionality in our own --after all, it's *XSL*-FO--,  
> however, we should probably allow a number of possibilities, ranging  
> from:
>    URL srcFileloc, URL xslFileloc, URL tgtFileloc --we could determine  
> the output target from tgtFileloc's extension (in a lot of situations)
> 
> over
>    File srcFile, File xslFile, File tgtFile
> 
> over users passing in their own InputSources, Transformers and  
> OutputStreams,

You're talking about convenience methods, right? I'm sure we can provide
a small number of them for beginners, but maybe we should put them in a
special class (like EasyFop) as public static methods.

> or in the end maybe even
>    Source src, Style style, Target tgt --where those three are our own  
> independent interfaces, and user-developers can code their own  
> customized implementations.

Please not! Source can be reused from JAXP as I have done in JAXG. Same
for Style where you can reuse JAXP interfaces and classes. Target is
another matter and it is exactly what JAXG provides (among a few other
things).

> As long as their objects know how to  
> produce sensible answers to FOP's questions, it will render them as  
> specified. This abstraction is more or less based on our Obj2PDF  
> example, but precisely that example would become much much simpler.  
> [Think of a Processor, without XML, XSLT or FO:  
> Object-over-Object-to-Object]

That was Jakarta Commons Morphos. It failed. It was a nice idea, though,
but IMO entirely out of scope for FOP.

> I have a feeling that such an approach would greatly simplify the  
> eventual idea of a pluggable Renderer framework --Target as a class  
> that is able to return a component that conforms to our most basic  
> Renderer interface. Setting it through a RENDER_TYPE constant will be  
> for convenience only.

That's cool for hardcore developers and a PITA for beginners who'd
rather concat a command-line String to pass it to Fop's main method.
Cough. Besides JAXG already handles that. :-)

> Especially the simpler ones are important --for rookie Java  
> developers--, since *ours* is the XML API, but the users-embedders'  
> shouldn't necessarily be. If they're interested and clever enough, they  
> will be driven towards learning more about SAX and JAXP anyway. 

Do you touch your code when it already works? I think it is very
important that people who work with XML understand a little bit of JAXP
(especially TraX) and that's why I wrote the Example* classes in the
first place. The current API we have, though breaking compatibility with
0.20.5 and not really based on general consensus, is encouraging the use
of JAXP which IMO is a Good Thing.

> In  
> which case they can refine their own particular usage pattern if they  
> want/need to --and, who knows, ultimately maybe even help us out in  
> adding enhancements (or at least discuss them here, and maybe inspire  
> others :-)).
> 
> > The only problem is that I still don't have a name for it that doesn't  
> > produce any problems (JAFOP was too close to FOP to potentially scare  
> > commercial implementors away and JAXG,
> > its current name, has been criticized by a Sun employee to be  
> > potentially problematic because of the use of the "JAX" prefix.)
> 
> Wouldn't worry about the name too much right now. I believe that the  
> idea in itself is worthwhile enough. Some cool name is bound to turn up  
> for it eventually.

I'm waiting for a cool name to pop up for half a year now. I even had a
help from a number of people. I should probably revisit all the
proposals I got. Anyway, looks like I really need to publish what I
currently have and if it's only to replace the old JAFOP on my website
which is really out of date now.


Jeremias Maerki