XML operators - Xalan requirement

• Key: DERBY-1923
• Type: Bug
• Status: Resolved
• Resolution: Fixed
• Priority: Major
• Assignee: Kim Haase
• Reporter: Laura Stewart
• Component/s: Documentation
• Affects Version/s: 10.2.1.6
• Fix Version/s: 10.5.2.0, 10.6.0.0

Description

From Daniel Debrunner:
The XML operators and data type include text about requiring Xalan etc. When trying out XML I felt lost at this point because there was no information on what I was meant to do. It was the feeling I was being told "You need to do something with Xalan to get this to work, but you are going to have to figure that out yourself". It stopped me from evaluating Mustang with XML. Can there be information in the developers' guide about this, and a link to that information from these Usage notes?
 

Comments

[Andrew McIntyre]

Unsetting Fix Version on unassigned issues.

[Kim Haase]

There is a note in the Dev Guide topic "XML data types and operators" (http://db.apache.org/derby/docs/dev/devguide/cdevstandardsxml.html) stating that Xalan comes with most JVMs now (with details). I think the last sentence of this topic can be removed now, since Derby doesn't support JDKs earlier than 1.4.

The sentence "To see a list of the versions of the JAXP implementation and of Apache Xalan that have been tested with Derby XML support, see to the Derby release notes" should also be removed. This information is no longer in the release notes, presumably because just about all JAXP/Xalan versions just work now.

From the XML operator and other topics in the Reference Manual that talk about Xalan, it would probably be appropriate to state briefly that Xalan support is in most JVMs and to point to the Dev Guide topic for details.

Does this make sense? I welcome other suggestions.

[Knut Anders Hatlen]

Sun's JVMs >= 1.5 have a Xalan library used internally which satisfies the minimum version requirements. However, the package names have been changed so that they don't conflict with the user's Xalan libraries, and therefore Derby won't find them (DERBY-2739). See incompatibility #9 in J2SE 5.0: http://java.sun.com/j2se/1.5.0/compatibility.html

AFAIK, Derby doesn't support the XML operators out of the box on any of the Sun JVMs. For 1.4.2, you need to use the Endorsed Standards Override Mechanism as mentioned in the dev guide. For 1.5.0 and later, wiring the Xalan jars into the classpath should be enough.

[Kim Haase]

Thanks, Knut Anders. So does that mean that for 1.5 or later JVMs I have to go to http://xml.apache.org/xalan-j/downloads.html and download a binary distribution, unzip it, and put the jars in the classpath?

Do I have to put all 4 jars in the classpath (serializer.jar, xalan.jar, xercesImpl.jar, xml-apis.jar) or just xalan.jar?

Also, the downloads page says,

To use Xalan-Java, you need the following:

    * The JDK or JRE 1.3.x, 1.4.x, or 5.x

It doesn't mention JDK 6 -- is the same true for JDK 6?

Also, you mentioned the Sun JVMs, but what about others (like IBM)? Is the same true for them?

Thanks!

[Knut Anders Hatlen]

I think you only need to specify xalan.jar in your classpath, the rest of them will be imported automatically by the manifest, but they need to be there in the same directory as xalan.jar. I'm not sure if you need all of them. I will have to test it to be sure.

It does work on JDK 6 even though it's not mentioned.

As for IBM JVMs, I think they still ship Xalan in the standard location. I think 1.5 (and later) satisfies the minimum requirement and should work out of the box. If a newer version of Xalan is required/desired, the Endorsed Standards Override Mechanism must be used. But I haven't tested this.

[Kim Haase]

Thanks again! Let me see if I have this figured out now:

IBM JVMs: For 1.4.2, use Endorsed Standards Override Mechanism; for 1.5 and 1.6, works out of box?

Sun JVMs: For 1.4.2, use Endorsed Standards Override Mechanism; for 1.5 and 1.6, download Xalan binary distribution from Apache, put xalan.jar into classpath (we think).

Is that right? currently we only mention the Endorsed Standards Override Mechanism in connection with Sun, which would imply that the IBM 1.4 JVM is okay; but you say that for IBM "I think 1.5 (and later) satisfies the minimum requirement", which implies that IBM 1.4 users would have to use the override mechanism too.

We need information from an IBM person on this. I guess you will be testing the Sun situation when you get a chance.

[Knut Anders Hatlen]

That sounds right. I'll test it as soon as I can, but it'll probably have to wait until after the weekend.

[Kim Haase]

Thanks! There's no rush about testing, because I am going on vacation for 3 weeks and won't be picking this up again till the end of June.

Perhaps by then we will also have some answers about the IBM JVMs. If anyone has Xalan information on other JVMs we should consider, please add a comment to this issue.

[Knut Anders Hatlen]

Here's what I found for Sun's JVM by running org.apache.derbyTesting.functionTests.tests.lang.XMLTypeAndOpsTest:

1.5.0, 1.6.0, 1.7.0: XML operators worked when xalan.jar (and serializer.jar implicitly via xalan.jar's manifest) was in the classpath

1.4.2: XML operators worked when the java.endorsed.dirs pointed to the Xalan 2.7 installation directory. (The minimum set of jars needed to get the tests running on 1.4.2 was xalan.jar, serializer.jar, xml-apis.jar and xercesImpl.jar)

[Kim Haase]

Attaching DERBY-1923.diff, DERBY-1923.stat, and DERBY-1923.zip, with changes to the following files:

M src/devguide/cdevstandardsxml.dita
M src/ref/rrefjdbcjsr169.dita
M src/ref/rreflimitsxml.dita
M src/ref/rreffuncxmlserialize.dita
M src/ref/rreffuncxmlquery.dita
M src/ref/rreffuncxmlexists.dita
M src/ref/rrefsqljtypexml.dita
M src/ref/rreffuncxmlparse.dita

I hope the text now clarifies the situation as far as it is known. If we get specific information about other JVMs, we can add it to the Developer's Guide topic.

Please let me know if any corrections are needed.

[Knut Anders Hatlen]

The patch looks like a good improvement to me. +1 to commit.

The sentence below may perhaps confuse some users into thinking that xalan.jar is the only jar file needed, whereas it in fact depends on serializer.jar being located in the same directory.

> (...) download and install a binary distribution of Xalan from Apache and place the xalan.jar file in your classpath.

Would it be worth mentioning that xalan.jar automatically wires other required jars in the same directory into the classpath so that no one is tempted to remove the other jars?

But anyway, +1 to commit the patch as it is. If we decide so, an extra sentence could be added later.

[Kim Haase]

Thanks very much, Knut. I agree that it would be very helpful to add a sentence making that classpath information more explicit. I've followed your suggestion to commit this patch and will file an additional patch for just the one file that needs another change.

Committed patch DERBY-1923.diff to documentation trunk at revision 793607.
Merged to 10.5 doc branch at revision 793611.

[Kim Haase]

Attaching DERBY-1923-2.diff and cdevstandardsxml.html, with Knut's suggested fix for this topic. I rearranged the wording a bit so that the prepositional phrases would be closest to the words they modify. Hope it makes sense to a non-grammarian.

[Knut Anders Hatlen]

Thanks, the prepositional phrases look well-placed to my untrained eyes. :)

+1 to commit.

[Kim Haase]

Thanks very much, Knut!

Committed patch DERBY-1923-2.diff to documentation trunk at revision 793922.
Merged to 10.5 doc branch at revision 793923.