Hi, Army, thanks for these docs. Really good reference sections. It
would be really helpful to provide a reference to the XQUERY/XPATH
syntax and semantics. These semantics are quite new to me and it was
hard to even follow your examples, let alone know how to do more complex
things. I recognize this is not the place to document it, but a
reference would be great.
Re: SQL State/message additions. I have a utility that generates the
appropriate documentation for SQL States by extracting directly out of
the message file using the ErrorMessages VTI. So no need to manually
insert these new SQL States (although it would be good if you could
verify they got in when I submit the patch).
Thanks,
David
A B (JIRA) wrote:
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12428434 ]
A B commented on DERBY-1655:
----------------------------
Review comments for "derby1655_devguide.diff":
cdevstandardsxml.html:
----------------------
-- 1 --
Current line:
Instead, users must bind and retrieve the XML data as Java
strings or character streams by explicitly specifying either
the XMLPARSE and XMLSERIALIZE XML operators as part of the
SQL queries.
Should be changed to:
Instead, users must bind and retrieve the XML data as Java
strings or character streams by explicitly specifying the
appropriate XML operator as part of the SQL statements.
More specifically, users should use the XMLPARSE operator
for binding data into XML values, and should use the
XMLSERIALIZE operator to retrieve XML values from a result
set.
-- 2 --
Current lines:
Additionally, there is no JDBC metatadata support for the
XML data type. The XML data type is not allowed in clauses
or operations specified in the expressions on LONG data
types.
Comment:
The fact that these two sentences are in the same paragraph
makes it seem like they are somehow tied together. But
they are not; these are two separate restrictions on XML
use. I think it'd be better to make the first sentence
be the last line of the paragraph preceding this one (i.e.
of the paragraph that begins with "There is no JDBC-side...").
The second sentence can then stand as its own paragraph.
-- 3 --
Current line:
The XML data type is not allowed in clauses or operations
specified in the expressions on LONG data types.
Should be changed to:
The XML data type is not allowed in any of the clauses or
operations mentioned in the "Expressions on LONGs" section
of this manual.
Comment:
Maybe could include the section number of the "Expressions on
LONGs" section, or else a link to that section for ease of reference.
-- 4 --
Current line:
For the XML operators to work properly, Derby requires that
a JAXP parser, such as Apache Xerces, and Apache Xalan are
listed in the Java classpath.
Comment:
The word "listed" should be changed to "included".
-- 5 --
Per David Van Couvering's email here:
http://www.nabble.com/-jira--Created%3A-%28DERBY-1655%29-Document-XML-functionality-for-10.2-tf2079655.html#a5733340
I think we should add a NOTE to the end of this section, saying
what David suggested. Such as:
NOTE:
Most Java virtual machines that are 1.4 or later have a JAXP
parser embedded in them. If you are using such a JVM then
you do not need to add any other JAXP classes to your classpath.
Similarly, if the JVM that you are using includes an embedded
version of Xalan, you will not need to add Xalan to your
classpath. Note, though, that the version of Xalan that is
included in some JVMs (such as Sun jdk1.4.2) may not satisfy
the minimum Xalan requirements for Derby. In that case
you will have to override the JVM's version of Xalan with
a newer version. You can do so through use of Java's
"Endorsed Standards Override Mechanisms", described here:
http://java.sun.com/j2se/1.4.2/docs/guide/standards/
If the JVM that you are using does not have its own JAXP parser
or its own version of Xalan, then you can put external versions
of those classes in your classpath and Derby will pick them
up.
Document XML functionality for 10.2
-----------------------------------
Key: DERBY-1655
URL: http://issues.apache.org/jira/browse/DERBY-1655
Project: Derby
Issue Type: Task
Components: Documentation
Affects Versions: 10.2.0.0
Reporter: A B
Assigned To: Laura Stewart
Fix For: 10.2.0.0
Attachments: ctoolsimport27052.html, derby1655_devguide.diff,
derby1655_devguide_html.zip, derby1655_ref.diff, derby1655_ref_html.zip,
derby1655_tools_html.diff, derby1655_tuning.diff, derby1655_tuning_html.zip,
DerbyXMLDoc_v1.html, DerbyXMLDoc_v2.html
DERBY-334 and DERBY-688 have added an XML datatype and four XML operators to
Derby. These are all going to be exposed to the user for general use as part
of the 10.2. release, so the datatype and operators need to be documented
accordingly.
