A quick take on a few of the FAQs I've seen lately on the list. This FAQ broadcast is a repeat of the earlier 0.3 broadcast; there are no changes except to put in a plug for org.apache.xalan.xslt.EnvironmentCheck, the Xalan environment self-checker, recently updated at: http://xml.apache.org/websrc/cvsweb.cgi/xml-xalan/java/src/org/apache/xalan/xslt/EnvironmentCheck.java?rev=1.3&content-type=text/vnd.viewcvs-markup We have eventual plans for a more formal FAQ; there are some plans for it in the works; I don't know what the status of those plans are. 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:<[EMAIL PROTECTED]> 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: <[EMAIL PROTECTED]> 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/ http://xml.apache.org/xalan-j/test/overview.html 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
