db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1402539 - in /db/derby/docs/trunk/src: devguide/ ref/ tools/
Date Fri, 26 Oct 2012 15:05:09 GMT
Author: chaase3
Date: Fri Oct 26 15:05:08 2012
New Revision: 1402539

URL: http://svn.apache.org/viewvc?rev=1402539&view=rev
Log:
DERBY-5926  Document user-defined aggregates (DERBY-672)

Created 2 new Reference Manual topics and 1 new Developer's Guide topic; modified 7 Reference
Manual topics and 1 Tools Guide topic.

Patch: DERBY-5926-3.diff

Added:
    db/derby/docs/trunk/src/devguide/cdevspecialuda.dita   (with props)
    db/derby/docs/trunk/src/ref/rrefsqljcreateaggregate.dita   (with props)
    db/derby/docs/trunk/src/ref/rrefsqljdropaggregate.dita   (with props)
Modified:
    db/derby/docs/trunk/src/devguide/derbydev.ditamap
    db/derby/docs/trunk/src/ref/refderby.ditamap
    db/derby/docs/trunk/src/ref/rrefsistabs28114.dita
    db/derby/docs/trunk/src/ref/rrefsistabssysperms.dita
    db/derby/docs/trunk/src/ref/rrefsqlj27781.dita
    db/derby/docs/trunk/src/ref/rrefsqlj33520.dita
    db/derby/docs/trunk/src/ref/rrefsqlj33923.dita
    db/derby/docs/trunk/src/ref/rrefsqljgrant.dita
    db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita
    db/derby/docs/trunk/src/tools/ctoolsgenddldb.dita

Added: db/derby/docs/trunk/src/devguide/cdevspecialuda.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialuda.dita?rev=1402539&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialuda.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialuda.dita Fri Oct 26 15:05:08 2012
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.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.
+-->
+<concept id="cdevspecialuda" xml:lang="en-us">
+<title>Programming user-defined aggregates</title>
+<shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> allows
+you to create custom aggregate operators, called user-defined aggregates (UDAs).
+</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>aggregates<indexterm>user-defined</indexterm></indexterm>
+<indexterm>user-defined aggregates<indexterm>programming</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<section><p>A UDA is a Java class that implements the
+<i>org.apache.derby.agg.Aggregator</i> interface.</p>
+<p>For example, the following class provides an aggregate that computes the
+median value from a list of objects. This is a generic class. Its parameter must
+be a linear (<i>Comparable</i>) type.</p>
+<codeblock>import java.util.ArrayList;
+import java.util.Collections;
+import org.apache.derby.agg.Aggregator;
+
+public class Median&lt;V extends Comparable&lt;V>> 
+        implements Aggregator&lt;V,V,Median&lt;V>>
+{
+    private ArrayList&lt;V> _values;
+
+    public Median() {}
+
+    public void init() { _values = new ArrayList&lt;V>(); }
+
+    public void accumulate( V value ) { _values.add( value ); }
+
+    public void merge( Median&lt;V> other )
+    { 
+        _values.addAll( other._values ); 
+    }
+
+    public V terminate()
+    {
+        Collections.sort( _values );
+
+        int count = _values.size();
+        
+        if ( count == 0 ) { return null; }
+        else { return _values.get( count/2 ); }
+    }
+}</codeblock>
+<p>Using this generic class, we can declare UDAs for all of the sortable
+<ph conref="../conrefs.dita#prod/productshortname"></ph> data types. For
+example:</p>
+<codeblock><b>create derby aggregate intMedian for int external name 'Median';
+create derby aggregate varcharMedian for varchar( 32672 ) external name
+  'Median';</b>
+</codeblock>
+<p>We can then use these UDAs just like built-in
+<ph conref="../conrefs.dita#prod/productshortname"></ph> aggregates:</p>
+<codeblock><b>create table intValues( a int, b int );
+create table varcharValues( a int, b varchar( 32672 ) );
+insert into intValues values ( 1, 1 ), ( 1, 10 ), ( 1, 100 ), 
+  ( 1, 1000 ), ( 2, 5 ), ( 2, 50 ), ( 2, 500 ), ( 2, 5000 );
+insert into varcharValues values ( 1, 'a' ), ( 1, 'ab' ), ( 1, 'abc' ), 
+  ( 2, 'a' ), ( 2, 'aa' ), ( 2, 'aaa' );
+
+select a, intMedian( b ) from intValues group by a;</b>
+<systemoutput>A          |2
+-----------------------
+1          |100
+2          |500
+</systemoutput>
+<b>select varcharMedian( b ) from varcharValues;</b>
+<systemoutput>1
+---
+aaa</systemoutput>
+</codeblock>
+</section>
+</conbody>
+</concept>

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

Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Fri Oct 26 15:05:08 2012
@@ -1728,6 +1728,8 @@ limitations under the License.
 </topicref>
 <topicref href="cdevspecialudt.dita" navtitle="Programming user-defined types">
 </topicref>
