From b6a88a28e3c9b1cfc3cbb7d3dc3044e52aecf054 Mon Sep 17 00:00:00 2001 From: Andy Tael Date: Wed, 22 Jan 2025 14:11:56 -0600 Subject: [PATCH] Cleaned up the Spring Starter page --- docs-source/spring/content/starters/_index.md | 22 +-- docs-source/spring/content/starters/aqjms.md | 127 ------------------ docs-source/spring/content/starters/ucp.md | 96 ------------- docs-source/spring/content/starters/wallet.md | 37 ----- docs-source/spring/data/menu/main.yaml | 7 - 5 files changed, 11 insertions(+), 278 deletions(-) delete mode 100644 docs-source/spring/content/starters/aqjms.md delete mode 100644 docs-source/spring/content/starters/ucp.md delete mode 100644 docs-source/spring/content/starters/wallet.md diff --git a/docs-source/spring/content/starters/_index.md b/docs-source/spring/content/starters/_index.md index 2bf079d14..d8d36d229 100644 --- a/docs-source/spring/content/starters/_index.md +++ b/docs-source/spring/content/starters/_index.md @@ -1,18 +1,18 @@ --- title: "Oracle Spring Boot Starters" -description: "Spring Boot Starters for Oracle Database" -keywords: "starter springboot spring development microservices development oracle database" +description: "Spring Boot Starters for Oracle Database and OCI" +keywords: "starter springboot spring development microservices development oracle database OCI" --- -Oracle provides a number of Spring Boot Starters that make it easy to use various Oracle technologies in Spring Boot projects. +## Spring Cloud Oracle -The Oracle Spring Boot Starters are available in [Maven Central](https://central.sonatype.com/namespace/com.oracle.database.spring) and include -the following starters. +Spring Cloud Oracle provides a number of Spring Boot Starters that make it easy to use various Oracle technologies in Spring Boot projects. -**Note**: The versioning of starters was originally in line with the matching Spring Boot version, but starting in November, 2023, the version -numbering scheme was changed to more closely align with Oracle Database version numbering. The 23.4.0 starter is supported for Spring Boot 3.0 -and later (including 3.1, 3.2). For Spring Boot 2.7.x users, use the matching 2.7.x version of the starter. +The Spring Cloud Oracle Starters are available in [Maven Central](https://central.sonatype.com/namespace/com.oracle.cloud.spring). -* [Oracle Spring Boot Starter for Universal Connection Pool](./ucp) -* [Oracle Spring Boot Starter for Wallet](./wallet) -* [Oracle Spring Boot Starter for AQ/JMS](./aqjms) +**Note**: The versioning of starters was originally in line with the matching Spring Boot version, but starting in November 2023, the version numbering scheme was changed to more closely align with Oracle Database version numbering. The 23.4.0 starter is supported for Spring Boot 3.0 and later (including 3.1, 3.2, 3.3 and 3.4). For Spring Boot 2.7.x users, use the matching 2.7.x version of the starter. + +For more information about Spring Cloud Oracle Starters: + +- The [GitHub repo](https://github.com/oracle/spring-cloud-oracle) +- The [Documentation](https://oracle.github.io/spring-cloud-oracle/latest/reference/html/index.html) diff --git a/docs-source/spring/content/starters/aqjms.md b/docs-source/spring/content/starters/aqjms.md deleted file mode 100644 index a2754a298..000000000 --- a/docs-source/spring/content/starters/aqjms.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "Oracle Spring Boot Starter for AQ/JMS" -description: "Spring Boot Starters for Advanced Queueing, Transactional Event Queues using JMS in Oracle Database" -keywords: "starter springboot jms aq txeventq queueing messaging asynchronous spring development microservices development oracle database" ---- - -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. - -**Note**: By default, the data Source and JMS Connection Factory that the starter injects into -your application share the same database transaction. This means that you can start a -transaction, read from a queue, perform an update operation, and then commit or rollback that -whole unit of work, including the message consumption. - -To add this starter to your project, add this Maven dependency: - -```xml - - com.oracle.database.spring - oracle-spring-boot-starter-aqjms - 23.4.0 - -``` - -For Gradle projects, add this dependency: - -```gradle -implementation 'com.oracle.database.spring:oracle-spring-boot-starter-aqjms:23.4.0' -``` - -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. - -**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. - -```java -package com.example.aqjms; - -import jakarta.jms.ConnectionFactory; - -import org.springframework.boot.SpringApplication; -import org.springframework.boot.autoconfigure.SpringBootApplication; -import org.springframework.boot.autoconfigure.jms.DefaultJmsListenerContainerFactoryConfigurer; -import org.springframework.context.ConfigurableApplicationContext; -import org.springframework.context.annotation.Bean; -import org.springframework.jms.annotation.EnableJms; -import org.springframework.jms.config.DefaultJmsListenerContainerFactory; -import org.springframework.jms.config.JmsListenerContainerFactory; -import org.springframework.jms.core.JmsTemplate; -import org.springframework.jms.support.converter.MappingJackson2MessageConverter; -import org.springframework.jms.support.converter.MessageConverter; -import org.springframework.jms.support.converter.MessageType; - -@SpringBootApplication -@EnableJms -public class JmsSampleApplication { - - @Bean - public JmsListenerContainerFactory myFactory(ConnectionFactory connectionFactory, - DefaultJmsListenerContainerFactoryConfigurer configurer) { - DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory(); - // This provides all Boot's defaults to this factory, including the message converter - configurer.configure(factory, connectionFactory); - // 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); - } - -} -``` - -To send a message to a JMS queue or topic, get an instance of the `JmsTemplate` from the Spring -Application context, and call the `convertAndSend()` method specifying the name of the queue or -topic, and providing the object to be converted and sent in the payload of the message, as shown -in the following example: - -```java -JmsTemplate jmsTemplate = context.getBean(JmsTemplate.class); -jmsTemplate.convertAndSend("mailbox", new Email(-1, "info@example.com", "Hello")); -``` - -To receive messages from a JMS queue or topic, create a method that takes your message class, for example `Email`, -as input. Annotate the method with the `@JmsListener` annotation, specifying the destination, that is the name of -the queue or topic, and the container factory name that you created earlier, as shown in the following example: - -```java -package com.example.aqjms; - -import org.springframework.jms.annotation.JmsListener; -import org.springframework.stereotype.Component; - -@Component -public class Receiver { - - @JmsListener(destination = "mailbox", containerFactory = "myFactory") - public void receiveMessage(Email email) { - System.out.println("Received <" + email + ">"); - } - -} -``` - -Note that 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 (as shown for the [UCP starter](./ucp)) and annotate the configuration with -the standard Spring `@Qualifier` annotation, specifying the correct name, for example `txevevntq`. diff --git a/docs-source/spring/content/starters/ucp.md b/docs-source/spring/content/starters/ucp.md deleted file mode 100644 index 0bb2ee9e0..000000000 --- a/docs-source/spring/content/starters/ucp.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "Oracle Spring Boot Starter for Universal Connection Pool" -description: "Spring Boot Starters for Universal Connection Pooling with Oracle Database" -keywords: "starter ucp oracle database springboot spring development microservices development" ---- - -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: - -```xml - - com.oracle.database.spring - oracle-spring-boot-starter-ucp - 23.4.0 - -``` - -For Gradle projects, add this dependency: - -```gradle -implementation 'com.oracle.database.spring:oracle-spring-boot-starter-ucp:23.4.0' -``` - -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). - -```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: account - password: account - 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: - -```yaml - datasource: - url: jdbc:oracle:thin:@//myhost:1521/pdb1:pooled -``` - -If you are using TNS, add `server=pooled` to the `connect_data`. For example: - -```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: - -```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("account"); - dataSource.setURL("jdbc:oracle:thin:@//myhost:1521/pdb1"); - dataSource.setDataSourceName("AccountConnectionPool"); - return dataSource; - } -} -``` diff --git a/docs-source/spring/content/starters/wallet.md b/docs-source/spring/content/starters/wallet.md deleted file mode 100644 index 026c6cf42..000000000 --- a/docs-source/spring/content/starters/wallet.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "Oracle Spring Boot Starter for Wallet" -description: "Spring Boot Starters for Oracle Database Wallet" -keywords: "starter wallet mtls oracle database springboot spring development microservices development" ---- - -This starter provides support for wallet-based authentication for Oracle Database connections. It depends -on the UCP starter. - -To add this starter to your project, add this Maven dependency: - -```xml - - com.oracle.database.spring - oracle-spring-boot-starter-wallet - 23.4.0 - -``` - -For Gradle projects, add this dependency: - -```gradle -implementation 'com.oracle.database.spring:oracle-spring-boot-starter-wallet:23.4.0' -``` - -You need to provide the wallet to your application. You can specify the location in the `spring.datasource.url` -as shown in the following example. - -```text -jdbc:oracle:thin:@mydb_tp?TNS_ADMIN=/oracle/tnsadmin -``` - -Note that the location specified in the `sqlnet.ora` must match the actual location of the file. - -If your service is deployed in Kubernetes, then the wallet should be placed in a Kubernetes secret which -is mounted into the pod at the location specified by the `TNS_ADMIN` parameter in the URL. - diff --git a/docs-source/spring/data/menu/main.yaml b/docs-source/spring/data/menu/main.yaml index 193dcb5a5..eede3e883 100644 --- a/docs-source/spring/data/menu/main.yaml +++ b/docs-source/spring/data/menu/main.yaml @@ -60,13 +60,6 @@ main: ref: "/development/envvars" - name: Spring Boot Starters ref: "/starters" - sub: - - name: "UCP" - ref: "/starters/ucp" - - name: "Wallet" - ref: "/starters/wallet" - - name: "AQ/JMS" - ref: "/starters/aqjms" - name: Infrastructure ref: "/infrastructure" sub: