Derby
  1. Derby
  2. DERBY-1655

Document XML functionality for 10.2

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.2.1.6
    • Fix Version/s: 10.2.1.6, 10.3.1.4
    • Component/s: Documentation
    • Labels:
      None
    • Urgency:
      Normal

      Description

      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.

      1. ctoolsimport27052.html
        5 kB
        Laura Stewart
      2. derby1655_devguide_html.zip
        3 kB
      3. derby1655_devguide_html2.zip
        6 kB
        Laura Stewart
      4. derby1655_devguide_html2.zip
        6 kB
        Laura Stewart
      5. derby1655_devguide.diff
        10 kB
      6. derby1655_devguide2.diff
        15 kB
        Laura Stewart
      7. derby1655_devguide3.diff
        15 kB
        Laura Stewart
      8. derby1655_ref_html.zip
        39 kB
        Laura Stewart
      9. derby1655_ref_html2.zip
        67 kB
        Laura Stewart
      10. derby1655_ref_html3.zip
        77 kB
        Laura Stewart
      11. derby1655_ref_html4.zip
        81 kB
        Laura Stewart
      12. derby1655_ref_html5.zip
        86 kB
        Laura Stewart
      13. derby1655_ref_html6.zip
        86 kB
        Laura Stewart
      14. derby1655_ref.diff
        71 kB
        Laura Stewart
      15. derby1655_ref2.diff
        101 kB
        Laura Stewart
      16. derby1655_ref3.diff
        101 kB
        Laura Stewart
      17. derby1655_ref4.diff
        98 kB
        Laura Stewart
      18. derby1655_ref5.diff
        102 kB
        Laura Stewart
      19. derby1655_ref6.diff
        102 kB
        Laura Stewart
      20. derby1655_tools_html.diff
        6 kB
        Laura Stewart
      21. derby1655_tuning_html.zip
        4 kB
        Laura Stewart
      22. derby1655_tuning.diff
        11 kB
        Laura Stewart
      23. DerbyXMLDoc_v1.html
        26 kB
        A B
      24. DerbyXMLDoc_v2.html
        55 kB
        A B
      25. ref_html3_comments.txt
        12 kB
        A B

        Issue Links

          Activity

          Hide
          A B added a comment -

          Attaching a first proposal for documentation of the XML datatype and corresponding operators. These changes are based on a quick examination of the existing Derby manuals.

          Two sections which are still missing are the descriptions of the XML operators and the new SQLSTATE messages for XML. Those are forthcoming; for now, the documentation changes shown in DerbyXMLDoc_v1.html concentrate on the documenting the XML datatype and the limitations of its use.

          I don't know anything about DITA or about how the docs are written, so I've just included my suggested changes in this HTML document. Hopefully someone more knowledgeable of the Derby doc process can take the steps to get these changes committed...

          Show
          A B added a comment - Attaching a first proposal for documentation of the XML datatype and corresponding operators. These changes are based on a quick examination of the existing Derby manuals. Two sections which are still missing are the descriptions of the XML operators and the new SQLSTATE messages for XML. Those are forthcoming; for now, the documentation changes shown in DerbyXMLDoc_v1.html concentrate on the documenting the XML datatype and the limitations of its use. I don't know anything about DITA or about how the docs are written, so I've just included my suggested changes in this HTML document. Hopefully someone more knowledgeable of the Derby doc process can take the steps to get these changes committed...
          Hide
          Laura Stewart added a comment -

          Army - I'll look at the html file and work it into DITA today.

          Show
          Laura Stewart added a comment - Army - I'll look at the html file and work it into DITA today.
          Hide
          David Van Couvering added a comment -

          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

          Show
          David Van Couvering added a comment - 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
          Hide
          A B added a comment -

          > 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:

          <begin quote>

          And then of course we have to add the new XML operators to this section: XMLPARSE, XMLSERIALIZE, XMLEXISTS, and XMLQUERY. These are forthcoming...

          <end quote>

          So yes, the details are on their way...

          Show
          A B added a comment - > 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: <begin quote> And then of course we have to add the new XML operators to this section: XMLPARSE, XMLSERIALIZE, XMLEXISTS, and XMLQUERY. These are forthcoming... <end quote> So yes, the details are on their way...
          Hide
          Laura Stewart added a comment -

          I added the attachements for the Dev Guide. Please review and commit if the updates are
          ready to be committed.

          Show
          Laura Stewart added a comment - I added the attachements for the Dev Guide. Please review and commit if the updates are ready to be committed.
          Hide
          Laura Stewart added a comment -

          Attached updates to the Tools and Utilities Guide.
          One file was updated.

          Please review and comment if these updates can be committed.

          Show
          Laura Stewart added a comment - Attached updates to the Tools and Utilities Guide. One file was updated. Please review and comment if these updates can be committed.
          Hide
          Laura Stewart added a comment -

          Attaching the doc updates for the Tuning Guide.
          Please review and comment if these updates are ready to be committed.

          Show
          Laura Stewart added a comment - Attaching the doc updates for the Tuning Guide. Please review and comment if these updates are ready to be committed.
          Hide
          Laura Stewart added a comment -

          Attached a patch and html.zip file with the updates to the Ref Manual for
          the XML support.

          Please review and comment so that we can commit these changes.

          FYI - There are additional updates to the Ref Manual that will be made:
          1. The new XML operators: XMLPARSE, XMLSERIALIZE, XMLEXISTS, and XMLQUERY. These are forthcoming...
          2. We're going to have to add several more error messages. These new error messages have yet to be finalized and are still forthcoming...

          Show
          Laura Stewart added a comment - Attached a patch and html.zip file with the updates to the Ref Manual for the XML support. Please review and comment so that we can commit these changes. FYI - There are additional updates to the Ref Manual that will be made: 1. The new XML operators: XMLPARSE, XMLSERIALIZE, XMLEXISTS, and XMLQUERY. These are forthcoming... 2. We're going to have to add several more error messages. These new error messages have yet to be finalized and are still forthcoming...
          Hide
          A B added a comment -

          Attaching a second version of the DerbyXMLDoc file, DerbyXMLDoc_v2.html, that includes two new sections to fill in missing information. In particular, the second version includes:

          1) First attempt at documentation for the four XML operators, XMLEXISTS, XMLPARSE, XMLQUERY, and XMLSERIALIZE.

          2) New SQLSTATEs to be added for the XML datatype and operators. The code to reflect the new SQLSTATEs hasn't been posted, but these are the SQLSTATEs that I plan to use.

          The new sections can be found by searching for "<BEGIN: Added with _v2 of this document>".

          Aside from these two new sections, the _v2 document is the same as the _v1 document. I know the doc patches for _v1 are still pending review-it's on my list to do-but I'm posting the rest of the doc changes for anyone who might be interested in testing the XML functionality (ex. as part of the "Buddy Testing" effort) while doc review is happening.

          Show
          A B added a comment - Attaching a second version of the DerbyXMLDoc file, DerbyXMLDoc_v2.html, that includes two new sections to fill in missing information. In particular, the second version includes: 1) First attempt at documentation for the four XML operators, XMLEXISTS, XMLPARSE, XMLQUERY, and XMLSERIALIZE. 2) New SQLSTATEs to be added for the XML datatype and operators. The code to reflect the new SQLSTATEs hasn't been posted, but these are the SQLSTATEs that I plan to use. The new sections can be found by searching for "<BEGIN: Added with _v2 of this document>". Aside from these two new sections, the _v2 document is the same as the _v1 document. I know the doc patches for _v1 are still pending review- it's on my list to do -but I'm posting the rest of the doc changes for anyone who might be interested in testing the XML functionality (ex. as part of the "Buddy Testing" effort) while doc review is happening.
          Hide
          A B added a comment -

          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.

          Show
          A B added a comment - 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.
          Hide
          A B added a comment -

          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 "##Unable to render embedded object: File (##". So if you are short on time, feel free to skip the minor changes and just focus on the changes tagged with "##) not found.##".

          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.

          Show
          A B added a comment - 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 "## Unable to render embedded object: File (##". So if you are short on time, feel free to skip the minor changes and just focus on the changes tagged with "##) not found. ##". 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.
          Hide
          Jean T. Anderson added a comment -

          Committed to the trunk derby1655_tuning.diff (revision 433298) and derby1655_tools_html.diff (revision 433307).

          Show
          Jean T. Anderson added a comment - Committed to the trunk derby1655_tuning.diff (revision 433298) and derby1655_tools_html.diff (revision 433307).
          Hide
          Laura Stewart added a comment -

          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.

          Show
          Laura Stewart added a comment - 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.
          Hide
          Laura Stewart added a comment -

          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?

          Show
          Laura Stewart added a comment - 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?
          Hide
          A B added a comment -

          > 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...

          Show
          A B added a comment - > 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...
          Hide
          Laura Stewart added a comment -

          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.

          Show
          Laura Stewart added a comment - 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.
          Hide
          A B added a comment -

          > 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...

          Show
          A B added a comment - > 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...
          Hide
          Laura Stewart added a comment -

          Updated patch files for XML support, based on all of the comments received so far.

          Show
          Laura Stewart added a comment - Updated patch files for XML support, based on all of the comments received so far.
          Hide
          Laura Stewart added a comment -

          Attaching HTML zip files with all of the changes. The latest files changed are;

          Doc Filename Title Summary of update
          devguide cdevdvlp30653 Derby limitations Added XML
          devguide cdevstandards805975 Added XML
          devguide derbyref.ditamap Added XML
          ref rrefexcept71493 SQLState and error message reference Added XML error message
          ref rreffuncxmlexists XMLEXISTS operator New file
          ref rreffuncxmlparse XMLPARSE operator New file
          ref rreffuncxmlquery XMLQUERY operator New file
          ref rreffuncxmlserialize XMLSERIALIZE operator New file

          Show
          Laura Stewart added a comment - Attaching HTML zip files with all of the changes. The latest files changed are; Doc Filename Title Summary of update devguide cdevdvlp30653 Derby limitations Added XML devguide cdevstandards805975 Added XML devguide derbyref.ditamap Added XML ref rrefexcept71493 SQLState and error message reference Added XML error message ref rreffuncxmlexists XMLEXISTS operator New file ref rreffuncxmlparse XMLPARSE operator New file ref rreffuncxmlquery XMLQUERY operator New file ref rreffuncxmlserialize XMLSERIALIZE operator New file
          Hide
          A B added a comment -

          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!

          Show
          A B added a comment - 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!
          Hide
          Laura Stewart added a comment -

          Hi Army -

          You were correct, the new files were missing from the html zip file and the last correction to that file was not completed properly. I have created a new patch and html zip file for the reference guide.

          Please review and let me know if there are any more changes that need to be made.

          Show
          Laura Stewart added a comment - Hi Army - You were correct, the new files were missing from the html zip file and the last correction to that file was not completed properly. I have created a new patch and html zip file for the reference guide. Please review and let me know if there are any more changes that need to be made.
          Hide
          Jean T. Anderson added a comment -

          Committed derby1655_devguide2.diff revision 433708.

          Show
          Jean T. Anderson added a comment - Committed derby1655_devguide2.diff revision 433708.
          Hide
          A B added a comment -

          Attaching a file, "ref_html3_comments.txt", that has my review comments for the documentation of the XML operators. Thank you for tackling this task, Laura--there's a lot of info in there so I appreciate your time!

          Show
          A B added a comment - Attaching a file, "ref_html3_comments.txt", that has my review comments for the documentation of the XML operators. Thank you for tackling this task, Laura--there's a lot of info in there so I appreciate your time!
          Hide
          Jean T. Anderson added a comment -

          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 "</meta>".

          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.

          Show
          Jean T. Anderson added a comment - 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 "</meta>". 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.
          Hide
          Laura Stewart added a comment -

          Based on the problems encountered with the build, I have prepared updated
          files (patch and html zip) for the developers guide.
          The problem was in the tagging for an external link.
          Builds run clean now.

          Show
          Laura Stewart added a comment - Based on the problems encountered with the build, I have prepared updated files (patch and html zip) for the developers guide. The problem was in the tagging for an external link. Builds run clean now.
          Hide
          Jean T. Anderson added a comment -

          Thanks, Laura. Build succeeds with derby1655_devguide3.diff, so committed to trunk revision 434236.

          Show
          Jean T. Anderson added a comment - Thanks, Laura. Build succeeds with derby1655_devguide3.diff, so committed to trunk revision 434236.
          Hide
          Laura Stewart added a comment -

          Updated the ref manual topics per comments received.
          The files included in this patch are:

          Filename Title Summary of update
          crefjdbc12657 JDBC Reference Added XML
          rrefbuiltchar CHAR Added XML
          rrefcreatefunctionstatement CREATE FUNCTION statement Added XML
          rrefcreateprocedurestatement CREATE PROCEDURE statement Added XML
          rrefdatefunc DATE Added XML
          rrefdayfunc DAY Added XML
          rrefdeclaretemptable DECLARE GLOBAL TEMPORARY TABLE statement Added XML
          rrefexcept71493 SQLState and error message reference Added XML error message
          rreffuncxmlexists XMLEXISTS operator New file
          rreffuncxmlparse XMLPARSE operator New file
          rreffuncxmlquery XMLQUERY operator New file
          rreffuncxmlserialize XMLSERIALIZE operator New file
          rrefhourfunc HOUR Added XML
          rrefjdbc20377 Mapping of java.sql.Types to SQL types Added XML
          rrefjdbcrefsqlxml java.sql.SQLXML New file
          rreflimitsxml XML limitations New file
          rrefminutefunc MINUTE Added XML
          rrefmonthfunc MONTH Added XML
          rrefsecondfunc SECOND Added XML
          rrefsqlj33562 CAST Added XML
          rrefsqlj58560 Data type assignments and comparison, sorting, and ordering Added XML
          rrefsqljtypexml XML data type New file
          rreftimefunc TIME Added XML
          rreftimestampfunc TIMESTAMP Added XML

          Show
          Laura Stewart added a comment - Updated the ref manual topics per comments received. The files included in this patch are: Filename Title Summary of update crefjdbc12657 JDBC Reference Added XML rrefbuiltchar CHAR Added XML rrefcreatefunctionstatement CREATE FUNCTION statement Added XML rrefcreateprocedurestatement CREATE PROCEDURE statement Added XML rrefdatefunc DATE Added XML rrefdayfunc DAY Added XML rrefdeclaretemptable DECLARE GLOBAL TEMPORARY TABLE statement Added XML rrefexcept71493 SQLState and error message reference Added XML error message rreffuncxmlexists XMLEXISTS operator New file rreffuncxmlparse XMLPARSE operator New file rreffuncxmlquery XMLQUERY operator New file rreffuncxmlserialize XMLSERIALIZE operator New file rrefhourfunc HOUR Added XML rrefjdbc20377 Mapping of java.sql.Types to SQL types Added XML rrefjdbcrefsqlxml java.sql.SQLXML New file rreflimitsxml XML limitations New file rrefminutefunc MINUTE Added XML rrefmonthfunc MONTH Added XML rrefsecondfunc SECOND Added XML rrefsqlj33562 CAST Added XML rrefsqlj58560 Data type assignments and comparison, sorting, and ordering Added XML rrefsqljtypexml XML data type New file rreftimefunc TIME Added XML rreftimestampfunc TIMESTAMP Added XML
          Hide
          Laura Stewart added a comment -

          Attaching updated files with patch #5 for the reference manual.
          Same files as listed for patch #4.

          Show
          Laura Stewart added a comment - Attaching updated files with patch #5 for the reference manual. Same files as listed for patch #4.
          Hide
          A B added a comment -

          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!

          Show
          A B added a comment - 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!
          Hide
          Laura Stewart added a comment -

          I believe that this patch (ref #6) fixes the problems with the links that were
          causing build problems. I ran both ant html.ref and ant pdf.ref and both ran cleanly.

          Please try this patch

          Show
          Laura Stewart added a comment - I believe that this patch (ref #6) fixes the problems with the links that were causing build problems. I ran both ant html.ref and ant pdf.ref and both ran cleanly. Please try this patch
          Hide
          Jean T. Anderson added a comment -

          Patch derby1655_ref6.diff committed to trunk revision 436862 (not merged to 10.2 branch yet).

          Show
          Jean T. Anderson added a comment - Patch derby1655_ref6.diff committed to trunk revision 436862 (not merged to 10.2 branch yet).
          Hide
          Jean T. Anderson added a comment -

          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?

          Show
          Jean T. Anderson added a comment - 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?
          Hide
          A B added a comment -

          I think all of the patches for this have been committed (at least, all of the doc changes that I suggested in DerbyXMLDoc_v2.html are, I believe, complete) so I'm clearing the "Patch Available" flag.

          At some point there has to be a release note w.r.t to XML saying, at the very least, what version of Xalan is recommended/tested for Derby. I'm not sure if that release note should be posted to this issue (as a doc thing) or to DERBY-688 (since that's where most of the 10.2 XML was completed). I guess my tendency is to lean toward the latter.

          Either way I think this issue can be "Resolved". If we decide later to put the release note here, we can do that before closing this issue. If we decide to put the release note into DERBY-688, we can close this issue when that decision is made.

          Show
          A B added a comment - I think all of the patches for this have been committed (at least, all of the doc changes that I suggested in DerbyXMLDoc_v2.html are, I believe, complete) so I'm clearing the "Patch Available" flag. At some point there has to be a release note w.r.t to XML saying, at the very least, what version of Xalan is recommended/tested for Derby. I'm not sure if that release note should be posted to this issue (as a doc thing) or to DERBY-688 (since that's where most of the 10.2 XML was completed). I guess my tendency is to lean toward the latter. Either way I think this issue can be "Resolved". If we decide later to put the release note here, we can do that before closing this issue. If we decide to put the release note into DERBY-688 , we can close this issue when that decision is made.
          Hide
          A B added a comment -

          Resolving per previous comment. Not closing, though, until the required release note(s) for XML have been posted to either this issue or DERBY-688.

          Show
          A B added a comment - Resolving per previous comment. Not closing, though, until the required release note(s) for XML have been posted to either this issue or DERBY-688 .
          Hide
          Rick Hillegas added a comment -

          Ported DERBY-1655 (436862, 434236, 434125, 433708, 433307, 433298) to 10.2 branch at subversion revision 436974.

          Show
          Rick Hillegas added a comment - Ported DERBY-1655 (436862, 434236, 434125, 433708, 433307, 433298) to 10.2 branch at subversion revision 436974.
          Hide
          A B added a comment -

          Decided to put the release note with DERBY-688, so I'm closing the issue. Additional comments on the documentation can be found on the Wiki for 10.2 doc review. Thanks for all the great work, Laura!

          Show
          A B added a comment - Decided to put the release note with DERBY-688 , so I'm closing the issue. Additional comments on the documentation can be found on the Wiki for 10.2 doc review. Thanks for all the great work, Laura!
          Hide
          Jean T. Anderson added a comment -

          Reopening to change fix version from 10.2.2.0 to 10.2.1.0. Jira will get updated with the right version number for the release version of 10.2.1.x.

          Show
          Jean T. Anderson added a comment - Reopening to change fix version from 10.2.2.0 to 10.2.1.0. Jira will get updated with the right version number for the release version of 10.2.1.x.

            People

            • Assignee:
              Laura Stewart
              Reporter:
              A B
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development