+<topicref href="cdevspecialuda.dita" navtitle="Programming user-defined aggregates">
+</topicref>
 </topicref>
 <topicref href="cdevconcepts19524.dita" navtitle="Controlling Derby application behavior">
 <topicref href="cdevconcepts38375.dita" navtitle="The JDBC Connection and Transaction
Model">

Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Fri Oct 26 15:05:08 2012
@@ -611,6 +611,8 @@ limitations under the License.
 <topicref href="rrefsqlj81859.dita" navtitle="ALTER TABLE statement"></topicref>
 <topicref href="rrefcallprocedure.dita" navtitle="CALL (PROCEDURE)"></topicref>
 <topicref collection-type="family" href="crefsqlj95081.dita" navtitle="CREATE statements">
+<topicref href="rrefsqljcreateaggregate.dita" navtitle="CREATE DERBY AGGREGATE statement">
+</topicref>
 <topicref href="rrefcreatefunctionstatement.dita" navtitle="CREATE FUNCTION statement">
 </topicref>
 <topicref href="rrefsqlj20937.dita" navtitle="CREATE INDEX statement"></topicref>
@@ -642,6 +644,8 @@ limitations under the License.
 </topicref>
 <topicref href="rrefsqlj35981.dita" navtitle="DELETE statement"></topicref>
 <topicref collection-type="family" href="crefsqlj80721.dita" navtitle="DROP statements">
+<topicref href="rrefsqljdropaggregate.dita" navtitle="DROP DERBY AGGREGATE statement">
+</topicref>
 <topicref href="rrefdropfunctionstatement.dita" navtitle="DROP FUNCTION statement">
 </topicref>
 <topicref href="rrefsqlj59893.dita" navtitle="DROP INDEX statement"></topicref>

Modified: db/derby/docs/trunk/src/ref/rrefsistabs28114.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsistabs28114.dita?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsistabs28114.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsistabs28114.dita Fri Oct 26 15:05:08 2012
@@ -20,8 +20,8 @@ limitations under the License.
 -->
 <reference id="rrefsistabs28114" xml:lang="en-us">
 <title>SYSALIASES system table</title>
-<shortdesc>The SYSALIASES table describes the procedures, functions, and
-user-defined types in the database.</shortdesc>
+<shortdesc>The SYSALIASES table describes the procedures, functions,
+user-defined types, and user-defined aggregates in the database.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>system tables<indexterm>SYSALIASES</indexterm></indexterm>
 <indexterm>aliases<indexterm>SYSALIASES system table</indexterm></indexterm>
@@ -61,8 +61,8 @@ user-defined types in the database.</sho
 <entry colname="2">VARCHAR</entry>
 <entry colname="3">128</entry>
 <entry colname="4">false</entry>
-<entry colname="5">Alias (in the case of a user-defined type, the name of the
-user-defined type)</entry>
+<entry colname="5">Alias (in the case of a user-defined type or user-defined
+aggregate, the name of the user-defined type or user-defined aggregate)</entry>
 </row>
 <row>
 <entry colname="1">SCHEMAID</entry>
