Uploaded image for project: 'Derby'
  1. Derby
  2. DERBY-3983

User Guide documentation on the limitations of small-device support is stale

Details

    • Improvement
    • Status: Closed
    • Major
    • Resolution: Fixed
    • 10.5.1.1
    • 10.5.1.1
    • Documentation
    • None

    Description

      The limitations of Derby's feature set on small devices is sketched in the Reference Guide in a section titled "JDBC Package for Connected Device Configuration/Foundation Profile (JSR169)". This section should be expanded to include other unsupported features identified in DERBY-3966:

      1) Lack of XML datatype (can be remedied if the small device platform can be supplemented with some extra, freely available jar files)

      2) Non-blocking io

      3) Java EE resource manager support, including distributed transactions

      4) Principal-based security

      5) LDAP-based authentication

      6) SSL/TLS encryption

      7) Replication

      Attachments

        1. DERBY-3983.diff
          5 kB
          Camilla Haase
        2. DERBY-3983-2.diff
          5 kB
          Camilla Haase
        3. rrefjdbcjsr169.html
          8 kB
          Camilla Haase
        4. rrefjdbcjsr169.html
          8 kB
          Camilla Haase

        Issue Links

          Activity

            chaase3 Camilla Haase added a comment -

            Changed file now appears in latest alpha docs, so closing issue.

            chaase3 Camilla Haase added a comment - Changed file now appears in latest alpha docs, so closing issue.
            chaase3 Camilla Haase added a comment -

            Thanks very much, Rick.

            Committed patch DERBY-3983-2.diff to documentation trunk at revision 732111.

            chaase3 Camilla Haase added a comment - Thanks very much, Rick. Committed patch DERBY-3983 -2.diff to documentation trunk at revision 732111.

            Thanks, Kim. This looks good to me. +1

            rhillegas Richard N. Hillegas added a comment - Thanks, Kim. This looks good to me. +1
            chaase3 Camilla Haase added a comment -

            Thanks, Rick, that's very helpful. Here are a revised patch (DERBY-3983-2.diff) and output file with a better organization, I hope.

            chaase3 Camilla Haase added a comment - Thanks, Rick, that's very helpful. Here are a revised patch ( DERBY-3983 -2.diff) and output file with a better organization, I hope.

            Thanks, Kim. This is a big improvement. It looks good to me.

            I have given some more thought to your question about the distinction between JSR169's limitations and Derby's limitations. I don't think the distinction is interesting to the user. I think that the user merely wants to come away from our user guides understanding:

            1) What features always work on small devices (presumably anything not mentioned on this webpage)

            2) What features might work on small devices if you included the correct libraries (e.g., the XML datatype

            3) What features never work on small devices (all of the other stuff listed on the page). If we wanted to invest some effort in refining this list, we might be able to identify some optional packages which the user could ship with their small platform and which would move some of the items in (3) up into (2). That could be a follow-on JIRA.

            Thanks!

            rhillegas Richard N. Hillegas added a comment - Thanks, Kim. This is a big improvement. It looks good to me. I have given some more thought to your question about the distinction between JSR169's limitations and Derby's limitations. I don't think the distinction is interesting to the user. I think that the user merely wants to come away from our user guides understanding: 1) What features always work on small devices (presumably anything not mentioned on this webpage) 2) What features might work on small devices if you included the correct libraries (e.g., the XML datatype 3) What features never work on small devices (all of the other stuff listed on the page). If we wanted to invest some effort in refining this list, we might be able to identify some optional packages which the user could ship with their small platform and which would move some of the items in (3) up into (2). That could be a follow-on JIRA. Thanks!
            chaase3 Camilla Haase added a comment -

            Thanks for the clarifications, Rick and Knut Anders.

            Here is a patch, DERBY-3983.diff, that I hope addresses the issue. I've also attached the revised output file. Please let me know if changes are needed; I'm particularly uncertain about the distinction between what's in the JSR and what's specific to the Derby implementation (I added this in order to avoid just repeating "is not supported" over and over).

            chaase3 Camilla Haase added a comment - Thanks for the clarifications, Rick and Knut Anders. Here is a patch, DERBY-3983 .diff, that I hope addresses the issue. I've also attached the revised output file. Please let me know if changes are needed; I'm particularly uncertain about the distinction between what's in the JSR and what's specific to the Derby implementation (I added this in order to avoid just repeating "is not supported" over and over).

            Bullet 3 is actually just a special case of bullet 7 (DriverManager is not supported). Since DriverManager is not supported, there is no way to connect by URL, and then you cannot get a connection to the URL jdbc:default:connection.

            knutanders Knut Anders Hatlen added a comment - Bullet 3 is actually just a special case of bullet 7 (DriverManager is not supported). Since DriverManager is not supported, there is no way to connect by URL, and then you cannot get a connection to the URL jdbc:default:connection.

            Thanks, Kim. I think your change to bullet 3 sounds good. More about bullet 2: I would reword it as follows:

            "JSR169 does not support Java functions and procedures that use server-side JDBC, that is, routines declared with CONTAINS SQL, READS SQL DATA or MODIFIES SQL DATA clauses."

            rhillegas Richard N. Hillegas added a comment - Thanks, Kim. I think your change to bullet 3 sounds good. More about bullet 2: I would reword it as follows: "JSR169 does not support Java functions and procedures that use server-side JDBC, that is, routines declared with CONTAINS SQL, READS SQL DATA or MODIFIES SQL DATA clauses."
            chaase3 Camilla Haase added a comment -

            Thanks, Rick, that helps a lot, and I'm making progress. I'll just leave bullet 2 as is till it gets cleared up.

            Another question about bullet 3 – the topic refers to jdbc:default:connection as "the standard API used to obtain a connection", but it seems to me that jdbc:default:connection isn't an API but a connection URL. Would it be okay to make that change?

            chaase3 Camilla Haase added a comment - Thanks, Rick, that helps a lot, and I'm making progress. I'll just leave bullet 2 as is till it gets cleared up. Another question about bullet 3 – the topic refers to jdbc:default:connection as "the standard API used to obtain a connection", but it seems to me that jdbc:default:connection isn't an API but a connection URL. Would it be okay to make that change?

            Thanks for picking this up, Kim.

            Some of the existing bullets refer to limitations in the JSR 169 api itself (1 and 7), some refer to limitations in Derby's implementation (4, 5, 6). I am not sure about bullet 3 but it seems to me to be a Derby limitation that you can't configure an EmbeddedSimpleDataSource to hand back the current connection. I confess that I don't understand bullet 2: the CONTAINS SQL, READS SQL, and MODIFIES SQL DATA language comes from the SQL Standard and is not part of the JDBC api; I don't know what the reference to "parameters" means.

            As far as Xalan is concerned, you might reproduce what is said about the XML Data Type in the Reference Guide. Thanks.

            rhillegas Richard N. Hillegas added a comment - Thanks for picking this up, Kim. Some of the existing bullets refer to limitations in the JSR 169 api itself (1 and 7), some refer to limitations in Derby's implementation (4, 5, 6). I am not sure about bullet 3 but it seems to me to be a Derby limitation that you can't configure an EmbeddedSimpleDataSource to hand back the current connection. I confess that I don't understand bullet 2: the CONTAINS SQL, READS SQL, and MODIFIES SQL DATA language comes from the SQL Standard and is not part of the JDBC api; I don't know what the reference to "parameters" means. As far as Xalan is concerned, you might reproduce what is said about the XML Data Type in the Reference Guide. Thanks.
            chaase3 Camilla Haase added a comment -

            This looks like a fairly simple fix. One question: is there a substantive difference between the statements in bullet items 2 and 3 of http://db.apache.org/derby/docs/dev/ref/rrefjdbcjsr169.html that such-and-such "is not supported in JSR169" and the simpler statements elsewhere that such-and-such "is not supported"? That is, are the first two a statement about the JSR 169 spec and the others a statement about Derby's implementation?

            Would it be useful to mention Xalan specifically? I'm not sure quite what to say, though.

            I'll also change "JSR169" to "JSR 169" throughout.

            chaase3 Camilla Haase added a comment - This looks like a fairly simple fix. One question: is there a substantive difference between the statements in bullet items 2 and 3 of http://db.apache.org/derby/docs/dev/ref/rrefjdbcjsr169.html that such-and-such "is not supported in JSR169" and the simpler statements elsewhere that such-and-such "is not supported"? That is, are the first two a statement about the JSR 169 spec and the others a statement about Derby's implementation? Would it be useful to mention Xalan specifically? I'm not sure quite what to say, though. I'll also change "JSR169" to "JSR 169" throughout.

            Hey Knut, thanks for the quick feedback!

            1) It is true that elsewhere the user guides say that you need Xalan in order to use the XML datatype. And if you know that those libraries aren't included in CDC/FP 1.1, then you can deduce that the XML datatype is not supported on small devices. However, the point of this JIRA is to collect together all of the known limitations of our small device support so that users can figure out at a glance what's supported and what's not.

            2) It's true that we don't say anything about non-blocking io elsewhere in our user guides. I don't know whether that's good or bad. However, I think that it's worth pointing out that the small device implementation is different here.

            6) I agree with this improvement. We should state that in general, client/server features are not available on small devices. This includes SSL/TLS support and Replication.

            Thanks!

            rhillegas Richard N. Hillegas added a comment - Hey Knut, thanks for the quick feedback! 1) It is true that elsewhere the user guides say that you need Xalan in order to use the XML datatype. And if you know that those libraries aren't included in CDC/FP 1.1, then you can deduce that the XML datatype is not supported on small devices. However, the point of this JIRA is to collect together all of the known limitations of our small device support so that users can figure out at a glance what's supported and what's not. 2) It's true that we don't say anything about non-blocking io elsewhere in our user guides. I don't know whether that's good or bad. However, I think that it's worth pointing out that the small device implementation is different here. 6) I agree with this improvement. We should state that in general, client/server features are not available on small devices. This includes SSL/TLS support and Replication. Thanks!

            > 1) Lack of XML datatype (can be remedied if the small device platform can be supplemented with some extra, freely available jar files)

            I think we already document that a newer version of Xalan is needed for the XML support to work (regardless of small platforms). We should check that Xalan actually works on the small platforms before we claim that it's possible to make it work with the extra jars.

            > 2) Non-blocking io

            This is not visible to the users (same functionality on the small platforms, but possibly performance differences), so I don't think we need to document it.

            > 6) SSL/TLS encryption

            Only used by the client and the server, I think. It's probably sufficient to document that the client and the server don't run on the small platforms.

            knutanders Knut Anders Hatlen added a comment - > 1) Lack of XML datatype (can be remedied if the small device platform can be supplemented with some extra, freely available jar files) I think we already document that a newer version of Xalan is needed for the XML support to work (regardless of small platforms). We should check that Xalan actually works on the small platforms before we claim that it's possible to make it work with the extra jars. > 2) Non-blocking io This is not visible to the users (same functionality on the small platforms, but possibly performance differences), so I don't think we need to document it. > 6) SSL/TLS encryption Only used by the client and the server, I think. It's probably sufficient to document that the client and the server don't run on the small platforms.

            People

              chaase3 Camilla Haase
              rhillegas Richard N. Hillegas
              Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: