doc: Add tutorial and code samples with Spring and Hikari

CHANGELOG.md

@@ -18,6 +18,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Sample code and tutorial for using the driver with:
   - [Spring and Hibernate](./examples/SpringHibernateExample/README.md)
   - [Spring and Wildfly](./examples/SpringWildflyExample/README.md)
+  - [Spring and Hikari](./examples/SpringBootHikariExample/README.md)
 
 ### :bug: Fixed
 - Pruned null connections in connection tracker plugins ([PR #461](https://github.com/awslabs/aws-advanced-jdbc-wrapper/pull/461))

examples/SpringBootHikariExample/README.md

@@ -0,0 +1,142 @@
+# Tutorial: Getting started with Spring Boot, Hikari, and the AWS Advanced JDBC Wrapper Driver
+
+In this tutorial, you will set up a Spring Boot application using Hikari and the AWS Advanced JDBC Driver.
+
+> Note: this tutorial was written using the following technologies:
+>    - Spring Boot 2.7.0
+>    - AWS Advanced JDBC Wrapper 2.2.0
+>    - Postgresql 42.5.4
+>    - Java 8
+
+
+## Step 1: Create a Gradle Project
+Create a Gradle Project with the following project hierarchy:
+```
+├───gradle
+│   └───wrapper
+│       ├───gradle-wrapper.jar
+│       └───gradle-wrapper.properties   
+├───build.gradle.kts
+├───gradlew
+└───src
+    └───main
+        ├───java
+        │   └───software
+        │       └───amazon
+        │           └───SpringBootHikariExampleApplication.java
+        └───resources
+            └───application.yml
+```
+When creating the `SpringBootHikariExampleApplication.java` class, add the following code to it.
+
+```java
+package software.amazon.SpringBootHikariExample;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class SpringBootHikariExampleApplication {
+  public static void main(String[] args) {
+    SpringApplication.run(SpringBootHikariExampleApplication.class, args);
+  }
+}
+```
+You may also use the Spring Initializr to create the boilerplate code:
+1. Go to https://start.spring.io/
+2. Select the Maven project and version 2.7.9 of the Spring Boot.
+3. Select Java version 8.
+4. Click Dependencies and select the following:
+    - Spring Web
+    - Spring Data JDBC
+    - PostgreSQL Driver
+
+## Step 2: Add the required Gradle Dependencies
+
+In the `build.gradle.kts` file, add the following dependencies.
+
+```kotlin
+dependencies {
+	implementation("org.springframework.boot:spring-boot-starter-data-jdbc")
+	implementation("org.springframework.boot:spring-boot-starter-web")
+	implementation(project(":aws-advanced-jdbc-wrapper"))
+	implementation("org.postgresql:postgresql:42.5.4")
+}
+```
+
+## Step 3: Configure the Datasource
+
+In the `application.yml` file, configure Hikari and AWS Advanced JDBC Wrapper Driver as its driver.
+
+```yaml
+spring:
+  datasource:
+    url: jdbc:aws-wrapper:postgresql://db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com:5432/database-name
+    username: some_username
+    password: some_password
+    driver-class-name: software.amazon.jdbc.Driver
+    hikari:
+      data-source-properties:
+        wrapperPlugins: failover,efm
+        wrapperDialect: aurora-pg
+      exception-override-class-name: software.amazon.jdbc.util.HikariCPSQLException
+```
+Note that in Spring Boot 2 and 3, Hikari is the default DataSource implementation. So, a bean explicitly specifying Hikari as a Datasource is not needed.
+
+Optionally, you may like to add in Hikari specific configurations like the following.
+```yaml
+spring:
+  datasource:
+    url: jdbc:aws-wrapper:postgresql://database-endpoint-url:5432/database-name
+    username: some_username
+    password: some_password
+    driver-class-name: software.amazon.jdbc.Driver
+    hikari:
+      data-source-properties:
+        wrapperPlugins: failover,efm
+        wrapperDialect: aurora-pg
+      exception-override-class-name: software.amazon.jdbc.util.HikariCPSQLException
+      max-lifetime: 840000
+      minimum-idle: 10
+      maximum-pool-size: 20
+      idle-timeout: 900000
+      read-only: true
+```
+
+
+## Step 4: Use JDBC Template 
+
+Create a new `ApiController` class like the following:
+
+```java
+package software.amazon.SpringBootHikariExample;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class ApiController {
+
+  @Autowired
+  private JdbcTemplate jdbcTemplate;
+
+  @GetMapping(value = "/select1")
+  public Integer getOne() {
+    return jdbcTemplate.queryForObject("SELECT 1;", Integer.class);
+  }
+}
+```
+
+The `@RestController` annotation on the class will allow methods in it to use annotations for mapping HTTP requests. 
+In this example, the `getOne()` method is annotated with `@GetMapping(value = "/select1")` which will route requests with the path `/select` to that method.
+Within the `getOne()` method, the `JdbcTemplate` is called to execute the query `SELECT 1;` and return its results.
+
+## Step 5: Run and call the application
+
+Start the application by running `./gradlew run` in the terminal. 
+
+Create an HTTP request to the application by running the following terminal command `curl http://localhost:8080/select1`.
+This will trigger the query statement `SELECT 1;` and return the results.  
+

examples/SpringBootHikariExample/build.gradle.kts

@@ -0,0 +1,28 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed 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
+ *:eq
+ * 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.
+ */
+
+plugins {
+	id("org.springframework.boot") version "2.7.0"
+	id("io.spring.dependency-management") version "1.1.0"
+}
+
+dependencies {
+	implementation("org.springframework.boot:spring-boot-starter-data-jdbc")
+	implementation("org.springframework.boot:spring-boot-starter-web")
+	implementation("org.postgresql:postgresql:42.5.4")
+    implementation(project(":aws-advanced-jdbc-wrapper"))
+
+}

examples/SpringBootHikariExample/gradle.properties

@@ -0,0 +1,16 @@
+#    Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#    Licensed 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.
+
+# Do not publish the Jar file for this subproject
+nexus.publish=false

examples/SpringBootHikariExample/src/main/java/software/amazon/SpringBootHikariExample/ApiController.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed 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.
+ */
+
+package software.amazon.SpringBootHikariExample;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class ApiController {
+
+  @Autowired
+  private JdbcTemplate jdbcTemplate;
+
+  @GetMapping(value = "/select1")
+  public Integer getOne() {
+    return jdbcTemplate.queryForObject("SELECT 1;", Integer.class);
+  }
+}

examples/SpringBootHikariExample/src/main/java/software/amazon/SpringBootHikariExample/SpringBootHikariExampleApplication.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed 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.
+ */
+
+package software.amazon.SpringBootHikariExample;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class SpringBootHikariExampleApplication {
+  public static void main(String[] args) {
+    SpringApplication.run(SpringBootHikariExampleApplication.class, args);
+  }
+}

examples/SpringBootHikariExample/src/main/resources/application.yml

@@ -0,0 +1,15 @@
+spring:
+  datasource:
+    url: jdbc:aws-wrapper:postgresql://db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com:5432/postgres
+    username: username
+    password: password
+    driver-class-name: software.amazon.jdbc.Driver
+    hikari:
+      data-source-properties:
+        wrapperPlugins: failover,efm
+        wrapperDialect: aurora-pg
+      max-lifetime: 840000
+      minimum-idle: 20
+      maximum-pool-size: 20
+      idle-timeout: 900000
+      read-only: true

examples/SpringHibernateExample/README.md

@@ -158,7 +158,7 @@ Configure Spring to use the AWS Advanced JDBC Driver as the default datasource.
 
    This example contains some very simple configurations for the IAM Authentication plugin, if you are interested in other configurations related to failover, please visit [the documentation for failover parameters](../../docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md#failover-parameters)
 2. Configure Hibernate dialect:
-   ```properties
+   ```yaml
    jpa:
     properties:
       hibernate:

examples/SpringWildflyExample/README.md

@@ -44,7 +44,7 @@ Create a Gradle project with the following project hierarchy:
               ├───amazon
               │   └───standalone.xml
 ```
-> Note: The wildfly directory will contain all the files you have downloaded in step 3. For simplicity, the diagram above only shows the files requiring modifications or need to be added.
+> Note: The wildfly directory will contain all the files that you will download in step 3. For simplicity, the diagram above only shows the files that either need to be added or require modifications.
 
 The file `Example.java` contains the following:
 ```java

settings.gradle.kts

@@ -23,7 +23,8 @@ include(
     "hikari",
     "driverexample",
     "springhibernate",
-    "springwildfly"
+    "springwildfly",
+    "springboothikariexample"
 )
 
 project(":aws-advanced-jdbc-wrapper").projectDir = file("wrapper")
@@ -32,6 +33,7 @@ project(":hikari").projectDir = file("examples/HikariExample")
 project(":driverexample").projectDir = file("examples/AWSDriverExample")
 project(":springhibernate").projectDir = file("examples/SpringHibernateExample")
 project(":springwildfly").projectDir = file("examples/SpringWildflyExample/spring")
+project(":springboothikariexample").projectDir = file("examples/SpringBootHikariExample")
 
 pluginManagement {
     plugins {