XSLT API Proposal

[Scott Boag/CAM/Lotus <Sc...@lotus.com>]

I apologize for the cross-post, but I wanted to make sure everyone saw this
note.

This is a proposal for a set of very simple XSLT interfaces (and three
support classes), that support both SAX and the DOM.  Though I have it
immediately in mind for Xalan, I would be glad to join with any other Java
XSLT processor implementers to make these interfaces generic and not linked
to any given implementation.

These interfaces will only be sufficient for some people, and not for
others, who will have to go to the underlying implementation's API.

I've thought about these interfaces for a long time now, have had some long
discussions with Stefano Mazzocchi and Keith Visco, among other people, and
I've tried to look at other non-Xalan APIs to get a good feel for the
general structure of what's out there, though I didn't get to all
implementations.  Besides this, I hope by now I have some experience on
what people like and need with these interfaces (mainly through experience
of my own painful failed API attempts).  I think these interfaces are at
least a good start... they are very simple, cover the basic requirements of
both DOM and SAX users, and should be easily implementable by most XSLT
processor vendors.

What this would mean to the Xalan code: I think it would be best if the
existing APIs don't change too much, including Xalan's packages, which I
would like to rearrange, but I think it would cause too much chaos at this
point.  This would be mainly a set of interfaces which Xalan would support,
and which people would be encouraged to use.

The idea for now is to put this into a org.apache.xslt package, but I would
love to have them put in some vender neutral place (Stefano suggested Tim
Bray host at xml.org).  Another idea might be to combine these with Assaf
Arkin's Serialize interfaces as a general Apache tools interfaces package.
Or maybe the above two ideas combined.  The idea is to make life less
confusing for application developers by providing them with well known and
agreed-upon interfaces for basic XML services, give them vendor choice for
these basic services, make my life easier by having a more familiar
interface for users (hence less support), and to generally further the goal
of having XML in as wide of usage as possible in order to make open
information exchange and manipulation over the Web genuinely tractable
(well, I wax grandiose...).

I would like to get feedback on these interfaces as soon as possible.  Feel
free to suggest changes, additions (keeping in mind the requirements for
providing only simple services at this time, not tooling interfaces and the
like... we can do these for verson 2.0), or voice disagreement with what's
proposed.

