Merge remote-tracking branch 'origin/master'

# Conflicts:
#	README.md
#	doc/Building-and-running-tests.md
#	doc/Building-source-code.md
#	doc/Getting-started-example.md

Author: morgiyan

README.md

@@ -1,13 +1,23 @@
-# 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.
+# 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 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.
+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. 
 
-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.
+SODA for Java supports:
 
-**This is an open source project maintained by Oracle Corp.**
+* 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 is built on top of native JSON support in the Oracle database.
+SODA for Java is built on top of native JSON support in the Oracle Database.
+
+**This is an open source project maintained by Oracle Corp.**
 
 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.
 
@@ -59,28 +69,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
 
-The documentation is located [here](http://docs.oracle.com/cd/E63251_01/index.htm).
+* [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](https://docs.oracle.com/en/database/oracle/simple-oracle-document-access/java-1/adsda/).
 
-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.
+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.

doc/Building-and-running-tests.md

@@ -1,19 +1,18 @@
-#Building and running the tests
+# Building and running the tests
 
-To build and execute SODA tests, you must have a live Oracle database
-12.1.0.2 instance, with patch 20885778 applied.
+To build and execute SODA tests, you must have an Oracle Database
+12.2.0.1 or above instance, or 12.1.0.2 instance with patch 20885778 applied.
 
-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).
+The patch is only necessary for the Oracle Database 12.1.0.2 release, and is not required for 12.2.0.1 and above releases of the Oracle Database. The patch 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).
 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 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):
+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):
 
-* ojdbc6.jar (the JDBC jar that ships with Oracle database version 12.1.0.2)
+* JDBC jar
 * javax.json-1.0.4.jar (JSR353 jar)
 * junit-3.8.1.jar (JUnit jar)
 * orajsoda.jar (SODA Java jar)
@@ -34,7 +33,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 mypass and opens it.
+This creates the wallet with the password mywalletpass 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:
 
@@ -55,13 +54,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=myaccount
-    Password=mypassword
-    Server=myoraclehost
-    Port=myoracleport
-    DBName=mysid
+    UserName=account
+    Password=password
+    Server=oracleHost
+    Port=oraclePort
+    DBName=oracleServiceName
 
-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.
+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.
 
 **(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:
 
@@ -74,3 +73,4 @@ If you're using an OS other then Linux, set the environment variable using the a
     ant -Ddatasource=datasource.properties
 
 The test framework should run and output "BUILD SUCCESSFUL" at the end. Open up a browser, and navigate to the /test/testoutput directory under the root SODA directory. Then navigate to the directory identified by the timestamp of your run (this directory is created by the test framework, on every run). From there, nagivate to /html/index.html, for a detailed test report. In case of test failures, this report allows you to navigate to the failures, and see the stack trace of their occurrence in each failed test.
+

doc/Building-source-code.md

@@ -1,30 +1,20 @@
-#Building the source code
+# Building the source code
 
-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. 
+SODA is built using Ant with Ivy. Make sure you have Ant 1.9 or above 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 12.1.0.2 release of the Oracle database.
+The only SODA dependency that must be manually downloaded is the Oracle JDBC jar that ships with the Oracle database. JDBC 6 or above jar is required.
 
-The JDBC jar can be downloaded from here:
+For example, if you're using JDK8 or above, you could use ojdbc8.jar that ships with Oracle Database 18c, available from [this page](https://www.oracle.com/technetwork/database/application-development/jdbc/downloads/jdbc-ucp-183-5013470.html). Alternatively, you can also use ojdbc8.jar that ships with OracleDatabase 12.2.0.1, available from [this page](https://www.oracle.com/technetwork/database/features/jdbc/jdbc-ucp-122-3110062.html). If you're still on JDK7 or even JDK6, you can use ojdbc7.jar or ojdbc6.jar respectively. These ship with Oracle Database 12.1.0.2, and are downloadable from [this page](http://www.oracle.com/technetwork/database/features/jdbc/default-2280470.html).
 
-[http://www.oracle.com/technetwork/database/features/jdbc/default-2280470.html](http://www.oracle.com/technetwork/database/features/jdbc/default-2280470.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).
 
-Make sure you pick ojdbc6.jar, out of the different flavors available. 
-
-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).
+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.
 
-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:
+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:
 
-    setenv JAVA6HOME /jdk6 
+    setenv JAVA_HOME /jdk8 
 
 ### Building with Ivy
 
@@ -42,17 +32,14 @@ IVY_HOME as follows:
     setenv IVY_HOME /home/myname/invyinstall
 
 If you don't have Ivy installed, it will be downloaded automatically to
-${user.home}/.ant/lib. See [https://ant.apache.org/manual/Tasks/property.html](https://ant.apache.org/manual/Tasks/property.html) for info on what ${user.home} resolves to on different operating
-systems.
+${user.home}/.ant/lib. See [https://ant.apache.org/manual/Tasks/property.html](https://ant.apache.org/manual/Tasks/property.html) for info on what ${user.home} resolves to on different operating systems.
 
 Finally, navigate to the top SODA Java directory (the one that contains LICENSE.txt),
 and execute the ant build file by typing:
 
     ant
 
-As this command is executing, you should see messages informing you about Ivy downloading itself 
-(unless it's already installed), downloading of the SODA dependencies, and code compilation 
-and archiving (jar creation).
+As this command is executing, you should see messages informing you about Ivy downloading itself (unless it's already installed), downloading of the SODA dependencies, and code compilation and archiving (jar creation).
 
 If the process gets stuck while downloading Ivy, or downloading SODA dependencies (in case you
 have Ivy installed already), and you're behind a firewall, make sure your proxy host and port
@@ -77,8 +64,7 @@ and execute the ant build file by typing the following command:
 
     ant -Ddownload.deps=false
 
-As this command is executing, you should see messages related to code compilation and archiving 
-(jar creation).
+As this command is executing, you should see messages related to code compilation and archiving (jar creation).
 
 If the build is successful, you should see orajsoda.jar (the SODA jar) in the /lib directory
 under the top SODA directory.