Skip to content

Commit d8f758b

Browse files
andytaelandytael
authored
Merge pull request #60 from oracle/doc-pom-update
Spring asciidoc pom update
2 parents dc8bf9e + b3c1332 commit d8f758b

File tree

8 files changed

+264
-37
lines changed

8 files changed

+264
-37
lines changed

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ build/
3434
!**/src/test/**/build/
3535

3636
### VS Code ###
37-
.vscode/**
37+
.vscode
3838
/.jpb/**
3939

4040
*.log

‎docs/pom.xml

Lines changed: 13 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<!--
3-
Copyright (c) 2023, Oracle and/or its affiliates.
3+
Copyright (c) 2023, 2024, Oracle and/or its affiliates.
44
Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
55
-->
66

@@ -50,38 +50,18 @@ Licensed under the Universal Permissive License v 1.0 as shown at https://oss.or
5050
<upload-docs-zip.phase>none</upload-docs-zip.phase>
5151

5252
<!--maven-resources-plugin:3.2.0:copy-resources fails: https://issues.apache.org/jira/browse/MSHARED-966-->
53-
<maven-resources-plugin.version>3.3.0</maven-resources-plugin.version>
54-
<asciidoctor.maven.plugin.version>2.2.4</asciidoctor.maven.plugin.version>
55-
<asciidoctorj.version>2.5.10</asciidoctorj.version>
56-
<jruby.version>9.4.2.0</jruby.version>
53+
<maven-resources-plugin.version>3.3.1</maven-resources-plugin.version>
54+
<asciidoctor.maven.plugin.version>3.0.0</asciidoctor.maven.plugin.version>
55+
<asciidoctorj.version>2.5.13</asciidoctorj.version>
56+
<spring-asciidoctor-backends.version>0.0.7</spring-asciidoctor-backends.version>
57+
<jruby.version>9.4.8.0</jruby.version>
5758

5859
<!-- Distribution management -->
5960
<repository.id>artifactory</repository.id>
6061
<repository.name>spring-cloud-oci-releases</repository.name>
6162
<repository.url>changeme</repository.url>
6263
</properties>
6364

64-
<repositories>
65-
<repository>
66-
<id>spring-releases</id>
67-
<name>Spring Releases</name>
68-
<url>https://repo.spring.io/release</url>
69-
<snapshots>
70-
<enabled>false</enabled>
71-
</snapshots>
72-
</repository>
73-
</repositories>
74-
<pluginRepositories>
75-
<pluginRepository>
76-
<id>spring-releases</id>
77-
<name>Spring Releases</name>
78-
<url>https://repo.spring.io/release</url>
79-
<snapshots>
80-
<enabled>false</enabled>
81-
</snapshots>
82-
</pluginRepository>
83-
</pluginRepositories>
84-
8565
<profiles>
8666
<profile>
8767
<id>asciidocs</id>
@@ -102,6 +82,11 @@ Licensed under the Universal Permissive License v 1.0 as shown at https://oss.or
10282
<artifactId>asciidoctorj</artifactId>
10383
<version>${asciidoctorj.version}</version>
10484
</dependency>
85+
<dependency>
86+
<groupId>io.spring.asciidoctor.backends</groupId>
87+
<artifactId>spring-asciidoctor-backends</artifactId>
88+
<version>${spring-asciidoctor-backends.version}</version>
89+
</dependency>
10590
</dependencies>
10691
<configuration>
10792
<sourceDirectory>src/main/asciidoc</sourceDirectory>
@@ -119,7 +104,7 @@ Licensed under the Universal Permissive License v 1.0 as shown at https://oss.or
119104
<goal>process-asciidoc</goal>
120105
</goals>
121106
<configuration>
122-
<backend>html5</backend>
107+
<backend>spring-html</backend>
123108
<attributes>
124109
<source-highlighter>rouge</source-highlighter>
125110
<imagesdir>./images</imagesdir>
@@ -152,3 +137,4 @@ Licensed under the Universal Permissive License v 1.0 as shown at https://oss.or
152137
</snapshotRepository>
153138
</distributionManagement>
154139
</project>
140+

‎docs/src/main/asciidoc/adb.adoc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright (c) 2023, Oracle and/or its affiliates.
1+
// Copyright (c) 2024, Oracle and/or its affiliates.
22
// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
33

44
[#autonomous-database]
@@ -29,8 +29,8 @@ dependencies {
2929

3030
=== Using Autonomous Database
3131

32-
The starter automatically configures and registers an `AutnomousDb` bean in the Spring application context.
33-
The `AutnomousDb` bean (link[Javadoc]) can be used to create an Autonomous Database, get details of an Autonomous Database,
32+
The starter automatically configures and registers an `AutonomousDb` bean in the Spring application context.
33+
The `AutonomousDb` bean (link[Javadoc]) can be used to create an Autonomous Database, get details of an Autonomous Database,
3434
delete an Autonomous Database and generate a wallet for an Autonomous Database.
3535

3636
[source,java]

‎docs/src/main/asciidoc/aqjms.adoc

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
// Copyright (c) 2024, Oracle and/or its affiliates.
2+
// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
3+
4+
[#AQ/JMS]
5+
== AQ/JMS
6+
7+
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.
8+
9+
**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.
10+
11+
To add this starter to your project, add this Maven dependency:
12+
13+
[source,xml]
14+
----
15+
<dependency>
16+
<groupId>com.oracle.database.spring</groupId>
17+
<artifactId>oracle-spring-boot-starter-aqjms</artifactId>
18+
<version>23.4.0</version>
19+
</dependency>
20+
----
21+
22+
For Gradle projects, add this dependency:
23+
24+
[source,subs="normal"]
25+
----
26+
dependencies {
27+
implementation 'com.oracle.database.spring:oracle-spring-boot-starter-aqjms:23.4.0'
28+
}
29+
----
30+
31+
=== Using AQ/JMS
32+
33+
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
34+
two following beans:
35+
36+
* 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.
37+
* 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.
38+
39+
**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
40+
examples.
41+
42+
[source,java]
43+
----
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 Application context, and call the `convertAndSend()` method specifying the name of the queue or
91+
topic, and providing the object to be converted and sent in the payload of the message, as shown in the following example:
92+
93+
[source,java]
94+
----
95+
JmsTemplate jmsTemplate = context.getBean(JmsTemplate.class);
96+
jmsTemplate.convertAndSend("mailbox", new Email(-1, "info@example.com", "Hello"));
97+
----
98+
99+
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:
100+
101+
[source,java]
102+
----
103+
package com.example.aqjms;
104+
105+
import org.springframework.jms.annotation.JmsListener;
106+
import org.springframework.stereotype.Component;
107+
108+
@Component
109+
public class Receiver {
110+
111+
@JmsListener(destination = "mailbox", containerFactory = "myFactory")
112+
public void receiveMessage(Email email) {
113+
System.out.println("Received <" + email + ">");
114+
}
115+
116+
}
117+
----
118+
119+
**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`.

‎docs/src/main/asciidoc/getting-started.adoc

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright (c) 2023, Oracle and/or its affiliates.
1+
// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
22
// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
33

44
== Getting Started
@@ -78,6 +78,16 @@ The following table highlights several samples of the most used integrations in
7878

7979
| Cloud Queue
8080
| https://github.com/oracle/spring-cloud-oci/tree/main/spring-cloud-oci-samples/spring-cloud-oci-queue-sample[spring-cloud-oci-queue-sample]
81+
82+
| Oracle Autonomous Database
83+
| https://github.com/oracle/spring-cloud-oci/tree/main/spring-cloud-oci-samples/spring-cloud-oci-adb-samples[spring-cloud-oci-adb-samples]
84+
85+
| Generative AI
86+
| https://github.com/oracle/spring-cloud-oci/tree/main/spring-cloud-oci-samples/spring-cloud-oci-gen-ai-sample[spring-cloud-oci-gen-ai-sample]
87+
88+
| Vault
89+
| https://github.com/oracle/spring-cloud-oci/tree/main/spring-cloud-oci-samples/spring-cloud-oci-vault-sample[spring-cloud-oci-vault-sample]
90+
8191
|===
8292

8393
Each sample application demonstrates how to use Spring Cloud OCI libraries in context and how to setup the dependencies for the project.

‎docs/src/main/asciidoc/index-docinfo.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
<!-- Copyright (c) 2023, Oracle and/or its affiliates.-->
1+
<!-- Copyright (c) 2023, 2024, Oracle and/or its affiliates.-->
22
<!-- Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/-->
33

44
<productname>Spring Cloud OCI</productname>
55
<releaseinfo>{project-version}</releaseinfo>
66
<copyright>
7-
<year>2022-2023</year>
7+
<year>2022-2024</year>
88
<holder>Oracle</holder>
99
</copyright>
1010
<legalnotice>

‎docs/src/main/asciidoc/index.adoc

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright (c) 2023, Oracle and/or its affiliates.
1+
// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
22
// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
33

44
[[spring-cloud-oci-reference]]
@@ -12,8 +12,6 @@ include::_attributes.adoc[]
1212

1313
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.
1414

15-
Spring Cloud OCI lets you leverage the power and simplicity of the Spring Framework to read and write from Spring Resources backed up by Oracle Cloud Storage
16-
1715
include::getting-started.adoc[]
1816

1917
include::core.adoc[]
@@ -32,6 +30,14 @@ include::streaming.adoc[]
3230

3331
include::queues.adoc[]
3432

33+
include::adb.adoc[]
34+
35+
include::vault.adoc[]
36+
37+
include::ucp.adoc[]
38+
39+
include::aqjms.adoc[]
40+
3541
== Configuration properties
3642

3743
To see the list of all OCI-related configuration properties see the link:appendix.html[Appendix page].

‎docs/src/main/asciidoc/ucp.adoc

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
// Copyright (c) 2024, Oracle and/or its affiliates.
2+
// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
3+
4+
[#universal-connection-pool]
5+
== Universal Connection Pool
6+
7+
This starter provides a connection (data source) to an Oracle Database using Universal Connection Pool, which provides an efficient way to use database connections.
8+
9+
To add this starter to your project, add this Maven dependency:
10+
11+
[source,xml]
12+
----
13+
<dependency>
14+
<groupId>com.oracle.database.spring</groupId>
15+
<artifactId>oracle-spring-boot-starter-ucp</artifactId>
16+
<version>23.4.0</version>
17+
</dependency>
18+
----
19+
20+
For Gradle projects, add this dependency:
21+
22+
[source,subs="normal"]
23+
----
24+
dependencies {
25+
implementation 'com.oracle.database.spring:oracle-spring-boot-starter-ucp:23.4.0'
26+
}
27+
----
28+
29+
=== Using Universal Connection Pool
30+
31+
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.
32+
33+
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).
34+
35+
[source,yaml]
36+
----
37+
spring:
38+
jpa:
39+
hibernate:
40+
ddl-auto: validate
41+
properties:
42+
hibernate:
43+
dialect: org.hibernate.dialect.OracleDialect
44+
format_sql: true
45+
show-sql: true
46+
datasource:
47+
url: jdbc:oracle:thin:@//myhost:1521/pdb1
48+
username: username
49+
password: password
50+
driver-class-name: oracle.jdbc.OracleDriver
51+
type: oracle.ucp.jdbc.PoolDataSource
52+
oracleucp:
53+
connection-factory-class-name: oracle.jdbc.pool.OracleDataSource
54+
connection-pool-name: AccountConnectionPool
55+
initial-pool-size: 15
56+
min-pool-size: 10
57+
max-pool-size: 30
58+
----
59+
60+
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).
61+
62+
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:
63+
64+
[source,yaml]
65+
----
66+
datasource:
67+
url: jdbc:oracle:thin:@//myhost:1521/pdb1:pooled
68+
----
69+
70+
If you are using TNS, add `server=pooled` to the `connect_data`. For example:
71+
72+
[source,text]
73+
----
74+
mydb_tp = (description=
75+
(retry_count=20)
76+
(retry_delay=3)
77+
(address=(protocol=tcps)(port=1521)(host=myhost))
78+
(connect_data=(service_name=pdb1)(server=pooled))
79+
(security=(ssl_server_dn_match=yes)))
80+
----
81+
82+
If you prefer to use Java configuration, the data source can be configured as shown in the following example:
83+
84+
[source,java]
85+
----
86+
import oracle.jdbc.pool.OracleDataSource;
87+
import org.springframework.context.annotation.Bean;
88+
import org.springframework.context.annotation.Configuration;
89+
90+
import javax.sql.DataSource;
91+
import java.sql.SQLException;
92+
93+
@Configuration
94+
public class DataSourceConfiguration {
95+
96+
@Bean
97+
public DataSource dataSource() throws SQLException {
98+
OracleDataSource dataSource = new OracleDataSource();
99+
dataSource.setUser("account");
100+
dataSource.setPassword("password");
101+
dataSource.setURL("jdbc:oracle:thin:@//myhost:1521/pdb1");
102+
dataSource.setDataSourceName("AccountConnectionPool");
103+
return dataSource;
104+
}
105+
}
106+
----

0 commit comments

Comments
 (0)