1.0.1-SNAPSHOT

1. Introduction

Spring Cloud for OCI, part of the Spring Cloud umbrella project, eases the integration with hosted OCI Services. It offers a convenient way to interact with OCI provided services using well-known Spring idioms and APIs, such as storage resources. Developers can build their application around the hosted services without having to worry about infrastructure or maintenance.

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

2. Getting Started

This section describes how to get started using Spring Cloud OCI libraries.

2.1. Spring Cloud OCI

Spring Cloud OCI module dependencies can be used directly in Maven with a direct configuration of the module. The Spring Cloud OCI module includes all transitive dependencies for the Spring modules, and the OCI SDK that are needed to operate the modules. The general dependency configuration will look like this:

<dependencies>
  <dependency>
    <groupId>com.oracle.cloud.spring</groupId>
    <artifactId>spring-cloud-oci-starter</artifactId>
    <version>{spring-cloud-oci-version}</version>
  </dependency>
</dependencies>

Different modules can be included by replacing the module name with the respective one (for example, spring-cloud-oci-starter-storage instead of spring-cloud-oci-starter)

2.1.1. Starter Dependencies

Spring Cloud OCI offers starter dependencies through Maven to easily depend on different modules of the library. Each starter contains all the dependencies and transitive dependencies needed to begin using their corresponding Spring Cloud OCI module.

For example, to write a Spring application with Cloud Storage, you include the spring-cloud-oci-starter-storage dependency in your project. You do not need to include the underlying spring-cloud-oci-storage dependency, because the starter dependency includes it.

A summary of these artifacts is provided here.

Spring Cloud OCI Starter Description Maven Artifact Name

Core

Automatically configure authentication

com.oracle.cloud.spring:spring-cloud-oci-starter

Object Storage

Provides integrations with OCI Cloud Storage

com.oracle.cloud.spring:spring-cloud-oci-starter-storage

2.2. Learning Spring Cloud OCI

There are a variety of resources to help you learn how to use Spring Cloud OCI libraries.

2.2.1. Sample Applications

The easiest way to learn how to use Spring Cloud OCI is to consult the sample applications on Github. Spring Cloud OCI provides sample applications which demonstrate how to use every integration in the library. The following table highlights several samples of the most used integrations in Spring Cloud OCI.

OCI Integration Sample Application

Cloud Storage

spring-cloud-oci-storage-sample

Cloud Notification

spring-cloud-oci-notification-sample

Cloud Logging

spring-cloud-oci-logging-sample

Cloud Streaming

spring-cloud-oci-streaming-sample

Cloud Function

spring-cloud-oci-function-sample

Cloud Queue

spring-cloud-oci-queue-sample

Each sample application demonstrates how to use Spring Cloud OCI libraries in context and how to setup the dependencies for the project. The applications are fully functional and can be deployed to OCI as well.

3. Spring Cloud OCI Core

Spring Cloud OCI provides a Spring Boot starter to auto-configure the core components.

Maven coordinates, using Spring Cloud OCI BOM:

<dependency>
    <groupId>com.oracle.cloud.spring</groupId>
    <artifactId>spring-cloud-oci-starter</artifactId>
</dependency>

Gradle coordinates:

dependencies {
    implementation("com.oracle.cloud.spring:spring-cloud-oci-starter")
}

3.1. Authentication Configuration

Spring Cloud OCI allows you to authenticate with OCI using various available options.

3.1.1. Configuration File Based Authentication

By default, configuration file based authentication is enabled. To set it explicitly, set the property spring.cloud.oci.config.type to FILE. The following are optional configurations to set a custom configuration profile name and file name.

spring.cloud.oci.config.profile = DEFAULT
spring.cloud.oci.config.file = <FILE_PATH>

For further details about the Authentication configuration file, refer SDK and CLI Configuration File

3.1.2. Simple Authentication

Set the property spring.cloud.oci.config.type to SIMPLE and add the following properties:

spring.cloud.oci.config.type = SIMPLE
spring.cloud.oci.config.userId = ocid1.user.oc1..<unique_ID>
spring.cloud.oci.config.tenantId = ocid1.tenancy.oc1..<unique_ID>
spring.cloud.oci.config.fingerprint = <FINGERPRINT>
spring.cloud.oci.config.privateKey = <PRIVATE_KEY_FILE_PATH>
spring.cloud.oci.config.passPhrase = <PASS_PHRASE>
spring.cloud.oci.config.region = <REGION>

Note: All the preceding properties are mandatory except spring.cloud.oci.config.passPhrase

3.1.3. Instance Principal Configuration

Set the config.type to INSTANCE_PRINCIPAL as shown here.

spring.cloud.oci.config.type = INSTANCE_PRINCIPAL

For further details, refer to OCI Instance Principal Authentication

3.1.4. Resource Principal Configuration

Set the config.type to RESOURCE_PRINCIPAL as shown here.

spring.cloud.oci.config.type = RESOURCE_PRINCIPAL

For further details, refer to OCI Resource Principal Authentication

3.1.5. Session token Configuration

Set the config.type to SESSION_TOKEN as shown here.

