[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12426964 ] Laura Stewart commented on DERBY-1655: -- Army - I'll look at the html file and work it into DITA today. > 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 > Fix For: 10.2.0.0 > > Attachments: DerbyXMLDoc_v1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12427252 ] David Van Couvering commented on DERBY-1655: Hi, I've read the docs and I have a couple of comments. Since I'm a complete newbie to SQL/XML hopefully these comments are valid for other new users... - As I mentioned in a separate email, it was not clear to me that if I'm running with a 1.4 VM I most likely already have an XML parser in my classpath. I'd like to see that clarified. - You refer to the SQL standard for the XML operators/commands, but the majority of users do not have access to these standards; they require payment and are not available on the web. I think we need to assume that users should be able to use our documents as the sole point of reference for how to use our product. The documentation so far provides some very high-level descriptoin of what you use XMLSERIALIZE and XMLPARSE for (although it is not at all clear what the required input/expected output and syntax is for these operations), and there is no guidance whatsoever for XMLQUERY and XMLEXISTS. I was thinking of writing some tests, but wouldn't know how to do it (unless I were to go and get the SQL standard and slog through it). I would like to see the syntax for these commands, as well as some examples. In my ideal world I would also love to see some sample programs. That is not to say that what is provided in the current patch should not be checked in, I think it's a good start. I just really want to see more. Thanks! David > 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: DerbyXMLDoc_v1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12427256 ] A B commented on DERBY-1655: > The documentation so far provides some very high-level descriptoin of what > you > use XMLSERIALIZE and XMLPARSE for (although it is not at all clear what the > required input/expected output and syntax is for these operations), and there > is > no guidance whatsoever for XMLQUERY and XMLEXISTS. I think I mentioned in the document this was a first draft, and incomplete. In particular, please notice the lines: And then of course we have to add the new XML operators to this section: XMLPARSE, XMLSERIALIZE, XMLEXISTS, and XMLQUERY. These are forthcoming... So yes, the details are on their way... > 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: DerbyXMLDoc_v1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12427280 ] Laura Stewart commented on DERBY-1655: -- I added the attachements for the Dev Guide. Please review and commit if the updates are ready to be committed. > 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: derby1655_devguide.diff, derby1655_devguide_html.zip, > DerbyXMLDoc_v1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ 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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[
http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429467 ]
A B commented on DERBY-1655:
Thank you Laura for taking the time to port the doc changes in _v1.html into
the Derby 10.2 manuals.
The changes in:
derby1655_tuning.diff
derby1655_tools_html.diff
look good to me and can be committed (+1).
The changes in
derby1655_devguide.diff
are still awaiting some slight updates per my previous comment.
And below I've include a couple of (very) minor comments on the changes in the
Reference Guide, i.e. the changes in:
derby1655_ref.diff
NOTE: Most of these are minor enough to be left as they are, with the exception
of those tagged with "##!##". So if you are short on time, feel free to skip
the minor changes and just focus on the changes tagged with "##!##".
File: rrefjdbcrefsqlxml.html
-- 1 --
Slight typo: can remove "to" just before "retrieve an XML" in the following
sentence:
You cannot instantiate a java.sql.SQLXML object in Derby,
or bind directly into an XML value or to retrieve an XML
value directly from a result set.
Suggested rewording (optional):
You cannot instantiate a java.sql.SQLXML object in Derby.
You also cannot bind directly into an XML value or retrieve
an XML value directly from a result set.
File: rrefsqljtypexml.html
--
-- 1 --
Comment: Can we explicitly mention XMLPARSE and XMLSERIALIZE in the following
sentence, like we do in rrefjdbcrefsqlxml.html?
Instead, you must bind and retrieve the XML data as Java
strings or character streams by explicitly specifying the
appropriate XML operators as part of your SQL queries.
Suggested rewording (optional):
Instead, you must bind and retrieve the XML data as Java
strings or character streams by explicitly specifying the
appropriate XML operators, XMLPARSE and XMLSERIALIZE, as
part of your SQL queries.
-- 2 --
Slight typo: Comma between the following two sentences should be a period:
The Java type for XML values is java.sql.SQLXML, The
java.sql.SQLXML type is not supported by Derby.
Suggested addition (optional): can we add the word "However" at the start of
the second sentence? And also at the start of the second sentence in this line:
The metadata type for XML values is SQLXML. The SQLXML type
is not supported by Derby.
-- 3 -- ##!##
Syntax update: One of the latest checkins for XML ("phase 4" patch) added a
restriction to the use of parameters in XMLPARSE, so the example in this file
needs to be updated. In particular, change
INSERT INTO myXmlTable(xcol) VALUES XMLPARSE(
DOCUMENT ? PRESERVE WHITESPACE)
to be
INSERT INTO myXmlTable(xcol) VALUES XMLPARSE (
DOCUMENT CAST (? AS CLOB) PRESERVE WHITESPACE)
File: rreflimitsxml.html
-- 1 --
Slight typo: replace "are in the classpath" with "to be in the classpath" in
the following sentence:
Requires the JAXP parser classes, such as Apache Xerces, and
Apache Xalan classes are in the classpath. Attempts to use XML
operators without these classes in the classpath results in an
error.
File: rrefsqlj33562.html
-- 1 -- ##!##
Comment: The XML row has dashes in it, which is correct. However the XML
column just has blank cells. Can we add dashes to the cells in the XML column,
as well, to be consistent with the rest of the table?
And that's it! Thanks for being so thorough with these.
> 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.1.0
>Reporter: A B
> Assigned To: Laura Stewart
> Fix For: 10.2.1.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.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429474 ] Jean T. Anderson commented on DERBY-1655: - Committed to the trunk derby1655_tuning.diff (revision 433298) and derby1655_tools_html.diff (revision 433307). > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429477 ] Laura Stewart commented on DERBY-1655: -- Hi Army - I am working on updating the dev guide now and will include these comments for the ref manual. I should have a patch out soon for you to review. > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429486 ] Laura Stewart commented on DERBY-1655: -- Regarding the new information about XMLEXISTS, you ask that it be put into the Built-in function section and yet you refer to it as an "operator". Unlike the concatenate operator (which to me is a symbol), XMLEXISTS is a function that accepts several arguments. Okay to refer to it as a function instead of an operator? > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429495 ] A B commented on DERBY-1655: > Okay to refer to it as a function instead of an operator? Great question. I guess I'm not sure what the answer here should be... I've been calling these "operators" because that's the term used in the SQL/XML[2006] specification. But the Derby doc says the following: "A built-in function is an expression in which an SQL keyword or special operator executes some operation." And the SQL/XML specification indicates XMLEXISTS, etc are reserved keywords. So based on that I guess it would be okay to refer to the new SQL/XML operators as Derby built-in functions, as well. My gut feeling, though, is that we should continue to use the term "operator" for these because a) that's the term used by the SQL/XML specification and b) I don't think we state anywhere that an "operator" cannot be a "function" as well. I am not going to complain one way or the other, though. If anyone else has a strong preference, feel free to speak 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429567 ] Laura Stewart commented on DERBY-1655: -- In the updated DerbyXMLDoc_v2.html file, there are references to SQL/XML[2006]. Do we really want to qualify the year? I think it might be better to just have SQL/XML, except perhaps in a concept topic, like cdevstandardsxml "XML data type and operators" Where most of the overview and general information should be. > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429569 ] A B commented on DERBY-1655: > I think it might be better to just have SQL/XML, except perhaps in a concept > topic, like > cdevstandardsxml "XML data type and operators" Where most of the overview and > general information should be. Sounds good to me... > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429760 ] A B commented on DERBY-1655: The latest changes to the devguide look great and can be commited: derby1655_devguide2.diff (+1) For the reference guide, it looks rrefsqljtypexml.html was not updated to reflect the comments I made above. I did look at the .diff file an I can see that the first two commens for that document were correctly applied, but the diff is a little confusing w.r.t the third comment--i.e. the one about the different XMLPARSE syntax. So can you post the updated html version of rrefsqljtypexml so that I can double-check it in HTML form? Also, you mentioned some new files for the XML operators, but I don't see them in the ref guide zip file (derby1655_ref_html2.zip). Again, I can see the changes in the .diff file, but I'd rather review them in HTML form, if possible... Thanks Laura! > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.0 > > Attachments: ctoolsimport27052.html, derby1655_devguide.diff, > derby1655_devguide2.diff, derby1655_devguide_html.zip, > derby1655_devguide_html2.zip, derby1655_ref.diff, derby1655_ref2.diff, > derby1655_ref_html.zip, derby1655_ref_html2.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429768 ] Jean T. Anderson commented on DERBY-1655: - Committed derby1655_devguide2.diff revision 433708. > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.0 > > Attachments: ctoolsimport27052.html, derby1655_devguide.diff, > derby1655_devguide2.diff, derby1655_devguide_html.zip, > derby1655_devguide_html2.zip, derby1655_ref.diff, derby1655_ref2.diff, > derby1655_ref3.diff, derby1655_ref_html.zip, derby1655_ref_html2.zip, > derby1655_ref_html3.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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12430075 ] Jean T. Anderson commented on DERBY-1655: - Revision 434125: reverted the commit of patch derby1655_devguide2.diff (revision 433708) because the PDF build fails. This warning appears in the 'ant pdf' build output in the pdf.devguide section: [xslt] file:/home/jta/DB-DERBY-SVN/derby/docs/trunk/DITA-OT1.1.2.1/xsl/xslfo/dita2fo-links.xsl:148:57: Warning! Can not load requested doc: The element type "meta" must be terminated by the matching end-tag "". The patch had these changes: A src/devguide/cdevstandardsxml.dita M src/devguide/derbydev.ditamap M src/devguide/cdevstandards805975.dita M src/devguide/cdevdvlp30653.dita 'ant pdf' and 'ant all' build successfully without the cdevstandardsxml.dita addition and the derbydev.ditamap changes. > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.0 > > Attachments: ctoolsimport27052.html, derby1655_devguide.diff, > derby1655_devguide2.diff, derby1655_devguide3.diff, > derby1655_devguide_html.zip, derby1655_devguide_html2.zip, > derby1655_devguide_html2.zip, derby1655_ref.diff, derby1655_ref2.diff, > derby1655_ref3.diff, derby1655_ref_html.zip, derby1655_ref_html2.zip, > derby1655_ref_html3.zip, derby1655_tools_html.diff, derby1655_tuning.diff, > derby1655_tuning_html.zip, DerbyXMLDoc_v1.html, DerbyXMLDoc_v2.html, > ref_html3_comments.txt > > > 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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12430132 ] Jean T. Anderson commented on DERBY-1655: - Thanks, Laura. Build succeeds with derby1655_devguide3.diff, so committed to trunk revision 434236. > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.0 > > Attachments: ctoolsimport27052.html, derby1655_devguide.diff, > derby1655_devguide2.diff, derby1655_devguide3.diff, > derby1655_devguide_html.zip, derby1655_devguide_html2.zip, > derby1655_devguide_html2.zip, derby1655_ref.diff, derby1655_ref2.diff, > derby1655_ref3.diff, derby1655_ref_html.zip, derby1655_ref_html2.zip, > derby1655_ref_html3.zip, derby1655_tools_html.diff, derby1655_tuning.diff, > derby1655_tuning_html.zip, DerbyXMLDoc_v1.html, DerbyXMLDoc_v2.html, > ref_html3_comments.txt > > > 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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12430367 ] A B commented on DERBY-1655: I reviewed the updated files for the XML operators and they all look great--thanks a ton for following through on this, Laura. +1 to commit the following patch: derby1655_ref5.diff Thanks Laura! > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.0 > > Attachments: ctoolsimport27052.html, derby1655_devguide.diff, > derby1655_devguide2.diff, derby1655_devguide3.diff, > derby1655_devguide_html.zip, derby1655_devguide_html2.zip, > derby1655_devguide_html2.zip, derby1655_ref.diff, derby1655_ref2.diff, > derby1655_ref3.diff, derby1655_ref4.diff, derby1655_ref5.diff, > derby1655_ref_html.zip, derby1655_ref_html2.zip, derby1655_ref_html3.zip, > derby1655_ref_html4.zip, derby1655_ref_html5.zip, derby1655_tools_html.diff, > derby1655_tuning.diff, derby1655_tuning_html.zip, DerbyXMLDoc_v1.html, > DerbyXMLDoc_v2.html, ref_html3_comments.txt > > > 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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12430546 ] Jean T. Anderson commented on DERBY-1655: - Patch derby1655_ref6.diff committed to trunk revision 436862 (not merged to 10.2 branch yet). > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.2.1.0 > > Attachments: ctoolsimport27052.html, derby1655_devguide.diff, > derby1655_devguide2.diff, derby1655_devguide3.diff, > derby1655_devguide_html.zip, derby1655_devguide_html2.zip, > derby1655_devguide_html2.zip, derby1655_ref.diff, derby1655_ref2.diff, > derby1655_ref3.diff, derby1655_ref4.diff, derby1655_ref5.diff, > derby1655_ref6.diff, derby1655_ref_html.zip, derby1655_ref_html2.zip, > derby1655_ref_html3.zip, derby1655_ref_html4.zip, derby1655_ref_html5.zip, > derby1655_ref_html6.zip, derby1655_tools_html.diff, derby1655_tuning.diff, > derby1655_tuning_html.zip, DerbyXMLDoc_v1.html, DerbyXMLDoc_v2.html, > ref_html3_comments.txt > > > 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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12430547 ] Jean T. Anderson commented on DERBY-1655: - I'm not sure what the status is for this issue. So far, patches have been committed for the Developer's Guide, Tools, Tuning, and the Reference Guide. Are any more patches in-progress ? Or can the "patch available" flag be unchecked and this issue marked resolved? > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.3.0.0 > > Attachments: ctoolsimport27052.html, derby1655_devguide.diff, > derby1655_devguide2.diff, derby1655_devguide3.diff, > derby1655_devguide_html.zip, derby1655_devguide_html2.zip, > derby1655_devguide_html2.zip, derby1655_ref.diff, derby1655_ref2.diff, > derby1655_ref3.diff, derby1655_ref4.diff, derby1655_ref5.diff, > derby1655_ref6.diff, derby1655_ref_html.zip, derby1655_ref_html2.zip, > derby1655_ref_html3.zip, derby1655_ref_html4.zip, derby1655_ref_html5.zip, > derby1655_ref_html6.zip, derby1655_tools_html.diff, derby1655_tuning.diff, > derby1655_tuning_html.zip, DerbyXMLDoc_v1.html, DerbyXMLDoc_v2.html, > ref_html3_comments.txt > > > 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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1655) Document XML functionality for 10.2
[ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12430643 ] Rick Hillegas commented on DERBY-1655: -- Ported DERBY-1655 (436862, 434236, 434125, 433708, 433307, 433298) to 10.2 branch at subversion revision 436974. > 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.1.0 >Reporter: A B > Assigned To: Laura Stewart > Fix For: 10.3.0.0 > > Attachments: ctoolsimport27052.html, derby1655_devguide.diff, > derby1655_devguide2.diff, derby1655_devguide3.diff, > derby1655_devguide_html.zip, derby1655_devguide_html2.zip, > derby1655_devguide_html2.zip, derby1655_ref.diff, derby1655_ref2.diff, > derby1655_ref3.diff, derby1655_ref4.diff, derby1655_ref5.diff, > derby1655_ref6.diff, derby1655_ref_html.zip, derby1655_ref_html2.zip, > derby1655_ref_html3.zip, derby1655_ref_html4.zip, derby1655_ref_html5.zip, > derby1655_ref_html6.zip, derby1655_tools_html.diff, derby1655_tuning.diff, > derby1655_tuning_html.zip, DerbyXMLDoc_v1.html, DerbyXMLDoc_v2.html, > ref_html3_comments.txt > > > 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. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
Re: [jira] Commented: (DERBY-1655) Document XML functionality for 10.2
Laura Stewart (JIRA) wrote: Laura Stewart commented on DERBY-1655: -- Army - I'll look at the html file and work it into DITA today. Thanks Laura! Army
Re: [jira] Commented: (DERBY-1655) Document XML functionality for 10.2
OK, missed that, thanks. David A B (JIRA) wrote: [ http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12427256 ] A B commented on DERBY-1655: The documentation so far provides some very high-level descriptoin of what you use XMLSERIALIZE and XMLPARSE for (although it is not at all clear what the required input/expected output and syntax is for these operations), and there is no guidance whatsoever for XMLQUERY and XMLEXISTS. I think I mentioned in the document this was a first draft, and incomplete. In particular, please notice the lines: And then of course we have to add the new XML operators to this section: XMLPARSE, XMLSERIALIZE, XMLEXISTS, and XMLQUERY. These are forthcoming... So yes, the details are on their way... 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: DerbyXMLDoc_v1.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.
Re: [jira] Commented: (DERBY-1655) Document XML functionality for 10.2
David Van Couvering wrote: OK, missed that, thanks. Thank YOU for actually reading the docs :) I'm glad there's interest in the new behavior, and I wish had the documentation completed by now for early feedback. But alas, things to do, things to do... Thanks again, Army
Re: [jira] Commented: (DERBY-1655) Document XML functionality for 10.2
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 dataty
Re: [jira] Commented: (DERBY-1655) Document XML functionality for 10.2
David Van Couvering wrote: 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. Hi David, I included some references to the relevant specification in the _v2 HTML document for XMLEXISTS and XMLQUERY operators: XPath: http://www.w3.org/TR/xpath XQuery: http://www.w3.org/TR/xquery/ Are you suggesting that additional referferences be provided? If so, what other kinds of references would you like to see? 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). Okay, thanks for letting me know. The only trick is that I haven't yet posted the patch with the new SQLSTATEs in it. If I can manage to do that later tonight, will that be in time for them to be picked up before you run your utility and submit your patch? Thanks (again) for taking the time to review the examples and for trying them out... Army
Re: [jira] Commented: (DERBY-1655) Document XML functionality for 10.2
Hi, Army. Army wrote: David Van Couvering wrote: 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. Hi David, I included some references to the relevant specification in the _v2 HTML document for XMLEXISTS and XMLQUERY operators: XPath: http://www.w3.org/TR/xpath XQuery: http://www.w3.org/TR/xquery/ Are you suggesting that additional referferences be provided? If so, what other kinds of references would you like to see? No, that's great, I think I missed these. 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). Okay, thanks for letting me know. The only trick is that I haven't yet posted the patch with the new SQLSTATEs in it. If I can manage to do that later tonight, will that be in time for them to be picked up before you run your utility and submit your patch? Well, the utility can be run multiple times. I am planning on suggesting that this be run (probably by the release manager?) prior to each snapshot/release candidate. David Thanks (again) for taking the time to review the examples and for trying them out... Army
Re: [jira] Commented: (DERBY-1655) Document XML functionality for 10.2
A B (JIRA) wrote: > [ > http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429467 > ] > > A B commented on DERBY-1655: > > > Thank you Laura for taking the time to port the doc changes in _v1.html into > the Derby 10.2 manuals. > > The changes in: > > derby1655_tuning.diff > derby1655_tools_html.diff > > look good to me and can be committed (+1). I'll commit these. -jean
Re: [jira] Commented: (DERBY-1655) Document XML functionality for 10.2
A B (JIRA) wrote: > [ > http://issues.apache.org/jira/browse/DERBY-1655?page=comments#action_12429760 > ] > > A B commented on DERBY-1655: > > > The latest changes to the devguide look great and can be commited: > > derby1655_devguide2.diff (+1) > I'll commit this. -jean
