A quick take on a few of the FAQs I've seen on the list. Updates are marked with *asterisks. We have eventual plans for a formal FAQs. @see also http://xml.apache.org/xalan-j/faq.html ---- Contents: questions ---------------- Q: Where do I email to ask Xalan questions? *Q: How can I self-diagnose many environment problems with EnvironmentCheck? 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: What's this 'xsltc' or 'translet' stuff I hear about? 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: What's happening with Xalan-J 1.x? (hint: upgrade to 2.x) Q: Is this FAQ useful to you? ---- Contents: answers ---------------- Q: Where do I email to ask Xalan questions? A: Use the appropriate email list! In almost all cases, you should be using one of the supported email lists, not mailing individual committers. -- [EMAIL PROTECTED] -- General list for users of Xalan-J 2.x. Ask your usage questions, ask about details of bugs, and general discussions about how Xalan works from a user perspective here. A significant portion of the existing xalan-dev traffic about the Java processor(s) (xalan/xsltc) should move here. -- [EMAIL PROTECTED] -- General list for users of Xalan-C 1.x - same subjects as above, but in C++ instead of Java. -- [EMAIL PROTECTED] -- The continuing list for developers on the Xalan project - committers and non-committers alike, Java and C++ versions alike. This is much more technical in nature and deals with Xalan internals, specific future release plans, and issues internal to the project community. Some/much of this traffic should really move to xalan-j-users over time. -- [EMAIL PROTECTED] -- A list specifically for cross-project issues at xml.apache.org. Ask questions about long term plans or detailed technical questions that pertain to *multiple* projects, like Xerces, Crimson, Cocoon, Xalan, etc. *Q: How can I self-diagnose many environment problems with EnvironmentCheck? *A: Check out EnvironmentCheck, our handy environment checker that performs a check of your environment. 8-) http://xml.apache.org/xalan-j/apidocs/org/apache/xalan/xslt/EnvironmentCheck.html (Or, until the on-line docs get refreshed, try this:) Usage-from the command line: java org.apache.xalan.xslt.EnvironmentCheck [-out outFile] Usage-from your java program: boolean environmentOK = (new EnvironmentCheck()).checkEnvironment(yourPrintWriter); Usage-from any stylesheet: <?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0" xmlns:xalan="http://xml.apache.org/xalan";> <xsl:output indent="yes"/> <xsl:template match="/"> <xsl:copy-of select="xalan:checkEnvironment()"/> </xsl:template> </xsl:stylesheet> Note that the updated version is not in 2.1.D10; it's currently 10-Sep-01 only in CVS. The new functionality includes the xalan:checkEnvironment() XSLT extension function, which you can simply call from your own stylesheet to make debugging your environment even easier. Running this and then looking at it's log for any ERROR or WARNING will often show you problems in your environment or CLASSPATH - if you still need help, please send the output of this tool along with your question to the list. 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) xalan-j-users and xalan-c-users, as well as many other useful lists, are also hosted there. 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: What's this 'xsltc' or 'translet' stuff I hear about? A: A team of folks from Sun recently donated a funky new XSLT processor called 'XSLTC' to the Xalan project, which we have incorporated into our source tree. It provides an XSLT processor that can compile xsl stylesheets into Java classes called tranlslets, which can result in faster performance in some cases. Most xsltc code is now checked into the org.apache.xalan.xsltc package. Xsltc currently supports it's native API for previous users, and is in the process of implementing the full JAXP/TrAX API set, which is the preferred usage. This allows users to choose between the xsltc implementation and the xalan implementation by simply setting javax.xml.transform.TransformerFactory property to the appropriate TransformerFactoryImpl class. Future plans include improving both sides of the processor, and merging as much of the common code as is practical. The xalan side will provide a full-featured and highly conformant processor for all general needs; and the xsltc side will provide a highly performant and easily cacheable processor for specific stylesheets and situations. 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? (Updated info coming soon at http://xml.apache.org/xalan-j/faq.html) 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; also the JAXP/TrAX spec requires 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(); // URLs must explicitly use only forward slashes if (File.separatorChar == '\\') tmp = tmp.replace('\\', '/'); // Ensure we have a maximum of three /// slashes if (tmp.startsWith("/")) return "file://" + tmp; else 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 (hint: send email to [EMAIL PROTECTED]) Q: What's happening with Xalan-J 1.x? (hint: upgrade to 2.x) A: The Xalan-J 1.x codebase has been removed from the active area of source control. You should probably upgrade to the 2.x processor, and especially upgrade to the JAXP/TrAX interfaces instead of the old native Processor.process() calls. Benefits of upgrading include faster performance, better conformance, and much better support. If you really need a 1.x build, old distributions are still posted at http://xml.apache.org/xalan-j/dist/old/ however the most common answer to questions relating to 1.x usage are "Can you upgrade?" 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... Note that this is currently maintained separately from the faq.xml/.html document that's checked into the xdocs dir, for no reason in particular. - Shane
