db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rhille...@apache.org
Subject svn commit: r750519 - in /db/derby/docs/trunk/src/ref: refderby.ditamap rrefcreatefunctionstatement.dita rrefcreateprocedurestatement.dita rrefsqljargmatching.dita
Date Thu, 05 Mar 2009 17:46:45 GMT
Author: rhillegas
Date: Thu Mar  5 17:46:44 2009
New Revision: 750519

URL: http://svn.apache.org/viewvc?rev=750519&view=rev
Log:
DERBY-4078: Document Derby's rules for matching routine signatures to the signatures of Java
methods.

Added:
    db/derby/docs/trunk/src/ref/rrefsqljargmatching.dita   (with props)
Modified:
    db/derby/docs/trunk/src/ref/refderby.ditamap
    db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita
    db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita

Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=750519&r1=750518&r2=750519&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Thu Mar  5 17:46:44 2009
@@ -446,6 +446,7 @@
 <topicref href="rrefsqljtypexml.dita" navtitle="XML data type"></topicref>
 </topicref>
 </topicref>
+<topicref href="rrefsqljargmatching.dita" navtitle="Argument matching"></topicref>
 <topicref href="rrefkeywords29722.dita" navtitle="SQL reserved words"></topicref>
 <topicref href="rrefsql9241891.dita" navtitle="Derby support for SQL-92 features ">
 </topicref>

Modified: db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita?rev=750519&r1=750518&r2=750519&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita Thu Mar  5 17:46:44 2009
@@ -33,7 +33,14 @@
 automatically gain the
 EXECUTE privilege on the function, and are able to grant this privilege to
 other users. The EXECUTE privileges cannot be revoked from the function and
-database owners.</p></section>
+database owners.</p>
+
+<p>
+For details on how Derby matches functions to Java methods,
+see <xref href="rrefsqljargmatching.dita#rrefsqljargmatching"></xref>.
+</p>
+
+</section>
 <refsyn><title>Syntax</title> <codeblock><b>CREATE FUNCTION
