From d1bec9e5f85a2b8274a7d145912b87b88b20f937 Mon Sep 17 00:00:00 2001 From: stewartbryson Date: Mon, 10 Apr 2023 11:48:00 -0400 Subject: [PATCH] Updated API docs. --- .../stewartbryson/ApplicationContainer.groovy | 6 +++--- .../io/github/stewartbryson/CreateCloneTask.groovy | 7 +++++-- .../io/github/stewartbryson/DropCloneTask.groovy | 7 +++++-- .../io/github/stewartbryson/SnowConfig.groovy | 8 ++++++++ .../groovy/io/github/stewartbryson/Snowflake.groovy | 3 +++ .../github/stewartbryson/SnowflakeExtension.groovy | 5 +++++ .../io/github/stewartbryson/SnowflakeJvm.groovy | 2 +- .../io/github/stewartbryson/SnowflakeSpec.groovy | 13 +++++++++++++ .../io/github/stewartbryson/SnowflakeTask.groovy | 1 + src/markdown/README.md | 2 +- 10 files changed, 45 insertions(+), 9 deletions(-) diff --git a/plugin/src/main/groovy/io/github/stewartbryson/ApplicationContainer.groovy b/plugin/src/main/groovy/io/github/stewartbryson/ApplicationContainer.groovy index 45c61a2..95f2bca 100644 --- a/plugin/src/main/groovy/io/github/stewartbryson/ApplicationContainer.groovy +++ b/plugin/src/main/groovy/io/github/stewartbryson/ApplicationContainer.groovy @@ -3,7 +3,7 @@ package io.github.stewartbryson import groovy.util.logging.Slf4j /** - * A domain container that allows for defining "Snowflake Applications." The plugin automatically creates the UDFs configured in this container. + * A domain container that allows for defining "Snowflake Applications." The plugin automatically creates the UDFs and procedures configured in this container. */ @Slf4j class ApplicationContainer { @@ -11,7 +11,7 @@ class ApplicationContainer { this.name = name } /** - * The name of the domain container. + * The name of the domain container, which equates to the name of the function or procedure. */ String name /** @@ -27,7 +27,7 @@ class ApplicationContainer { */ String type = 'function' /** - * The 'language' property of the UDF, currently only 'JAVA' is supported. DEFAULT: 'JAVA'. + * The 'language' property of the UDF. DEFAULT: 'JAVA'. */ String language = 'JAVA' /** diff --git a/plugin/src/main/groovy/io/github/stewartbryson/CreateCloneTask.groovy b/plugin/src/main/groovy/io/github/stewartbryson/CreateCloneTask.groovy index 8570bb1..98708fd 100644 --- a/plugin/src/main/groovy/io/github/stewartbryson/CreateCloneTask.groovy +++ b/plugin/src/main/groovy/io/github/stewartbryson/CreateCloneTask.groovy @@ -4,13 +4,16 @@ import groovy.util.logging.Slf4j import org.gradle.api.tasks.TaskAction /** - * A superclass for creating Gradle tasks that use ephemeral Snowflake clones. + * A Gradle task for creating ephemeral testing environments in Snowflake. */ @Slf4j abstract class CreateCloneTask extends SnowflakeTask { + /** + * Constructor. + */ CreateCloneTask() { - description = "A Cacheable Gradle task for creating ephemeral testing environments in Snowflake." + description = "A Gradle task for creating ephemeral testing environments in Snowflake." group = "verification" } diff --git a/plugin/src/main/groovy/io/github/stewartbryson/DropCloneTask.groovy b/plugin/src/main/groovy/io/github/stewartbryson/DropCloneTask.groovy index 4e9c1c6..9fb9248 100644 --- a/plugin/src/main/groovy/io/github/stewartbryson/DropCloneTask.groovy +++ b/plugin/src/main/groovy/io/github/stewartbryson/DropCloneTask.groovy @@ -4,13 +4,16 @@ import groovy.util.logging.Slf4j import org.gradle.api.tasks.TaskAction /** - * A superclass for creating Gradle tasks that use ephemeral Snowflake clones. + * A Gradle task for dropping ephemeral testing environments. */ @Slf4j abstract class DropCloneTask extends SnowflakeTask { + /** + * Constructor. + */ DropCloneTask() { - description = "A Cacheable Gradle task for dropping ephemeral testing environments in Snowflake." + description = "A Gradle task for dropping ephemeral testing environments in Snowflake." group = "verification" } diff --git a/plugin/src/main/groovy/io/github/stewartbryson/SnowConfig.groovy b/plugin/src/main/groovy/io/github/stewartbryson/SnowConfig.groovy index 7079466..993e3a9 100644 --- a/plugin/src/main/groovy/io/github/stewartbryson/SnowConfig.groovy +++ b/plugin/src/main/groovy/io/github/stewartbryson/SnowConfig.groovy @@ -3,6 +3,9 @@ package io.github.stewartbryson import groovy.util.logging.Slf4j import org.ini4j.Ini +/** + * A class for parsing a SnowSQL config file. + */ @Slf4j class SnowConfig { /** @@ -56,6 +59,11 @@ class SnowConfig { this.config = new File(config) } + /** + * Build a Map of connection properties for making a Snowflake connection. + * + * @return Snowflake connection properties. + */ Map getConnectionsProps() { //Map props1 = [account: "account", user: "user", password: "password"] Map props = [:] diff --git a/plugin/src/main/groovy/io/github/stewartbryson/Snowflake.groovy b/plugin/src/main/groovy/io/github/stewartbryson/Snowflake.groovy index 5affd4a..00eb797 100644 --- a/plugin/src/main/groovy/io/github/stewartbryson/Snowflake.groovy +++ b/plugin/src/main/groovy/io/github/stewartbryson/Snowflake.groovy @@ -6,6 +6,9 @@ import groovy.util.logging.Slf4j import java.sql.ResultSet import java.sql.Statement +/** + * A class that manages connecting to Snowflake, as well as providing information about that connection. Used by core plugin tasks as well as the {@link SnowflakeSpec} specification. + */ @Slf4j class Snowflake { /** diff --git a/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeExtension.groovy b/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeExtension.groovy index 8654cd4..3f188fc 100644 --- a/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeExtension.groovy +++ b/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeExtension.groovy @@ -16,6 +16,11 @@ class SnowflakeExtension { private String projectName private CiInformation ci + /** + * Constructor. + * + * @param project + */ SnowflakeExtension(Project project) { this.project = project this.projectName = project.rootProject.name diff --git a/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeJvm.groovy b/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeJvm.groovy index 5c94cf9..4d8d91f 100644 --- a/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeJvm.groovy +++ b/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeJvm.groovy @@ -15,7 +15,7 @@ import java.sql.ResultSet import java.sql.Statement /** - * A Cacheable Gradle task for publishing UDFs to Snowflake. + * A Cacheable Gradle task for publishing UDFs and procedures to Snowflake. */ @Slf4j @CacheableTask diff --git a/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeSpec.groovy b/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeSpec.groovy index 727aeba..e3b8335 100644 --- a/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeSpec.groovy +++ b/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeSpec.groovy @@ -1,8 +1,13 @@ package io.github.stewartbryson +import groovy.util.logging.Slf4j import spock.lang.Shared import spock.lang.Specification +/** + * A Spock specification for functional testing in Snowflake. + */ +@Slf4j class SnowflakeSpec extends Specification { @Shared @@ -14,6 +19,9 @@ class SnowflakeSpec extends Specification { @Shared private Snowflake snowflake = new Snowflake() + /** + * Built-in Spock method executed at the beginning of spec execution. + */ def setupSpec() { snowflake = new Snowflake(connection) if (ephemeral) { @@ -22,6 +30,11 @@ class SnowflakeSpec extends Specification { } } + /** + * Returns the first column of the first row of a SELECT statement. Useful for testing scalar function calls. + * @param sql + * @return The first column of the first row of a SELECT statement. + */ def selectSingleValue(String sql) { snowflake.getScalarValue(sql) } diff --git a/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeTask.groovy b/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeTask.groovy index f4a67f3..e8c61d1 100644 --- a/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeTask.groovy +++ b/plugin/src/main/groovy/io/github/stewartbryson/SnowflakeTask.groovy @@ -67,5 +67,6 @@ abstract class SnowflakeTask extends DefaultTask { log.warn "Reusing existing connection." snowflake = project.session } + snowflake.session } } diff --git a/src/markdown/README.md b/src/markdown/README.md index 170946d..e524062 100644 --- a/src/markdown/README.md +++ b/src/markdown/README.md @@ -46,7 +46,7 @@ features for teams already using Gradle in other areas of the organization. It has three basic modes: 1. Lightweight publishing to internal Snowflake stages using Snowpark. -2. Slightly heavier publishing using external Snowflake stages and auto-configuration of +2. Slightly heavier publishing using external Snowflake stages and autoconfiguration of the [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) plugin. 3. Publishing to Snowflake using external stages and custom configuration of the [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) plugin.