xalan-dev list proto-FAQ v0.3 - Readme First!

[Sh...@lotus.com]

A quick take on a few of the FAQs I've seen lately on the list. New/Updated
items from the immediately-preceding proto-FAQ 0.2 are marked with leading
*.

We have eventual plans for a more formal FAQ but in the meantime, here's a
few quick answers.

---- Contents: questions ----------------
*Q: How do I submit a bug about Xalan?
*Q: How come my [DTD doesn't get validated|my &entities; aren't resolved]?
Q: How do I search xalan-dev posts?
Q: How do I write/fix/update my XSLT stylesheet to ...
Q: I'm getting NoSuchMethod error with Xalan and Tomcat...
Q: I'm getting an unusual error relating to DOM classes, SAX classes,
javax.xml.* classes - what's wrong?
Q-: I'm getting a "Namespace not supported by SAXParser" exception - what's
wrong?
Q-: I'm getting a an error about my stylesheet missing the xsl:version
attribute - what's wrong?
Q-: My DOMSource can't be built/transformed - what's wrong?
Q: How come my xsl:include/import file isn't found?
Q: Why do I get 'file not found' when I pass c:\path\filename.txt?
Q: My transform/process seems to complete but there's nothing in the output
file!
Q: How do I unsubscribe from this list? Help!
Q: How do I submit a patch to Xalan?
Q: Is this FAQ useful to you?

---- Contents: answers ----------------
* Q: How do I report a bug about Xalan?
* A: Use Bugzilla.  http://nagoya.apache.org/bugzilla/enter_bug.cgi
First, do a quick check in Bugzilla to see if someone else has already
reported a similar bug.  If not, then:
Make your summary briefly describe what's not working.  Fill in any of the
other fields if you have a good idea of the right answer (like priority,
functional area, etc.); leave them blank if you're not sure.
Then in the body of the bug, describe clearly and completely what your
code is trying to do, what actually happened (presumably the bug), and what
you expected to happen (the desired behavior).

Be *sure* to specify those other important details - like reporting against
the specific Xalan build
(Java/C++) and specific verison number you're using, which platform and
JDK/compiler; etc.  And be sure to include at least a snippet of the code
you executed along with any stacktraces or error printouts.  If the code
isn't simple, then please attach enough code (plus stylesheets and XML
documents) to reproduce the basic problem.  .Zip or .tar.gz files are fine
to save space.  One of the more common requests on the list is asking bug
reporters to send in their stylesheets - we can't work on it if we can't
reproduce the problem ourselves.


*Q: How come my [DTD doesn't get validated|my &entities; aren't resolved]?
*A: You probably want the xerces-j-dev list, not the xalan-dev list, since
these kinds of issues are most often with the XML parser, and not the XSLT
processor.  Many aspects of reading in XML files for use are handled in the
parser, and Xalan doesn't even know about them.


Q: How do I search xalan-dev posts?
A: http://marc.theaimsgroup.com/?l=xalan-dev&r=1&w=2  (Many thanks to the
AIMS Group for hosting! Note that the links from the on-line xml.apache.org
site actually point to another archive that's currently outdated)


Q: How do I write/fix/update my XSLT stylesheet to create XHTML / make
tables / do something special...
A: Stop right there.  This is the xalan-dev list, for discussions about how
Xalan itself works and is developed, not a general tutorial on writing XSLT
stylesheets.  We try to help when we can but you'll get better and quicker
help in other places.  Join the famed xsl-list at Mulberrytech, or see one
of the references/tutorials/guidebooks below:

  http://xml.apache.org/xalan-j/overview.html#uptospeed
  http://mulberrytech.com/xsl/xsl-list/index.html
  http://www.dpawson.co.uk/xsl/xslfaq.html
  http://www.objectsbydesign.com/projects/xslt/xslt_by_example.html
  http://www.zvon.org/xxl/XSLTutorial/Books/Book1/index.html


