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

• Key: DERBY-3983
• Type: Improvement
• Status: Closed
• Resolution: Fixed
• Priority: Major
• Assignee: Kim Haase
• Reporter: Rick Hillegas
• Component/s: Documentation
• Affects Version/s: 10.5.1.1
• Fix Version/s: 10.5.1.1

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

Comments

[Knut Anders Hatlen]

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

[Rick Hillegas]

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!

[Kim Haase]

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.

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.

[Kim Haase]

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?

[Rick Hillegas]

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

[Knut Anders Hatlen]

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.

[Kim Haase]

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

[Rick Hillegas]

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!

[Kim Haase]

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

[Rick Hillegas]

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

[Kim Haase]

Thanks very much, Rick.

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

[Kim Haase]

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