Skip to content

Commit 99d9856

Browse files
markxnelsonmarkxnelson
authored
Updated starters, with doc and CB3 updated to consume them (#785)
* spring boot starters 23.4.0 Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>
1 parent 9792073 commit 99d9856

File tree

14 files changed

+295
-15
lines changed

14 files changed

+295
-15
lines changed

‎cloudbank-v3/spring-apps-spring3/account/src/main/resources/application.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ spring:
1313
ddl-auto: validate
1414
properties:
1515
hibernate:
16-
dialect: org.hibernate.dialect.Oracle12cDialect
16+
dialect: org.hibernate.dialect.OracleDialect
1717
format_sql: true
1818
show-sql: true
1919
microtx:

‎cloudbank-v3/spring-apps-spring3/checks/src/main/resources/application.yaml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,7 @@ spring:
44
zipkin:
55
base-url: ${zipkin.base-url}
66

7-
oracle:
8-
aq:
7+
datasource:
98
url: ${spring.datasource.url}
109
username: ${spring.datasource.username}
1110
password: ${spring.datasource.password}

‎docs-source/spring/content/development/starters/_index.md

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs-source/spring/content/starters/_index.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: "Oracle Spring Boot Starters"
3+
---
4+
5+
Oracle provides a number of Spring Boot Starters that make it easy to use various Oracle technologies in Spring Boot projects.
6+
7+
The Oracle Spring Boot Starters are available in [Maven Central](https://central.sonatype.com/namespace/com.oracle.database.spring) and include
8+
the following starters.
9+
10+
**Note**: The versioning of starters was originally in line with the matching Spring Boot version, but starting in November, 2023, the version
11+
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
12+
and later (including 3.1, 3.2). For Spring Boot 2.7.x users, use the matching 2.7.x version of the starter.
13+
14+
15+
* [Oracle Spring Boot Starter for Universal Connection Pool](./ucp)
16+
* [Oracle Spring Boot Starter for Wallet](./wallet)
17+
* [Oracle Spring Boot Starter for AQ/JMS](./aqjms)

‎docs-source/spring/content/starters/aqjms.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: "Oracle Spring Boot Starter for AQ/JMS"
3+
---
4+
5+
This starter provides support for Oracle Transactional Event Queues (TxEventQ) and Oracle Advanced Queuing (AQ)
6+
as Java Message Service (JMS) providers. It depends on the Universal Connection Pool (UCP) starter.
7+
8+
**Note**: By default, the data Source and JMS Connection Factory that the starter injects into
9+
your application share the same database transaction. This means that you can start a
10+
transaction, read from a queue, perform an update operation, and then commit or rollback that
11+
whole unit of work, including the message consumption.
12+
13+
To add this starter to your project, add this Maven dependency:
14+
15+
```xml
16+
<dependency>
17+
<groupId>com.oracle.database.spring</groupId>
18+
<artifactId>oracle-spring-boot-starter-aqjms</artifactId>
19+
<version>23.4.0</version>
20+
</dependency>
21+
```
22+
23+
For Gradle projects, add this dependency:
24+
25+
```
26+
implementation 'com.oracle.database.spring:oracle-spring-boot-starter-aqjms:23.4.0'
27+
```
28+
29+
To configure your application to use Oracle Transactional Event Queues or Oracle Advanced
30+
Queuing, you must annotate you application with the `@EnableJms` annotation, and create the
31+
two following beans:
32+
33+
* A `JmsListenerContainerFactory<?>` bean, which can be created as shown in the following example. Note that
34+
you can override settings if you need to. Also, note that the name of the method defines
35+
the name of the factory, which you will use when creating JMS listeners.
36+
* A `MessageConverter` bean to map objects of your class representing the payload into a
37+
text based format (like JSON) that can be used in the actual messages.
38+
39+
**Note**: Any queues or topics that you want to use must be pre-created in the database.
40+
See [Sample Code](https://www.oracle.com/database/advanced-queuing/#rc30sample-code) for
41+
examples.
42+
43+
```java
44+
package com.example.aqjms;
45+
46+
import jakarta.jms.ConnectionFactory;
47+
48+
import org.springframework.boot.SpringApplication;
49+
import org.springframework.boot.autoconfigure.SpringBootApplication;
50+
import org.springframework.boot.autoconfigure.jms.DefaultJmsListenerContainerFactoryConfigurer;
51+
import org.springframework.context.ConfigurableApplicationContext;
52+
import org.springframework.context.annotation.Bean;
53+
import org.springframework.jms.annotation.EnableJms;
54+
import org.springframework.jms.config.DefaultJmsListenerContainerFactory;
55+
import org.springframework.jms.config.JmsListenerContainerFactory;
56+
import org.springframework.jms.core.JmsTemplate;
57+
import org.springframework.jms.support.converter.MappingJackson2MessageConverter;
58+
import org.springframework.jms.support.converter.MessageConverter;
59+
import org.springframework.jms.support.converter.MessageType;
60+
61+
@SpringBootApplication
62+
@EnableJms
63+
public class JmsSampleApplication {
64+
65+
@Bean
66+
public JmsListenerContainerFactory<?> myFactory(ConnectionFactory connectionFactory,
67+
DefaultJmsListenerContainerFactoryConfigurer configurer) {
68+
DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory();
69+
// This provides all Boot's defaults to this factory, including the message converter
70+
configurer.configure(factory, connectionFactory);
71+
// You could override some of Boot's defaults here if necessary
72+
return factory;
73+
}
74+
75+
@Bean
76+
public MessageConverter jacksonJmsMessageConverter() {
77+
MappingJackson2MessageConverter converter = new MappingJackson2MessageConverter();
78+
converter.setTargetType(MessageType.TEXT);
79+
converter.setTypeIdPropertyName("_type");
80+
return converter;
81+
}
82+
83+
public static void main(String[] args) {
84+
ConfigurableApplicationContext context = SpringApplication.run(JmsSampleApplication.class, args);
85+
}
86+
87+
}
88+
```
89+
90+
To send a message to a JMS queue or topic, get an instance of the `JmsTemplate` from the Spring
91+
Application context, and call the `convertAndSend()` method specifying the name of the queue or
92+
topic, and providing the object to be converted and sent in the payload of the message, as shown
93+
in the following example:
94+
95+
```java
96+
JmsTemplate jmsTemplate = context.getBean(JmsTemplate.class);
97+
jmsTemplate.convertAndSend("mailbox", new Email(-1, "info@example.com", "Hello"));
98+
```
99+
100+
To receive messages from a JMS queue or topic, create a method that takes your message class, for example `Email`,
101+
as input. Annotate the method with the `@JmsListener` annotation, specifying the destination, that is the name of
102+
the queue or topic, and the container factory name that you created earlier, as shown in the following example:
103+
104+
```java
105+
package com.example.aqjms;
106+
107+
import org.springframework.jms.annotation.JmsListener;
108+
import org.springframework.stereotype.Component;
109+
110+
@Component
111+
public class Receiver {
112+
113+
@JmsListener(destination = "mailbox", containerFactory = "myFactory")
114+
public void receiveMessage(Email email) {
115+
System.out.println("Received <" + email + ">");
116+
}
117+
118+
}
119+
```
120+
121+
Note that the starter uses the configuration for `spring.datasource` as the connection
122+
details for the Oracle Database hosting the queues and topics. If you wish to use a different
123+
configuration, you must use a named configuration, for example `spring.datasource.txeventq` and use Java
124+
configuration (as shown for the [UCP starter](./ucp)) and annotate the configuration with
125+
the standard Spring `@Qualifier` annotation, specifying the correct name, for example `txevevntq`.
126+

‎docs-source/spring/content/starters/ucp.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
title: "Oracle Spring Boot Starter for Universal Connection Pool"
3+
---
4+
5+
This starter provides a connection (data source) to an Oracle Database using Universal Connection Pool, which provides an efficient way
6+
to use database connections.
7+
8+
To add this starter to your project, add this Maven dependency:
9+
10+
```xml
11+
<dependency>
12+
<groupId>com.oracle.database.spring</groupId>
13+
<artifactId>oracle-spring-boot-starter-ucp</artifactId>
14+
<version>23.4.0</version>
15+
</dependency>
16+
```
17+
18+
For Gradle projects, add this dependency:
19+
20+
```
21+
implementation 'com.oracle.database.spring:oracle-spring-boot-starter-ucp:23.4.0'
22+
```
23+
24+
An Oracle data source is injected into your application and can be used normally. You must configure
25+
the data source as shown below, and you should also add either Spring Data JDBC or Spring Data JPA to your project.
26+
27+
To configure the data source, provide a `spring.datasource` object in your Spring `application.yaml`,
28+
or equivalent, as shown in the following example. The `oracleucp` entry is optional, and can be used
29+
to fine tune the configuration of the connection pool, if desired. For details of available settings,
30+
refer to the [JavaDoc](https://docs.oracle.com/en/database/oracle/oracle-database/21/jjuar/oracle/ucp/jdbc/UCPDataSource.html).
31+
32+
```yaml
33+
spring:
34+
jpa:
35+
hibernate:
36+
ddl-auto: validate
37+
properties:
38+
hibernate:
39+
dialect: org.hibernate.dialect.OracleDialect
40+
format_sql: true
41+
show-sql: true
42+
datasource:
43+
url: jdbc:oracle:thin:@//myhost:1521/pdb1
44+
username: account
45+
password: account
46+
driver-class-name: oracle.jdbc.OracleDriver
47+
type: oracle.ucp.jdbc.PoolDataSource
48+
oracleucp:
49+
connection-factory-class-name: oracle.jdbc.pool.OracleDataSource
50+
connection-pool-name: AccountConnectionPool
51+
initial-pool-size: 15
52+
min-pool-size: 10
53+
max-pool-size: 30
54+
```
55+
56+
The `spring.datasource.url` can be in the basic format (as previously shown), or in TNS format if your application
57+
uses Transparent Network Substrate (TNS).
58+
59+
Note that the connections to the database use the `DEDICATED` server by default. If you wish to use `SHARED`
60+
or `POOLED`, you can append that to the basic URL, or add it to the TNS names entry. For example, to use
61+
database resident pooled connections, you would change the URL shown in the previsou example to the following:
62+
63+
```yaml
64+
datasource:
65+
url: jdbc:oracle:thin:@//myhost:1521/pdb1:pooled
66+
```
67+
68+
If you are using TNS, add `server=pooled` to the `connect_data`. For example:
69+
70+
```
71+
mydb_tp = (description=
72+
(retry_count=20)
73+
(retry_delay=3)
74+
(address=(protocol=tcps)(port=1521)(host=myhost))
75+
(connect_data=(service_name=pdb1)(server=pooled))
76+
(security=(ssl_server_dn_match=yes)))
77+
```
78+
79+
If you prefer to use Java configuration, the data source can be configured as shown in the following example:
80+
81+
```java
82+
import oracle.jdbc.pool.OracleDataSource;
83+
import org.springframework.context.annotation.Bean;
84+
import org.springframework.context.annotation.Configuration;
85+
86+
import javax.sql.DataSource;
87+
import java.sql.SQLException;
88+
89+
@Configuration
90+
public class DataSourceConfiguration {
91+
92+
@Bean
93+
public DataSource dataSource() throws SQLException {
94+
OracleDataSource dataSource = new OracleDataSource();
95+
dataSource.setUser("account");
96+
dataSource.setPassword("account");
97+
dataSource.setURL("jdbc:oracle:thin:@//myhost:1521/pdb1");
98+
dataSource.setDataSourceName("AccountConnectionPool");
99+
return dataSource;
100+
}
101+
}
102+
```
103+

‎docs-source/spring/content/starters/wallet.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: "Oracle Spring Boot Starter for Wallet"
3+
---
4+
5+
This starter provides support for wallet-based authentication for Oracle Database connections. It depends
6+
on the UCP starter.
7+
8+
To add this starter to your project, add this Maven dependency:
9+
10+
```xml
11+
<dependency>
12+
<groupId>com.oracle.database.spring</groupId>
13+
<artifactId>oracle-spring-boot-starter-wallet</artifactId>
14+
<version>23.4.0</version>
15+
</dependency>
16+
```
17+
18+
For Gradle projects, add this dependency:
19+
20+
```
21+
implementation 'com.oracle.database.spring:oracle-spring-boot-starter-wallet:23.4.0'
22+
```
23+
24+
You need to provide the wallet to your application. You can specify the location in the `spring.datasource.url`
25+
as shown in the following example.
26+
27+
```
28+
jdbc:oracle:thin:@mydb_tp?TNS_ADMIN=/oracle/tnsadmin
29+
```
30+
31+
Note that the location specified in the `sqlnet.ora` must match the actual location of the file.
32+
33+
If your service is deployed in Kubernetes, then the wallet should be placed in a Kubernetes secret which
34+
is mounted into the pod at the location specified by the `TNS_ADMIN` parameter in the URL.
35+

‎docs-source/spring/data/menu/main.yaml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,15 @@ main:
4545
sub:
4646
- name: Authorization Server
4747
ref: "/security/azn-server"
48+
- name: "Spring Boot Starters"
49+
ref: "/development/starters"
50+
sub:
51+
- name: "UCP"
52+
ref: "/starters/ucp"
53+
- name: "Wallet"
54+
ref: "/starters/wallet"
55+
- name: "AQ/JMS"
56+
ref: "/starters/aqjms"
4857
- name: Database Access
4958
ref: "/database"
5059
- name: Kubernetes Access

‎docs-source/spring/data/menu/more.yaml

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
more:
22
- name: "Read our blogs!"
33
ref: "/blogs"
4-
- name: "Spring Boot Starters"
5-
ref: "https://central.sonatype.com/namespace/com.oracle.database.spring"
6-
external: true
4+
5+

‎spring/oracle-spring-boot-starters/23.4.0/oracle-spring-boot-starter-ucp/oracle-spring-boot-starter-ucp-23.4.0.pom

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@
1414

1515
<artifactId>oracle-spring-boot-starter-ucp</artifactId>
1616
<version>23.4.0</version>
17-
<packaging>pom</packaging>
1817

1918
<name>Oracle Spring Boot Starter - UCP</name>
2019
<description>Oracle's implementation of Spring Boot Starter for using with Oracle UCP</description>

0 commit comments

Comments
 (0)