Q:<df...@coremetrics.com>
I am getting an error message that I think is due to a class conflict
between XALAN & TOMCAT. Running the xalan servlet example generates an
error:
java.lang.NoSuchMethodError
 at org.apache.xpath.DOM2Helper.getLocalNameOfNode(DOM2Helper.java:326)
 ...
A: <ly...@ssmb.com>
If using Tomcat < 4.0 then put the Xalan classes in the tomcat.[bat|sh]
CLASSPATH definition BEFORE xml.jar

*Q: I'm getting an unusual error relating to DOM classes, SAX classes,
javax.xml.* classes - what's wrong?
NOTE: A number of seemingly odd NoSuchMethod or other exceptions can be due
to classpath ordering issues.  Many products include their own copies of
the org.w3c.dom.*, org.xml.sax.*, and javax.xml.* standard packages, some
of which may be outdated or incompatible.  Xalan relies on finding the
versions of these packages either in xalan.jar or xerces.jar, so a number
of problems can be solved by either putting xalan.jar/xerces.jar earlier or
first on the CLASSPATH, and by searching your classpath or extensions
directory for other jars that might include these standard packages -
especially versions of jaxp.jar, parser.jar, xml.jar, crimson.jar.

* NOTE-ALSO: Remember, if it works standalone, but doesn't work in your
[server|servlet|jsp page|etc] then it is most likely a configuration
problem with your server, and not a Xalan problem.

