cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steve Muench" <smue...@us.oracle.com>
Subject Re: XSLT API Proposal (Draft 2)
Date Tue, 08 Feb 2000 18:22:12 GMT
Scott,

I like the idea of trying to put the names of
the interfaces in a sentence to check their
usability.

USE CASE
--------
Transform "source.xml" into "out.html" using "style.xsl"

I think people can easily understand that they need to:

  (*) Use an "XSLT Processor"...
  (*) To transform the source XML document "source.xml"
  (*) Into the resulting out.html output
  (*) Using the stylesheet "style.xsl"
  (*) Taking an optional set of parameters as input

They are happy when they can type a command-line that
mimics this understanding like (I know our command-line
syntax so I'm using that at an example):

  $ oraxsl -p x='y' z=10  source.xml style.xsl out.html

Which just "gets the job done". 

So conceptually, the user thinks of the command-line
utility as playing the role of the XSLTProcessor
and what's going on under the covers as:

XSLTProcessor.process( source, style, parameters, output )

I think people understand that the set of parameters
can be different for each "run" of the stylesheet,
so they think of the parameters as being in a separate
"bag" from the stylesheet itself.

I think this was the kind of simplicity that Jeff Mackay
was getting at with the ADO reference. A programmer
wanting to make straightforward use of an XSLT processor
could effectively do it with one static method.

Processor.process( Source, Stylesheet, Params, Result )

And that doing it several times "in a row" you might
want the same Stylesheet to be used with:

  -> Different Sources
  -> Different sets of Parameter Values
  -> Different Result outputs

So it feels to me like the stylesheet is the
immutable part and represents the in-memory,
ready-to-be-used version of what's serialized
as text in the "style.xsl" file in this example
and that the dynamic parts are the "tuple" of:

(Source, Params, Result)

So, it would make sense to me as a user to:

  (*) Construct a Stylesheet, given "style.xsl" as input
  (*) For each "run" of this stylesheet, 
      => Construct a XSLTProcessor and
      => Call process(Source,Stylesheet,Params,Result)

Just my two cents on a user-perspective.

__________________________________________________________
Steve Muench, Lead XML Evangelist / Consulting Product Mgr
Oracle Corp, Business Components for Java Development Team
http://technet.oracle.com/tech/xml
----- Original Message ----- 
From: "Scott Boag/CAM/Lotus" <Scott_Boag@lotus.com>
To: <xalan-dev@xml.apache.org>
Cc: <cocoon-dev@xml.apache.org>; <xalan-dev@xml.apache.org>
Sent: Monday, February 07, 2000 10:52 PM
Subject: RE: XSLT API Proposal (Draft 2)


| 
| > Step
| > back and look at the interfaces from a user's point of view rather than
| an
| > implementor's point of view.
| 
| Yep, we've been trying.  Sometimes easier said than done... one of the
| reasons to get wide review for this.
| 
| > Can the operation of an
| > implementation be explained in plain English?
| 
| Can XSLT be explained in plain English?  :-)  What makes perfect sense to
| me, doesn't always make sense to others.
| 
| I'm not kidding.  The XSLT process tends to be hard to convey to someone
| who isn't familiar with it.  And even with people who are -- in the XSLT WG
| we would constantly get tangled up with communication because many of the
| meanings of the processes aren't in common usage.
| 
| > How much documentation does a first-time user have to read to understand
| the
| > abstractions? I would think the goal would be to minimize this.
| 
| Yep.  You're preaching to the choir.  After supporting LotusXSL and Xalan
| for a while now, I can tell you I really really really want very easy and
| understandable interfaces.  The question is how to get there.  I'll take
| any help I can get!
| 
| > - Processor (possibly split into Compiler and Interpreter interfaces?)
| 
| I'm worried Compiler might be misinterpreted as Java byte code compilation,
| and I'm not sure what Interpreter means.  I've considered both these.
| 
| > - Stylesheet (or maybe TransformRuleSet to avoid confusion with CSS?)
| 
| Yep, that's what everybody has as a stylesheet class.  The problem is, if
| you name an interface Stylesheet, everyone has to change existing
| implementations.  Maybe it's important enough to go through the pain of
| this.  What do other's think?
| 
| The other slight issue is that Stylesheet is somewhat misleading. One could
| argue that an XSLT transformation sheet isn't a stylesheet in itself.  But
| I don't think this is a strong argument for not using it, since it is in
| common usage.
| 
| > - CompiledStylesheet (if necessary)
| 
| Not sure what this would be vs. Stylesheet.
| 
| > - InputSource
| 
| SAX already uses this.  That's why it's tagged XSLTInputSource.
| 
| > - Result
| 
| Yep, perhaps better than ResultTarget.  I was trying to mirror
| XSLTResultTarget.
| 
| > Transformation and TransformContext seem to be a bit abstract.
| 
| I agree about Transformation.  TransformationContext seems to me to be very
| exact.  But... what's english to me might be greek to you.
| 
| What about just "Session" or "TransformSession"?
| 
| > Threading
| > issues could be considered implementation or quality-of-service details
| that
| > don't belong in the interfaces.
| 
| This I strongly disagree with.  I don't think that threading issues are
| clear enough in today's interfaces.  It's very important that both
| implementors and users understand threading up front, and that it is part
| and parcel of the character of the class.  Good concurrency pervades
| everything.  It tells you if something can be safely mutated or not, and it
| tells you if you have a long or short term object.  These issues will
| otherwise rise up as surprising "gotchas" during deployment, both on the
| client and the server.  Even in a simple "hello world" program, you want to
| users to start learning this, and getting used to it.  Anyway, that's my
| opinion.
| 
| > Another suggestion: take a look at Microsoft's ADO interfaces
| 
| OK.  They're not the first thing that comes to mind when I think of a good
| interface, but I'll take another look upon your recommendation.
| 
| > Maybe something similar could be done with the XSL processor.  I could
| > create (and parse) a stylesheet and transform an input source into a
| result,
| > without the need to create a processor, compile the stylesheet, apply the
| > compiled sheet to an input source, etc.  You get the idea.
| 
| The problem I run into trying to achieve this is that you start having
| multiple ways to do things... and end up making a broader, more complicated
| interface.
| 
| > Just my two cents as an interested observer.
| 
| Thanks!  Please keep contributing.  Somewhere here there's got to be the
| perfect interface...
| 
| -scott
| 
| 
| 
| 
| 
| 


Mime
View raw message