Document the SQL Standard routine matching rules which Derby now supports

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

Description

The Reference Guide should explain the method resolution rules for functions and procedures. The full rules are described in the SignatureMapping.html webpage attached to DERBY-3652. At this point, Derby implements those rules for the datatypes which Derby supports, except for LOB arguments. That exception may be largely lifted as a result of the work being done on DERBY-4066.

Comments

[Rick Hillegas]

Attaching derby-4078-01-aa-refGuide.diff and a corresponding tarball of generated html pages: derby-4078-01-aa-refGuide.tar. This patch adds a new section to the Reference Guide, explaining how Derby matches SQL routines to Java methods.

Touches the following files:

A src/ref/rrefsqljargmatching.dita

This new section explains how Derby matches SQL signatures to Java signatures.


M src/ref/rrefcreateprocedurestatement.dita
M src/ref/rrefcreatefunctionstatement.dita

These pages now refer the reader to the signature matching section.


M src/ref/refderby.ditamap

Adds the new section to the table of contents.

[Kim Haase]

This is an excellent writeup, Rick. It's very clearly written. Just a few comments/questions --

In the last bullet item in second bullet list, you might wrap the occurrences of "n" in italics, since they are placeholders.

Example of argument matching: My first thought is, if the created function matches all of those methods, does that mean that such a declaration would cause an error when the function is invoked? Or maybe you could say "would match" instead of "matches", and then note that java.lang.Math provides only the first form of the method and therefore there's no ambiguity?

Is there a particular rationale for the order of types in the table? Just for consistency you might want to use the order in http://db.apache.org/derby/docs/dev/ref/rrefsqlj58560.html, which groups the types similarly but in a slightly different order.

I can see that it is a little hard to figure out where to place the new topic. I was thinking that it would make sense either to put it after the "Statements" section (where CREATE PROCEDURE and CREATE FUNCTION are introduced) or after the "Data types" section. But you probably have a reason for placing it where you did (between "JOIN operations" and "Queries").

[Rick Hillegas]

Thanks for the quick feedback, Kim. I have addressed all of your comments in the next rev of the patch, which I am attaching: derby-4078-01-ab-refGuide

[Kim Haase]

Thanks -- the changes look fine. Looks like you moved the topic outside the "SQL language reference" section to the top level along with "SQL reserved words" and "Derby support for SQL-92 features" -- which probably makes sense. It is sort of on the borderline.

[Rick Hillegas]

Thanks for the review, Kim. I have committed derby-4078-01-ab-refGuide at subversion revision 750519.

I don't have any clear theory about the best place to put this material in the Reference Guide. Feel free to move this section around if you have even a mild preference for some better location. Thanks.

[Kim Haase]

I think the Ref Guide location you chose is just fine, Rick.

+1 to resolve and close this issue.

[Rick Hillegas]

Thanks, Kim.