diff --git a/site/docs/releases/changelog.md b/site/docs/releases/changelog.md index e91845fd..3d560a31 100644 --- a/site/docs/releases/changelog.md +++ b/site/docs/releases/changelog.md @@ -7,17 +7,32 @@ sidebar_position: 1 List of upcoming and historic changes to Spring Cloud Oracle. -### Next, TBD +### 2.0.1, TBD + +#### Database Starters + +- Upgrade third-party dependencies +- OpenTelemetry with Oracle AI Database documentation: + - Added starter usage and configuration guidance for `spring-boot-starter-oracle-otel` + - Documented how Oracle JDBC tracing spans flow into OpenTelemetry backends +- Oracle Spatial documentation and sample: + - Added starter documentation for GeoJSON-first `SDO_GEOMETRY` development + - Added the spatial sample reference covering the REST-based landmarks example + +#### Spring Cloud Stream Binder for TxEventQ + +- Upgrade third-party dependencies #### Spring Cloud OCI +- Upgrade third-party dependencies - OCI Object Storage `WritableResource` support: - The OCI Object Storage Spring `Resource` now also implements `WritableResource`, allowing object uploads through `getOutputStream()` - The Object Storage sample now demonstrates Spring `Resource`, `WritableResource`, and direct `Storage` API round trips for objects and bucket lifecycle operations - The Object Storage documentation now includes `WritableResource` usage in addition to the existing `Resource` examples -### 2.0.0, March TBD +### 2.0.0, March 31st The 2.0.0 adds support for Spring Boot 4 and Spring Framework 7, and includes numerous third party dependency updates. diff --git a/site/docusaurus.config.ts b/site/docusaurus.config.ts index 583ad3fa..9424a0b7 100644 --- a/site/docusaurus.config.ts +++ b/site/docusaurus.config.ts @@ -71,7 +71,7 @@ const config: Config = { }, { type: 'docsVersionDropdown', - versions: ['current', '2.0.0' ] + versions: ['current', '2.0.1', '2.0.0' ] }, { href: 'https://github.com/oracle/spring-cloud-oracle', diff --git a/site/versioned_docs/version-2.0.0/releases/changelog.md b/site/versioned_docs/version-2.0.0/releases/changelog.md index aa7b89bc..a3f343c1 100644 --- a/site/versioned_docs/version-2.0.0/releases/changelog.md +++ b/site/versioned_docs/version-2.0.0/releases/changelog.md @@ -7,7 +7,7 @@ sidebar_position: 1 List of upcoming and historic changes to Spring Cloud Oracle. -### 2.0.0, March TBD +### 2.0.0, March 31st The 2.0.0 adds support for Spring Boot 4 and Spring Framework 7, and includes numerous third party dependency updates. diff --git a/site/versioned_docs/version-2.0.1/database/_category_.json b/site/versioned_docs/version-2.0.1/database/_category_.json new file mode 100644 index 00000000..e9e675a3 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/database/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Oracle AI Database Starters", + "position": 2, + "link": { + "type": "generated-index", + "description": "Spring Boot starters for Oracle AI Database connections, messaging, JSON features, and Kafka-compatible TxEventQ access." + } +} diff --git a/site/versioned_docs/version-2.0.1/database/aq-jms.md b/site/versioned_docs/version-2.0.1/database/aq-jms.md new file mode 100644 index 00000000..2c58374b --- /dev/null +++ b/site/versioned_docs/version-2.0.1/database/aq-jms.md @@ -0,0 +1,131 @@ +--- +title: AQ/JMS +sidebar_position: 3 +--- + +# Spring JMS with TxEventQ + +The AQ/JMS starter provides Spring Boot support for Oracle Transactional Event Queues (TxEventQ) as a [Spring JMS provider](https://spring.io/guides/gs/messaging-jms). + +## Dependency Coordinates + +To use Oracle AI Database for JMS, include the oracle-spring-boot-starter-aqjms and spring-boot-starter-jdbc dependencies in your project: + +```xml + + com.oracle.database.spring + oracle-spring-boot-starter-aqjms + + + + org.springframework.boot + spring-boot-starter-jdbc + +``` + +## Database Permissions + +The database JMS user should have at least the following permissions to produce and consume messages with Oracle AI Database: + +```sql +grant aq_user_role to testuser; +grant execute on dbms_aq to testuser; +grant execute on dbms_aqadm to testuser; +grant execute ON dbms_aqin TO testuser; +grant execute ON dbms_aqjms TO testuser; +``` + +## Create a JMS Queue or Topic + +JMS applications must have an existing queue or topic. You may create this from your application code, or do so with a PL/SQL statement. The following snippet creates a JMS queue named `MY_JMS_QUEUE` in the `TESTUSER` schema: + +```sql +begin + dbms_aqadm.create_transactional_event_queue( + queue_name => 'TESTUSER.MY_JMS_QUEUE', + -- False -> JMS Queue. True -> JMS Topic + multiple_consumers => false + ); + + -- start the TEQ + dbms_aqadm.start_queue( + queue_name => 'TESTUSER.MY_JMS_QUEUE' + ); +end; +/ +``` + +## Database Connection + +JMS uses a standard Spring Boot datasource JDBC connection. Oracle AI Database JMS producers and consumers will use autowired Spring JDBC datasource: + +```yaml +spring: + datasource: + username: ${USERNAME} + password: ${PASSWORD} + url: ${JDBC_URL} + driver-class-name: oracle.jdbc.OracleDriver + type: oracle.ucp.jdbc.PoolDataSourceImpl + oracleucp: + initial-pool-size: 1 + min-pool-size: 1 + max-pool-size: 30 + connection-pool-name: TxEventQSample + connection-factory-class-name: oracle.jdbc.pool.OracleDataSource +``` + +## Produce and consume messages + +You can use Spring JMS abstractions like `JMSTemplate`, `JMSListener`, and `JMSClient` in your Spring Boot applications with Oracle AI Database. + +### Producer Example with `JMSTemplate` + +```java +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.beans.factory.annotation.Value; +import org.springframework.stereotype.Service; +import org.springframework.jms.core.JmsTemplate; + +@Service +public class Producer { + + private static final Logger log = LoggerFactory.getLogger(Producer.class); + + JmsTemplate jmsTemplate; + + @Value("${txeventq.topic.name}") + private String topic; + + public Producer(JmsTemplate jmsTemplate) { + this.jmsTemplate = jmsTemplate; + } + + public void sendMessageToTopic(String message) + { + jmsTemplate.convertAndSend(topic,message); + log.info("Sending message: {} to topic {}", message, topic); + } +} +``` + +### Consumer Example with `@JMSListener` + +```java +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.jms.annotation.JmsListener; +import org.springframework.stereotype.Service; + +@Service +public class Consumer { + + private static final Logger log = LoggerFactory.getLogger(Consumer.class); + + @JmsListener(destination = "${txeventq.topic.name}") + public void receiveMessage(String message) { + log.info("Received message: {}", message); + } +} +``` \ No newline at end of file diff --git a/site/versioned_docs/version-2.0.1/database/json-collections.md b/site/versioned_docs/version-2.0.1/database/json-collections.md new file mode 100644 index 00000000..b2d51768 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/database/json-collections.md @@ -0,0 +1,95 @@ +--- +title: JSON Collections and Duality Views +sidebar_position: 4 +--- + +# JSON Collections and Duality Views + +The JSON starter provides dependencies and utilities for working with Oracle AI Database JSON data, including the JSON data type, JSON Relational Duality Views, and [Oracle's efficient serialized JSON format, OSON](https://medium.com/db-one/a-deep-dive-into-binary-json-formats-oson-e3190e5e9eb0). + +## Dependency Coordinates + +```xml + + com.oracle.database.spring + oracle-spring-boot-starter-json-collections + +``` + +## JSONB Conversion + +The `JSONB` bean converts Java objects to and from OSON using `fromOSON` and `toOSON`. `InputStream`, `JsonParser`, `ByteBuffer`, and `byte[]` are supported as OSON input types. + +```java +@Autowired +JSONB jsonb; + +// byte[], JsonParser, and ByteBuffer also supported as input types +Student student = jsonb.fromOSON(inputStream, Student.class); +byte[] bytes = jsonb.toOSON(student); +``` + +## Mapping OSON Rows + +`JSONBRowMapper` converts OSON database columns to Java objects: + +```java +RowMapper rowMapper = new JSONBRowMapper<>(this.jsonb, Student.class); + +List students = jdbcTemplate.query(con -> { + PreparedStatement ps = con.prepareStatement(""" + select * from students_dv v + where v.data.first_name = ? + and v.data.last_name = ? + """); + ps.setString(1, firstName); + ps.setString(2, lastName); + return ps; +}, rowMapper); +``` + +By default, the first column is selected as the JSON column. You may customize this when instantiating the `JSONBRowMapper`: + +```java +RowMapper rowMapper = new JSONBRowMapper<>( + this.jsonb, + Student.class, + 2 // column number of OSON data +); +``` + +## OSON Kafka Serializers + +Spring Boot applications that mix OKafka APIs with OSON data may benefit from using OSON as the message serialization format. This is particularly useful when you're already using OSON as the storage format - messages sent as OSON may be inserted into a table using Oracle's JSON type without any further serialization. + +The `OSONKafkaSerializationFactory` bean provides factory methods for kafka-java serializers and deserializers that allow you to send events in OSON format. + +### Consumer Deserializer + +```java +@Autowired +private OSONKafkaSerializationFactory osonKafkaSerializationFactory; + +Deserializer keyDeserializer = new StringDeserializer(); +Deserializer valueDeserializer = osonKafkaSerializationFactory.createDeserializer(Sensor.class); +return new KafkaConsumer<>(props, keyDeserializer, valueDeserializer); +``` + +### Producer Serializer + +```java +@Autowired +private OSONKafkaSerializationFactory osonKafkaSerializationFactory; + + +Serializer keySerializer = new StringSerializer(); +Serializer valueSerializer = osonKafkaSerializationFactory.createSerializer(); +return new KafkaProducer<>(props, keySerializer, valueSerializer); +``` + +The Kafka/OSON classes will only be autowired if `kafka-clients` is on the classpath. + +## Learn by example + +- [Spring JDBC with JSON Relational Duality Views](https://github.com/oracle/spring-cloud-oracle/tree/main/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-json-duality) +- [JSON Event Streaming](https://github.com/oracle/spring-cloud-oracle/tree/main/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-json-events) \ No newline at end of file diff --git a/site/versioned_docs/version-2.0.1/database/json-relational-duality-view-builder.md b/site/versioned_docs/version-2.0.1/database/json-relational-duality-view-builder.md new file mode 100644 index 00000000..2dfa623b --- /dev/null +++ b/site/versioned_docs/version-2.0.1/database/json-relational-duality-view-builder.md @@ -0,0 +1,106 @@ +--- +title: JSON Relational Duality View Builder +sidebar_position: 5 +--- + +Oracle AI Database’s JSON Relational Duality Views (or simply duality views) let you treat relational tables and JSON documents as two sides of the same model: build your relational schema, and use comprehensive, normalized JSON documents on top. + +The JSON Relational Duality View builder allows developers to automatically generate duality view DDL from plain Java classes or JPA entities. + +## Dependency Coordinates + +```xml + + com.oracle.database.spring + oracle-spring-boot-json-relational-duality-views + +``` + +## Enable Duality View Builder with package scanning + +The Duality View builder must be explicitly enabled through package scanning. + +```java +@SpringBootApplication(scanBasePackages = { + "com.example", + // Enable the duality view event listener + "com.oracle.spring.json.duality.builder" +}) +public class Application { // main class } +``` + +## Annotations for Duality View Generation + +The custom `@JsonRelationalDualityView `annotation denotes that a Java class (usually a JPA entity) should have a duality view generated from its structure. Fields and annotations on the class are used to dynamically construct the duality view. + +You may apply this annotation to any nested classes to create nested objects in your view. + +The custom `@AccessMode` annotation is used to specify insert, update, and delete functionality on view objects. By default, read-only access is granted in the generated view. + +The jakarta.json `@JsonbProperty("_id")` annotation is recommended for any root ID fields: duality views use the _id field in JSON documents for the root primary key. It may also be used to rename class fields in the resulting duality view. + +The jakarta.json `@JsonbTransient` annotation is recommended to skip specific fields in the generated duality view. This is necessary for cyclic objects. + +## Annotate Java Classes or JPA Entities + +Any Java class or JPA entity annotated with `@JsonRelationalDualityView` on the Spring Boot classpath scan will have a duality view generated from it's metadata. + +For example, the `Actor` entity is annotated with `@JsonRelationalDualityView`, and a duality view generated at startup time, but after Hibernate runs: + +```java +@Entity +@Table(name = "actor") +@JsonRelationalDualityView(accessMode = @AccessMode(insert = true)) +public class Actor { + @JsonbProperty(_ID_FIELD) + @Id + @Column(name = "actor_id") + @GeneratedValue(strategy = GenerationType.IDENTITY) + private Long actorId; + + // other entity fields, Movies, Directors, etc. +``` + +A resulting duality view definition from this JPA entity may look like this: + +```sql +create force editionable json relational duality view actor_dv as actor @insert { + _id : actor_id + firstName : first_name + lastName : last_name + movies : movie_actor @insert [ { + movie @unnest @insert { + _id : movie_id + title + releaseYear : release_year + genre + director @insert @link (from : [director_id]) { + _id : director_id + firstName : first_name + lastName : last_name + } + } + } ] +} +``` + +## Control generation through Spring properties + +We can configure duality view generation in Spring JPA settings. The same ddl-auto values for JPA can be used for duality views: + +```yaml +spring: + jpa: + hibernate: + ddl-auto: create-drop + show-sql: true + dv: + # create-drop views after JPA ddl-auto is complete + ddl-auto: create-drop + # Print JSON Relational Duality Views to the console + show-sql: true +``` + +## Learn By Example + +- [JPA Duality View Builder Sample with Actor, Movie, and Director entities](https://github.com/anders-swanson/oracle-database-code-samples/tree/main/json/jpa-duality-views) \ No newline at end of file diff --git a/site/versioned_docs/version-2.0.1/database/okafka.md b/site/versioned_docs/version-2.0.1/database/okafka.md new file mode 100644 index 00000000..506493bf --- /dev/null +++ b/site/versioned_docs/version-2.0.1/database/okafka.md @@ -0,0 +1,110 @@ +--- +title: OKafka +sidebar_position: 5 +--- + +# OKafka + +The OKafka starter enables Spring Boot applications to use Kafka-style producer, consumer, and administration APIs with Oracle AI Database Transactional Event Queues. + +This starter brings in the `com.oracle.database.messaging:okafka` dependency so applications can: + +- create Kafka-style producers and consumers backed by Oracle TxEventQ +- manage TxEventQ topics with the OKafka admin client +- use Oracle AI Database as the event log while keeping a Kafka client programming model + +## Dependency Coordinates + +```xml + + com.oracle.database.spring + oracle-spring-boot-starter-okafka + +``` + +## Connection Properties + +OKafka uses standard Kafka-style properties together with Oracle-specific settings for the target database service and wallet or TNS directory: + +```java +Properties props = new Properties(); +props.put("oracle.service.name", serviceName); +props.put("security.protocol", securityProtocol); +props.put("bootstrap.servers", bootstrapServers); +props.put("oracle.net.tns_admin", ojdbcPath); +``` + +- `oracle.service.name` selects the Oracle AI Database service, for example `freepdb1` +- `bootstrap.servers` identifies the database listener host and port +- `oracle.net.tns_admin` points to a wallet or connection-properties directory when needed +- `security.protocol` can be `PLAINTEXT` for local development or `SSL` for wallet-backed connections + +## Producer and Consumer Setup + +Applications use the Oracle OKafka producer and consumer implementations directly: + +```java +props.put("enable.idempotence", "true"); +props.put("key.serializer", "org.apache.kafka.common.serialization.StringSerializer"); +props.put("value.serializer", "org.apache.kafka.common.serialization.StringSerializer"); + +KafkaProducer okafkaProducer = new KafkaProducer<>(props); +``` + +```java +props.put("group.id", "MY_CONSUMER_GROUP"); +props.put("enable.auto.commit", "false"); +props.put("max.poll.records", 2000); +props.put("key.deserializer", "org.apache.kafka.common.serialization.StringDeserializer"); +props.put("value.deserializer", "org.apache.kafka.common.serialization.StringDeserializer"); +props.put("auto.offset.reset", "earliest"); + +Consumer okafkaConsumer = new KafkaConsumer<>(props); +``` + +Use the Oracle OKafka client classes rather than the default Apache Kafka implementations: + +- `org.oracle.okafka.clients.producer.KafkaProducer` +- `org.oracle.okafka.clients.consumer.KafkaConsumer` +- `org.oracle.okafka.clients.admin.AdminClient` + +## Topic Administration + +You can create a TxEventQ topic through the OKafka admin client: + +```java +NewTopic topic = new NewTopic("OKAFKA_SAMPLE", 1, (short) 1); +OKafkaUtil.createTopicIfNotExists(kafkaProperties, topic); +``` + +In production code, it is common to handle `TopicExistsException` so repeated startup does not fail when the topic already exists. + +## Database Permissions + +The database user needs the privileges required for TxEventQ and OKafka access. A representative setup looks like this: + +```sql +grant aq_user_role to TESTUSER; +grant execute on dbms_aq to TESTUSER; +grant execute on dbms_aqadm to TESTUSER; +grant select on gv_$session to TESTUSER; +grant select on v_$session to TESTUSER; +grant select on gv_$instance to TESTUSER; +grant select on gv_$listener_network to TESTUSER; +grant select on SYS.DBA_RSRC_PLAN_DIRECTIVES to TESTUSER; +grant select on gv_$pdbs to TESTUSER; +grant select on user_queue_partition_assignment_table to TESTUSER; +exec dbms_aqadm.GRANT_PRIV_FOR_RM_PLAN('TESTUSER'); +``` + +## When To Use OKafka + +Use the OKafka starter when your application already follows Kafka client concepts such as producers, consumers, groups, serializers, and topic administration, but you want Oracle AI Database TxEventQ as the messaging backend. + +Choose this starter when you want Kafka-style APIs directly. If you want higher-level Spring messaging abstractions instead, consider the AQ/JMS starter or the Spring Cloud Stream binder for TxEventQ. + +## Learn by Example + +See the sample application: + +- [oracle-spring-boot-sample-okafka](https://github.com/oracle/spring-cloud-oracle/tree/main/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-okafka) diff --git a/site/versioned_docs/version-2.0.1/database/opentelemetry-with-oracle.md b/site/versioned_docs/version-2.0.1/database/opentelemetry-with-oracle.md new file mode 100644 index 00000000..49347e7c --- /dev/null +++ b/site/versioned_docs/version-2.0.1/database/opentelemetry-with-oracle.md @@ -0,0 +1,60 @@ +--- +title: OpenTelemetry with Oracle AI Database +sidebar_position: 6 +--- + +# OpenTelemetry with Oracle AI Database + +The `spring-boot-starter-oracle-otel` starter provides a tools instrumenting Oracle JDBC activity in Spring Boot applications with OpenTelemetry. + +Use it when you want traces to flow from an incoming Spring Boot HTTP request into Oracle Database JDBC operations so those spans can be exported to an OpenTelemetry backend such as Grafana LGTM or Zipkin-compatible tooling. + +## Dependency Coordinates + +```xml + + com.oracle.database.spring + spring-boot-starter-oracle-otel + +``` + +## Database Driver Tracing + +This starter is intended to support Oracle JDBC OpenTelemetry instrumentation in a Spring Boot application. The sample application demonstrates the typical flow: + +- a Spring MVC endpoint receives the request +- Spring Boot tracing creates the application span +- Oracle JDBC OpenTelemetry instrumentation contributes database spans for JDBC work + +## Enable the database tracing provider + +In your application properties, enable JMX beans (for the tracing provider), and set the `oracle.jdbc.provider.traceEventListener` JDBC connection URL property to `open-telemetry-trace-event-listener-provider` like so: + +```yaml +spring: + jmx: + enabled: true + datasource: + # Docker compose Oracle Free container + url: jdbc:oracle:thin:@localhost:1522/freepdb1?oracle.jdbc.provider.traceEventListener=open-telemetry-trace-event-listener-provider +``` + +## Configuration Notes + +The Oracle JDBC OpenTelemetry provider supports system properties such as: + +- `oracle.jdbc.provider.opentelemetry.enabled` to enable or disable the provider +- `oracle.jdbc.provider.opentelemetry.sensitive-enabled` to control export of sensitive values such as SQL text + +When tracing is configured in the application, a request that performs JDBC work can be viewed as a single trace spanning the HTTP layer and the database layer. + +## Learn by Example + +See the sample application: + +- [oracle-spring-boot-sample-otel](https://github.com/oracle/spring-cloud-oracle/tree/main/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-otel) + +## References + +- [Spring Boot tracing](https://docs.spring.io/spring-boot/reference/actuator/tracing.html) +- [OJDBC OpenTelemetry provider](https://github.com/oracle/ojdbc-extensions/tree/main/ojdbc-provider-opentelemetry) diff --git a/site/versioned_docs/version-2.0.1/database/spatial.md b/site/versioned_docs/version-2.0.1/database/spatial.md new file mode 100644 index 00000000..5490c4bd --- /dev/null +++ b/site/versioned_docs/version-2.0.1/database/spatial.md @@ -0,0 +1,244 @@ +--- +title: Oracle Spatial +sidebar_position: 6 +--- + +The Oracle Spatial starter adds Spring Boot auto-configuration for GeoJSON-first Oracle Spatial development with [`SDO_GEOMETRY`](https://docs.oracle.com/en/database/oracle/oracle-database/23/spatl/sdo_geometry-object-type.html). + +This starter is for geographic and topographic spatial data. + +## Dependency Coordinates + +```xml + + com.oracle.database.spring + oracle-spring-boot-starter-spatial + +``` + +## Provided Beans + +When Oracle JDBC is on the classpath and a `DataSource` is present, the starter auto-configures: + +- `OracleSpatialJdbcOperations` +- `OracleSpatialProperties` + +If your application provides its own bean of the same type, the starter backs off and uses your custom bean instead. + +## What You Inject vs What You Build + +The starter injects one main working bean: + +- `OracleSpatialJdbcOperations` + - the Spring JDBC entry point for spatial work + - creates GeoJSON-backed bind values + - creates bindable SQL expressions and predicates + - provides a `RowMapper` for projected GeoJSON columns + - applies spatial bind parameters to `JdbcClient.StatementSpec` + +Per query, `OracleSpatialJdbcOperations` creates lightweight value objects: + +- `SpatialGeometry` + - a GeoJSON payload plus SRID +- `SpatialExpression` + - a SQL expression such as `SDO_UTIL.TO_GEOJSON(...)` or `SDO_GEOM.SDO_DISTANCE(...)` +- `SpatialPredicate` + - a SQL predicate such as `SDO_FILTER(...) = 'TRUE'` +- `SpatialRelationMask` + - enum values for `SDO_RELATE` masks such as `ANYINTERACT`, `INSIDE`, and `CONTAINS` + +These are not Spring beans. They are query parts that keep the spatial SQL fragment and its JDBC bind values together. + +## Configuration Properties + +```yaml +oracle: + database: + spatial: + enabled: true + default-srid: 4326 + default-distance-unit: M +``` + +`default-distance-unit` is intentionally flexible and can be set to Oracle-style unit tokens such as `M`, `KM`, or `UNIT=MILE`. + +These properties affect generated SQL directly: + +- `default-srid` is used when GeoJSON is converted to `SDO_GEOMETRY` +- `default-distance-unit` is used when distance clauses are generated for `SDO_WITHIN_DISTANCE` and `SDO_GEOM.SDO_DISTANCE` + +If you are new to SRIDs, Oracle uses the SRID value to identify the geometry's spatial reference system or coordinate system. [Oracle's coordinate system documentation](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/coordinate-systems-spatial-reference-systems.html) and the [`SDO_SRID` section of the `SDO_GEOMETRY` reference](https://docs.oracle.com/en/database/oracle/oracle-database/23/spatl/sdo_geometry-object-type.html) are the best places to start. + +## Using the Starter + +Inject `OracleSpatialJdbcOperations` into a Spring JDBC service and let it supply the spatial expressions, predicates, and row mapping while your code still owns the full SQL statement: + +```java +@Service +class LandmarkService { + private final JdbcClient jdbcClient; + private final OracleSpatialJdbcOperations spatial; + + LandmarkService(JdbcClient jdbcClient, OracleSpatialJdbcOperations spatial) { + this.jdbcClient = jdbcClient; + this.spatial = spatial; + } + + Landmark create(Landmark landmark) { + SpatialGeometry geometry = spatial.geometry(landmark.geometry()); + SpatialExpression insertGeometry = spatial.fromGeoJson(geometry); + + spatial.bind( + jdbcClient.sql("insert into landmarks (id, name, category, geometry) values (:id, :name, :category, " + + insertGeometry.expression() + ")"), + insertGeometry) + .param("id", landmark.id()) + .param("name", landmark.name()) + .param("category", landmark.category()) + .update(); + + SpatialExpression projectedGeometry = spatial.toGeoJson("geometry"); + return jdbcClient.sql("select id, name, category, " + + projectedGeometry.selection("geometry") + + " from landmarks where id = :id") + .param("id", landmark.id()) + .query((rs, rowNum) -> new Landmark( + rs.getLong("id"), + rs.getString("name"), + rs.getString("category"), + rs.getString("geometry"))) + .single(); + } +} +``` + +In this pattern: + +- the application boundary stays GeoJSON-first +- the starter keeps Oracle Spatial SQL fragments attached to their JDBC bind values +- `JdbcClient` still owns the statement lifecycle +- schema creation, metadata registration, and spatial index creation remain outside the starter +- generated bind names such as `spatialGeometry1` are internal implementation details and may increment over time, so callers should not depend on specific parameter names in logs + +## `OracleSpatialJdbcOperations` + +`OracleSpatialJdbcOperations` is the main API exposed by the starter. + +Geometry creation: + +- `geometry(String geoJson)` +- `geometry(String geoJson, int srid)` + +Expression creation: + +- `fromGeoJson(SpatialGeometry geometry)` + - returns `SDO_UTIL.FROM_GEOJSON(...)` +- `toGeoJson(String geometryColumn)` + - returns `SDO_UTIL.TO_GEOJSON(...)` +- `nearestNeighborDistance()` + - returns `SDO_NN_DISTANCE(1)` +- `distance(String geometryColumn, SpatialGeometry geometry, Number tolerance)` +- `distance(String geometryColumn, SpatialGeometry geometry, Number tolerance, String unit)` + - return `SDO_GEOM.SDO_DISTANCE(...)` + +Predicate creation: + +- `filter(String geometryColumn, SpatialGeometry geometry)` + - wraps [`SDO_FILTER`](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_filter.html) +- `relate(String geometryColumn, SpatialGeometry geometry, SpatialRelationMask mask)` + - wraps [`SDO_RELATE`](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_relate.html) +- `withinDistance(String geometryColumn, SpatialGeometry geometry, Number distance)` +- `withinDistance(String geometryColumn, SpatialGeometry geometry, Number distance, String unit)` + - wrap [`SDO_WITHIN_DISTANCE`](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_within_distance.html) +- `nearestNeighbor(String geometryColumn, SpatialGeometry geometry, int numResults)` + - wraps [`SDO_NN`](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_nn.html) + +Spring JDBC integration: + +- `bind(JdbcClient.StatementSpec statement, SpatialJdbcBindable... parts)` + - applies bind values from spatial expressions and predicates to a `JdbcClient` statement +- `geoJsonRowMapper(String columnLabel)` + - returns a `RowMapper` for GeoJSON projections + +## Query Patterns + +Insert GeoJSON as `SDO_GEOMETRY`: + +```java +SpatialGeometry geometry = spatial.geometry(geoJson); +SpatialExpression insertGeometry = spatial.fromGeoJson(geometry); + +spatial.bind( + jdbcClient.sql("insert into landmarks (geometry) values (" + insertGeometry.expression() + ")"), + insertGeometry) + .update(); +``` + +Project `SDO_GEOMETRY` back to GeoJSON: + +```java +SpatialExpression projectedGeometry = spatial.toGeoJson("geometry"); + +String geoJson = jdbcClient.sql("select " + projectedGeometry.selection("geometry") + " from landmarks where id = :id") + .param("id", id) + .query(spatial.geoJsonRowMapper("geometry")) + .single(); +``` + +Apply a filter plus exact relationship check: + +```java +SpatialGeometry searchGeometry = spatial.geometry(polygonGeoJson); +SpatialPredicate filter = spatial.filter("geometry", searchGeometry); +SpatialPredicate relate = spatial.relate("geometry", searchGeometry, SpatialRelationMask.ANYINTERACT); + +spatial.bind( + jdbcClient.sql("select id from landmarks where " + + filter.clause() + " and " + relate.clause()), + filter, relate) + .query(Long.class) + .list(); +``` + +Find nearby rows and order by distance: + +```java +SpatialGeometry referenceGeometry = spatial.geometry(pointGeoJson); +SpatialPredicate within = spatial.withinDistance("geometry", referenceGeometry, 2000); +SpatialExpression distance = spatial.distance("geometry", referenceGeometry, 0.005); + +spatial.bind( + jdbcClient.sql("select id, " + distance.selection("distance") + + " from landmarks where " + within.clause() + + " order by distance fetch first 3 rows only"), + within, distance) + .query((rs, rowNum) -> rs.getLong("id")) + .list(); +``` + +## Usage Notes + +- Manage spatial table DDL, `USER_SDO_GEOM_METADATA`, and spatial index creation in your migrations or setup SQL rather than expecting starter beans to create them. +- Use `SDO_FILTER` as a primary filter and `SDO_RELATE` for exact mask-based checks. +- Use `SDO_WITHIN_DISTANCE` for radius filtering and `SDO_NN` for nearest-neighbor searches. +- Do not combine `SDO_NN` and `SDO_WITHIN_DISTANCE` in the same `WHERE` clause. +- Use `SDO_WITHIN_DISTANCE` ordered by `SDO_GEOM.SDO_DISTANCE` when you need both a distance bound and a result count. +- `nearestNeighbor(...)` and `nearestNeighborDistance()` currently assume Oracle operator id `1`. If you need more advanced SQL with multiple `SDO_NN` operators in a single statement, build that query manually. + +## Further Reading + +- [Oracle Spatial Concepts](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/spatial-concepts.html) +- [SDO_GEOMETRY Object Type](https://docs.oracle.com/en/database/oracle/oracle-database/23/spatl/sdo_geometry-object-type.html) +- [Coordinate Systems (Spatial Reference Systems)](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/coordinate-systems-spatial-reference-systems.html) +- [SDO_SRID in the spatial data types and metadata reference](https://docs.oracle.com/en/database/oracle/oracle-database/21/spatl/spatial-datatypes-metadata.html) +- [SDO_UTIL.FROM_GEOJSON](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_util-from_geojson.html) +- [SDO_UTIL.TO_GEOJSON](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_util-to_geojson.html) +- [SDO_FILTER](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_filter.html) +- [SDO_RELATE](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_relate.html) +- [SDO_WITHIN_DISTANCE](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_within_distance.html) +- [SDO_NN](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_nn.html) +- [SDO_NN_DISTANCE](https://docs.oracle.com/en/database/oracle/oracle-database/26/spatl/sdo_nn_distance.html) + +## Sample + +See the spatial sample application under `database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-spatial` for a REST-based example that stores and queries `SDO_GEOMETRY` values using GeoJSON. Its `GET /landmarks/near` endpoint accepts compact GeoJSON in the `geometry` query parameter. diff --git a/site/versioned_docs/version-2.0.1/database/ucp.md b/site/versioned_docs/version-2.0.1/database/ucp.md new file mode 100644 index 00000000..d49bd7c7 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/database/ucp.md @@ -0,0 +1,39 @@ +--- +title: Universal Connection Pool +sidebar_position: 1 +--- + +# Universal Connection Pool + +The UCP starter provides an Oracle AI Database `DataSource` backed by Universal Connection Pool. + +## Dependency Coordinates + +```xml + + com.oracle.database.spring + oracle-spring-boot-starter-ucp + +``` + +## Configuring the Data Source + +Configure `spring.datasource` in `application.yaml` and add Spring Data JDBC or Spring Data JPA as needed: + +```yaml +spring: + datasource: + url: jdbc:oracle:thin:@//myhost:1521/pdb1 + username: username + password: password + driver-class-name: oracle.jdbc.OracleDriver + type: oracle.ucp.jdbc.PoolDataSourceImpl + oracleucp: # Any UCP specific connection parameters defined here + 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 `oracleucp` block is optional and can be used to fine-tune the pool configuration with Oracle UCP specific properties. diff --git a/site/versioned_docs/version-2.0.1/database/wallet.md b/site/versioned_docs/version-2.0.1/database/wallet.md new file mode 100644 index 00000000..224d6cda --- /dev/null +++ b/site/versioned_docs/version-2.0.1/database/wallet.md @@ -0,0 +1,19 @@ +--- +title: Oracle AI Database Wallet +sidebar_position: 2 +--- + +# Oracle AI Database Wallet + +The Wallet starter adds the Oracle security libraries needed for Oracle AI Database Wallet based authentication, including common Autonomous AI Database mTLS scenarios. + +## Dependency Coordinates + +```xml + + com.oracle.database.spring + oracle-spring-boot-starter-wallet + +``` + +Use this starter together with the UCP starter or another Oracle JDBC-based integration when your connection relies on wallet credentials and TNS configuration. diff --git a/site/versioned_docs/version-2.0.1/intro.md b/site/versioned_docs/version-2.0.1/intro.md new file mode 100644 index 00000000..c876fe61 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/intro.md @@ -0,0 +1,62 @@ +--- +title: Project Overview +sidebar_position: 1 +--- + +# Spring Cloud Oracle + +Spring Cloud Oracle is a multi-module project providing Spring Boot integrations for Oracle AI Database, Oracle Cloud Infrastructure, and Oracle AI Database native messaging. + +The repository is organized around three subprojects: + +## Oracle AI Database Spring Boot Starters + +The database starters implement Spring Boot integrations for Oracle AI Database development, focusing on application connectivity, database-native messaging, and modern data features. + +- Universal Connection Pool (`UCP`) for Oracle-backed `DataSource` configuration +- Oracle AI Database Wallet support for secure connectivity +- `AQ/JMS` integration for Oracle Advanced Queuing and Transactional Event Queues +- OKafka messaging with Apache Kafka Java APIs +- JSON collections and JSON Relational Duality Views for Oracle AI Database 26ai style data access + +## Spring Cloud Stream Binder for Oracle TxEventQ + +The TxEventQ stream binder implements the Spring Cloud Stream programming model on top of Oracle AI Database Transactional Event Queues. + +This subproject is for teams building event-driven services that want: + +- standard Spring Cloud Stream `Supplier`, `Function`, and `Consumer` bindings +- Oracle AI Database-backed messaging semantics +- integration with the same Oracle connection infrastructure used elsewhere in the project + +## Spring Cloud OCI + +Spring Cloud OCI provides idiomatic Spring integrations for Oracle Cloud Infrastructure services. OCI capabilities are packaged as Spring Boot starters, templates, resources, and configuration mechanisms. + +Spring Cloud OCI includes integrations for services such as: + +- Autonomous Database +- Vault +- Object Storage +- Streaming +- Queues +- Notifications +- Logging +- Email Delivery +- Functions +- Oracle NoSQL Database +- Generative AI +- +## How They Fit Together + +These three subprojects are complementary: + +- the database starters cover direct Oracle AI Database integration +- the TxEventQ binder adds Spring Cloud Stream support for Oracle AI Database messaging +- Spring Cloud OCI connects Spring applications to managed OCI services around the database and application runtime + +Together, they provide a source of integrations for building Spring applications that span Oracle technologies. + +## Contributing + +Contributions are welcomed in the form of bug reports, features, documentation, and pull requests. See [CONTRIBUTING.md](https://github.com/oracle/spring-cloud-oracle/blob/main/CONTRIBUTING.md) for details on contributing to this project. \ No newline at end of file diff --git a/site/versioned_docs/version-2.0.1/oci/_category_.json b/site/versioned_docs/version-2.0.1/oci/_category_.json new file mode 100644 index 00000000..c7ec2bf8 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Oracle Cloud Infrastructure (OCI)", + "position": 4, + "link": { + "type": "generated-index", + "description": "Authentication, configuration, and Spring Boot integrations for OCI services." + } +} diff --git a/site/versioned_docs/version-2.0.1/oci/autonomous-database.md b/site/versioned_docs/version-2.0.1/oci/autonomous-database.md new file mode 100644 index 00000000..743b3eb1 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/autonomous-database.md @@ -0,0 +1,72 @@ +--- +title: Autonomous Database +sidebar_position: 3 +--- + +# Autonomous Database + +[OCI Autonomous Database](https://docs.oracle.com/en/cloud/paas/atp-cloud/index.html) is a managed data service that automates patching, upgrades, tuning, and routine maintenance. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-adb + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-adb") +} +``` + +## Using Autonomous Database + +The starter auto-configures an `AutonomousDb` bean that can create, inspect, start, stop, and delete an Autonomous Database, and generate wallets. + +```java +@Autowired +AutonomousDb autonomousDatabase; + +public void createAutonomousDatabase() { + autonomousDatabase.createAutonomousDatabase( + databaseName, compartmentId, adminPassword, dataStorageSizeInGBs, computeCount); +} + +public void getAutonomousDatabase() { + AutonomousDbDetails response = autonomousDatabase.getAutonomousDatabase(databaseId); +} + +public void getAutonomousDatabaseWallet() { + GenerateAutonomousDatabaseWalletResponse response = + autonomousDatabase.generateAutonomousDatabaseWallet(databaseId, password); + InputStream is = response.getInputStream(); + int contentLength = response.getContentLength(); +} + +public void startAutonomousDatabase() { + StartAutonomousDatabaseResponse response = + autonomousDatabase.startAutonomousDatabase(databaseId); +} + +public void stopAutonomousDatabase() { + StopAutonomousDatabaseResponse response = + autonomousDatabase.stopAutonomousDatabase(databaseId); +} +``` + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.adb.enabled` | Enables the OCI Autonomous Database APIs | No | `true` | + +## Sample + +See [`spring-cloud-oci-adb-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-adb-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/configuration-properties.md b/site/versioned_docs/version-2.0.1/oci/configuration-properties.md new file mode 100644 index 00000000..036fdc4d --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/configuration-properties.md @@ -0,0 +1,74 @@ +--- +title: Configuration Properties +sidebar_position: 2 +--- + +# Configuration Properties + +This page summarizes the common Spring Cloud Oracle OCI properties and the subset that supports configuration refresh at runtime. + +## Common OCI Properties + +| Name | Default | Description | +| --- | --- | --- | +| `spring.cloud.oci.config.profile` | `DEFAULT` | Name of the profile in the OCI auth config file | +| `spring.cloud.oci.config.file` | NA | Location of the OCI auth config file | +| `spring.cloud.oci.config.type` | `FILE` | Auth type. Allowed values are `FILE`, `SIMPLE`, `INSTANCE_PRINCIPAL`, `RESOURCE_PRINCIPAL`, `SESSION_TOKEN`, and `WORKLOAD_IDENTITY` | +| `spring.cloud.oci.config.federation-endpoint` | NA | Optional token endpoint for `INSTANCE_PRINCIPAL`, `RESOURCE_PRINCIPAL`, or `WORKLOAD_IDENTITY` | +| `spring.cloud.oci.config.userId` | NA | User OCID for `SIMPLE` auth | +| `spring.cloud.oci.config.tenantId` | NA | Tenancy OCID for `SIMPLE` auth | +| `spring.cloud.oci.config.fingerprint` | NA | Public key fingerprint for `SIMPLE` auth | +| `spring.cloud.oci.config.privateKey` | NA | Private key file path for `SIMPLE` auth | +| `spring.cloud.oci.config.passPhrase` | NA | Passphrase for the private key, if encrypted | +| `spring.cloud.oci.config.region` | NA | OCI region used for authentication | +| `spring.cloud.oci.region.static` | NA | Static region used for API calls, overriding auth-file region | +| `spring.cloud.oci.compartment.static` | NA | Default OCI compartment OCID | +| `spring.cloud.oci.storage.enabled` | `true` | Enables the OCI Object Storage module | +| `spring.cloud.oci.notification.enabled` | `true` | Enables the OCI Notifications module | +| `spring.cloud.oci.logging.enabled` | `true` | Enables the OCI Logging module | + +## Configuration Refresh + +The following properties support runtime configuration refresh without restarting the application: + +| Name | Default | +| --- | --- | +| `spring.cloud.oci.config.profile` | `DEFAULT` | +| `spring.cloud.oci.config.file` | NA | +| `spring.cloud.oci.config.type` | NA | +| `spring.cloud.oci.config.userId` | NA | +| `spring.cloud.oci.config.tenantId` | NA | +| `spring.cloud.oci.config.fingerprint` | NA | +| `spring.cloud.oci.config.privateKey` | NA | +| `spring.cloud.oci.config.passPhrase` | NA | +| `spring.cloud.oci.config.region` | NA | +| `spring.cloud.oci.region.static` | NA | +| `spring.cloud.oci.compartment.static` | NA | +| `spring.cloud.oci.logging.logId` | NA | + +Spring Boot Actuator can be used to trigger refresh explicitly. + +### Maven + +```xml + + org.springframework.boot + spring-boot-starter-actuator + +``` + +### Gradle + +```groovy +dependencies { + implementation("org.springframework.boot:spring-boot-starter-actuator") +} +``` + +Expose the refresh endpoint: + +```properties +management.endpoints.web.exposure.include=refresh +``` + +After updating the externalized configuration, call `POST /actuator/refresh`. diff --git a/site/versioned_docs/version-2.0.1/oci/core.md b/site/versioned_docs/version-2.0.1/oci/core.md new file mode 100644 index 00000000..cb9a9e52 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/core.md @@ -0,0 +1,147 @@ +--- +title: OCI Core +sidebar_position: 1 +--- + +# OCI Core + +Spring Cloud Oracle provides a core starter that auto-configures OCI authentication and shared infrastructure for the service-specific starters. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter") +} +``` + +## Authentication Configuration + +Spring Cloud Oracle supports multiple OCI authentication strategies. + +### Configuration File Based Authentication + +Configuration-file authentication is enabled by default. To set it explicitly: + +```properties +spring.cloud.oci.config.type=FILE +spring.cloud.oci.config.profile=DEFAULT +spring.cloud.oci.config.file= +``` + +For details about the OCI config file format, see the [SDK and CLI configuration file documentation](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm). + +### Simple Authentication + +Use `SIMPLE` when you want to provide credentials directly via Spring configuration: + +```properties +spring.cloud.oci.config.type=SIMPLE +spring.cloud.oci.config.userId=ocid1.user.oc1.. +spring.cloud.oci.config.tenantId=ocid1.tenancy.oc1.. +spring.cloud.oci.config.fingerprint= +spring.cloud.oci.config.privateKey= +spring.cloud.oci.config.passPhrase= +spring.cloud.oci.config.region= +``` + +All properties are required except `spring.cloud.oci.config.passPhrase`. + +### Instance Principal + +```properties +spring.cloud.oci.config.type=INSTANCE_PRINCIPAL +spring.cloud.oci.config.federation-endpoint=https://auth.us-ashburn-1.oraclecloud.com +``` + +See [OCI Instance Principal Authentication](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm). + +### Resource Principal + +```properties +spring.cloud.oci.config.type=RESOURCE_PRINCIPAL +spring.cloud.oci.config.federation-endpoint=https://auth.us-ashburn-1.oraclecloud.com +``` + +See [OCI Resource Principal Authentication](https://docs.public.oneportal.content.oci.oraclecloud.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm#sdk_authentication_methods_resource_principal). + +### Session Token + +```properties +spring.cloud.oci.config.type=SESSION_TOKEN +``` + +See the [OCI session token authentication reference](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm#ariaid-title12). + +### Workload Identity + +```properties +spring.cloud.oci.config.type=WORKLOAD_IDENTITY +spring.cloud.oci.config.federation-endpoint=https://auth.us-ashburn-1.oraclecloud.com +``` + +See [OKE Workload Identity Authentication](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm). + +## Region Configuration + +To set a region for the entire application: + +```properties +spring.cloud.oci.region.static=us-ashburn-1 +``` + +`spring.cloud.oci.region.static` takes precedence over `spring.cloud.oci.config.region` and the region in the OCI auth configuration file. + +## Compartment Configuration + +To define a default compartment for OCI operations: + +```properties +spring.cloud.oci.compartment.static= +``` + +### Starters + +| Starter | Description | Artifact | +| --- | --- | --- | +| Core | Auto-configures OCI authentication and shared infrastructure | `com.oracle.cloud.spring:spring-cloud-oci-starter` | +| Object Storage | Integrates OCI Object Storage with Spring storage and resource APIs | `com.oracle.cloud.spring:spring-cloud-oci-starter-storage` | +| Autonomous Database | Provides access to OCI Autonomous Database lifecycle operations | `com.oracle.cloud.spring:spring-cloud-oci-starter-adb` | +| Vault | Exposes OCI Vault as a Spring property source and API client | `com.oracle.cloud.spring:spring-cloud-oci-starter-vault` | +| Streaming | Integrates OCI Streaming for producing and consuming records | `com.oracle.cloud.spring:spring-cloud-oci-starter-streaming` | +| Queue | Integrates OCI Queue APIs for queue and message operations | `com.oracle.cloud.spring:spring-cloud-oci-starter-queue` | +| Notifications | Publishes notifications and manages topics and subscriptions | `com.oracle.cloud.spring:spring-cloud-oci-starter-notification` | +| Logging | Sends application logs to OCI Logging | `com.oracle.cloud.spring:spring-cloud-oci-starter-logging` | +| Email Delivery | Implements Spring mail integration on OCI Email Delivery | `com.oracle.cloud.spring:spring-cloud-oci-starter-email` | +| Functions | Invokes OCI Functions from Spring applications | `com.oracle.cloud.spring:spring-cloud-oci-starter-function` | +| Oracle NoSQL Database | Adds Spring Data style support for Oracle NoSQL Database | `com.oracle.cloud.spring:spring-cloud-oci-starter-nosql` | +| Generative AI | Exposes OCI Generative AI chat and embedding models | `com.oracle.cloud.spring:spring-cloud-oci-starter-gen-ai` | + +## Learn by Example + +The repository includes sample applications for the most important integrations: + +| Integration | Sample | +|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Object Storage | [`spring-cloud-oci-storage-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-storage-sample) | +| Notifications | [`spring-cloud-oci-notification-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-notification-sample) | +| Generative AI | [`spring-cloud-oci-gen-ai-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-gen-ai-sample) | +| Logging | [`spring-cloud-oci-logging-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-logging-sample) | +| Streaming | [`spring-cloud-oci-streaming-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-streaming-sample) | +| Functions | [`spring-cloud-oci-function-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-function-sample) | +| Queue | [`spring-cloud-oci-queue-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-queue-sample) | +| Autonomous Database | [`spring-cloud-oci-adb-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-adb-sample) | +| Vault | [`spring-cloud-oci-vault-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-vault-sample) | + +Each sample is intended to be deployable and to show both dependency setup and API usage in context. \ No newline at end of file diff --git a/site/versioned_docs/version-2.0.1/oci/email-delivery.md b/site/versioned_docs/version-2.0.1/oci/email-delivery.md new file mode 100644 index 00000000..679d5817 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/email-delivery.md @@ -0,0 +1,106 @@ +--- +title: Email Delivery +sidebar_position: 10 +--- + +# Email Delivery + +[OCI Email Delivery](https://docs.oracle.com/en-us/iaas/Content/Email/home.htm) provides Spring Mail integrations through `MailSender` and `JavaMailSender`. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-email + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-email") +} +``` + +## SMTP Configuration + +Email Delivery uses standard Spring Mail SMTP configuration: + +```yaml +spring: + mail: + host: ${OCI_SMTP_HOST} + username: ${OCI_SMTP_USERNAME} + password: ${OCI_SMTP_PASSWORD} + port: 587 +``` + +Create SMTP credentials in OCI and use the OCI Email Delivery SMTP endpoint for `spring.mail.host`. + +## Using `MailSender` + +```java +@Service +public class EmailService { + private final MailSender mailSender; + + public EmailService(@Qualifier("ociMailSender") MailSender mailSender) { + this.mailSender = mailSender; + } + + public void sendSimpleMail(String from, String to, String subject, String text) { + SimpleMailMessage message = new SimpleMailMessage(); + message.setFrom(from); + message.setTo(to); + message.setSubject(subject); + message.setText(text); + mailSender.send(message); + } +} +``` + +## Using `JavaMailSender` + +```java +@Service +public class EmailService { + private final JavaMailSender javaMailSender; + + public EmailService(@Qualifier("ociJavaMailSender") JavaMailSender javaMailSender) { + this.javaMailSender = javaMailSender; + } + + public void sendJavaMail( + String from, + String to, + String subject, + String text, + File fileAttachment) throws MessagingException { + MimeMessage message = javaMailSender.createMimeMessage(); + Multipart multipartContent = new MimeMultipart(); + MimeBodyPart textContent = new MimeBodyPart(); + textContent.setContent(text, "text/html"); + multipartContent.addBodyPart(textContent); + + MimeBodyPart attachmentContent = new MimeBodyPart(); + DataSource source = new FileDataSource(fileAttachment); + attachmentContent.setDataHandler(new DataHandler(source)); + attachmentContent.setFileName(fileAttachment.getName()); + multipartContent.addBodyPart(attachmentContent); + + message.setFrom(from); + message.setRecipients(Message.RecipientType.TO, InternetAddress.parse(to)); + message.setSubject(subject); + message.setContent(multipartContent); + javaMailSender.send(message); + } +} +``` + +## Sample + +See [`spring-cloud-oci-email-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-email-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/functions.md b/site/versioned_docs/version-2.0.1/oci/functions.md new file mode 100644 index 00000000..0c312e40 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/functions.md @@ -0,0 +1,51 @@ +--- +title: Functions +sidebar_position: 11 +--- + +# Functions + +[OCI Functions](https://docs.oracle.com/en-us/iaas/Content/Functions/Concepts/functionsoverview.htm) is a fully managed functions-as-a-service platform. Spring Cloud Oracle provides a client for invoking deployed functions. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-function + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-function") +} +``` + +## Using Functions + +The starter auto-configures a `Function` bean for invoking OCI Functions. + +```java +@Autowired +private Function function; + +public void invoke() { + InvokeFunctionResponse response = + function.invokeFunction(functionOcid, endpoint, mode, requestBody); +} +``` + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.function.enabled` | Enables the OCI Functions APIs | No | `true` | + +## Sample + +See [`spring-cloud-oci-function-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-function-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/generative-ai.md b/site/versioned_docs/version-2.0.1/oci/generative-ai.md new file mode 100644 index 00000000..7302bdd5 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/generative-ai.md @@ -0,0 +1,81 @@ +--- +title: Generative AI +sidebar_position: 13 +--- + +# Generative AI + +[OCI Generative AI](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm) provides managed chat and embedding models through Spring-friendly abstractions. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-gen-ai + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-gen-ai") +} +``` + +## Using Chat Models + +The starter auto-configures a `ChatModel` bean: + +```java +@Autowired +private ChatModel chatModel; + +public void chat() { + ChatResponse response = chatModel.chat("my chat prompt"); +} +``` + +## Using Embedding Models + +The starter auto-configures an `EmbeddingModel` bean: + +```java +@Autowired +private EmbeddingModel embeddingModel; + +public void embed() { + EmbedTextResponse response = embeddingModel.embed("my embedding text"); +} +``` + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.genai.enabled` | Enables the OCI Generative AI client | No | `true` | +| `spring.cloud.oci.genai.embedding.enabled` | Enables embedding APIs | No | `false` | +| `spring.cloud.oci.genai.embedding.on-demand-model-id` | On-demand embedding model ID | No | | +| `spring.cloud.oci.genai.embedding.dedicated-cluster-endpoint` | Dedicated embedding endpoint | No | | +| `spring.cloud.oci.genai.embedding.compartment` | Compartment for embedding | Yes | | +| `spring.cloud.oci.genai.embedding.truncate` | Truncation mode: `START`, `END`, or `NONE` | No | `NONE` | +| `spring.cloud.oci.genai.chat.enabled` | Enables chat APIs | No | `false` | +| `spring.cloud.oci.genai.chat.on-demand-model-id` | On-demand chat model ID | No | | +| `spring.cloud.oci.genai.chat.dedicated-cluster-endpoint` | Dedicated chat endpoint | No | | +| `spring.cloud.oci.genai.chat.compartment` | Compartment for chat | Yes | | +| `spring.cloud.oci.genai.chat.preample-override` | Overrides the model preamble | No | | +| `spring.cloud.oci.genai.chat.temperature` | Output temperature | No | `1.0` | +| `spring.cloud.oci.genai.chat.top-p` | Top P sampling value | No | `0.75` | +| `spring.cloud.oci.genai.chat.top-k` | Top K sampling value | No | `0.0` | +| `spring.cloud.oci.genai.chat.frequency-penalty` | Penalty for repeated tokens | No | `0.0` | +| `spring.cloud.oci.genai.chat.presence-penalty` | Penalty when a token already appears | No | `0.0` | +| `spring.cloud.oci.genai.chat.max-tokens` | Maximum output tokens | No | `600` | + +For chat and embedding, specify either an on-demand model ID or a dedicated cluster endpoint for the respective feature. + +## Sample + +See [`spring-cloud-oci-gen-ai-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-gen-ai-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/logging.md b/site/versioned_docs/version-2.0.1/oci/logging.md new file mode 100644 index 00000000..d1915f96 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/logging.md @@ -0,0 +1,52 @@ +--- +title: Logging +sidebar_position: 9 +--- + +# Logging + +[OCI Logging](https://docs.oracle.com/en-us/iaas/Content/Logging/home.htm) is a managed service for collecting and searching logs from OCI resources and applications. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-logging + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-logging") +} +``` + +## Using Logging + +The starter auto-configures a `LogService` bean for sending application logs to OCI Logging. + +```java +@Autowired +private LogService logService; + +public void putLog() { + PutLogsResponse response = logService.putLog("log-text"); +} +``` + +Set `spring.cloud.oci.logging.logId` in application configuration to target the destination log. + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.logging.enabled` | Enables the OCI Logging APIs | No | `true` | + +## Sample + +See [`spring-cloud-oci-logging-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-logging-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/nosql.md b/site/versioned_docs/version-2.0.1/oci/nosql.md new file mode 100644 index 00000000..bbb882f5 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/nosql.md @@ -0,0 +1,88 @@ +--- +title: Oracle NoSQL Database +sidebar_position: 12 +--- + +# Oracle NoSQL Database + +[Oracle NoSQL Database](https://docs.oracle.com/en-us/iaas/nosql-database/index.html) provides managed JSON, table, and key-value storage with flexible transaction guarantees. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-nosql + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-nosql") +} +``` + +## Using NoSQL Repositories + +The starter auto-configures `NosqlDBConfig` so you can use repository-based access. + +```yaml +spring: + cloud: + oci: + config: + type: file + region: + static: us-ashburn-1 +``` + +Enable repositories: + +```java +import com.oracle.nosql.spring.data.config.AbstractNosqlConfiguration; +import com.oracle.nosql.spring.data.repository.config.EnableNosqlRepositories; +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; + +@SpringBootApplication +@EnableNosqlRepositories +public class MyApp extends AbstractNosqlConfiguration { + public static void main(String[] args) { + SpringApplication.run(MyApp.class, args); + } +} +``` + +Define repository and entity types: + +```java +public interface BookRepository extends NosqlRepository { + Iterable findByAuthor(String author); + Iterable findByTitle(String title); +} +``` + +```java +@NosqlTable(tableName = "books") +public class Book { + @NosqlId(generated = true) + long id; + String title; + String author; + double price; +} +``` + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.nosql.enabled` | Enables the NoSQL DB configuration | No | `true` | + +## Sample + +See [`spring-cloud-oci-nosql-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-nosql-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/notifications.md b/site/versioned_docs/version-2.0.1/oci/notifications.md new file mode 100644 index 00000000..f999d82b --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/notifications.md @@ -0,0 +1,51 @@ +--- +title: Notifications +sidebar_position: 8 +--- + +# Notifications + +[OCI Notifications](https://www.oracle.com/devops/notifications/) is a pub/sub service for delivering alerts and messages to email, SMS, Functions, Slack, PagerDuty, and custom HTTPS endpoints. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-notification + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-notification") +} +``` + +## Using Notifications + +The starter auto-configures a `Notification` bean for topic, subscription, and publish operations. + +```java +@Autowired +private Notification notification; + +public void createTopic() { + CreateTopicResponse response = + notification.createTopic("my-topic", compartmentOcid); +} +``` + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.notification.enabled` | Enables the OCI Notifications APIs | No | `true` | + +## Sample + +See [`spring-cloud-oci-notification-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-notification-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/queues.md b/site/versioned_docs/version-2.0.1/oci/queues.md new file mode 100644 index 00000000..4967d31b --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/queues.md @@ -0,0 +1,54 @@ +--- +title: Queues +sidebar_position: 7 +--- + +# Queues + +[OCI Queue](https://docs.oracle.com/en-us/iaas/Content/queue/home.htm) is a managed queueing service for independently processed messages without loss or duplication. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-queue + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-queue") +} +``` + +## Using Queues + +The starter auto-configures a `Queue` bean for queue and message operations. + +```java +@Autowired +private Queue queue; + +public void createQueue() { + String queueId = queue.createQueue( + "my-queue", + compartmentId, + deadLetterQueueDeliveryCount, + retentionInSeconds); +} +``` + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.queue.enabled` | Enables the OCI Queue APIs | No | `true` | + +## Sample + +See [`spring-cloud-oci-queue-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-queue-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/storage.md b/site/versioned_docs/version-2.0.1/oci/storage.md new file mode 100644 index 00000000..90495dc7 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/storage.md @@ -0,0 +1,98 @@ +--- +title: Object Storage +sidebar_position: 4 +--- + +# Object Storage + +[OCI Object Storage](https://www.oracle.com/cloud/storage/) stores arbitrary files and objects. Spring Cloud Oracle adds both a storage API and a Spring `Resource` integration. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-storage + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-storage") +} +``` + +## Using Object Storage + +The starter auto-configures a `Storage` bean for bucket and object operations. + +```java +@Autowired +private Storage storage; + +public void createBucketAndUploadFile() { + Bucket bucket = storage.createBucket("my-bucket"); + + storage.upload( + "my-bucket", + "my-file.txt", + inputStream, + StorageObjectMetadata.builder().contentType("text/plain").build()); +} +``` + +## Spring Resource Support + +Object Storage objects can be accessed using Spring's resource abstraction. + +```java +@Value("https://objectstorage.${OCI_REGION}.oraclecloud.com/n/${OCI_NAMESPACE}/b/${OCI_BUCKET}/o/${OCI_OBJECT}") +private Resource myObjectResource; +``` + +```java +Resource objectResource = applicationContext.getResource( + "https://objectstorage.${OCI_REGION}.oraclecloud.com/n/${OCI_NAMESPACE}/b/${OCI_BUCKET}/o/${OCI_OBJECT}"); +``` + +The resulting `Resource` can be read like other Spring resources. + +```java +try (InputStream inputStream = myObjectResource.getInputStream()) { + String content = new String(inputStream.readAllBytes(), StandardCharsets.UTF_8); +} +``` + +Object Storage resources also implement Spring's `WritableResource`, so they can be used for write operations as well. + +```java +@Value("https://objectstorage.${OCI_REGION}.oraclecloud.com/n/${OCI_NAMESPACE}/b/${OCI_BUCKET}/o/${OCI_OBJECT}") +private WritableResource myWritableObjectResource; +``` + +You can also resolve a writable object resource programmatically from the application context. + +```java +WritableResource writableResource = (WritableResource) applicationContext.getResource( + "https://objectstorage.${OCI_REGION}.oraclecloud.com/n/${OCI_NAMESPACE}/b/${OCI_BUCKET}/o/${OCI_OBJECT}"); + +try (OutputStream outputStream = writableResource.getOutputStream()) { + outputStream.write("Hello Object Storage".getBytes(StandardCharsets.UTF_8)); +} +``` + +Data written through `WritableResource#getOutputStream()` is uploaded to OCI Object Storage when the stream is closed. + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.storage.enabled` | Enables the OCI Object Storage APIs | No | `true` | + +## Learn By Example + +See [`spring-cloud-oci-storage-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-storage-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/streaming.md b/site/versioned_docs/version-2.0.1/oci/streaming.md new file mode 100644 index 00000000..6ba31e2b --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/streaming.md @@ -0,0 +1,55 @@ +--- +title: Streaming +sidebar_position: 6 +--- + +# Streaming + +[OCI Streaming](https://docs.oracle.com/en-us/iaas/Content/Streaming/home.htm) is a managed service for ingesting and consuming high-volume data streams in real time. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-streaming + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-streaming") +} +``` + +## Using Streaming + +The starter auto-configures a `Streaming` bean for creating streams and sending or receiving messages. + +```java +@Autowired +private Streaming streaming; + +public void putMessages() { + PutMessagesResponse response = + streaming.putMessages(streamId, "key".getBytes(), "value".getBytes()); +} + +public void getMessages() { + GetMessagesResponse response = streaming.getMessages(streamId, "cursor"); +} +``` + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.stream.enabled` | Enables the OCI Streaming APIs | No | `true` | + +## Sample + +See [`spring-cloud-oci-streaming-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-streaming-sample). diff --git a/site/versioned_docs/version-2.0.1/oci/vault.md b/site/versioned_docs/version-2.0.1/oci/vault.md new file mode 100644 index 00000000..c7ddef2b --- /dev/null +++ b/site/versioned_docs/version-2.0.1/oci/vault.md @@ -0,0 +1,95 @@ +--- +title: Vault +sidebar_position: 5 +--- + +# Vault + +[OCI Vault](https://docs.oracle.com/en-us/iaas/Content/KeyManagement/home.htm) can be used both as a Spring property source and as an application bean for managing secrets. + +## Dependency Coordinates + +### Maven + +```xml + + com.oracle.cloud.spring + spring-cloud-oci-starter-vault + +``` + +### Gradle + +```groovy +dependencies { + implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-vault") +} +``` + +## Using Vault as a Property Source + +Secrets can be loaded dynamically into the Spring environment: + +```yaml +spring: + cloud: + oci: + config: + type: file + region: + static: us-ashburn-1 + vault: + enabled: true + compartment: ${OCI_COMPARTMENT_ID} + property-refresh-interval: 10000ms + property-sources: + - vault-id: ${OCI_VAULT_ID} +``` + +```java +@Value("${secretname}") +String secretValue; +``` + +## Using `VaultTemplate` + +The starter also auto-configures a `VaultTemplate` bean for secret operations. + +```yaml +spring: + cloud: + oci: + config: + type: file + region: + static: us-ashburn-1 + vault: + compartment: ${OCI_COMPARTMENT_ID} + vault-id: ${OCI_VAULT_ID} + enabled: true +``` + +```java +@Autowired +private VaultTemplate vaultTemplate; + +public String getSecretByName(String secretName) { + GetSecretBundleByNameResponse bundle = vaultTemplate.getSecret(secretName); + return vaultTemplate.decodeBundle(bundle); +} +``` + +## Configuration + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| `spring.cloud.oci.vault.enabled` | Enables the OCI Vault APIs | No | `true` | +| `spring.cloud.oci.vault.compartment` | Compartment for Vault APIs and property sources | Yes | | +| `spring.cloud.oci.vault.vault-id` | Vault OCID for Vault APIs | Yes | | +| `spring.cloud.oci.vault.property-refresh-interval` | Refresh interval for property reload | No | `10m` | +| `spring.cloud.oci.vault.property-sources` | List of Vaults to use as property sources | No | | +| `spring.cloud.oci.vault.property-sources[i].vault-id` | Vault OCID for a property source entry | Yes | | + +## Sample + +See [`spring-cloud-oci-vault-sample`](https://github.com/oracle/spring-cloud-oracle/tree/main/spring-cloud-oci/spring-cloud-oci-samples/spring-cloud-oci-vault-sample). diff --git a/site/versioned_docs/version-2.0.1/releases/_category_.json b/site/versioned_docs/version-2.0.1/releases/_category_.json new file mode 100644 index 00000000..7f747ba1 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/releases/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Releases", + "position": 5, + "link": { + "type": "generated-index", + "description": "Spring Cloud Oracle releases, changelog, and roadmap." + } +} diff --git a/site/versioned_docs/version-2.0.1/releases/changelog.md b/site/versioned_docs/version-2.0.1/releases/changelog.md new file mode 100644 index 00000000..3d560a31 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/releases/changelog.md @@ -0,0 +1,51 @@ +--- +title: Database Changelog +sidebar_position: 1 +--- + +# Release Notes + +List of upcoming and historic changes to Spring Cloud Oracle. + +### 2.0.1, TBD + +#### Database Starters + +- Upgrade third-party dependencies +- OpenTelemetry with Oracle AI Database documentation: + - Added starter usage and configuration guidance for `spring-boot-starter-oracle-otel` + - Documented how Oracle JDBC tracing spans flow into OpenTelemetry backends +- Oracle Spatial documentation and sample: + - Added starter documentation for GeoJSON-first `SDO_GEOMETRY` development + - Added the spatial sample reference covering the REST-based landmarks example + +#### Spring Cloud Stream Binder for TxEventQ + +- Upgrade third-party dependencies + +#### Spring Cloud OCI + +- Upgrade third-party dependencies +- OCI Object Storage `WritableResource` support: + - The OCI Object Storage Spring `Resource` now also implements `WritableResource`, allowing object uploads through `getOutputStream()` + - The Object Storage sample now demonstrates Spring `Resource`, `WritableResource`, and direct `Storage` API round trips for objects and bucket lifecycle operations + - The Object Storage documentation now includes `WritableResource` usage in addition to the existing `Resource` examples + + +### 2.0.0, March 31st + +The 2.0.0 adds support for Spring Boot 4 and Spring Framework 7, and includes numerous third party dependency updates. + +Notably, the documentation has been updated and moved to a new site. For historic documentation in the 1.x release line, review documentation from prior releases on GitHub. + +#### Database Starters + +- Upgrade third-party dependencies and migrated to Spring Boot 4 + +#### Spring Cloud Stream Binder for TxEventQ + +- Upgrade third-party dependencies and migrated to Spring Boot 4 + +#### Spring Cloud OCI + +- Upgrade third-party dependencies and migrated to Spring Boot 4 diff --git a/site/versioned_docs/version-2.0.1/stream-binder/_category_.json b/site/versioned_docs/version-2.0.1/stream-binder/_category_.json new file mode 100644 index 00000000..bae355ab --- /dev/null +++ b/site/versioned_docs/version-2.0.1/stream-binder/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Spring Cloud Stream Binder for TxEventQ", + "position": 3, + "link": { + "type": "generated-index", + "description": "Spring Cloud Stream support for Oracle Database Transactional Event Queues." + } +} diff --git a/site/versioned_docs/version-2.0.1/stream-binder/getting-started.md b/site/versioned_docs/version-2.0.1/stream-binder/getting-started.md new file mode 100644 index 00000000..7c58be4c --- /dev/null +++ b/site/versioned_docs/version-2.0.1/stream-binder/getting-started.md @@ -0,0 +1,148 @@ +--- +title: Get Started +sidebar_position: 2 +--- + +In this section, we’ll walk through how to get started with the Spring Cloud Stream binder for Oracle AI Database TxEventQ. + +A end-to-end sample for the binder can be found here: [TxEventQ Stream Binder Sample Application](https://github.com/oracle/spring-cloud-oracle/tree/main/database/spring-cloud-stream-binder-oracle-txeventq/spring-cloud-stream-binder-txeventq-sample) + +## Dependency Coordinates + +The binder JAR is available on Maven central, and may be added to your POM like so: + +```xml + + com.oracle.database.spring.cloud-stream-binder + spring-cloud-stream-binder-oracle-txeventq + +``` + +## Database Permissions + +The database user producing/consuming events with the stream binder for TxEventQ requires the following database permissions: + +```sql +grant execute on dbms_aq to testuser; +grant execute on dbms_aqadm to testuser; +grant execute on dbms_aqin to testuser; +grant execute on dbms_aqjms_internal to testuser; +grant execute on DBMS_RESOURCE_MANAGER to testuser; +grant select on sys.aq$_queue_shards to testuser; +grant select on user_queue_partition_assignment_table to testuser; +``` + +## Database Connection + +The stream binder uses a standard Spring datasource JDBC connection to stream events. With YAML properties, it should look something like this: + +```yaml +spring: + datasource: + username: ${USERNAME} + password: ${PASSWORD} + url: ${JDBC_URL} + driver-class-name: oracle.jdbc.OracleDriver + type: oracle.ucp.jdbc.PoolDataSourceImpl + oracleucp: + initial-pool-size: 1 + min-pool-size: 1 + max-pool-size: 30 + connection-pool-name: TxEventQSample + connection-factory-class-name: oracle.jdbc.pool.OracleDataSource +``` + +## Implementing Producers and Consumers + +With Spring Cloud Stream, the producer/consumer code abstracts away references to TxEventQ, using pure Spring APIs to produce and consume messages. + +Let’s start by implementing a producer that returns a phrase word-by-word, indicating when it has processed the whole phrase. + +```java +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.function.Supplier; + +public class WordSupplier implements Supplier { +private final String[] words; +private final AtomicInteger idx = new AtomicInteger(0); +private final AtomicBoolean done = new AtomicBoolean(false); + + public WordSupplier(String phrase) { + this.words = phrase.split(" "); + } + + @Override + public String get() { + int i = idx.getAndAccumulate(words.length, (x, y) -> { + if (x < words.length - 1) { + return x + 1; + } + done.set(true); + return 0; + }); + return words[i]; + } + + public boolean done() { + return done.get(); + } +} +``` + +Next, let’s add Spring beans for producers and consumers, including our WordSupplier and two more simple functional interfaces. + +```java +import java.util.function.Consumer; +import java.util.function.Function; + +import org.springframework.beans.factory.annotation.Value; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +@Configuration +public class StreamConfiguration { +private @Value("${phrase}") String phrase; + + @Bean + public Function toUpperCase() { + return String::toUpperCase; + } + + @Bean + public Consumer stdoutConsumer() { + return s -> System.out.println("Consumed: " + s); + } + + @Bean + public WordSupplier wordSupplier() { + return new WordSupplier(phrase); + } +} +``` + +## Wire up producers and consumer bindings with Spring Cloud Stream + +Let’s configure the Spring Cloud Stream bindings. + +In our binding configuration, the wordSupplier producer has toUpperCase as a destination, and the stdoutConsumer consumer reads from toUpperCase. The result of this acyclic producer-consumer configuration is that each word from the phrase is converted to uppercase and sent to stdout. + +```yaml +phrase: "Spring Cloud Stream simplifies event-driven microservices with powerful messaging capabilities." + +spring: + cloud: + stream: + bindings: + wordSupplier-out-0: + destination: toUpperCase-in-0 + group: t1 + producer: + required-groups: + - t1 + stdoutConsumer-in-0: + destination: toUpperCase-out-0 + group: t1 + function: + definition: wordSupplier;toUpperCase;stdoutConsumer +``` \ No newline at end of file diff --git a/site/versioned_docs/version-2.0.1/stream-binder/overview.md b/site/versioned_docs/version-2.0.1/stream-binder/overview.md new file mode 100644 index 00000000..b14ea3d1 --- /dev/null +++ b/site/versioned_docs/version-2.0.1/stream-binder/overview.md @@ -0,0 +1,23 @@ +--- +title: Overview +sidebar_position: 1 +--- + +# Spring Cloud Stream Binder for Oracle TxEventQ + +[Spring Cloud Stream](https://spring.io/projects/spring-cloud-stream) is a Java framework designed for building event-driven microservices backed by a scalable, fault-tolerant messaging systems. The Oracle AI Database [Transactional Event Queues (TxEventQ)](https://www.oracle.com/database/advanced-queuing/) stream binder implementation allows developers to leverage Oracle’s database messaging platform within the Spring Cloud Stream ecosystem, all while keeping your data within the converged database. + +The TxEventQ stream binder integration combines the power of Oracle’s database-enabled messaging system with Spring Cloud Stream’s functional, event-driven development model. With the TxEventQ stream binder, Spring applications can seamlessly produce and consume messages with Oracle AI Database’s high-performance, transactional messaging system, benefiting from Spring’s abstraction layer and configuration capabilities. + +## Key Features of TxEventQ Stream Binder + +Oracle Database TxEventQ provides a high-throughput, reliable messaging platform built directly into the database. + +- Real-time messaging with multiple publishers, consumers, and topics — all with a simple functional interface. +- High throughput on RAC: 100 billion messages per day were measured on an 8-node Oracle Real Application Clusters (RAC) database. +- Convergence of data: Your messaging platform lives within the database. +- Integration with Spring Cloud Stream makes it easy-to-use, and easy to get started. + +## Database Version Support + +The stream binder supports database versions from Oracle Database 23ai. For best results, we recommend using the latest patch version of Oracle AI Database 26ai. diff --git a/site/versioned_sidebars/version-2.0.1-sidebars.json b/site/versioned_sidebars/version-2.0.1-sidebars.json new file mode 100644 index 00000000..caea0c03 --- /dev/null +++ b/site/versioned_sidebars/version-2.0.1-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/site/versions.json b/site/versions.json index 3aea0349..80c8bf8d 100644 --- a/site/versions.json +++ b/site/versions.json @@ -1,3 +1,4 @@ [ + "2.0.1", "2.0.0" ]