Migrate db starters, fixes

Author: andytael

docs/src/main/asciidoc/aqjms.adoc renamed to docs/src/main/asciidoc/db_starters.adoc

@@ -1,8 +1,10 @@
 // Copyright (c) 2024, Oracle and/or its affiliates.
 // Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
-[#AQ/JMS]
-== AQ/JMS
+[[database-spring-starters]]
+== Database Spring Boot Starters
+
+=== AQ/JMS
 
 This starter provides support for Oracle Transactional Event Queues (TxEventQ) and Oracle Advanced Queuing (AQ) as Java Message Service (JMS) providers. It depends on the Universal Connection Pool (UCP) starter.
 
@@ -28,13 +30,13 @@ dependencies {
 }
 ----
 
-=== Using AQ/JMS
+==== Using AQ/JMS
 
 To configure your application to use Oracle Transactional Event Queues or Oracle Advanced Queuing, you must annotate you application with the `@EnableJms` annotation, and create the
 two following beans:
 
 * A `JmsListenerContainerFactory<?>` bean, which can be created as shown in the following example. Note that you can override settings if you need to.  Also, note that the name of the method defines the name of the factory, which you will use when creating JMS listeners.
-* A `MessageConverter` bean to map objects of your class representing the payload into a text based format (like JSON) that can be used in the actual messages.  
+* A `MessageConverter` bean to map objects of your class representing the payload into a text based format (like JSON) that can be used in the actual messages.
 
 **Note**: Any queues or topics that you want to use must be pre-created in the database. See [Sample Code](https://www.oracle.com/database/advanced-queuing/#rc30sample-code) for
 examples.
@@ -71,19 +73,19 @@ public class JmsSampleApplication {
    // You could override some of Boot's defaults here if necessary
    return factory;
  }
-  
+
  @Bean
  public MessageConverter jacksonJmsMessageConverter() {
    MappingJackson2MessageConverter converter = new MappingJackson2MessageConverter();
    converter.setTargetType(MessageType.TEXT);
    converter.setTypeIdPropertyName("_type");
    return converter;
  }
-  
+
  public static void main(String[] args) {
    ConfigurableApplicationContext context = SpringApplication.run(JmsSampleApplication.class, args);
  }
-  
+
 }
 ----
 
@@ -117,3 +119,107 @@ public class Receiver {
 ----
 
 **Note**: The starter uses the configuration for `spring.datasource` as the connection details for the Oracle Database hosting the queues and topics. If you wish to use a different configuration, you must use a named configuration, for example `spring.datasource.txeventq` and use Java configuration and annotate the configuration with the standard Spring `@Qualifier` annotation, specifying the correct name, for example `txevevntq`.
+
+=== Universal Connection Pool
+
+This starter provides a connection (data source) to an Oracle Database using Universal Connection Pool, which provides an efficient way to use database connections.
+
+To add this starter to your project, add this Maven dependency:
+
+[source,xml]
+----
+<dependency>
+    <groupId>com.oracle.database.spring</groupId>
+    <artifactId>oracle-spring-boot-starter-ucp</artifactId>
+    <version>23.4.0</version>
+</dependency>
+----
+
+For Gradle projects, add this dependency:
+
+[source,subs="normal"]
+----
+dependencies {
+    implementation 'com.oracle.database.spring:oracle-spring-boot-starter-ucp:23.4.0'
+}
+----
+
+==== Using Universal Connection Pool
+
+An Oracle data source is injected into your application and can be used normally. You must configure the data source as shown below, and you should also add either Spring Data JDBC or Spring Data JPA to your project.
+
+To configure the data source, provide a `spring.datasource` object in your Spring `application.yaml`, or equivalent, as shown in the following example.  The `oracleucp` entry is optional, and can be used to fine tune the configuration of the connection pool, if desired.  For details of available settings, refer to the [JavaDoc](https://docs.oracle.com/en/database/oracle/oracle-database/21/jjuar/oracle/ucp/jdbc/UCPDataSource.html).
+
+[source,yaml]
+----
+spring:
+  jpa:
+    hibernate:
+      ddl-auto: validate
+    properties:
+      hibernate:
+        dialect: org.hibernate.dialect.OracleDialect
+        format_sql: true
+    show-sql: true
+  datasource:
+    url: jdbc:oracle:thin:@//myhost:1521/pdb1
+    username: username
+    password: password
+    driver-class-name: oracle.jdbc.OracleDriver
+    type: oracle.ucp.jdbc.PoolDataSource
+    oracleucp:
+      connection-factory-class-name: oracle.jdbc.pool.OracleDataSource
+      connection-pool-name: AccountConnectionPool
+      initial-pool-size: 15
+      min-pool-size: 10
+      max-pool-size: 30
+----
+
+The `spring.datasource.url` can be in the basic format (as previously shown), or in TNS format if your application uses Transparent Network Substrate (TNS).
+
+Note that the connections to the database use the `DEDICATED` server by default. If you wish to use `SHARED` or `POOLED`, you can append that to the basic URL, or add it to the TNS names entry. For example, to use database resident pooled connections, you would change the URL shown in the previous example to the following:
+
+[source,yaml]
+----
+  datasource:
+    url: jdbc:oracle:thin:@//myhost:1521/pdb1:pooled
+----
+
+If you are using TNS, add `server=pooled` to the `connect_data`. For example:
+
+[source,text]
+----
+mydb_tp = (description=
+ (retry_count=20)
+ (retry_delay=3)
+ (address=(protocol=tcps)(port=1521)(host=myhost))
+ (connect_data=(service_name=pdb1)(server=pooled))
+ (security=(ssl_server_dn_match=yes)))
+----
+
+If you prefer to use Java configuration, the data source can be configured as shown in the following example:
+
+[source,java]
+----
+import oracle.jdbc.pool.OracleDataSource;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import javax.sql.DataSource;
+import java.sql.SQLException;
+
+@Configuration
+public class DataSourceConfiguration {
+
+    @Bean
+    public DataSource dataSource() throws SQLException {
+        OracleDataSource dataSource = new OracleDataSource();
+        dataSource.setUser("account");
+        dataSource.setPassword("password");
+        dataSource.setURL("jdbc:oracle:thin:@//myhost:1521/pdb1");
+        dataSource.setDataSourceName("AccountConnectionPool");
+        return dataSource;
+    }
+}
+----
+

docs/src/main/asciidoc/index.adoc

@@ -34,9 +34,7 @@ include::streaming.adoc[]
 
 include::vault.adoc[]
 
-include::ucp.adoc[]
-
-include::aqjms.adoc[]
+include::db_starters.adoc[]
 
 == Configuration properties
 

docs/src/main/asciidoc/ucp.adoc

@@ -1,8 +1,8 @@
 // Copyright (c) 2024, Oracle and/or its affiliates.
 // Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
-[#vault]
-== Vault
+[#oci-vault]
+== OCI Vault
 
 https://docs.oracle.com/en-us/iaas/Content/KeyManagement/home.htm[Vault] can be used as a Spring property source for Vault secrets, and as an application bean for creating, updating, listing, and deleting secrets from a Vault.