The basics of the API is that a XSLTProcessor object is in charge of
creating a Transform object (in honor of XT's DOM transform object).  The
Transform object has a process method, which takes XSLTInputSource and
XSLTResultTarget arguments.  I know that some people feel that the
XSLTProcessor should have a process method on it, but the stylesheet
definitely needs one, and I would really like to not have it in two places.
I brought the XSLTInputSource and XSLTResultTarget objects from Xalan
pretty much as they were.  I know some people feel that the XSLTInputSource
should have a setDocumentHandler method on it, but I much prefer to have
both the XSLTProcessor and the Transform objects derive from
DocumentHandler instead.  I don't think that XSLTInputSource should have a
setDocumentHandler method on it because DocumentHandler is a event source
which "pushes" things to the processor, while all the parameters to
XSLTInputSource are things that the processor "pulls" out of the source...
one has an external source start the process, while the other requires that
the process method starts the process.

There are also some requirements about thread safety that I pushed to the
interface, that I hope make sense to people.  See the class descriptions.

I didn't do a Factory object for the XSLTProcessor.  If anyone has really
good ideas on this, please contribute.  Otherwise I think we could do
without this.

(See attached file: XSLTResultTarget.java)(See attached file:
XSLTException.java)(See attached file: XSLTInputSource.java)(See attached
file: XSLTProcessor.java)(See attached file: Transform.java)

-scott

Re: XSLT API Proposal

[K Karun <kk...@us.oracle.com>]

Scott,

  I have a couple of comments/ideas based on Oracle XSLT implementation.
Overall, the APIs look good and generic enough. But a few changes, which
would make it easier for me to change Oracle XSLT to use these APIs.

  XSLTResultTarget needs to know xsl:output attributes, so that
DocumentHandler can customize the output. One way to provide this
information is to have a TransformContext associated with Transform
object. Initially, this context can provide just xsl:output information.
It is useful to have it and extend it in future, to provide information
similar to XSLTProcessorContext in Xalan. It will also be an aide in
developing a uniform mechanism for extension elements (similar to JSP
TagLib mechanism).

  Also, XSLTProcessor seems to be mixing two functions. It is used as
Transform object builder, as well as an environment to the Transform
object. So it might be simpler to split XSLTProcessor into
XSLTProcessorEnv and TransformBuilder.

  TransformBuilder can extend org.xml.sax.DocumentHandler and have
setParser(), createTransform(), and getTransform() functions.
XSLTProcessorEnv can store parameter bindings, source parser, and may be
other things (error stream, tracelisteners, debuglevel). And it will
need set/get method for these. It might be okay to have setParameter()
in both Transform and XSLTProcessorEnv, given that setParameter() in
Transform would override a setting in XSLTProcessorEnv.

  Finally, it will be useful to have XSLInputSource implement
EntityResolver or something similar. This would be useful for
xsl:include, xsl:import, and external entity references in input xml.
And for XSLInputSource 2.0, it would be nice to have some generic
XLocator kind of functionality. 

Thanks
Karun

-- 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
K. Karun                          Project Lead, Java XML Components
CORE and XML Development          Phone: (650) 506 9874
Server Technologies               Fax:   (650) 506 7203
Oracle Corporation                http://technet.oracle.com/tech/xml
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Scott Boag/CAM/Lotus wrote:
> 
> I apologize for the cross-post, but I wanted to make sure everyone saw this
> note.
> 
> This is a proposal for a set of very simple XSLT interfaces (and three
> support classes), that support both SAX and the DOM.  Though I have it
> immediately in mind for Xalan, I would be glad to join with any other Java
> XSLT processor implementers to make these interfaces generic and not linked
> to any given implementation.
> 
> These interfaces will only be sufficient for some people, and not for
> others, who will have to go to the underlying implementation's API.
> 
> I've thought about these interfaces for a long time now, have had some long
> discussions with Stefano Mazzocchi and Keith Visco, among other people, and
> I've tried to look at other non-Xalan APIs to get a good feel for the
> general structure of what's out there, though I didn't get to all
> implementations.  Besides this, I hope by now I have some experience on
> what people like and need with these interfaces (mainly through experience
> of my own painful failed API attempts).  I think these interfaces are at
> least a good start... they are very simple, cover the basic requirements of
> both DOM and SAX users, and should be easily implementable by most XSLT
> processor vendors.
> 
> What this would mean to the Xalan code: I think it would be best if the
> existing APIs don't change too much, including Xalan's packages, which I
> would like to rearrange, but I think it would cause too much chaos at this
> point.  This would be mainly a set of interfaces which Xalan would support,
> and which people would be encouraged to use.
> 
> The idea for now is to put this into a org.apache.xslt package, but I would
> love to have them put in some vender neutral place (Stefano suggested Tim
> Bray host at xml.org).  Another idea might be to combine these with Assaf
> Arkin's Serialize interfaces as a general Apache tools interfaces package.
> Or maybe the above two ideas combined.  The idea is to make life less
> confusing for application developers by providing them with well known and
> agreed-upon interfaces for basic XML services, give them vendor choice for
> these basic services, make my life easier by having a more familiar
> interface for users (hence less support), and to generally further the goal
> of having XML in as wide of usage as possible in order to make open
> information exchange and manipulation over the Web genuinely tractable
> (well, I wax grandiose...).
> 
> I would like to get feedback on these interfaces as soon as possible.  Feel
> free to suggest changes, additions (keeping in mind the requirements for
> providing only simple services at this time, not tooling interfaces and the
> like... we can do these for verson 2.0), or voice disagreement with what's
> proposed.
> 
> The basics of the API is that a XSLTProcessor object is in charge of
> creating a Transform object (in honor of XT's DOM transform object).  The
> Transform object has a process method, which takes XSLTInputSource and
> XSLTResultTarget arguments.  I know that some people feel that the
> XSLTProcessor should have a process method on it, but the stylesheet
> definitely needs one, and I would really like to not have it in two places.
> I brought the XSLTInputSource and XSLTResultTarget objects from Xalan
> pretty much as they were.  I know some people feel that the XSLTInputSource
> should have a setDocumentHandler method on it, but I much prefer to have
> both the XSLTProcessor and the Transform objects derive from
> DocumentHandler instead.  I don't think that XSLTInputSource should have a
> setDocumentHandler method on it because DocumentHandler is a event source
> which "pushes" things to the processor, while all the parameters to
> XSLTInputSource are things that the processor "pulls" out of the source...
> one has an external source start the process, while the other requires that
> the process method starts the process.
> 
> There are also some requirements about thread safety that I pushed to the
> interface, that I hope make sense to people.  See the class descriptions.
> 
> I didn't do a Factory object for the XSLTProcessor.  If anyone has really
> good ideas on this, please contribute.  Otherwise I think we could do
> without this.
> 
> (See attached file: XSLTResultTarget.java)(See attached file:
> XSLTException.java)(See attached file: XSLTInputSource.java)(See attached
> file: XSLTProcessor.java)(See attached file: Transform.java)
> 
> -scott
> 
>   ------------------------------------------------------------------------
>                             Name: XSLTResultTarget.java
>    XSLTResultTarget.java    Type: Java File (application/x-unknown-content-type-JDeveloper.JavaFile)
>                         Encoding: base64
> 
>                          Name: XSLTException.java
>    XSLTException.java    Type: Java File (application/x-unknown-content-type-JDeveloper.JavaFile)
>                      Encoding: base64
> 
>                            Name: XSLTInputSource.java
>    XSLTInputSource.java    Type: Java File (application/x-unknown-content-type-JDeveloper.JavaFile)
>                        Encoding: base64
> 
>                          Name: XSLTProcessor.java
>    XSLTProcessor.java    Type: Java File (application/x-unknown-content-type-JDeveloper.JavaFile)
>                      Encoding: base64
> 
>                      Name: Transform.java
>    Transform.java    Type: Java File (application/x-unknown-content-type-JDeveloper.JavaFile)
>                  Encoding: base64