* NOTE-ALSO: If using any JDK 1.2+ or higher, you must also check your
/lib/ext or extensions directory for copies of the above files, since they
are 'magically' included in the beginning of your classpath.  To get rid of
files in your extensions directory, you must delete them or move them out
of the directory - simply renaming them will *not* work (maybe: rename the
extension to not be .jar, but I haven't tested this).
Scott Boag added:  "Go to the JDK 1.2+'s lib\ext directory.  Remove
crimson.jar, and any other jar
that may have JAXP interfaces.  lib\ext is a "magic" directory that loads
all the jars in there in front of the classpath.  So you don't see them,
and the *only* solution is physical removal.
This whole thing with the lib\ext directory has generated more email, and
confused users, more than any other issue.  Through no fault of either
Xerces or Xalan, from what I can tell.
Users who are upset about this as I am should write a note to Sun asking
them to fix the lib\ext mechanism.  This is totally broken."


Q-: I'm getting a "Namespace not supported by SAXParser" exception - what's
wrong?
Q-: I'm getting a an error about my stylesheet missing the xsl:version
attribute - what's wrong?
*Q-: My DOMSource can't be built/transformed - what's wrong?
A: Make sure you have a namespace-aware parser configured.  Some parsers
support namespaces by default, some you have to ask for support.  Try
adding something like the second line here:
  javax.xml.parsers.SAXParserFactory factory =
javax.xml.parsers.SAXParserFactory.newInstance();
  factory.setNamespaceAware(true); // Xerces needs this set


Q: How come my xsl:include/import file isn't found?
A: Did you remember to setSystemId() on your Source objects? When passing
any kind of InputStream, Reader, or Node object to Xalan as the source for
your stylesheet, you should also set the systemId on the object so Xalan
knows where to resolve URL's from.  A short example with Xalan-J 2.x:

  // When using InputStream/Reader/Node, must also setSystemId()
  java.io.InputStream xslStream = new FileInputStream
("/local/path/to/file.xsl");
  jaxax.xml.transform.Source xslSource = new
jaxax.xml.transform.stream.StreamSource(xslStream);
  xslSource.setSystemId("file:///legal/url/to/file.xsl");

  // Using a URL string effectively sets systemId for you
  jaxax.xml.transform.Source xmlSource = new
jaxax.xml.transform.stream.StreamSource(xmlURL);

  jaxax.xml.transform.Templates templates =
factory.newTemplates(xslSource);
  jaxax.xml.transform.Transformer transformer = templates.newTransformer();
  transformer.transform(xmlSource, result);


Q: Why do I get 'file not found' when I pass c:\path\filename.txt?
A: Xalan often requires legal URLs as system identifiers, not local
pathnames (this is partly due to underlying parsers requiring this).  A
simple (but not always correct!) way to change a local pathname into a URL
in Java 1.1x is:
  public static String filenameToURL(String filename)
  {
    File f = new File(filename);
    String tmp = f.getAbsolutePath();
    if (File.separatorChar == '\\')
    {
      tmp = tmp.replace('\\', '/');
    }
    // Note: gives incorrect results when filename already begins with
file:///
    return "file:///" + tmp;
  }
For a slightly more detailed example, see org.apache.xml.utils.
SystemIDResolver

Learn more about the details of URL/URIs:
  ftp://ftp.isi.edu/in-notes/rfc1738.txt
  ftp://ftp.isi.edu/in-notes/rfc1808.txt
  ftp://ftp.isi.edu/in-notes/rfc2396.txt


*Q: My transform/process seems to complete but there's nothing in the
output file!
*A: Did you flush/close your outputStream?  Remember, if you create a
stream, you are responsible for flushing it.  Compare and contrast the
following two examples:

  // Create a result from a String / URI: Xalan owns the underlying
'stream'
  transformer.transform(xmlSource, new StreamResult
("file:///c:/bar/foo.xml"));

  // Create a result from a Writer / OutputStream: you own the underlying
stream
  FileOutputStream fos = new FileOutputStream("c:\bar\foo.xml");
  transformer.transform(xmlSource, new StreamResult(fos));
  fos.flush() // needed to ensure output written out!


Q: How do I submit a patch to Xalan?
A: Make your subject line start with [PATCH] and then note the filename(s)
and briefly what the patch does.
In the body of the email, describe what you patched and why, and any
questions or hints you might have for committers who will be reviewing the
patch.  Always include the patch as an attachment to the email: this
prevents problems with mailers that wrap long lines.  If the patch is
small, then *also* include a copy of the patch in the body of the email
itself (which makes it quicker to review).
The best way to create a patch currently (someone suggest better ways as
needed) is to use the CVS diff command like so:
  cvs diff -u FileName.java >> FileName.java.patch
This creates a _u_nified diff of your local FileName.java against the most
recent revision in the repository, putting the output into
FileName.java.patch
For hints on using CVS, see http://xml.apache.org/cvs.html


Q: How do I unsubscribe from this list? Help!
A: Don't panic!  And please don't send unsubscribe reqests to the list.
See:
http://xml.apache.org/mail.html


Oh, and the question that should be obvious:
Q: Where's the Xalan homepages?
A: http://xml.apache.org/xalan-j/
   http://xml.apache.org/xalan-c/


Q: Is this FAQ useful to you?
A: Well, is it?  Comments please!  Specific comments, especially from
volunteers to help out with either the list, this FAQ, or our website are
even better...


- Shane

RE: xalan-dev list proto-FAQ v0.3 - Readme First!

[Peter Murphy <pe...@fast.fujitsu.com.au>]

> -----Original Message-----
> From: Shane_Curcuru@lotus.com [mailto:Shane_Curcuru@lotus.com]
> Sent: Saturday, March 17, 2001 7:09 AM
> To: xalan-dev@xml.apache.org
> Subject: xalan-dev list proto-FAQ v0.3 - Readme First!
>
>
> A quick take on a few of the FAQs I've seen lately on the list.
> New/Updated
> items from the immediately-preceding proto-FAQ 0.2 are marked with leading
> *.
>
> We have eventual plans for a more formal FAQ but in the meantime, here's a
> few quick answers.
>

Shane, I LIKE it.

But I'm a little bit confused: is this a FAQ for Xalan developers, or just
Xalan-J? For example:

> Q: I'm getting an unusual error relating to DOM classes, SAX classes,
> javax.xml.* classes - what's wrong?
>
[...]

> NOTE: A number of seemingly odd NoSuchMethod or other exceptions
> can be due to classpath ordering issues.  Many products include their own
copies of
> the org.w3c.dom.*, org.xml.sax.*, and javax.xml.* standard packages, some
> of which may be outdated or incompatible.

Regards,
Peter