Merge pull request #68 from oracle/atael-doc-updates

Java doc links, typos, and bugs

Author: andytael

docs/src/main/asciidoc/adb.adoc

@@ -8,7 +8,7 @@ https://docs.oracle.com/en/cloud/paas/atp-cloud/index.html[Autonomous Database]
 on self-driving Oracle Autonomous Database technology to deliver automated patching, upgrades, and tuning, including
 performing all routine database maintenance tasks while the system is running, without human intervention.
 
-Maven coordinates, using <<getting-started.adoc#bill-of-materials, Spring Cloud OCI BOM>>:
+Maven coordinates:
 
 [source,xml]
 ----
@@ -30,19 +30,12 @@ dependencies {
 === Using Autonomous Database
 
 The starter automatically configures and registers an `AutonomousDb` bean in the Spring application context.
-The `AutonomousDb` bean (link[Javadoc]) can be used to create an Autonomous Database, get details of an Autonomous Database,
+The `AutonomousDb` bean (https://oracle.github.io/spring-cloud-oci/{project-version}/javadocs/com/oracle/cloud/spring/adb/package-summary.html[Javadoc]) can be used to create an Autonomous Database, get details of an Autonomous Database,
 delete an Autonomous Database and generate a wallet for an Autonomous Database.
 
 [source,java]
 ----
 @Autowired
-private Queue queue;
-
-public void createQueue() {
-
-    String queueId = queue.createQueue("my-queue", <<compartmentId>>, <<deadLetterQueueDeliveryCount>>, <<retentionInSeconds>>);
-}
-@Autowired
 AutonomousDb autonomousDatabase;
 
 public void createAutonomousDatabase() {

docs/src/main/asciidoc/core.adoc

@@ -1,12 +1,12 @@
-// Copyright (c) 2023, Oracle and/or its affiliates.
+// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
 // Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
 [#spring-cloud-oci-core]
 == Spring Cloud OCI Core
 
 Spring Cloud OCI provides a Spring Boot starter to auto-configure the core components.
 
-Maven coordinates, using <<getting-started.adoc#bill-of-materials, Spring Cloud OCI BOM>>:
+Maven coordinates:
 
 [source,xml]
 ----

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/function.adoc

@@ -1,13 +1,13 @@
-// Copyright (c) 2023, Oracle and/or its affiliates.
+// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
 // Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
 [#cloud-function]
 == Cloud Functions
 
 https://docs.oracle.com/en-us/iaas/Content/Functions/Concepts/functionsoverview.htm[OCI Functions] is a fully managed, multi-tenant, highly scalable, on-demand, Functions-as-a-Service platform. It is built on enterprise-grade Oracle Cloud Infrastructure and powered by the Fn Project open source engine. Use OCI Functions when you want to focus on writing code to meet business needs. The Spring Cloud module for OCI Functions allows to invoke an OCI Function.
-A Spring Boot starter is provided to auto-configure the Function component.
+A Spring Boot starter is provided to autoconfigure the Function component.
 
-Maven coordinates, using <<getting-started.adoc#bill-of-materials, Spring Cloud OCI BOM>>:
+Maven coordinates:
 
 [source,xml]
 ----
@@ -29,7 +29,7 @@ dependencies {
 === Using Cloud Functions
 
 The starter automatically configures and registers a `Function` bean in the Spring application context.
-The `Function` bean (link[Javadoc]) can be used to invoke a function with parameter inputs 'functionOcid' and 'endpoint'
+The `Function` bean (https://oracle.github.io/spring-cloud-oci/{project-version}/javadocs/com/oracle/cloud/spring/function/package-summary.html[Javadoc]) can be used to invoke a function with parameter inputs 'functionOcid' and 'endpoint'
 
 [source,java]
 ----

docs/src/main/asciidoc/genai.adoc

@@ -6,7 +6,7 @@
 
 https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm[OCI Generative AI] is a fully managed service that provides a set of state-of-the-art, customizable large language models (LLMs) that cover a wide range of use cases, including chat and creating text embeddings.
 
-Maven coordinates, using <<getting-started.adoc#bill-of-materials, Spring Cloud OCI BOM>>:
+Maven coordinates:
 
 [source,xml]
 ----
@@ -28,12 +28,11 @@ dependencies {
 === Using Generative AI Chat
 
 The starter configures and registers a `ChatModel` bean in the Spring application context.
-The `ChatModel` bean (link[Javadoc]) can be used to interact with OCI Generative AI Chat Models.
+The `ChatModel` bean (https://oracle.github.io/spring-cloud-oci/{project-version}/javadocs/com/oracle/cloud/spring/genai/package-summary.html[Javadoc]) can be used to interact with OCI Generative AI Chat Models.
 
 [source,java]
 ----
 @Autowired
-@Autowired
 private ChatModel chatModel;
 
 public void embed() {
@@ -44,7 +43,7 @@ public void embed() {
 === Using Generative AI Embedding
 
 The starter configures and registers an `EmbeddingModel` bean in the Spring application context.
-The `EmbeddingModel` bean (link[Javadoc]) can be used to create text embeddings using OCI Generative AI Embedding Models.
+The `EmbeddingModel` bean (https://oracle.github.io/spring-cloud-oci/{project-version}/javadocs/com/oracle/cloud/spring/genai/package-summary.html[Javadoc]) can be used to create text embeddings using OCI Generative AI Embedding Models.
 
 [source,java]
 ----
@@ -82,7 +81,6 @@ The Spring Boot Starter for Oracle Cloud Generative AI provides the following co
 
 |===
 
-
 === Sample
 
 A sample application provided https://github.com/oracle/spring-cloud-oci/tree/main/spring-cloud-oci-samples/spring-cloud-oci-gen-ai-sample[here] contains the examples to demonstrates the usage of OCI Spring Cloud Generative AI module.

docs/src/main/asciidoc/index.adoc

@@ -6,37 +6,35 @@
 
 include::_attributes.adoc[]
 
-Documentation for version *{project-version}*
+Documentation for version *+{project-version}+*
 
 == Introduction
 
 Spring Cloud for OCI, part of the Spring Cloud umbrella project, eases the integration with hosted OCI Services. It offers a convenient way to interact with OCI provided services using well-known Spring idioms and APIs, such as storage resources. Developers can build their application around the hosted services without having to worry about infrastructure or maintenance.
 
 include::getting-started.adoc[]
 
+include::adb.adoc[]
+
 include::core.adoc[]
 
-include::storage.adoc[]
+include::function.adoc[]
 
-include::notifications.adoc[]
+include::logging.adoc[]
 
 include::genai.adoc[]
 
-include::logging.adoc[]
-
-include::function.adoc[]
+include::storage.adoc[]
 
-include::streaming.adoc[]
+include::notifications.adoc[]
 
 include::queues.adoc[]
 
-include::adb.adoc[]
+include::streaming.adoc[]
 
 include::vault.adoc[]
 
-include::ucp.adoc[]
-
-include::aqjms.adoc[]
+include::db_starters.adoc[]
 
 == Configuration properties
 

docs/src/main/asciidoc/logging.adoc

@@ -1,13 +1,13 @@
-// Copyright (c) 2023, Oracle and/or its affiliates.
+// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
 // Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
 [#cloud-logging]
 == Cloud Logging
 
 https://docs.oracle.com/en-us/iaas/Content/Logging/home.htm[OCI Logging] service is a highly scalable and fully managed single pane of glass for all the logs in your tenancy. Logging provides access to logs from OCI resources. These logs include critical diagnostic information that describes how resources are performing and being accessed. Use Logging to enable, manage, and search Audit, Service, and Custom logs. The Spring Cloud module for OCI Logging allows ingesting logs associated with a logId.
-A Spring Boot starter is provided to auto-configure the Logging component.
+A Spring Boot starter is provided to autoconfigure the Logging component.
 
-Maven coordinates, using <<getting-started.adoc#bill-of-materials, Spring Cloud OCI BOM>>:
+Maven coordinates::
 
 [source,xml]
 ----
@@ -29,7 +29,7 @@ dependencies {
 === Using Cloud Logging
 
 The starter automatically configures and registers a `Logging` bean in the Spring application context.
-The `Logging` bean (link[Javadoc]) can be used to ingest logs associated with a logId specified in the property `spring.cloud.oci.logging.logId` within the application configuration file
+The `Logging` bean (https://oracle.github.io/spring-cloud-oci/{project-version}/javadocs/com/oracle/cloud/spring/logging/package-summary.html[Javadoc]) can be used to ingest logs associated with a logId specified in the property `spring.cloud.oci.logging.logId` within the application configuration file
 
 [source,java]
 ----

docs/src/main/asciidoc/notifications.adoc

@@ -1,13 +1,13 @@
-// Copyright (c) 2023, Oracle and/or its affiliates.
+// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
 // Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
 [#cloud-notifications]
 == Cloud Notifications
 
 https://www.oracle.com/in/devops/notifications/[OCI Notifications] is a highly available, low latency publish/subscribe (pub/sub) service that sends alerts and messages to Oracle Cloud Functions, email, SMS, and message delivery partners, including Slack, PagerDuty and custom HTTPS endpoint. Spring Cloud module for Oracle Cloud Notifications allows you to create a Topic, then create and publish messages to multiple subscription types such as Oracle Cloud Functions, email, SMS, Slack, PagerDuty and custom HTTPS endpoint.
-A Spring Boot starter is provided to auto-configure the various Notification components.
+A Spring Boot starter is provided to autoconfigure the various Notification components.
 
-Maven coordinates, using <<getting-started.adoc#bill-of-materials, Spring Cloud OCI BOM>>:
+Maven coordinates:
 
 [source,xml]
 ----
@@ -29,7 +29,7 @@ dependencies {
 === Using Cloud Notifications
 
 The starter automatically configures and registers a `Notification` bean in the Spring application context.
-The `Notification` bean (link[Javadoc]) can be used to create a Topic, create, list, get a Subscription, and publish messages to the Subscriptions in a Topic.
+The `Notification` bean (https://oracle.github.io/spring-cloud-oci/{project-version}/javadocs/com/oracle/cloud/spring/notification/package-summary.html[Javadoc]) can be used to create a Topic, create, list, get a Subscription, and publish messages to the Subscriptions in a Topic.
 
 [source,java]
 ----

docs/src/main/asciidoc/queues.adoc

@@ -1,13 +1,13 @@
-// Copyright (c) 2023, Oracle and/or its affiliates.
+// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
 // Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
 [#cloud-queues]
 == Cloud Queues
 
 https://docs.oracle.com/en-us/iaas/Content/queue/home.htm[OCI Queues] is a highly available, low latency publish/subscribe (pub/sub) service, handles high volume transactional data that requires independently processed messages without loss or duplication. Spring Cloud module for Oracle Cloud Queues allows you to create a queue, get a queue, list queues, delete a queue, put messages, get messages, update messages and delete a message.
-A Spring Boot starter is provided to auto-configure the various Queue components.
+A Spring Boot starter is provided to autoconfigure the various Queue components.
 
-Maven coordinates, using <<getting-started.adoc#bill-of-materials, Spring Cloud OCI BOM>>:
+Maven coordinates:
 
 [source,xml]
 ----
@@ -29,7 +29,7 @@ dependencies {
 === Using Cloud Queues
 
 The starter automatically configures and registers a `Queue` bean in the Spring application context.
-The `Queue` bean (link[Javadoc]) can be used to create a queue, get a queue, list queues, delete a queue, put messages, get messages, update messages and delete a message.
+The `Queue` bean (https://oracle.github.io/spring-cloud-oci/{project-version}/javadocs/com/oracle/cloud/spring/queue/package-summary.html[Javadoc]) can be used to create a queue, get a queue, list queues, delete a queue, put messages, get messages, update messages and delete a message.
 
 [source,java]
 ----