@@ -84,7 +84,7 @@ user-defined type)</entry>
 <entry colname="3">1</entry>
 <entry colname="4">false</entry>
 <entry colname="5"><i>'F'</i> (function), <i>'P'</i> (procedure),
-<i>'A'</i> (user-defined type)</entry>
+<i>'A'</i> (user-defined type), <i>'G'</i> (user-defined aggregate)</entry>
 </row>
 <row>
 <entry colname="1">NAMESPACE</entry>
@@ -92,7 +92,7 @@ user-defined type)</entry>
 <entry colname="3">1</entry>
 <entry colname="4">false</entry>
 <entry colname="5"><i>'F'</i> (function), <i>'P'</i> (procedure),
-<i>'A'</i> (user-defined type)</entry>
+<i>'A'</i> (user-defined type), <i>'G'</i> (user-defined aggregate)</entry>
 </row>
 <row>
 <entry colname="1">SYSTEMALIAS</entry>

Modified: db/derby/docs/trunk/src/ref/rrefsistabssysperms.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsistabssysperms.dita?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsistabssysperms.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsistabssysperms.dita Fri Oct 26 15:05:08 2012
@@ -23,7 +23,7 @@ under the License.    
 <reference id="rrefsistabssysperms" xml:lang="en-us">
 <title>SYSPERMS system table</title>
 <shortdesc>The SYSPERMS table describes the USAGE permissions for
-sequence generators and user-defined types.</shortdesc>
+sequence generators, user-defined types, and user-defined aggregates.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>system tables<indexterm>SYSPERMS</indexterm></indexterm>
 <indexterm>sequence generators<indexterm>SYSPERMS system table</indexterm></indexterm>
@@ -65,8 +65,8 @@ key.</entry>
 <entry colname="2">VARCHAR</entry>
 <entry colname="3">36</entry>
 <entry colname="4">false</entry>
-<entry colname="5">The kind of object receiving the permission. The only valid
-values are <i>'SEQUENCE'</i> and <i>'TYPE'</i>.</entry>
+<entry colname="5">The kind of object receiving the permission. Valid values are
+<i>'SEQUENCE'</i>, <i>'TYPE'</i>, and <i>'DERBY AGGREGATE'</i>.</entry>
 </row>
 <row>
 <entry colname="1">OBJECTID</entry>
@@ -75,9 +75,9 @@ values are <i>'SEQUENCE'</i> and <i>'TYP
 <entry colname="4">false</entry>
 <entry colname="5">The UUID of the object receiving the permission. For
 sequence generators, the only valid values are SEQUENCEIDs in the
-SYS.SYSSEQUENCES table. For user-defined types, the only valid values are
-ALIASIDs in the SYS.SYSALIASES table if the SYSALIASES row describes a
-user-defined type.</entry>
+SYS.SYSSEQUENCES table. For user-defined types and user-defined aggregates, the
+only valid values are ALIASIDs in the SYS.SYSALIASES table if the SYSALIASES row
+describes a user-defined type or user-defined aggregate.</entry>
 </row>
 <row>
 <entry colname="1">PERMISSION</entry>
@@ -108,9 +108,10 @@ privilege was granted</entry>
 <entry colname="2">CHAR</entry>
 <entry colname="3">1</entry>
 <entry colname="4">false</entry>
-<entry colname="5">If the GRANTEE is the owner of the sequence generator or
-user-defined type, this value is <i>'Y'</i>. If the GRANTEE is not the owner
of
-the sequence generator or user-defined type, this value is <i>'N'</i>.</entry>
+<entry colname="5">If the GRANTEE is the owner of the sequence generator,
+user-defined type, or user-defined aggregate, this value is <i>'Y'</i>. If the
+GRANTEE is not the owner of the sequence generator, user-defined type, or
+user-defined aggregate, this value is <i>'N'</i>.</entry>
 </row>
 </tbody>
 </tgroup>

Modified: db/derby/docs/trunk/src/ref/rrefsqlj27781.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj27781.dita?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj27781.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj27781.dita Fri Oct 26 15:05:08 2012
@@ -26,8 +26,12 @@ limitations under the License.
 <refbody>
 <section> <p>MAX is an aggregate function that evaluates the maximum of an
 expression over a set of rows (see <xref href="rrefsqlj33923.dita#rrefsqlj33923"></xref>).
