You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by pa...@apache.org on 2020/09/15 03:07:56 UTC
[groovy] 02/02: doco: add minimal DataSet section
This is an automated email from the ASF dual-hosted git repository.
paulk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git
commit 67b111ba888bab477ff93413c15a4866ae80dad6
Author: Paul King <pa...@asert.com.au>
AuthorDate: Tue Sep 15 13:07:04 2020 +1000
doco: add minimal DataSet section
---
subprojects/groovy-sql/build.gradle | 2 +-
.../groovy-sql/src/spec/doc/sql-userguide.adoc | 27 +++++++++++++-
.../{build.gradle => src/spec/test/Author.groovy} | 24 +++---------
.../spec/test/AuthorTestHelper.groovy} | 30 ++++++---------
.../groovy-sql/src/spec/test/SqlTest.groovy | 43 ++++++++++++++++++++++
5 files changed, 87 insertions(+), 39 deletions(-)
diff --git a/subprojects/groovy-sql/build.gradle b/subprojects/groovy-sql/build.gradle
index aa3474c..a17563e 100644
--- a/subprojects/groovy-sql/build.gradle
+++ b/subprojects/groovy-sql/build.gradle
@@ -29,7 +29,7 @@ dependencies {
tasks.withType(Test) {
excludes = ['**/*TestCase.class', '**/*$*.class']
// required for DataSet tests
- classpath = classpath + files('src/test/groovy')
+ classpath = classpath + files('src/test/groovy') + files('src/spec/test')
}
task moduleDescriptor(type: org.codehaus.groovy.gradle.WriteExtensionDescriptorTask) {
diff --git a/subprojects/groovy-sql/src/spec/doc/sql-userguide.adoc b/subprojects/groovy-sql/src/spec/doc/sql-userguide.adoc
index e7223f6..6f44f8e 100644
--- a/subprojects/groovy-sql/src/spec/doc/sql-userguide.adoc
+++ b/subprojects/groovy-sql/src/spec/doc/sql-userguide.adoc
@@ -475,4 +475,29 @@ include::../test/SqlTest.groovy[tags=sql_use_stored_fun_inout_parameter,indent=0
== Using DataSets
-(TBD)
+Groovy provides a gapi:groovy.sql.DataSet[] class which enhances the gapi:groovy.sql.Sql[] class
+with what can be thought of as mini https://en.wikipedia.org/wiki/Object-relational_mapping[ORM] functionality.
+Databases are accessed and queried using POGO fields and operators rather than JDBC-level API calls and RDBMS column names.
+
+So, instead of a query like:
+[source,groovy]
+----
+include::../test/SqlTest.groovy[tags=without_dataset,indent=0]
+----
+
+You can write code like this:
+
+[source,groovy]
+----
+include::../test/AuthorTestHelper.groovy[tags=with_dataset,indent=0]
+----
+
+Here we have a helper "domain" class:
+
+[source,groovy]
+----
+include::../test/Author.groovy[tags=dataset_class,indent=0]
+----
+
+Database access and manipulation involves creating or working with
+instances of the domain class.
\ No newline at end of file
diff --git a/subprojects/groovy-sql/build.gradle b/subprojects/groovy-sql/src/spec/test/Author.groovy
similarity index 51%
copy from subprojects/groovy-sql/build.gradle
copy to subprojects/groovy-sql/src/spec/test/Author.groovy
index aa3474c..84736ab 100644
--- a/subprojects/groovy-sql/build.gradle
+++ b/subprojects/groovy-sql/src/spec/test/Author.groovy
@@ -16,24 +16,10 @@
* specific language governing permissions and limitations
* under the License.
*/
-dependencies {
- api rootProject // Sql uses Closure...
- testImplementation group: 'org.hsqldb', name: 'hsqldb', version: '2.5.1'
-// uncomment to test with other databases (requires changes elsewhere too)
-// testImplementation 'com.h2database:h2:1.3.164'
-// testImplementation 'hsqldb:hsqldb:1.8.0.10'
- testImplementation project(':groovy-test')
-}
-
-// TODO move to parent build.gradle subprojects
-tasks.withType(Test) {
- excludes = ['**/*TestCase.class', '**/*$*.class']
-// required for DataSet tests
- classpath = classpath + files('src/test/groovy')
-}
-task moduleDescriptor(type: org.codehaus.groovy.gradle.WriteExtensionDescriptorTask) {
- extensionClasses = 'org.apache.groovy.sql.extensions.SqlExtensions'
+// tag::dataset_class[]
+class Author {
+ String firstname
+ String lastname
}
-
-compileJava.dependsOn moduleDescriptor
+// end::dataset_class[]
diff --git a/subprojects/groovy-sql/build.gradle b/subprojects/groovy-sql/src/spec/test/AuthorTestHelper.groovy
similarity index 51%
copy from subprojects/groovy-sql/build.gradle
copy to subprojects/groovy-sql/src/spec/test/AuthorTestHelper.groovy
index aa3474c..1c2d86c 100644
--- a/subprojects/groovy-sql/build.gradle
+++ b/subprojects/groovy-sql/src/spec/test/AuthorTestHelper.groovy
@@ -16,24 +16,18 @@
* specific language governing permissions and limitations
* under the License.
*/
-dependencies {
- api rootProject // Sql uses Closure...
- testImplementation group: 'org.hsqldb', name: 'hsqldb', version: '2.5.1'
-// uncomment to test with other databases (requires changes elsewhere too)
-// testImplementation 'com.h2database:h2:1.3.164'
-// testImplementation 'hsqldb:hsqldb:1.8.0.10'
- testImplementation project(':groovy-test')
-}
-// TODO move to parent build.gradle subprojects
-tasks.withType(Test) {
- excludes = ['**/*TestCase.class', '**/*$*.class']
-// required for DataSet tests
- classpath = classpath + files('src/test/groovy')
-}
+import groovy.sql.Sql
-task moduleDescriptor(type: org.codehaus.groovy.gradle.WriteExtensionDescriptorTask) {
- extensionClasses = 'org.apache.groovy.sql.extensions.SqlExtensions'
+class AuthorTestHelper {
+ static void testAuthorDataSet(Sql sql) {
+ // tag::with_dataset[]
+ def authorDS = sql.dataSet('Author')
+ def result = authorDS.findAll{ it.firstname > 'Dierk' }
+ .findAll{ it.lastname < 'Pragt' }
+ .sort{ it.lastname }
+ .reverse()
+ assert result.rows()*.firstname == ['Eric', 'Guillaume', 'Paul']
+ // end::with_dataset[]
+ }
}
-
-compileJava.dependsOn moduleDescriptor
diff --git a/subprojects/groovy-sql/src/spec/test/SqlTest.groovy b/subprojects/groovy-sql/src/spec/test/SqlTest.groovy
index fa12d25..7dc94de 100644
--- a/subprojects/groovy-sql/src/spec/test/SqlTest.groovy
+++ b/subprojects/groovy-sql/src/spec/test/SqlTest.groovy
@@ -504,6 +504,49 @@ class SqlTest extends GroovyTestCase {
'''
}
+ void testDataSets() {
+ assertScript '''
+ import groovy.sql.Sql
+ import groovy.sql.DataSet
+ def url = 'jdbc:hsqldb:mem:yourDB'
+ def user = 'sa'
+ def password = ''
+ def driver = 'org.hsqldb.jdbcDriver'
+ Sql.withInstance(url, user, password, driver) { sql ->
+ sql.execute """
+ DROP TABLE Author IF EXISTS
+ """
+ sql.execute """
+ CREATE TABLE Author (
+ id INTEGER GENERATED BY DEFAULT AS IDENTITY,
+ firstname VARCHAR(64),
+ lastname VARCHAR(64)
+ )
+ """
+
+ sql.withBatch(3) { stmt ->
+ stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Dierk', 'Koenig')"
+ stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Paul', 'King')"
+ stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Guillaume', 'Laforge')"
+ stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Eric', 'Milles')"
+ stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Cedric', 'Champeau')"
+ stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Erik', 'Pragt')"
+ stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Jon', 'Skeet')"
+ }
+ // tag::without_dataset[]
+ def qry = """SELECT * FROM Author
+ WHERE (firstname > ?)
+ AND (lastname < ?)
+ ORDER BY lastname DESC"""
+ def params = ['Dierk', 'Pragt']
+ def result = sql.rows(qry, params)
+ assert result*.firstname == ['Eric', 'Guillaume', 'Paul']
+ // end::without_dataset[]
+ AuthorTestHelper.testAuthorDataSet(sql)
+ }
+ '''
+ }
+
void testPagination() {
assertScript '''
import groovy.sql.Sql