spring.cloud.oci.config.type = SESSION_TOKEN

For further details, refer to docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm#ariaid-title12

3.2. Region Configuration

OCI services are available in different regions. Based on the custom requirements, you can host the application on different OCI regions. The following configuration allows you to set a specific region for the entire application.

spring.cloud.oci.region.static = us-ashburn-1

Region value set in the preceding property takes precedence over the property spring.cloud.oci.config.region and region from the Authentication configuration file

3.3. Compartment Configuration

A compartment is a logical container, used to organize and control access to the OCI Resources (Compute, Storage, Network, Load Balancer, etc.) created within that compartment. The following configuration allows you to set the default compartment for your application.

spring.cloud.oci.compartment.static = <COMPARTMENT_OCID>

4. Cloud Storage

Oracle Cloud Storage allows you to store any types of file. A Spring Boot starter is provided to auto-configure the various Storage components.

Maven coordinates, using Spring Cloud OCI BOM:

<dependency>
    <groupId>com.oracle.cloud.spring</groupId>
    <artifactId>spring-cloud-oci-starter-storage</artifactId>
</dependency>

Gradle coordinates:

dependencies {
    implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-storage")
}

4.1. Using Cloud Storage

The starter automatically configures and registers a Storage bean in the Spring application context. The Storage bean (link[Javadoc]) can be used to list, create, update or delete buckets and objects.

@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());
}

4.2. Cloud Storage Objects Spring Resources

Spring Resources are an abstraction for several low-level resources, such as file system files, classpath files, servlet context-relative files, etc. Spring Cloud OCI adds a new resource type: an Oracle Cloud Storage (OCS) object.

The Spring Resource Abstraction for Oracle Cloud Storage allows OCS objects to be accessed by their OCS URL using the @Value annotation or the Spring application context:

@Value("ocs://[YOUR_OCS_BUCKET]/[OCS_FILE_NAME]")
private Resource ocsResource;
SpringApplication.run(...).getResource("ocs://[YOUR_OCS_BUCKET]/[OCS_FILE_NAME]");

This creates a Resource object that can be used to read the object, among other possible operations.

Currently this resource is only readable.

4.3. Configuration

The Spring Boot Starter for Oracle Cloud Storage provides the following configuration options:

Name

Description

Required

Default value

spring.cloud.oci.storage.enabled

Enables the OCI storage APIs.

No

true

4.4. Sample

A sample application provided here contains the examples to demonstrate the usage of OCI Spring Cloud Storage module.

5. Cloud Notifications

OCI Notifications is a highly available, low latency publish/subscribe (pub/sub) service that sends alerts and messages to Oracle Cloud Functions, email, SMS, and message delivery partners, including Slack, PagerDuty and custom HTTPS endpoint. Spring Cloud module for Oracle Cloud Notifications allows you to create a Topic, then create and publish messages to multiple subscription types such as Oracle Cloud Functions, email, SMS, Slack, PagerDuty and custom HTTPS endpoint. A Spring Boot starter is provided to auto-configure the various Notification components.

Maven coordinates, using Spring Cloud OCI BOM:

<dependency>
    <groupId>com.oracle.cloud.spring</groupId>
    <artifactId>spring-cloud-oci-starter-notification</artifactId>
</dependency>

Gradle coordinates:

dependencies {
    implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-notification")
}

5.1. Using Cloud Notifications

The starter automatically configures and registers a Notification bean in the Spring application context. The Notification bean (link[Javadoc]) can be used to create a Topic, create, list, get a Subscription, and publish messages to the Subscriptions in a Topic.

@Autowired
private Notification notification;

public void createTopic() {

    CreateTopicResponse response = notification.createTopic("my-topic", <<compartment-ocid>>);
}

5.2. Configuration

The Spring Boot Starter for Oracle Cloud Notifications provides the following configuration options:

Name

Description

Required

Default value

spring.cloud.oci.notification.enabled

Enables the OCI Notifications APIs.

No

true

5.3. Sample

A sample application provided here contains the examples to demonstrates the usage of OCI Spring Cloud Notification module.

6. Cloud Logging

OCI Logging service is a highly scalable and fully managed single pane of glass for all the logs in your tenancy. Logging provides access to logs from OCI resources. These logs include critical diagnostic information that describes how resources are performing and being accessed. Use Logging to enable, manage, and search Audit, Service, and Custom logs. The Spring Cloud module for OCI Logging allows ingesting logs associated with a logId. A Spring Boot starter is provided to auto-configure the Logging component.

Maven coordinates, using Spring Cloud OCI BOM:

<dependency>
    <groupId>com.oracle.cloud.spring</groupId>
    <artifactId>spring-cloud-oci-starter-logging</artifactId>
</dependency>

Gradle coordinates:

dependencies {
    implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-logging")
}

6.1. Using Cloud Logging

The starter automatically configures and registers a Logging bean in the Spring application context. The Logging bean (link[Javadoc]) can be used to ingest logs associated with a logId specified in the property spring.cloud.oci.logging.logId within the application configuration file

@Autowired
private LogService logService;