-MAX is allowed only on expressions that evaluate to built-in data types (including
-CHAR, VARCHAR, DATE, TIME, CHAR FOR BIT DATA, etc.).</p></section>
+MAX is allowed only on expressions that evaluate to indexable data types
+(specifically, those marked with a Y in the second table, "Comparisons allowed
+by <ph conref="../conrefs.dita#prod/productshortname"></ph>", in
+<xref href="rrefsqlj58560.dita#rrefsqlj58560"></xref>). This means that MAX
+cannot be used with expressions that evaluate to BLOB, CLOB, LONG VARCHAR, LONG
+VARCHAR FOR BIT DATA, XML, or user-defined types.</p></section>
 <refsyn><title>Syntax</title> <codeblock><b>MAX ( [ DISTINCT
| ALL ] <i>Expression</i> )</b></codeblock> <p>The
 DISTINCT and ALL qualifiers eliminate or retain duplicates, but 
 these qualifiers have no effect in a MAX expression. Only one DISTINCT aggregate

Modified: db/derby/docs/trunk/src/ref/rrefsqlj33520.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj33520.dita?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj33520.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj33520.dita Fri Oct 26 15:05:08 2012
@@ -26,8 +26,12 @@ limitations under the License.
 <refbody>
 <section> <p>MIN is an aggregate function that evaluates the minimum of
 an expression over a set of rows (see <xref href="rrefsqlj33923.dita#rrefsqlj33923"></xref>).
-MIN is allowed only on expressions that evaluate to built-in data types (including
-CHAR, VARCHAR, DATE, TIME, etc.).</p></section>
+MIN is allowed only on expressions that evaluate to indexable data types
+(specifically, those marked with a Y in the second table, "Comparisons allowed
+by <ph conref="../conrefs.dita#prod/productshortname"></ph>", in
+<xref href="rrefsqlj58560.dita#rrefsqlj58560"></xref>). This means that MIN
+cannot be used with expressions that evaluate to BLOB, CLOB, LONG VARCHAR, LONG
+VARCHAR FOR BIT DATA, XML, or user-defined types.</p></section>
 <refsyn><title>Syntax</title> <codeblock><b>MIN ( [ DISTINCT
| ALL ] <i>Expression</i> )</b></codeblock> <p>The
 DISTINCT and ALL qualifiers eliminate or retain duplicates, but these qualifiers
 have no effect in a MIN expression. Only one DISTINCT aggregate expression

Modified: db/derby/docs/trunk/src/ref/rrefsqlj33923.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj33923.dita?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj33923.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj33923.dita Fri Oct 26 15:05:08 2012
@@ -34,8 +34,21 @@ other built-in functions operate on a si
 on a set of values and reduce them to a single scalar value. Built-in aggregates
 can calculate the minimum, maximum, sum, count, and average of an expression
 over a set of values as well as count rows.</p></section>
-<section><p>The built-in aggregates can operate on the data types shown in
-the following table.</p>
+<section><p>In addition to the built-in aggregates,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> allows you to create
+custom aggregate operators, called user-defined aggregates (UDAs). For
+information on creating and removing UDAs, see
+<xref href="rrefsqljcreateaggregate.dita#rrefsqljcreateaggregate"></xref> and
+<xref href="rrefsqljdropaggregate.dita#rrefsqljdropaggregate"></xref>. See
+<xref href="rrefsqljgrant.dita#rrefsqljgrant"></xref> and
+<xref href="rrefsqljrevoke.dita#rrefsqljrevoke"></xref> for information on usage
+privileges for UDAs.</p>
+<p>For information on writing the Java classes that implement UDAs, see
+"Programming user-defined aggregates" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p>
+</section>
+<section><p>The built-in aggregates can operate on expressions that evaluate
to
+the data types shown in the following table.</p>
 <table frame="all">
 <title>Permitted data types for built-in aggregates</title>
 <desc>This table lists the data types that are valid for each of the built-in aggregates.</desc>
