Derby
  1. Derby
  2. DERBY-4572

Documentation needed for user-defined types

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      DERBY-651 provides support for user-defined types, which now need to be documented.

      1. ASF.LICENSE.NOT.GRANTED--DERBY-4572.diff
        46 kB
        Kim Haase
      2. ASF.LICENSE.NOT.GRANTED--DERBY-4572.stat
        0.5 kB
        Kim Haase
      3. ASF.LICENSE.NOT.GRANTED--DERBY-4572.zip
        33 kB
        Kim Haase
      4. DERBY-4572-2.diff
        61 kB
        Kim Haase
      5. DERBY-4572-2.stat
        0.5 kB
        Kim Haase
      6. DERBY-4572-2.zip
        38 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Attaching DERBY-4572.diff, DERBY-4572.stat, and DERBY-4572.zip, an initial patch for the user-defined types documentation. Please let me know what changes are needed.

          In a couple of system table topics in the reference manual I took the opportunity to do some formatting cleanup in addition to adding the new content. Hope that's not too distracting.

          Show
          Kim Haase added a comment - Attaching DERBY-4572 .diff, DERBY-4572 .stat, and DERBY-4572 .zip, an initial patch for the user-defined types documentation. Please let me know what changes are needed. In a couple of system table topics in the reference manual I took the opportunity to do some formatting cleanup in addition to adding the new content. Hope that's not too distracting.
          Hide
          John added a comment -

          It would be preferable if a development howto about custom formatters for storing UDT types

          Show
          John added a comment - It would be preferable if a development howto about custom formatters for storing UDT types
          Hide
          Rick Hillegas added a comment -

          Thanks for the UDT documentation, Kim. It looks great. I have a couple comments:

          rrefsqljargmatching

          I can see that UDTs don't fit the current definition of either primitive or wrapper matches. To keep this simple (and not add another column to the table), I would recommend re-wording the definition of "wrapper match" as follows:

          "For builtin datatypes, Derby looks for a wrapper class in the java.lang or java.sql packages corresponding to the SQL type. For instance, SQL INTEGER matches java.lang.Integer. For a user-defined type (UDT), Derby looks for the UDT's external name class."

          Then in the table, put "-" in the Primitive Match column for the User-defined type row.

          rrefsqljcreatetype

          o I would reword the first sentence after the syntax block:

          "If the Java class does not implement java.io.Serializable, or if it is not public and visible on the classpath, then Derby raises an exception when preparing statements which refer to the user-defined type."

          o I would also recommend making the final paragraph more specific:

          "You can use JDBC setObject() and getObject() methods to store and retrieve values of user-defined types. For example:"

          And in the example, "getObject()" should be "rs.getObject()".

          rrefsqljgrant

          o I have misgivings about the following sentence. It might be fixed by just adding user-defined types to the list of schema objects. However, that list is getting unwieldy. Maybe the list could be collapsed to just "a schema object".

          "The syntax that you use for the GRANT statement depends on whether you are granting privileges to a table, a routine, or a sequence generator, or granting a role."

          o I recommend putting TYPE in all caps like the other keywords on this page:

          "GRANT USAGE ON TYPE [ schemaName. ] typeName TO grantees"

          o I think that the page needs an example of GRANT USAGE ON TYPE at the end.

          rrefsqljrevoke

          o I wonder if the syntax for revoking USAGE privilege on a sequence generator should be modified so that the sequence name looks like the type name in the follow-on syntax description. That would eliminate the need for the separate definition of sequenceName later on. Something like this:

          REVOKE USAGE ON SEQUENCE [ schemaName. ] sequenceName FROM grantees RESTRICT

          o I think that the page needs an example of REVOKE USAGE ON TYPE at the end.

          Show
          Rick Hillegas added a comment - Thanks for the UDT documentation, Kim. It looks great. I have a couple comments: rrefsqljargmatching I can see that UDTs don't fit the current definition of either primitive or wrapper matches. To keep this simple (and not add another column to the table), I would recommend re-wording the definition of "wrapper match" as follows: "For builtin datatypes, Derby looks for a wrapper class in the java.lang or java.sql packages corresponding to the SQL type. For instance, SQL INTEGER matches java.lang.Integer. For a user-defined type (UDT), Derby looks for the UDT's external name class." Then in the table, put "-" in the Primitive Match column for the User-defined type row. rrefsqljcreatetype o I would reword the first sentence after the syntax block: "If the Java class does not implement java.io.Serializable, or if it is not public and visible on the classpath, then Derby raises an exception when preparing statements which refer to the user-defined type." o I would also recommend making the final paragraph more specific: "You can use JDBC setObject() and getObject() methods to store and retrieve values of user-defined types. For example:" And in the example, "getObject()" should be "rs.getObject()". rrefsqljgrant o I have misgivings about the following sentence. It might be fixed by just adding user-defined types to the list of schema objects. However, that list is getting unwieldy. Maybe the list could be collapsed to just "a schema object". "The syntax that you use for the GRANT statement depends on whether you are granting privileges to a table, a routine, or a sequence generator, or granting a role." o I recommend putting TYPE in all caps like the other keywords on this page: "GRANT USAGE ON TYPE [ schemaName. ] typeName TO grantees" o I think that the page needs an example of GRANT USAGE ON TYPE at the end. rrefsqljrevoke o I wonder if the syntax for revoking USAGE privilege on a sequence generator should be modified so that the sequence name looks like the type name in the follow-on syntax description. That would eliminate the need for the separate definition of sequenceName later on. Something like this: REVOKE USAGE ON SEQUENCE [ schemaName. ] sequenceName FROM grantees RESTRICT o I think that the page needs an example of REVOKE USAGE ON TYPE at the end.
          Hide
          Kim Haase added a comment -

          Thanks, Rick! I'm working on these.

          About changing the syntax for sequence name to match that of type name – does a type name need to be a SQL92Identifier, as a sequence name does? That is stated explicitly in the sequence generator spec but not in the UDT one.

          If so I should change them both in parallel.

          Show
          Kim Haase added a comment - Thanks, Rick! I'm working on these. About changing the syntax for sequence name to match that of type name – does a type name need to be a SQL92Identifier, as a sequence name does? That is stated explicitly in the sequence generator spec but not in the UDT one. If so I should change them both in parallel.
          Hide
          Rick Hillegas added a comment -

          Thanks, Kim. Yes, a type name is a SQL92Identifier, just like a sequence name. Thanks.

          Show
          Rick Hillegas added a comment - Thanks, Kim. Yes, a type name is a SQL92Identifier, just like a sequence name. Thanks.
          Hide
          Kim Haase added a comment -

          Thanks, Rick! I've incorporated your comments (including modifying the CREATE SEQUENCE and DROP SEQUENCE syntax to be consistent with CREATE TYPE and DROP TYPE).

          Attaching DERBY-4572-2.diff, DERBY-4572-2.stat, and DERBY-4572-2.zip.

          With the rrefsqljargmatching topic, I decided that the insertion of the word "Derby" was a good opportunity to get rid of all the hard-coded "Derby"s from this topic and replace them with the phrase from the conrefs file. So there are a lot more diffs than before in this file.

          Show
          Kim Haase added a comment - Thanks, Rick! I've incorporated your comments (including modifying the CREATE SEQUENCE and DROP SEQUENCE syntax to be consistent with CREATE TYPE and DROP TYPE). Attaching DERBY-4572 -2.diff, DERBY-4572 -2.stat, and DERBY-4572 -2.zip. With the rrefsqljargmatching topic, I decided that the insertion of the word "Derby" was a good opportunity to get rid of all the hard-coded "Derby"s from this topic and replace them with the phrase from the conrefs file. So there are a lot more diffs than before in this file.
          Hide
          Rick Hillegas added a comment -

          Thanks, Kim. This new patch looks great to me. +1

          Show
          Rick Hillegas added a comment - Thanks, Kim. This new patch looks great to me. +1
          Hide
          Kim Haase added a comment -

          Thanks very much, Rick!

          Committed patch DERBY-4572-2.diff to documentation trunk at revision 935706.

          Show
          Kim Haase added a comment - Thanks very much, Rick! Committed patch DERBY-4572 -2.diff to documentation trunk at revision 935706.
          Hide
          Kim Haase added a comment -

          Closing, since documentation appears in Latest Alpha Manuals.

          Show
          Kim Haase added a comment - Closing, since documentation appears in Latest Alpha Manuals.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Kim Haase
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development