<i><xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionname"
 >function-name</xref></i> ( [ <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionparameter">FunctionParameter</xref
 > 

Modified: db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita?rev=750519&r1=750518&r2=750519&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita Thu Mar  5 17:46:44 2009
@@ -32,7 +32,14 @@
 <xref href="rrefattrib26867.dita#rrefattrib26867">database owner</xref>
 automatically gain the EXECUTE privilege
 on the procedure, and are able to grant this privilege to other users. The
-EXECUTE privileges cannot be revoked from the procedure and database owners.</p></section>
+EXECUTE privileges cannot be revoked from the procedure and database owners.</p>
+
+<p>
+For details on how Derby matches procedures to Java methods,
+see <xref href="rrefsqljargmatching.dita#rrefsqljargmatching"></xref>.
+</p>
+
+</section>
 <refsyn><title>Syntax</title><codeblock><b>CREATE PROCEDURE
<i><xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproprocedurename"
 >procedure-Name</xref></i> ( [ <xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproprocedureparameter">ProcedureParameter</xref
 >

Added: db/derby/docs/trunk/src/ref/rrefsqljargmatching.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljargmatching.dita?rev=750519&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljargmatching.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefsqljargmatching.dita Thu Mar  5 17:46:44 2009
@@ -0,0 +1,280 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<reference id="rrefsqljargmatching" xml:lang="en-us">
+<title>Argument matching</title>
+<prolog><metadata>
+<keywords><indexterm>Argument matching</indexterm><indexterm>CREATE
FUNCTION</indexterm><indexterm>CREATE PROCEDURE</indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+
+<p>
+When you declare a function or procedure using CREATE
+FUNCTION/PROCEDURE, Derby does not verify whether a matching Java
+method exists. Instead, Derby looks for a matching method only when you invoke the
+function or procedure in a later SQL statement. At that time, Derby
+searches for a public, static method having the class and method name
+declared in the EXTERNAL NAME clause of the earlier
+CREATE FUNCTION/PROCEDURE statement. Furthermore, the Java types of
+the method's arguments and return value must match the SQL types
+declared in the CREATE FUNCTION/PROCEDURE statement. The
+following may happen:
+</p>
+
+<ul>
+<li><b>Success</b> - If exactly one Java method matches, then Derby
+invokes it.</li>
+<li><b>Ambiguity</b> - Derby raises an error if more than one method matches.</li>
+<li><b>Failure</b> - Derby also raises an error if no method matches.</li>
+</ul>
+
+<p>
+In mapping SQL data types to Java data types, Derby considers the following
+kinds of matches:
+</p>
+
+<ul>
+<li><b>Primitive match</b> - Derby looks for a primitive Java type
+corresponding to the SQL type. For instance, SQL INTEGER matches Java <i>int</i>.</li>
+<li><b>Wrapper match</b> - Derby looks for a wrapper class
+in the <i>java.lang</i> or <i>java.sql</i> packages corresponding
to the SQL type. For instance, SQL
+INTEGER matches <i>java.lang.Integer</i>.</li>
+<li><b>Array match</b> - For OUT and INOUT procedure arguments, Derby
+looks for an array of the corresponding primitive or wrapper type. For
+instance, an OUT procedure argument of type SQL INTEGER matches
+<i>int[]</i> and <i>Integer[]</i>.</li>
+<li><b>ResultSet match</b> - If a procedure is declared to return <i>n</i>
+RESULT SETS, then Derby looks for a method whose last <i>n</i> arguments are
+of type <i>java.sql.ResultSet[]</i>.</li>
+</ul>
+
+<p>
+Derby resolves function and procedure invocations as follows:
+</p>
+
+<ul>
+<li><b>Function</b> - Derby looks for a method whose argument and
+return types are <i>primitive match</i>es or <i>wrapper match</i>es
for
+the function's SQL arguments and return value.</li>
+<li><b>Procedure</b> - Derby looks for a method which returns void and
+whose argument types match as follows:
+  <ul>
+  <li><i>IN</i> - Method arguments are
+  <i>primitive match</i>es or <i>wrapper match</i>es  for the
+  procedure's IN arguments.</li>
+  <li><i>OUT and INOUT</i> - Method arguments are
+  <i>array match</i>es  for the
+  procedure's OUT and INOUT arguments.</li>
+  </ul>
+In addition, if the procedure returns <i>n</i> RESULT SETS,
+then the last <i>n</i> arguments of the Java method must be of type 
+<i>java.sql.ResultSet[]</i>.</li>
+</ul>
+
+</section>
+
+<section>
+<title>Example of argument matching</title>
+
+<p>
+The following function...
+</p>
+
+<codeblock><b>
+CREATE FUNCTION TO_DEGREES
+( RADIANS DOUBLE )
+RETURNS DOUBLE
+PARAMETER STYLE JAVA
+NO SQL LANGUAGE JAVA
+EXTERNAL NAME 'acme.MathUtils.toDegrees'
+</b></codeblock>
+
+<p>
+...would match all of the following methods:
+</p>
+
+<codeblock><b>
+public static double toDegrees( double arg ) {...}
+public static Double toDegrees( double arg ) {...}
+public static double toDegrees( Double arg ) {...}
+public static Double toDegrees( Double arg ) {...}
+</b></codeblock>
+
+<p>
+Note that Derby would raise an exception if Derby found more than one matching method.
+</p>
+
+</section>
+
+
+<section><title>Mapping SQL data types to Java data types</title>
+
+<p>
+The following table shows how Derby maps specific SQL data types to Java
+data types:
+</p>
+
+<table>
+<title>SQL and Java type correspondence</title>
+
+<tgroup cols="3">
+<colspec colname="sqltype" colwidth="330*"/>
+<colspec colname="primitive" colwidth="330*"/>
+<colspec colname="wrapper" colwidth="330*"/>
+
+<thead>
+    <row>
+      <entry colname="sqltype" valign="top">SQL type</entry>
+      <entry colname="primitive" valign="top">Primitive match</entry>
+      <entry colname="wrapper" valign="top">Wrapper match</entry>
+    </row>
+</thead>
+
+<tbody>
+
+    <row>
+      <entry colname="sqltype">SMALLINT</entry>
+      <entry colname="primitive"><i>short</i></entry>
+      <entry colname="wrapper"><i>java.lang.Integer</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">INTEGER</entry>
+      <entry colname="primitive"><i>int</i></entry>
+      <entry colname="wrapper"><i>java.lang.Integer</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">BIGINT</entry>
+      <entry colname="primitive"><i>long</i></entry>
+      <entry colname="wrapper"><i>java.lang.Long</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">DECIMAL</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.math.BigDecimal</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">NUMERIC</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.math.BigDecimal</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">REAL</entry>
+      <entry colname="primitive"><i>float</i></entry>
+      <entry colname="wrapper"><i>java.lang.Float</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">DOUBLE</entry>
+      <entry colname="primitive"><i>double</i></entry>
+      <entry colname="wrapper"><i>java.lang.Double</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">FLOAT</entry>
+      <entry colname="primitive"><i>double</i></entry>
+      <entry colname="wrapper"><i>java.lang.Double</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">CHAR</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.lang.String</i></entry>
+    </row>
+
+    <row>
+      <entry colname="sqltype">VARCHAR</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.lang.String</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">LONG VARCHAR</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.lang.String</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">CHAR FOR BIT DATA</entry>
+      <entry colname="primitive"><i>byte[]</i></entry>
+      <entry colname="wrapper">-</entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">VARCHAR FOR BIT DATA</entry>
+      <entry colname="primitive"><i>byte[]</i></entry>
+      <entry colname="wrapper">-</entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">LONG VARCHAR FOR BIT DATA</entry>
+      <entry colname="primitive"><i>byte[]</i></entry>
+      <entry colname="wrapper">-</entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">CLOB</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.sql.Clob</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">BLOB</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.sql.Blob</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">DATE</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.sql.Date</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">TIME</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.sql.Time</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">TIMESTAMP</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper"><i>java.sql.Timestamp</i></entry>
+    </row>
+    
+    <row>
+      <entry colname="sqltype">XML</entry>
+      <entry colname="primitive">-</entry>
+      <entry colname="wrapper">-</entry>
+    </row>
+    
+</tbody>
+</tgroup>
+</table>
+
+</section>
+
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/ref/rrefsqljargmatching.dita
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message