@@ -50,23 +63,23 @@ the following table.</p>
 </thead>
 <tbody>
 <row>
-<entry colname="1">COUNT</entry>
+<entry colname="1"><xref href="rrefsqlj38716.dita#rrefsqlj38716">COUNT</xref></entry>
 <entry colname="2">All types</entry>
 </row>
 <row>
-<entry colname="1">MIN</entry>
-<entry colname="2">Numeric built-in data types</entry>
+<entry colname="1"><xref href="rrefsqlj33520.dita#rrefsqlj33520">MIN</xref></entry>
+<entry colname="2">Data types that can be indexed</entry>
 </row>
 <row>
-<entry colname="1">MAX</entry>
-<entry colname="2">Numeric built-in data types</entry>
+<entry colname="1"><xref href="rrefsqlj27781.dita#rrefsqlj27781">MAX</xref></entry>
+<entry colname="2">Data types that can be indexed</entry>
 </row>
 <row>
-<entry colname="1">AVG</entry>
+<entry colname="1"><xref href="rrefsqlj32693.dita#rrefsqlj32693">AVG</xref></entry>
 <entry colname="2">Numeric built-in data types</entry>
 </row>
 <row>
-<entry colname="1">SUM</entry>
+<entry colname="1"><xref href="rrefsqlj13083.dita#rrefsqlj13083">SUM</xref></entry>
 <entry colname="2">Numeric built-in data types</entry>
 </row>
 </tbody>
@@ -103,14 +116,6 @@ HAVING c2 &gt;
     WHERE t2.y = SUM(t1.c3)) </b></codeblock></p></section>
 <section><p>A cursor declared on a <i>ResultSet</i> that includes
an aggregate
 in the outer query block is not updatable.</p></section>
-<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph>
supports
-the following aggregates:<ul>
-<li><xref href="rrefsqlj32693.dita#rrefsqlj32693"></xref></li>
-<li><xref href="rrefsqlj38716.dita#rrefsqlj38716"></xref></li>
-<li><xref href="rrefsqlj27781.dita#rrefsqlj27781"></xref></li>
-<li><xref href="rrefsqlj33520.dita#rrefsqlj33520"></xref></li>
-<li><xref href="rrefsqlj13083.dita#rrefsqlj13083"></xref></li>
-</ul></p></section>
 </refbody>
 </reference>
 

