{"id":18554219,"url":"https://github.com/oracle/nosql-spring-sdk","last_synced_at":"2025-04-09T23:31:00.270Z","repository":{"id":37913903,"uuid":"336844802","full_name":"oracle/nosql-spring-sdk","owner":"oracle","description":"SDK for Spring Data for Oracle NoSQL Database","archived":false,"fork":false,"pushed_at":"2025-03-20T17:53:59.000Z","size":1272,"stargazers_count":8,"open_issues_count":0,"forks_count":11,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-20T18:38:24.691Z","etag":null,"topics":["java","nosql","nosql-database","oracle","spring","spring-boot"],"latest_commit_sha":null,"homepage":"https://www.oracle.com/database/nosql/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oracle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-07T17:21:10.000Z","updated_at":"2025-03-20T17:53:55.000Z","dependencies_parsed_at":"2024-05-22T22:24:04.118Z","dependency_job_id":"c4368131-c7d2-4c30-84f7-6725ef8b0dac","html_url":"https://github.com/oracle/nosql-spring-sdk","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fnosql-spring-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fnosql-spring-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fnosql-spring-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fnosql-spring-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oracle","download_url":"https://codeload.github.com/oracle/nosql-spring-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248129581,"owners_count":21052598,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","nosql","nosql-database","oracle","spring","spring-boot"],"created_at":"2024-11-06T21:20:17.376Z","updated_at":"2025-04-09T23:31:00.261Z","avatar_url":"https://github.com/oracle.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Oracle NoSQL Database SDK for Spring Data\n\n## About\n\nOracle NoSQL SDK for Spring Data provides a Spring Data\nimplementation module to connect to an\n[Oracle NoSQL Database](https://www.oracle.com/database/technologies/related/nosql.html)\ncluster or to\n[Oracle NoSQL Cloud Service](https://www.oracle.com/database/nosql-cloud.html).\n\n## Requirements\n\nJava versions 17 and higher are supported.\n\n## Installation\n\nThe Oracle NoSQL SDK for Spring Data can be included in a project in 2 ways:\n\n1. Include a dependency in a Maven project\n2. Download from GitHub\n\n### Install as a Project Dependency\n\nThis dependency can be used to include the SDK and its dependencies in your\nproject. The version changes with each release.\n\n```\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.oracle.nosql.sdk\u003c/groupId\u003e\n  \u003cartifactId\u003espring-data-oracle-nosql\u003c/artifactId\u003e\n  \u003cversion\u003e2.2.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nOptionally, the packages can be manually installed in a local maven repository by\n downloading from\n  [releases page](https://github.com/oracle/nosql-spring-sdk/releases), and\n  running the following command (-sources and -javadoc files are optional):\n\n```\nmvn install:install-file \\\n-DpomFile=spring-data-oracle-nosql-x.y.z.pom \\\n-Dfile=spring-data-oracle-nosql-x.y.z.jar \\\n-Dsources=spring-data-oracle-nosql-x.y.z-sources.jar \\\n-Djavadoc=spring-data-oracle-nosql-x.y.z-javadoc.jar\n```\n\n### Download from GitHub\n\nYou can download the Oracle NoSQL SDK for Spring Data as an archive from\n[GitHub](https://github.com/oracle/nosql-spring-sdk/releases). The archive\ncontains the runtime library and its dependencies, examples, and\nAPI documentation.\n\n## Documentation\n\nSee [Oracle NoSQL SDK for Spring Data javadoc](https://oracle.github.io/nosql-spring-sdk/) for the latest API documentation.  See [Spring Data SDK Developers Guide](https://docs.oracle.com/en/database/other-databases/nosql-database/23.1/springsdk/index.html) for examples and additional details on the SDK.\n\nGeneral documentation about the Oracle NoSQL Database Cloud Service, Oracle NoSQL Database and Spring Data SDK\nDevelopers Guide can be found in these locations:\n\n* [Oracle NoSQL Database Cloud Service](https://docs.oracle.com/en/cloud/paas/nosql-cloud/nosql_dev.html)\n* [Oracle NoSQL Database On Premise](https://docs.oracle.com/en/database/other-databases/nosql-database/)\n\n\n\n## Changes\n\nSee [CHANGELOG](./CHANGELOG.md) for changes in each release.\n\n## Usage\n\n* The example below also requires an additional dependency:\n\n    ```xml\n    \u003cdependency\u003e\n      \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n      \u003cartifactId\u003espring-boot-starter\u003c/artifactId\u003e\n      \u003cversion\u003e3.4.3\u003c/version\u003e\n    \u003c/dependency\u003e\n    ```\n\n* Define an AppConfig class that provides a nosqlDBConfig bean that returns an\nOracle NoSQL DB configuration:\n\n    ```java\n    package org.example.app;\n\n    import com.oracle.nosql.spring.data.config.AbstractNosqlConfiguration;\n    import com.oracle.nosql.spring.data.config.NosqlDbConfig;\n    import com.oracle.nosql.spring.data.repository.config.EnableNosqlRepositories;\n\n    import org.springframework.context.annotation.Bean;\n    import org.springframework.context.annotation.Configuration;\n\n    import oracle.nosql.driver.kv.StoreAccessTokenProvider;\n\n    @Configuration\n    @EnableNosqlRepositories\n    public class AppConfig extends AbstractNosqlConfiguration {\n\n        @Bean\n        public NosqlDbConfig nosqlDbConfig() {\n            return new NosqlDbConfig(\n                \"localhost:8080\",                   // endpoint URL\n                new StoreAccessTokenProvider());    // AuthorizationProvider\n        }\n    }\n    ```\n\nNote: Depending on individual scenario use the appropriate AuthorizationProvider:\n - For cloud configuration use the following example or see\n    [documentation](https://docs.oracle.com/en/cloud/paas/nosql-cloud/uapic/index.html#UAPIC-GUID-6DB8FA3D-1E31-49E6-A54E-908F187968A2):\n\n\n    ```java\n    new oracle.nosql.driver.iam.SignatureProvider(\n                        tenantId,             // OCID\n                        userId,               // OCID\n                        fingerprint,          // String\n                        File privateKeyFile,\n                        char[] passphrase)\n    ```\n\n   * For cloud configuration when application is running in the same region\n     use instance principal authentication. This requires a one-time\n     [setup](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm).\n\n       ```java\n       oracle.nosql.driver.iam.SignatureProvider.createWithInstancePrincipal()\n       ```\n\n - For cloud simulator use:\n\n    ```java\n    com.oracle.nosql.spring.data.NosqlDbFactory.CloudSimProvider.getProvider()\n    ```\n\n - For on-prem configuration use one of the following examples or see\n [documentation](https://docs.oracle.com/en/database/other-databases/nosql-database/24.3/admin/obtaining-nosql-handle.html).\n\n   * For unsecure example:\n\n     ```java\n     new oracle.nosql.driver.kv.StoreAccessTokenProvider()\n     ```\n\n   * For secure example use:\n\n     ```java\n     new oracle.nosql.driver.kv.StoreAccessTokenProvider(\"username\", \"password\".toCharArray())\n     ```\n\nNote: For convenience one can use the following\n    com.oracle.nosql.spring.data.NosqlDbConfig methods:\n\n  - for cloud: NosqlDbConfig.createCloudConfig(\"endpoint\", configFile);\n  - for cloud simulator: NosqlDbConfig.createCloudSimConfig(\"endpoint\");\n  - for on-prem unsecure store: NosqlDbConfig.createProxyConfig(\"endpoint\");\n  - for on-prem secure store: NosqlDbConfig.createProxyConfig(\"endpoint\", user, password);\n\n* Define the entity class:\n\n  ```java\n  package org.example.app;\n\n  import com.oracle.nosql.spring.data.core.mapping.NosqlId;\n\n  public class Customer {\n      @NosqlId(generated = true)\n      long customerId;\n      String firstName;\n      String lastName;\n\n      @Override\n      public String toString() {\n          return \"Customer{\" +\n              \"customerId=\" + customerId +\n              \", firstName='\" + firstName + '\\'' +\n              \", lastName='\" + lastName + '\\'' +\n              '}';\n      }\n  }\n  ```\n\n* Declare a repository that extends NosqlRepository:\n\n    ```java\n    package org.example.app;\n\n    import com.oracle.nosql.spring.data.repository.NosqlRepository;\n\n    public interface CustomerRepository\n        extends NosqlRepository\u003cCustomer, Long\u003e\n    {\n        Iterable\u003cCustomer\u003e findByLastName(String lastname);\n    }\n    ```\n\n* Write the main application class. This requires adding dependencies to org\n.springframework.boot:spring-boot and org.springframework\n.boot:spring-boot-autoconfigure.\n\n  ```java\n  package org.example.app;\n\n  import org.springframework.beans.factory.annotation.Autowired;\n  import org.springframework.boot.CommandLineRunner;\n  import org.springframework.boot.SpringApplication;\n  import org.springframework.boot.autoconfigure.SpringBootApplication;\n  import org.springframework.context.ConfigurableApplicationContext;\n\n  @SpringBootApplication\n  public class App implements CommandLineRunner\n  {\n      @Autowired\n      private CustomerRepository repo;\n\n      public static void main( String[] args )\n      {\n          ConfigurableApplicationContext\n              ctx = SpringApplication.run(App.class, args);\n          SpringApplication.exit(ctx, () -\u003e 0);\n          ctx.close();\n          System.exit(0);\n      }\n\n      @Override\n      public void run(String... args) throws Exception {\n\n          repo.deleteAll();\n\n          Customer s1 = new Customer();\n          s1.firstName = \"John\";\n          s1.lastName = \"Doe\";\n\n          repo.save(s1);\n          System.out.println(\"\\nsaved: \" + s1); // customerId contains generated value\n\n          Customer s2 = new Customer();\n          s2.firstName = \"John\";\n          s2.lastName = \"Smith\";\n\n          repo.save(s2);\n          System.out.println(\"\\nsaved: \" + s2); // customerId contains generated value\n\n          System.out.println(\"\\nfindAll:\");\n          Iterable\u003cCustomer\u003e customers = repo.findAll();\n\n          for (Customer s : customers) {\n              System.out.println(\"  Customer: \" + s);\n          }\n\n          System.out.println(\"\\nfindByLastName: Smith\");\n          customers = repo.findByLastName(\"Smith\");\n\n          for (Customer s : customers) {\n              System.out.println(\"  Customer: \" + s);\n          }\n      }\n  }\n  ```\n\n## Build and run the example code\n\nExample code requires an Oracle NoSQL DB instance and a local http proxy running\n on port 8080.\n\nStart a kvlite instance with helperHosts \"localhost:5000\":\n\n```\njava -jar /path_to/kvstore.jar kvlite -root kvroot -host localhost -port 5000 -store kvstore -secure-config disable \u0026\n```\n\nStart http proxy with endpoint URL \"localhost:8080\":\n\n```\njava -jar /path_to/httpproxy.jar -storeName kvstore -httpPort 8080 -helperHosts localhost:5000 -verbose true \u0026\n```\n\nExecute the example code:\n\n```\nmvn exec:java -Dexec.mainClass=\"org.example.app.App\"\n```\n\nTo log the internally generated queries, one has to enable the debug level by\n adding following logging flag:\n\n```\nmvn exec:java -Dexec.mainClass=\"org.example.app.App\" -Dlogging.level.com.oracle.nosql.spring.data=DEBUG\n```\n\n## Run unit tests\n\nRunning tests require a running store and proxy. The test.serverType and\ntest.endpoint system properties must be specified.\n```\nmvn test -Dtest.serverType=onprem -Dtest.endpoint=http://127.0.0.1:8080\n```\nBy default, if no option is specified, onprem serverType and http://127.0.0\n.1:8080 endpoint is assumed.\n\nTests can be also be run on:\n - onprem:  \n    ```\n    mvn -B -Ptest-onprem test -DargLine=\"-Dtest.endpoint=$ONPREM_ENDPOINT\"\n    ```\n - onprem-secure:\n    Must specify the user, password, trustfile and trust file access password.\n    ```\n    mvn -B -Ptest-onprem-secure test -DargLine=\"-Dtest.endpoint=$ONPREM_SEC_ENDPOINT -Dtest.user=$DRIVER_USER -Dtest.trust=$DRIVER_TRUST_FILE -Dtest.password=$DRIVER_PASS -Dtest.trust.password=$DRIVER_TRUST_PASS\"\n    ```\n - cloudsim:\n    ```\n    mvn -B -Ptest-cloudsim test -DargLine=\"-Dtest.endpoint=$CLOUDSIM_ENDPOINT\"\n    ```\n\n## License\n\nCopyright (c) 2020, 2025 Oracle and/or its affiliates.\nReleased under the Universal Permissive License v1.0 as shown at\n\u003chttps://oss.oracle.com/licenses/upl/\u003e.\nSee the [LICENSE](LICENSE.txt) file.\n\nThe [THIRD\\_PARTY\\_LICENSES](THIRD_PARTY_LICENSES.txt) file contains third\nparty notices and licenses.\n\n## Documentation\n* [API documentation](https://oracle.github.io/nosql-spring-sdk/)\n* [Developer's Guide](https://docs.oracle.com/en/database/other-databases/nosql-database/24.3/springsdk/index.html)\n\n## Help\n\n* Open an issue in the [Issues](https://github.com/oracle/nosql-spring-sdk/issues) page\n* Post your question on the [Oracle NoSQL Database Community](https://community.oracle.com/community/groundbreakers/database/nosql_database).\n* [Email to nosql\\_sdk\\_help\\_grp@oracle.com](mailto:nosql_sdk_help_grp@oracle.com)\n\nWhen requesting help please be sure to include as much detail as possible,\nincluding version of the SDK and **simple**, standalone example code as needed.\n\n## Contributing\n\nThis project welcomes contributions from the community. Before submitting a pull\nrequest, please [review our contribution guide](./CONTRIBUTING.md).\n\n## Security\n\nPlease consult the [security guide](./SECURITY.md) for our responsible security\nvulnerability disclosure process.\n\n\nEnjoy.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fnosql-spring-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foracle%2Fnosql-spring-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fnosql-spring-sdk/lists"}