Merge pull request #263 from eclipse/enhance-oracle-configuration

Enhance Oracle NoSQL Configuration

Author: otaviojava

README.adoc

@@ -1058,13 +1058,13 @@ Stream<Person> stream = template.select(Person.class , filter);
 
 image::https://www.jnosql.org/img/logos/oracle.png[Oracle NoSQL Project,align="center"width=25%,height=25%]
 
-https://www.oracle.com/database/nosql/technologies/nosql/[Oracle NoSQL Database] is a native multi-model database that provides flexible data models for documents, graphs, and key values. You can develop high-performance applications using a user-friendly SQL-like query language or JavaScript extensions.
+[Oracle NoSQL Database](https://www.oracle.com/database/nosql/technologies/nosql/) is a versatile multi-model database offering flexible data models for documents, graphs, and key-value pairs. It empowers developers to build high-performance applications using a user-friendly SQL-like query language or JavaScript extensions.
 
-This API offers support for *Document* and *Key-Value* data types.
+This API provides support for *Document* and *Key-Value* data types.
 
-=== How To Install
+=== Installation
 
-You can use either the Maven or Gradle dependencies:
+You can include Oracle NoSQL as a dependency using either Maven or Gradle:
 
 [source,xml]
 ----
@@ -1077,41 +1077,60 @@ You can use either the Maven or Gradle dependencies:
 
 === Configuration
 
-This API provides the ```OracleNoSQLConfigurations``` class to programmatically establish the credentials.
-Please note that you can establish properties using the https://microprofile.io/microprofile-config/[MicroProfile Config] specification.
+The API offers the `OracleNoSQLConfigurations` class to programmatically set up credentials. It also supports configuration via the [MicroProfile Config](https://microprofile.io/microprofile-config/) specification.
 
 [cols="Oracle NoSQL Properties"]
 |===
 | Property Name | Description
 
-| `jnosql.oracle.nosql.host` | Specifies the hostname or IP address of the Oracle NoSQL database server.
+| `jnosql.oracle.nosql.host` | Hostname or IP address of the Oracle NoSQL database server.
 
-| `jnosql.oracle.nosql.user` | Specifies the username used to authenticate with the Oracle NoSQL database.
+| `jnosql.oracle.nosql.user` | Username for Oracle NoSQL database authentication.
 
-| `jnosql.oracle.nosql.password` | Specifies the password used to authenticate with the Oracle NoSQL database.
+| `jnosql.oracle.nosql.password` | Password for Oracle NoSQL database authentication.
 
-| `jnosql.oracle.nosql.table.read.limit` | Specifies the desired throughput of read operations when creating a table using Eclipse JNoSQL.
+| `jnosql.oracle.nosql.table.read.limit` | Desired throughput of read operations when creating tables with Eclipse JNoSQL.
 
-| `jnosql.oracle.nosql.table.write.limit` | Specifies the desired throughput of write operations when creating a table using Eclipse JNoSQL.
+| `jnosql.oracle.nosql.table.write.limit` | Desired throughput of write operations when creating tables with Eclipse JNoSQL.
 
-| `jnosql.oracle.nosql.table.storage.gb` | Specifies the maximum storage, in gigabytes, to be consumed by a table created using Eclipse JNoSQL.
+| `jnosql.oracle.nosql.table.storage.gb` | Maximum storage in gigabytes for tables created with Eclipse JNoSQL.
 
-| `jnosql.oracle.nosql.table.wait.millis` | Specifies the total amount of time to wait, in milliseconds, when creating a table.
+| `jnosql.oracle.nosql.table.wait.millis` | Total waiting time in milliseconds when creating a table.
 
-| `jnosql.oracle.nosql.table.delay.millis` | Specifies the amount of time to wait, in milliseconds, between polling attempts when creating a table.
+| `jnosql.oracle.nosql.table.delay.millis` | Time between polling attempts in milliseconds when creating a table.
 
-| `jnosql.oracle.nosql.deployment` | Specifies the deployment type for Oracle NoSQL database.
+| `jnosql.oracle.nosql.tenant.id` | Tenant ID for Oracle NoSQL database in a Cloud deployment.
 
-| `jnosql.oracle.nosql.tenant.id` | Specifies the Oracle NoSQL database tenant ID for Cloud deployment.
+| `jnosql.oracle.nosql.fingerprint` | Fingerprint for authentication with Oracle NoSQL database in a Cloud deployment.
 
-| `jnosql.oracle.nosql.fingerprint` | Specifies the fingerprint for authentication with Oracle NoSQL database for Cloud deployment.
+| `jnosql.oracle.nosql.private.key` | Private key for authentication with Oracle NoSQL database in a Cloud deployment.
 
-| `jnosql.oracle.nosql.private.key` | Specifies the private key for authentication with Oracle NoSQL database for Cloud deployment.
-|===
+| `jnosql.oracle.nosql.compartment` | Compartment name in Oracle Cloud Infrastructure.
+
+| `jnosql.oracle.nosql.namespace` | Namespace name in Oracle NoSQL on-premises.
+
+| `jnosql.oracle.nosql.profile.name` | Specifies the profile name used to load session token in Oracle NoSQL cloud.
+
+| `jnosql.oracle.nosql.config.file` | Specifies the path of configuration file used to load session token in Oracle NoSQL cloud.
+
+| `jnosql.oracle.nosql.deployment` | Specifies the deployment type for Oracle NoSQL database. You can choose from the following options:
 
+- `ON_PREMISES`: Represents an on-premises deployment where software solutions are deployed and managed within an organization's physical premises or data centers.
 
+- `CLOUD_API_KEY`: Represents a cloud deployment using API key for authentication and authorization.
 
-This is an example using Oracle NoSQL's Document API with MicroProfile Config.
+- `CLOUD_INSTANCE_PRINCIPAL`: Represents a cloud deployment using instance principal for authentication and authorization.
+
+- `CLOUD_RESOURCE_PRINCIPAL`: Represents a cloud deployment using resource principal for authentication and authorization.
+
+- `CLOUD_INSTANCE_OBO_USER`: Represents a cloud deployment using instance principal for delegation with an OBO token.
+
+- `CLOUD_SECURITY_TOKEN`: Represents a "Cloud" deployment using resource principal for delegation with an OBO token.
+|===
+
+Below are examples using Oracle NoSQL's Document API and Key-Value API with MicroProfile Config.
+
+**Document API Example:**
 
 [source,properties]
 ----
@@ -1120,7 +1139,7 @@ jnosql.document.database=library
 jnosql.oracle.nosql.host=http://localhost:8080
 ----
 
-This is an example using Oracle NoSQL's Key-Value API with MicroProfile Config.
+**Key-Value API Example:**
 
 [source,properties]
 ----
@@ -1129,7 +1148,7 @@ jnosql.keyvalue.database=library
 jnosql.oracle.nosql.host=http://localhost:8080
 ----
 
-The config settings are the default behavior; nevertheless, there is an option to do it programmatically. Create a class that implements the `Supplier<ArangoDBDocumentManager>` and then defines it as an `@Alternative` and the `Priority`.
+Although these are the default configuration settings, you have the option to configure them programmatically. Create a class that implements `Supplier<OracleNoSQLDocumentManager>`, annotate it with `@Alternative`, and set the priority using `@Priority`.
 
 [source,java]
 ----
@@ -1151,7 +1170,7 @@ public class ManagerSupplier implements Supplier<OracleNoSQLDocumentManager> {
 
 === Repository
 
-The ```OracleNoSQLRepository``` interface is an extension of the Repository interface that allows execution of SQL via the ```@SQL``` annotation. Also, it's possible to combine with ```@Param``` annotation to execute parameterized SQL queries:
+The `OracleNoSQLRepository` interface extends the Repository interface and allows executing SQL queries using the `@SQL` annotation. You can also combine it with the `@Param` annotation for parameterized SQL queries:
 
 [source,java]
 ----
@@ -1169,7 +1188,7 @@ interface PersonRepository extends OracleNoSQLRepository<Person, String> {
 
 === Template
 
-The ```OracleNoSQLTemplate``` interface is a specialization of the ```DocumentTemplate``` interface that allows using synchronous SQL operation.
+The `OracleNoSQLTemplate` interface, an extension of the `DocumentTemplate`, enables synchronous SQL operations.
 
 [source,java]
 ----

jnosql-nosql-oracle/src/main/java/org/eclipse/jnosql/databases/oracle/communication/DefaultOracleNoSQLDocumentManager.java

@@ -20,6 +20,7 @@
 import jakarta.json.JsonValue;
 import jakarta.json.bind.Jsonb;
 import oracle.nosql.driver.NoSQLHandle;
+import oracle.nosql.driver.TimeToLive;
 import oracle.nosql.driver.ops.DeleteRequest;
 import oracle.nosql.driver.ops.GetRequest;
 import oracle.nosql.driver.ops.GetResult;
@@ -86,26 +87,17 @@ public String name() {
     @Override
     public DocumentEntity insert(DocumentEntity entity) {
         Objects.requireNonNull(entity, "entity is required");
-        Map<String, Object> entityMap = new HashMap<>(entity.toMap());
-        entityMap.put(ENTITY, entity.name());
-        String id = entity.find(ID).map(Document::get)
-                .map(Object::toString)
-                .orElseGet(() -> UUID.randomUUID().toString());
-
-        MapValue mapValue = new MapValue().put(ORACLE_ID, id).put(ENTITY, entity.name());
-        MapValue contentVal = mapValue.putFromJson("content", jsonB.toJson(entityMap),
-                OPTIONS);
-        PutRequest putRequest = new PutRequest()
-                .setValue(contentVal)
-                .setTableName(name());
-
-        serviceHandle.put(putRequest);
+        put(entity, TimeToLive.DO_NOT_EXPIRE);
         return entity;
     }
 
+
     @Override
     public DocumentEntity insert(DocumentEntity entity, Duration ttl) {
-       throw new UnsupportedOperationException("Oracle NoSQL database does not support TTL");
+       Objects.requireNonNull(entity, "entity is required");
+        Objects.requireNonNull(ttl, "ttl is required");
+        put(entity, TimeToLive.ofHours(ttl.toHours()));
+        return entity;
     }
 
     @Override
@@ -117,7 +109,10 @@ public Iterable<DocumentEntity> insert(Iterable<DocumentEntity> entities) {
 
     @Override
     public Iterable<DocumentEntity> insert(Iterable<DocumentEntity> entities, Duration ttl) {
-        throw new UnsupportedOperationException("Oracle NoSQL database does not support TTL");
+        Objects.requireNonNull(entities, "entities is required");
+        Objects.requireNonNull(ttl, "ttl is required");
+        StreamSupport.stream(entities.spliterator(), false).forEach(d -> insert(d, ttl));
+        return entities;
     }
 
     @Override
@@ -286,4 +281,23 @@ private List<DocumentEntity> executeSQL(String sql, List<FieldValue> params) {
         } while (!queryRequest.isDone());
         return entities;
     }
+
+    private void put(DocumentEntity entity, TimeToLive ttl) {
+        Map<String, Object> entityMap = new HashMap<>(entity.toMap());
+        entityMap.put(ENTITY, entity.name());
+        String id = entity.find(ID).map(Document::get)
+                .map(Object::toString)
+                .orElseGet(() -> UUID.randomUUID().toString());
+
+        MapValue mapValue = new MapValue().put(ORACLE_ID, id).put(ENTITY, entity.name());
+        MapValue contentVal = mapValue.putFromJson("content", jsonB.toJson(entityMap),
+                OPTIONS);
+        PutRequest putRequest = new PutRequest()
+                .setValue(contentVal)
+                .setTTL(ttl)
+                .setTableName(name());
+
+        serviceHandle.put(putRequest);
+    }
+
 }

jnosql-nosql-oracle/src/main/java/org/eclipse/jnosql/databases/oracle/communication/DeploymentType.java

@@ -20,6 +20,7 @@
 import org.eclipse.jnosql.communication.Configurations;
 import org.eclipse.jnosql.communication.Settings;
 
+import java.io.File;
 import java.io.IOException;
 import java.util.List;
 import java.util.Optional;
@@ -33,8 +34,12 @@ public enum DeploymentType implements Function<Settings, Optional<AuthorizationP
     /**
      * Represents an "On-premises" deployment where software solutions are deployed and managed
      * within an organization's physical premises or data centers.
+     * Usage: Choose this deployment type when your software solutions are hosted and managed within your organization's physical infrastructure.
+     * - Authentication: Uses username and password for access.
+     * - Configuration: Requires USER (username) and PASSWORD (password).
+     *   If not provided, it falls back to default values or empty credentials.
      */
-    ON_PREMISES{
+    ON_PREMISES {
         @Override
         public Optional<AuthorizationProvider> apply(Settings settings) {
             String user = settings.get(List.of(OracleNoSQLConfigurations.USER.get(), Configurations.USER.get()))
@@ -51,10 +56,9 @@ public Optional<AuthorizationProvider> apply(Settings settings) {
     },
 
     /**
-     * Represents a "Cloud" deployment where software solutions are delivered and managed
-     * over the internet (the cloud) by Oracle cloud provider.
+     * Represents a "Cloud" deployment using API key for authentication and authorization.
      */
-    CLOUD{
+    CLOUD_API_KEY {
         @Override
         public Optional<AuthorizationProvider> apply(Settings settings) {
 
@@ -69,14 +73,58 @@ public Optional<AuthorizationProvider> apply(Settings settings) {
             if(user != null && password.length > 0 && tenantId != null && fingerprint != null && privateKey != null) {
                 return Optional.of(new SignatureProvider(tenantId, user, fingerprint, privateKey, password));
             }
-
             try {
                 return Optional.of(new SignatureProvider());
             } catch (IOException e) {
                 throw new OracleNoSQLException("Error to load configuration to Oracle Cloud at Oracle NoSQL", e);
             }
 
         }
+    },
+    /**
+     * Represents a "Cloud" deployment using resource principal for authentication and authorization.
+     */
+    CLOUD_INSTANCE_PRINCIPAL {
+        @Override
+        public Optional<AuthorizationProvider> apply(Settings settings) {
+            return Optional.of(SignatureProvider.createWithInstancePrincipal());
+        }
+    },
+    /**
+     * Represents a "Cloud" deployment using resource principal for authentication and authorization.
+     */
+    CLOUD_RESOURCE_PRINCIPAL {
+        @Override
+        public Optional<AuthorizationProvider> apply(Settings settings) {
+            return Optional.of(SignatureProvider.createWithResourcePrincipal());
+        }
+    },
+    /**
+     * Represents a "Cloud" deployment using instance principal for delegation with an OBO token.
+     */
+    CLOUD_INSTANCE_OBO_USER {
+        @Override
+        public Optional<AuthorizationProvider> apply(Settings settings) {
+            return Optional.of(SignatureProvider.createWithInstancePrincipalForDelegation(new File(System.getenv("OCI_obo_token_path"))));
+        }
+    },
+    /**
+     * Represents a "Cloud" deployment using resource principal for delegation with an OBO token.
+     */
+    CLOUD_SECURITY_TOKEN {
+        @Override
+        public Optional<AuthorizationProvider> apply(Settings settings) {
+
+            String profileName = settings.get(OracleNoSQLConfigurations.PROFILE_NAME, String.class).orElse(null);
+            String configFile = settings.get(OracleNoSQLConfigurations.CONFIG_FILE, String.class).orElse(null);
+            if(profileName != null && configFile != null) {
+                return Optional.of(SignatureProvider.createWithSessionToken(configFile, profileName));
+            } else if(profileName != null) {
+                return Optional.of(SignatureProvider.createWithSessionToken(profileName));
+            } else  {
+                return Optional.of(SignatureProvider.createWithSessionToken());
+            }
+        }
     };
 
 

jnosql-nosql-oracle/src/main/java/org/eclipse/jnosql/databases/oracle/communication/NoSQLHandleConfigConfiguration.java

@@ -20,11 +20,14 @@
 
 import java.util.List;
 import java.util.function.Function;
+import java.util.logging.Logger;
 
 enum NoSQLHandleConfigConfiguration implements Function<Settings, NoSQLHandleConfiguration> {
 
     INSTANCE;
 
+    private static final Logger LOGGER = Logger.getLogger(NoSQLHandleConfigConfiguration.class.getName());
+
     private static final String DEFAULT_HOST = "http://localhost:8080";
     private static final int DEFAULT_TABLE_READ_LIMITS = 25;
     private static final int DEFAULT_TABLE_WRITE_LIMITS = 25;
@@ -33,12 +36,16 @@ enum NoSQLHandleConfigConfiguration implements Function<Settings, NoSQLHandleCon
     private static final int DEFAULT_TABLE_DELAY_MILLIS = 500;
     @Override
     public NoSQLHandleConfiguration apply(Settings settings) {
+
         String host = settings.get(List.of(OracleNoSQLConfigurations.HOST.get(), Configurations.HOST.get()))
                 .map(Object::toString).orElse(DEFAULT_HOST);
 
 
         DeploymentType deploymentType = settings.get(OracleNoSQLConfigurations.DEPLOYMENT.get())
                 .map(Object::toString).map(DeploymentType::parse).orElse(DeploymentType.ON_PREMISES);
+
+        LOGGER.info("Connecting to Oracle NoSQL database at " + host + " using " + deploymentType + " deployment type");
+
         NoSQLHandleConfig config = new NoSQLHandleConfig(host);
 
         deploymentType.apply(settings).ifPresent(config::setAuthorizationProvider);
@@ -48,6 +55,10 @@ public NoSQLHandleConfiguration apply(Settings settings) {
         int waitMillis = settings.getOrDefault(OracleNoSQLConfigurations.TABLE_WAIT_MILLIS, DEFAULT_TABLE_WAIT_MILLIS);
         int delayMillis = settings.getOrDefault(OracleNoSQLConfigurations.TABLE_DELAY_MILLIS, DEFAULT_TABLE_DELAY_MILLIS);
         var tableLimits = new TableCreationConfiguration(readLimit, writeLimit, storageGB, waitMillis, delayMillis);
+        settings.get(OracleNoSQLConfigurations.NAMESPACE.get())
+                .map(Object::toString).ifPresent(config::setDefaultNamespace);
+        settings.get(OracleNoSQLConfigurations.COMPARTMENT.get())
+                .map(Object::toString).ifPresent(config::setDefaultCompartment);
         return new NoSQLHandleConfiguration(config, tableLimits);
     }
 }