Added: db/derby/docs/trunk/src/ref/rrefsqljcreateaggregate.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljcreateaggregate.dita?rev=1402539&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljcreateaggregate.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefsqljcreateaggregate.dita Fri Oct 26 15:05:08 2012
@@ -0,0 +1,104 @@
+<?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="rrefsqljcreateaggregate" xml:lang="en-us">
+<title>CREATE DERBY AGGREGATE statement</title>
+<prolog><metadata>
+<keywords><indexterm>CREATE DERBY AGGREGATE statement</indexterm>
+<indexterm>SQL statements<indexterm>CREATE DERBY AGGREGATE</indexterm></indexterm>
+<indexterm>user-defined aggregates<indexterm>creating</indexterm></indexterm>
+<indexterm>aggregates<indexterm>user-defined</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section><p>The CREATE DERBY AGGREGATE statement creates a user-defined
+aggregate (UDA). A UDA is a custom aggregate operator.</p></section>
+<refsyn><title>Syntax</title>
+<codeblock><b>CREATE DERBY AGGREGATE [ <i><xref 
+href="rrefschemaname.dita#rrefschemaname">schemaName</xref>.</i> ] <i><xref
+href="crefsqlj34834.dita#crefsqlj34834">SQL92Identifier</xref></i>
+FOR <i>ValueDataType</i>
+[ RETURNS <i>ReturnDataType</i> ]
+EXTERNAL NAME <i>ClassNameString</i></b></codeblock>
+<p>The aggregate name is composed of an optional <i>schemaName</i> and
a
+<i>SQL92Identifier</i>. If a <i>schemaName</i> is not provided, the
current
+schema is the default schema. If a qualified aggregate name is specified, the
+schema name cannot begin with SYS.</p>
+<p>In general, UDAs live in the same namespace as one-argument user-defined
+functions (see
+<xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement"></xref>).
+A schema-qualified UDA name may not be the schema-qualified name of a
+one-argument user-defined function.</p>
+<p>An unqualified UDA name may not be the name of an aggregate defined in
+part 2 of the SQL Standard, section 10.9:</p>
+<codeblock>ANY
+AVG
+COLLECT
+COUNT
+EVERY
+FUSION
+INTERSECTION
+MAX
+MIN
+SOME
+STDDEV_POP
+STDDEV_SAMP
+SUM
+VAR_POP
+VAR_SAMP</codeblock>
+<p>In addition, an unqualified UDA name may not be the name of any of the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> built-in functions
+which take one argument.</p>
+<p>The <i>ValueDataType</i> can be any valid nullable
+<ph conref="../conrefs.dita#prod/productshortname"></ph> data type except for
+XML, including user-defined types.</p>
+<p>The <i>ReturnDataType</i> can be any valid nullable
+<ph conref="../conrefs.dita#prod/productshortname"></ph> data type except for
+XML. If the <i>ReturnDataType</i> is omitted, it defaults to be the same as
+<i>ValueDataType</i>.</p>
+<p>The <i>ClassNameString</i> is a single-quoted string. It is the full
name of
+a Java class which implements the <i>org.apache.derby.agg.Aggregator</i>
+interface. That contract is not checked until a statement is compiled which
+invokes the UDA.</p>
+<p>The owner of the schema where the UDA lives automatically gains the USAGE
+privilege on the UDA and can grant this privilege to other users and roles. Only
+the <xref href="rrefattrib26867.dita#rrefattrib26867">database owner</xref> and
+the owner of the UDA can grant these USAGE privileges. The USAGE privilege
+cannot be revoked from the schema owner. See
+<xref href="rrefsqljgrant.dita#rrefsqljgrant"></xref> and
+<xref href="rrefsqljrevoke.dita#rrefsqljrevoke"></xref> for more
+information.</p>
+</refsyn>
+<example><title>Examples</title>
+<codeblock><b>CREATE DERBY AGGREGATE mode FOR INT
+EXTERNAL NAME 'com.example.myapp.aggs.Mode';
+
+CREATE DERBY AGGREGATE types.maxPrice FOR PRICE
+EXTERNAL NAME 'com.example.myapp.types.PriceMaxer';
+
+CREATE DERBY AGGREGATE types.avgLength FOR VECTOR
+RETURNS DOUBLE
+EXTERNAL NAME 'com.example.myapp.types.VectorLength';</b></codeblock>
+<p>See "Programming user-defined aggregates" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph> for more details about
+creating and using user-defined aggregates.</p>
+</example>
+</refbody>
+</reference>

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

Added: db/derby/docs/trunk/src/ref/rrefsqljdropaggregate.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljdropaggregate.dita?rev=1402539&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljdropaggregate.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefsqljdropaggregate.dita Fri Oct 26 15:05:08 2012
@@ -0,0 +1,57 @@
+<?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="rrefsqljdropaggregate" xml:lang="en-us">
+<title>DROP DERBY AGGREGATE statement</title>
+<prolog><metadata>
+<keywords><indexterm>DROP DERBY AGGREGATE statement</indexterm>
+<indexterm>SQL statements<indexterm>DROP DERBY AGGREGATE</indexterm></indexterm>
+<indexterm>user-defined aggregates<indexterm>dropping</indexterm></indexterm>
+<indexterm>aggregates<indexterm>user-defined</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section><p>The DROP DERBY AGGREGATE statement removes a user-defined aggregate
+(UDA) that was created using a
+<xref href="rrefsqljcreateaggregate.dita#rrefsqljcreateaggregate"></xref>.</p>
+</section>
+<refsyn><title>Syntax</title>
+<codeblock><b>DROP DERBY AGGREGATE [ <i><xref 
+href="rrefschemaname.dita#rrefschemaname">schemaName</xref>.</i> ] <i><xref
+href="crefsqlj34834.dita#crefsqlj34834">SQL92Identifier</xref></i> RESTRICT</b></codeblock>
+<p>The aggregate name is composed of an optional <i>schemaName</i> and
a
+<i>SQL92Identifier</i>. If a <i>schemaName</i> is not provided, the
current
+schema is the default schema. If a qualified aggregate name is specified, the
+schema name cannot begin with SYS.</p>
+<p>The RESTRICT keyword is required. CASCADE semantics are not supported. That
+is, <ph conref="../conrefs.dita#prod/productshortname"></ph> will not track down
+and drop orphaned objects.</p>
+<p>Dropping a UDA implicitly drops all USAGE privileges that reference it. See
+<xref href="rrefsqljgrant.dita#rrefsqljgrant"></xref> and
+<xref href="rrefsqljrevoke.dita#rrefsqljrevoke"></xref> for more
+information.</p>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> raises an error
if a
+trigger or view references the UDA.</p>
+</refsyn>
+<example><title>Example</title>
+<codeblock><b>DROP DERBY AGGREGATE mode RESTRICT;</b></codeblock>
+</example>
+</refbody>
+</reference>

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

Modified: db/derby/docs/trunk/src/ref/rrefsqljgrant.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljgrant.dita?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljgrant.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqljgrant.dita Fri Oct 26 15:05:08 2012
@@ -40,7 +40,8 @@ from a table.</li>
 <li>Create a trigger on a table.</li>
 <li>Update data in a table or in a subset of columns in a table.</li>
 <li>Run a specified function or procedure.</li>
-<li>Use a sequence generator or a user-defined type.</li>
+<li>Use a sequence generator, a user-defined type, or a user-defined
+aggregate.</li>
 </ul></p><p>Before you issue a GRANT statement, check that the
 <codeph><xref href="rrefpropersqlauth.dita#rrefpropersqlauth">derby.database.sqlAuthorization</xref></codeph>
property
 is set to <codeph>true</codeph>. The <codeph>derby.database.sqlAuthorization</codeph>
property
@@ -85,6 +86,18 @@ information.</p>
 <i>SQL92Identifier</i>. If a <i>schemaName</i> is not provided, the
current
 schema is the default schema. If a qualified type name is specified, the schema
 name cannot begin with SYS.</p></section>
+<section id="grantaggsyn"><title>Syntax for user-defined aggregates</title>
+<codeblock><b>GRANT USAGE ON DERBY AGGREGATE [ <i><xref 
+href="rrefschemaname.dita#rrefschemaname">schemaName</xref>.</i> ] <i><xref
+href="crefsqlj34834.dita#crefsqlj34834">SQL92Identifier</xref></i> TO <i><xref
href="rrefsqljgrant.dita#rrefsqljgrant/grantgrantees">grantees</xref></i></b></codeblock>
+<p>In order to use a user-defined aggregate, you must have the USAGE privilege
+on it. This privilege can be granted to users and to roles. See 
+<xref href="rrefsqljcreateaggregate.dita#rrefsqljcreateaggregate"></xref> for
+more information.</p>
+<p>The aggregate name is composed of an optional <i>schemaName</i> and
a
+<i>SQL92Identifier</i>. If a <i>schemaName</i> is not provided, the
current
+schema is the default schema. If a qualified aggregate name is specified, the
+schema name cannot begin with SYS.</p></section>
 <section id="grantrolesyn"><title>Syntax for roles</title>
 <codeblock><b>GRANT <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i>
[ {, <i><xref
 href="rrefrolename.dita#rrefrolename">roleName</xref></i> }* ] TO <i><xref

@@ -181,7 +194,10 @@ following syntax:</p>
 <codeph>price</codeph> to the role <codeph>finance_role</codeph>,
use the
 following syntax:</p>
 <codeblock><b>GRANT USAGE ON TYPE price TO finance_role;</b></codeblock>
+<p>To grant the USAGE privilege on the user-defined aggregate
+<codeph>types.maxPrice</codeph> to the role <codeph>sales_role</codeph>,
use the
+following syntax:</p>
+<codeblock><b>GRANT USAGE ON DERBY AGGREGATE types.maxPrice TO sales_role;</b></codeblock>
 </example>
-
 </refbody>
 </reference>

Modified: db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita Fri Oct 26 15:05:08 2012
@@ -39,7 +39,8 @@ from a table.</li>
 <li>Create a trigger on a table.</li>
 <li>Update data in a table or in a subset of columns in a table.</li>
 <li>Run a specified routine (function or procedure).</li>
-<li>Use a sequence generator or a user-defined type.</li>
+<li>Use a sequence generator, a user-defined type, or a user-defined
+aggregate.</li>
 </ul></p><p>The
 <codeph><xref href="rrefpropersqlauth.dita#rrefpropersqlauth">derby.database.sqlAuthorization</xref></codeph>
 property must be set to <codeph>true</codeph> before you can use the GRANT
@@ -95,6 +96,21 @@ information.</p>
 <i>SQL92Identifier</i>. If a <i>schemaName</i> is not provided, the
current
 schema is the default schema. If a qualified type name is specified, the schema
 name cannot begin with SYS.</p></section>
+<section id="revokeaggsyn"><title>Syntax for user-defined aggregates</title>
+<codeblock><b>REVOKE USAGE ON DERBY AGGREGATE  [ <i><xref 
+href="rrefschemaname.dita#rrefschemaname">schemaName</xref>.</i> ] <i><xref
+href="crefsqlj34834.dita#crefsqlj34834">SQL92Identifier</xref></i> FROM <i><xref
href="rrefsqljrevoke.dita#rrefsqljrevoke/revokegrantees">grantees</xref></i>
RESTRICT</b></codeblock>
+<p>In order to use a user-defined aggregate, you must have the USAGE privilege
+on it. This privilege can be revoked from users and roles. Only RESTRICTed
+revokes are allowed. This means that the REVOKE statement cannot make a view or
+trigger unusable by its owner. The USAGE privilege cannot be revoked from the
+schema owner. See
+<xref href="rrefsqljcreateaggregate.dita#rrefsqljcreateaggregate"></xref> for
+more information.</p>
+<p>The aggregate name is composed of an optional <i>schemaName</i> and
a
+<i>SQL92Identifier</i>. If a <i>schemaName</i> is not provided, the
current
+schema is the default schema. If a qualified aggregate name is specified, the
+schema name cannot begin with SYS.</p></section>
 <section><title>Syntax for roles</title>
 <codeblock><b>REVOKE <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i>
[ {, <i><xref
 href="rrefrolename.dita#rrefrolename">roleName</xref></i> }* ] FROM <i><xref

@@ -270,6 +286,10 @@ following syntax:</p>
 <codeph>price</codeph> from the role <codeph>finance_role</codeph>,
use the
 following syntax:</p>
 <codeblock><b>REVOKE USAGE ON TYPE price FROM finance_role;</b></codeblock>
+<p>To revoke the USAGE privilege on the user-defined aggregate
+<codeph>types.maxPrice</codeph> from the role <codeph>sales_role</codeph>,
use
+the following syntax:</p>
+<codeblock><b>REVOKE USAGE ON DERBY AGGREGATE types.maxPrice FROM sales_role;</b></codeblock>
 </example>
 </refbody>
 </reference>

Modified: db/derby/docs/trunk/src/tools/ctoolsgenddldb.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/ctoolsgenddldb.dita?rev=1402539&r1=1402538&r2=1402539&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tools/ctoolsgenddldb.dita (original)
+++ db/derby/docs/trunk/src/tools/ctoolsgenddldb.dita Fri Oct 26 15:05:08 2012
@@ -34,6 +34,9 @@ generating the DDL for a database: 
 <li>Triggers</li>
 <li>Tables</li>
 <li>Views</li>
+<li>Roles</li>
+<li>User-defined types</li>
+<li>User-defined aggregates</li>
 </ul>
 <note>When dblook runs against a database that has jar files
 installed, it will create a new directory, called <codeph>DERBYJARS</codeph>,
within



Mime
View raw message