Skip to content

Commit

Permalink
Soda 1.1.4
Browse files Browse the repository at this point in the history
Soda 1.1.4
  • Loading branch information
morgiyan committed Apr 22, 2020
1 parent 357fb69 commit a3e165a
Show file tree
Hide file tree
Showing 137 changed files with 9,616 additions and 2,378 deletions.
46 changes: 14 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,14 @@
# SODA 1.1.0
Simple Oracle Document Access (SODA) is an API which allows you to use the Oracle Database as a NoSQL JSON document store. Although SODA is particularly powerful when it comes to JSON data, data of any other type is supported as well.
# SODA 1.0.0
Simple Oracle Document Access (SODA) is a new family of APIs from Oracle that let you create Oracle Database applications at a level of simplicity and ease-of-use typically associated with NoSQL document stores. More specifically, SODA lets you create and store collections of documents in Oracle Database, retrieve them, and query them, without needing to know Structured Query Language (SQL) or how the data in the documents is stored in the database.

With the SODA architecture, your data is stored as documents, and documents are organized into collections. Each document contains the actual data, as well as additional information automatically maintained by SODA, such as unique key, last-modified timestamp, version, type, etc. SODA lets you create and store such collections of documents in the Oracle Database, and perform create, retrive, update, and delete (CRUD) operations on these documents, without needing to know Structured Query Language (SQL), or JDBC, or how the data is stored in the database. Essentially SODA provides a virtual NoSQL document store on top of your Oracle Database. Under the covers, a collection is stored as a regular Oracle Database table, and each document is stored as a row in the table. SQL access to the table using standard tools is still allowed.
SODA for Java is a Java library that provides SODA. You can use it to perform create, retrieve, update, and delete (CRUD) operations on documents of any kind, and you can use it to query JSON documents.