public void putLog() {

    PutLogsResponse response = logService.putLog("log-text");
}

6.2. Configuration

The Spring Boot Starter for Oracle Cloud Logging provides the following configuration options:

Name

Description

Required

Default value

spring.cloud.oci.logging.enabled

Enables the OCI Logging APIs.

No

true

6.3. Sample

A sample application provided here contains the examples to demonstrates the usage of OCI Spring Cloud Logging module.

7. Cloud Functions

OCI Functions is a fully managed, multi-tenant, highly scalable, on-demand, Functions-as-a-Service platform. It is built on enterprise-grade Oracle Cloud Infrastructure and powered by the Fn Project open source engine. Use OCI Functions when you want to focus on writing code to meet business needs. The Spring Cloud module for OCI Functions allows to invoke an OCI Function. A Spring Boot starter is provided to auto-configure the Function component.

Maven coordinates, using Spring Cloud OCI BOM:

<dependency>
    <groupId>com.oracle.cloud.spring</groupId>
    <artifactId>spring-cloud-oci-starter-function</artifactId>
</dependency>

Gradle coordinates:

dependencies {
    implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-function")
}

7.1. Using Cloud Functions

The starter automatically configures and registers a Function bean in the Spring application context. The Function bean (link[Javadoc]) can be used to invoke a function with parameter inputs 'functionOcid' and 'endpoint'

@Autowired
private Function function;

public void invoke() {

    InvokeFunctionResponse invokeFunctionResponse = function.invokeFunction(functionOcid, endpoint, mode, requestBody);
}

7.2. Configuration

The Spring Boot Starter for Oracle Cloud Function provides the following configuration options:

Name

Description

Required

Default value

spring.cloud.oci.function.enabled

Enables the OCI Functions APIs.

No

true

7.3. Sample

A sample application provided here contains the examples to demonstrates the usage of OCI Spring Cloud Function module.

8. Cloud Stream

OCI Streaming service provides a fully managed, scalable, and durable solution for ingesting and consuming high-volume data streams in real time. A Spring Boot starter is provided to auto-configure the Streaming component.

Maven coordinates, using Spring Cloud OCI BOM:

<dependency>
    <groupId>com.oracle.cloud.spring</groupId>
    <artifactId>spring-cloud-oci-starter-streaming</artifactId>
</dependency>

Gradle coordinates:

dependencies {
    implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-streaming")
}

8.1. Using Cloud Streaming

The starter automatically configures and registers a Streaming bean in the Spring application context. The Streaming bean (link[Javadoc]) can be used to create streamPool, stream in OCI and ingest and consume high-volume data streams with a streamId

@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");
}

8.2. Configuration

The Spring Boot Starter for Oracle Cloud Stream provides the following configuration options:

Name

Description

Required

Default value

spring.cloud.oci.stream.enabled

Enables the OCI Streaming APIs.

No

true

8.3. Sample

A sample application provided here contains the examples to demonstrates the usage of OCI Spring Cloud Streaming module.

9. Cloud Queues

OCI Queues is a highly available, low latency publish/subscribe (pub/sub) service, handles high volume transactional data that requires independently processed messages without loss or duplication. Spring Cloud module for Oracle Cloud Queues allows you to create a queue, get a queue, list queues, delete a queue, put messages, get messages, update messages and delete a message. A Spring Boot starter is provided to auto-configure the various Queue components.

Maven coordinates, using Spring Cloud OCI BOM:

<dependency>
    <groupId>com.oracle.cloud.spring</groupId>
    <artifactId>spring-cloud-oci-starter-queue</artifactId>
</dependency>

Gradle coordinates:

dependencies {
    implementation("com.oracle.cloud.spring:spring-cloud-oci-starter-queue")
}

9.1. Using Cloud Queues

The starter automatically configures and registers a Queue bean in the Spring application context. The Queue bean (link[Javadoc]) can be used to create a queue, get a queue, list queues, delete a queue, put messages, get messages, update messages and delete a message.

@Autowired
private Queue queue;

public void createQueue() {

    String queueId = queue.createQueue("my-queue", <<compartmentId>>, <<deadLetterQueueDeliveryCount>>, <<retentionInSeconds>>);
}

9.2. Configuration

The Spring Boot Starter for Oracle Cloud Queues provides the following configuration options:

Name

Description

Required

Default value

spring.cloud.oci.queue.enabled

Enables the OCI Queue APIs.

No

true

9.3. Sample

A sample application provided here contains the examples to demonstrates the usage of OCI Spring Cloud Queue module.

10. Configuration properties

To see the list of all OCI-related configuration properties see the Appendix page.

10.1. Configuration Refresh

The following properties are supported for Configuration auto-refresh at runtime without the need to restart applications

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 explicitly refresh the externalized configuration during runtime. Add the corresponding build dependency to enable the Actuator:

Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Gradle:

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-actuator")
}

Set management.endpoints.web.exposure.include=refresh in the externalized configuration file of the Spring Boot Application to enable /actuator/refresh endpoint.

To refresh the updated Configuration properties at runtime make a POST API call to /actuator/refresh endpoint