SODA for Java, hosted in this repository, is a library which implements SODA for use with Java.
SODA for REST, which can be used from any programming language capable of making http requests,
is also available. SODA for REST is not part of this repository, and is released separately as part
of [Oracle Rest Data Serices (ORDS)](http://www.oracle.com/technetwork/developer-tools/rest-data-services/overview/index.html) and
documented [here](https://docs.oracle.com/cd/E56351_01/doc.30/e58123/toc.htm).

Both SODA for REST and SODA for Java are available on the cloud. Please refer to the cloud [documentation](https://docs.oracle.com/en/cloud/paas/exadata-express-cloud/develop-document-store-applications-using-soda.html) for more info.

SODA for Java supports:

* CRUD operations on documents containing data of any type using unique document keys
* CRUD operations on documents containing JSON data using QBEs (simple pattern-like queries-by-example expressed in JSON), or unique document keys
* Bulk read/write operations
* Optimistic locking
* Transactions
* Document collections backed by Oracle Database tables or views
* Mapping of existing Oracle Database tables or views as document collections

SODA for Java is stable, well-documented, and has a comprehensive test suite. We are actively working on adding new features as well.

SODA for Java is built on top of native JSON support in the Oracle Database.
With the SODA architecture, a database contains collections, and each collection contains documents. SODA is designed primarily for working with JSON documents, but a document can be of any Multipurpose Internet Mail Extensions (MIME) type.

**This is an open source project maintained by Oracle Corp.**

SODA is built on top of native JSON support in the Oracle database.

See the [Oracle as a Document Store](http://www.oracle.com/technetwork/database/application-development/oracle-document-store/index.html) page on the Oracle Technology Network for more info.

### Getting started
Expand Down Expand Up @@ -77,28 +59,28 @@ while (c.hasNext())

Note that there's no SQL or JDBC programming required. Under the covers, SODA for Java transparently converts operations on document collections into SQL and executes it over JDBC.

See [Getting Started with SODA for Java](https://github.com/oracle/soda-for-java/blob/master/doc/Getting-started-example.md) for a complete introductory example.
See [Getting Started with SODA for Java](https://github.com/oracle/SODA-FOR-JAVA/blob/master/doc/Getting-started-example.md) for a complete introductory example.

### Documentation

* [Introduction to SODA](https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdi/). This book covers subjects common to all SODA impls, such as QBEs and indexing.
* SODA Java documentation is located [here](http://docs.oracle.com/cd/E63251_01/index.htm).
The documentation is located [here](http://docs.oracle.com/cd/E63251_01/index.htm).

The Javadoc is located [here](http://oracle.github.io/soda-for-java).
The Javadoc is located [here](http://oracle.github.io/SODA-FOR-JAVA).

### Build

SODA for Java source code is built with Ant and (optionally) Ivy. See [Building the source code](https://github.com/oracle/soda-for-java/blob/master/doc/Building-source-code.md) for
SODA for Java source code is built with Ant and (optionally) Ivy. See [Building the source code](https://github.com/oracle/SODA-FOR-JAVA/blob/master/doc/Building-source-code.md) for
details.

SODA for Java comes with a testsuite, built with JUnit and driven by Ant. See [Building and running the tests](https://github.com/oracle/soda-for-java/blob/master/doc/Building-and-running-tests.md) for details.
SODA for Java comes with a testsuite, built with JUnit and driven by Ant. See [Building and running the tests]
(https://github.com/oracle/SODA-FOR-JAVA/blob/master/doc/Building-and-running-tests.md) for details.

### Contributions

SODA is an open source project. See [Contributing](https://github.com/oracle/soda-for-java/blob/master/CONTRIBUTING.md) for details.
SODA is an open source project. See [Contributing](https://github.com/oracle/SODA-FOR-JAVA/blob/master/CONTRIBUTING.md) for details.

Oracle gratefully acknowledges the contributions to SODA made by the community.

### Getting in touch

Please open an issue [here](https://github.com/oracle/soda-for-java/issues), or post to the [ORDS, SODA, and JSON in the database forum](https://community.oracle.com/community/database/developer-tools/oracle_rest_data_services/) with SODA-FOR-JAVA in the subject line.
Please open an issue [here](https://github.com/oracle/SODA-FOR-JAVA/issues), or post to the [ORDS, SODA, and JSON in the database forum] (https://community.oracle.com/community/database/developer-tools/oracle_rest_data_services/) with SODA-FOR-JAVA in the subject line.
10 changes: 7 additions & 3 deletions build.xml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?xml version="1.0"?>

<!--
Copyright (c) 2014, 2015, 2016, 2017 Oracle and/or its affiliates. All rights reserved.
Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved.
DESCRIPTION
The main ant build for json.
Expand All @@ -14,17 +14,22 @@

<import file="json.xml"/>
<import file="getivy.xml"/>
<!--
<import file="ivysettings.xml"/>
-->

<property name="download.deps" value=""/>

<condition property="skip.ivy">
<equals arg1="${download.deps}" arg2="false"/>
</condition>


<target name="all" depends="resolve,compile,archive" description="Compiles the source and creates the jar"/>

<!-- Ivy targets (get dependencies using ivy, generate report, clean ivy cache) -->

<ivy:settings file="ivysettings.xml"/>
<target name="resolve" unless="skip.ivy" depends="init-ivy" description="Retrieves dependencies">
<ivy:retrieve/>
</target>
Expand Down Expand Up @@ -59,7 +64,6 @@
use="true"
author="false"
failonerror="true"
executable="${javac.java.home}/bin/javadoc"
/>
</target>

Expand All @@ -77,7 +81,7 @@
<fileset dir="${classes.dir}"/>
<fileset dir="${resources.dir}"/>
<manifest>
<attribute name="Repository-Id" value="XDK_SODA1.1.0_LINUX.X64_RELEASE"/>
<attribute name="Repository-Id" value="XDK_SODA1.0.0_LINUX.X64_151009 GITHUB"/>
</manifest>
</jar>
</target>
Expand Down
25 changes: 13 additions & 12 deletions doc/Building-and-running-tests.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
# Building and running the tests
#Building and running the tests

To build and execute SODA tests, you must have a live Oracle database
12.2.0.1 instance, or 12.1.0.2 instance with patch 20885778 applied.
12.1.0.2 instance, with patch 20885778 applied.

The patch is only necessary for the 12.1.0.2 release, and is available from My Oracle Support ([https://support.oracle.com](https://support.oracle.com)). Select tab Patches & Updates. Search for patch number, 20885778 or access it directly at this URL: [https://support.oracle.com/rs?type=patch&id=20885778](https://support.oracle.com/rs?type=patch&id=20885778).
Obtain the patch from My Oracle Support ([https://support.oracle.com](https://support.oracle.com)).
Select tab Patches & Updates. Search for patch number, 20885778 or access it directly at this URL: [https://support.oracle.com/rs?type=patch&id=20885778](https://support.oracle.com/rs?type=patch&id=20885778).
Make sure you follow all the installation steps specified in the README.txt file included with
the patch, including the post-installation step.

The test framework is located in the /test directory under the root SODA directory (the root SODA directory is the one containing LICENSE.txt file). It's built with JUnit and driven by Ant. The actual Java test files are in /test/src/oracle/json/tests/soda. To configure the database instance and the test framework, follow these steps (note that some of them require sysdba access).

**(1)** Build the source code (which includes downloading SODA dependencies), as described
in [Building the source code](https://github.com/oracle/soda-for-java/blob/master/doc/Building-source-code.md). Make sure you perform all steps described in this link. Specifically, make sure that the JAVA_HOME environment variable is set, and that the following jars are located in the /lib directory under the top level SODA directory (the one that contains LICENSE.txt):
in [Building the source code](https://github.com/oracle/SODA-FOR-JAVA/blob/master/doc/Building-source-code.md). Make sure you perform all steps described in this link. Specifically, make sure that the JAVA6HOME environment variable is set, and that the following jars are located in the /lib directory under the top level SODA directory (the one that contains LICENSE.txt):

* JDBC jar
* ojdbc6.jar (the JDBC jar that ships with Oracle database version 12.1.0.2)
* javax.json-1.0.4.jar (JSR353 jar)
* junit-3.8.1.jar (JUnit jar)
* orajsoda.jar (SODA Java jar)
Expand All @@ -33,7 +34,7 @@ The directory /path/to/wallet/dir should already exist; if not then you should c

alter system set encryption key authenticated by "mywalletpass";

This creates the wallet with the password mywalletpass and opens it.
This creates the wallet with the password mypass and opens it.

The above steps are needed only once. After the wallet is created and open, it stays open as long as the database is up (unless it is explicitly closed). If the database is restarted, you have to open the wallet with:

Expand All @@ -54,13 +55,13 @@ Note: do not use a quoted (case-sensitive) account name.
**(5)** Provide the database instance connection info to the SODA test framework. Edit datasource.properties
located in /test/datasource.properties, under the top level SODA directory. The file has the following contents:

UserName=account
Password=password
Server=oracleHost
Port=oraclePort
DBName=oracleServiceName
UserName=myaccount
Password=mypassword
Server=myoraclehost
Port=myoracleport
DBName=mysid

Replace myaccount and mypassword with the account name and password created in step 3. Replace myoraclehost and myoracleport with the host name and port on which the Oracle instance is running/listening. Replace mydbname with the Oracle Service Name.
Replace myaccount and mypassword with the account name and password created in step 3. Replace myoraclehost and myoracleport with the host name and port on which the Oracle instance is running/listening. Replace mydbname with the Oracle SID.

**(6)** Supply the directory where sqlplus is located to the test framework by setting the SODA_SQLPLUS environment variable. For example, assume sqlplus is located in /oracle/software/bin. Then, assuming you're on Linux and using the C shell (csh) do:

Expand Down
23 changes: 10 additions & 13 deletions doc/Building-source-code.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,30 @@
# Building the source code
#Building the source code

SODA is built using Ant with Ivy. Make sure you have Ant 1.9 or above installed and configured.
SODA is built using Ant with Ivy. Make sure you have ant installed and configured.
It's not required that Ivy is installed - as long as you have an internet connection,
the build process will download Ivy and use it to download SODA dependencies.

The only SODA dependency that must be manually downloaded is the Oracle JDBC jar that ships with
the Oracle database.
the 12.1.0.2 release of the Oracle database.

JDBC jars for use with JDK 6, 7, and 8 ship with Oracle Database 12.1.0.2 and can be downloaded from here:
The JDBC jar can be downloaded from here:

[http://www.oracle.com/technetwork/database/features/jdbc/default-2280470.html](http://www.oracle.com/technetwork/database/features/jdbc/default-2280470.html)

Make sure you pick either ojdbc6.jar (for use with JDK 6), or ojdbc7.jar (for use with JDK 7 and 8),
out of the different flavors available.
Make sure you pick ojdbc6.jar, out of the different flavors available.

If you are using JDK 8 and planning to run SODA with Oracle Database 12.2.0.1, you can alternatively download ojdbc8.jar from here:

http://www.oracle.com/technetwork/database/features/jdbc/jdbc-ucp-122-3110062.html

Copy the downloaded JDBC jar to the /lib directory under the root SODA directory (the root SODA directory is the one containing LICENSE.txt file).
Copy the downloaded ojdbc6.jar to the /lib directory under the root SODA directory (the root SODA directory is the one containing LICENSE.txt file).

Other dependencies will be automatically downloaded by Ivy. You also have the
option to not use Ivy, and to download the dependencies manually (see "Building without Ivy" below).

The following instructions require setting various environment variables. They assume you're on Linux, and using the C Shell (csh). On other OSes, you would set environment variables analogously, using a mechanism appropriate for your specific operating system.

Set the JAVA_HOME environment variable to the JDK install directory. At a minimum, JDK 6 is required. For example, assuming you are using JDK 8 installed under /jdk8, and you're using the C Shell (csh) on Linux, do:
SODA builds using Java 6. Set the JAVA6HOME environment
variable to the JDK install directory. For example, assuming JDK6 is installed
under /jdk6, and you're using the C Shell (csh) on Linux, do:

setenv JAVA_HOME /jdk8
setenv JAVA6HOME /jdk6

### Building with Ivy

Expand Down
Loading

0 comments on commit a3e165a

Please sign in to comment.