Merge pull request #27 from VedantMahajanOracle/XDK_SODA1_LINUX.X64_240916

240916

Author: morgiyan

README.md

@@ -88,10 +88,10 @@ 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 Maven. See [Building the source code](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](doc/Building-and-running-tests.md) for details.
 
 ## Contributing
 

THIRD_PARTY_LICENSES.txt

@@ -12,11 +12,13 @@ The test framework is located in the /test directory under the root SODA directo
 **(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):
 
-* JDBC jar
-* javax.json-1.1.4.jar (JSR353 jar)
-* junit-3.8.1.jar (JUnit jar)
+* javax.json-*.jar
+* junit-*.jar
 * orajsoda.jar (SODA Java jar)
-      
+* jakarta.json-*.jar
+* jakarta.json-api-*.jar
+* ojdbc8-*.jar
+
 **(2)** Some of the tests use encrypted data, so you must open a wallet.
 
 Set the parameter in sqlnet.ora, if not set already, to specify the location of the wallet:
@@ -69,7 +71,7 @@ Replace myaccount and mypassword with the account name and password created in s
 If you're using an OS other then Linux, set the environment variable using the appropriate mechanism.
 
 **(7)** Navigate to the /test directory under the root SODA directory, and run the test framework:
-  
+
     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.

build.xml

@@ -1,63 +1,21 @@
 # Building the source code
 
-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. 
+SODA is built using Maven. Make sure you have Apache Maven 3.6.2 or above installed and configured.
 
 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 8 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 JAVA_HOME /jdk8 
 
-### Building with Ivy
-
-If you're behind a firewall, you might need to set the proxy host and port
-number by setting the ANT_OPTS environment variable. For example, assuming
-your proxy host is myproxy.mycompany.com and the port is 80, do:
-
-    setenv ANT_OPTS "-Dhttp.proxyHost=myproxy.mycompany.com -Dhttp.proxyPort=80 -Dhttps.proxyHost=myproxy.mycompany.com -Dhttps.proxyPort=80"
-
-If you have Ivy installed already, set the IVY_HOME environment variable.
-The ivy.jar file must be located under the IVY_HOME/lib. For example,
-suppose your ivy.jar is in /home/myname/ivyinstall/lib. Then you would set
-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.
-
-Finally, navigate to the top SODA Java directory (the one that contains LICENSE.txt),
-and execute the ant build file by typing:
-
-    ant
+### Building with Maven
 
-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).
+`cd soda-for-java`\
+`mvn clean install`
 
-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
-settings are correct.
-
-If the build is successful, you should see orajsoda.jar (the SODA jar) in the /lib directory
-under the top SODA directory.
-
-### Building without Ivy
-
-SODA has the following dependencies:
-
-* ojdbc8.jar or above (JDBC jar)
-* javax.json-1.1.4.jar (JSR353 jar)
-* junit-3.8.1.jar (JUnit jar, only used by the testsuite)
-
-Download the jdbc jar ([https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc8/19.3.0.0/ojdbc8-19.3.0.0.jar](https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc8/19.3.0.0/ojdbc8-19.3.0.0.jar)), javax.json-1.1.4.jar ([http://search.maven.org/remotecontent?filepath=org/glassfish/javax.json/1.1.4/javax.json-1.1.4.jar](http://search.maven.org/remotecontent?filepath=org/glassfish/javax.json/1.0.4/javax.json-1.0.4.jar)) and junit-3.8.1.jar ([http://central.maven.org/maven2/junit/junit/3.8.1/junit-3.8.1.jar](http://central.maven.org/maven2/junit/junit/3.8.1/junit-3.8.1.jar)).
-
-Place these jars in the /lib directory under the root SODA directory. 
-
-Finally, navigate to the top SODA Java directory (the one that contains LICENSE.txt),
-and execute the ant build file by typing the following command:
-
-    ant -Ddownload.deps=false
+If you're behind a firewall, you might need to set the proxy host and port
+number. For example, assuming your proxy host is myproxy.mycompany.com and the port is 80, do:
 
-As this command is executing, you should see messages related to code compilation and archiving (jar creation).
+`mvn clean install -Dhttp.proxyHost=myproxy.mycompany.com -Dhttp.proxyPort=80 -Dhttps.proxyHost=myproxy.mycompany.com -Dhttps.proxyPort=80`
 
-If the build is successful, you should see orajsoda.jar (the SODA jar) in the /lib directory
-under the top SODA directory.
+If the build is successful, you should see orajsoda.jar (the SODA jar) and other dependency jars in the /lib directory under the top SODA directory.

doc/Building-and-running-tests.md

@@ -10,18 +10,20 @@ document collections will be stored in this schema. Pick or create a schema
 for this purpose, and then issue the following command (in sqlplus, for example):
 
     grant SODA_APP to schemaName;
-    
+
 The following simple SODA Java program performs several common operations:
 
- * Creates a new collection
- * Inserts documents into the collection
- * Retrieves the first inserted document by its auto-generated key
- * Retrieves documents matching a query-by-example, or QBE
+* Creates a new collection
+* Inserts documents into the collection
+* Retrieves the first inserted document by its auto-generated key
+* Retrieves documents matching a query-by-example, or QBE
 
 ```java
 import java.sql.Connection;
 import java.sql.DriverManager;
 
+import oracle.jdbc.OracleConnection;
+
 import oracle.soda.rdbms.OracleRDBMSClient;
 
 import oracle.soda.OracleDatabase;
@@ -53,10 +55,11 @@ public class testSODA {
     try {
         // Get a JDBC connection to an Oracle instance
         conn = DriverManager.getConnection(url, props);
-
+        
+        OracleConnection oracleConn = (OracleConnection) conn;
         // Enable JDBC implicit statement caching
-        conn.setImplicitCachingEnabled(true);
-        conn.setStatementCacheSize(50);
+        oracleConn.setImplicitCachingEnabled(true);
+        oracleConn.setStatementCacheSize(50);
 
         // Get an OracleRDBMSClient - starting point of SODA for 
         // Java application
@@ -156,11 +159,11 @@ public class testSODA {
 
 Copy and paste this code into a file called testSODA.java. Then modify the "url" String at the beginning of the program with connection info for your Oracle RDBMS instance. Also "user" and "password" properties set at the beginning of the program need to be modified with the schema name which will contain the table backing the collection, and the password for that schema.
 
-To compile and run SODA for Java application you will need the orajsoda-version.jar and its dependencies (javax.json-1.1.4.jar, which is the JSR252 implementation, and the Oracle JDBC jar). Obtain the latest SODA for Java jar and its dependencies using these Maven coordinates:
+To compile and run SODA for Java application you will need the orajsoda-version.jar and its dependencies (javax.json-1.1.4.jar, which is the JSR252 implementation, and the Oracle JDBC jar, JSON API - jakarta.json-api-2.1.3.jar, Parsson - jakarta.json-1.1.5.jar). Obtain the latest SODA for Java jar and its dependencies using these Maven coordinates:
 
 **Group id:** com.oracle.database.soda  
 **Artifact id:** orajsoda  
-**Version:** 1.1.7.1  
+**Version:** 1.1.7.1
 
 The above will automatically pull the latest versions of the dependencies needed to work with SODA on all supported database versions and cloud services. **Note:** there was an issue with 1.1.7 SODA release on Maven Central - an incorrect version for the javax.json dependency was stated in the SODA POM. This is fixed in the 1.1.7.1 SODA patch release on Maven Central, so please use 1.1.7.1 as the release version.
 
@@ -172,21 +175,28 @@ If you need to download the SODA jar and the dependencies manually, you can do t
 
 *    orajsoda-version.jar. The SODA jar. Download the latest version [here](https://github.com/oracle/soda-for-java/releases).
 
+*    JSONP API. jakarta.json-api-2.1.3.jar. Download the latest version [here](https://mvnrepository.com/artifact/jakarta.json/jakarta.json-api/2.1.3).
+
+*    Parsson. jakarta.json-1.1.5.jar. Download the latest version [here](https://mvnrepository.com/artifact/org.eclipse.parsson/parsson/1.1.5).
+
+
 Compile and run testSODA.java, making sure the necessary jars are in the classpath. JDK 8 or above is required. For example, assuming you're in the directory where the jars are located, and you are using ojdbc8.jar, do:
 
-    javac -classpath "orajsoda.jar" testSODA.java
-    java -classpath "orajsoda-version.jar:ojdbc8.jar:javax.json-1.0.4.jar:." testSODA
+    javac -classpath "orajsoda.jar:ojdbc8.jar" testSODA.java
+    java -classpath "orajsoda.jar:ojdbc8.jar:javax.json-1.1.4.jar:jakarta.json-api-2.1.3.jar:jakarta.json-1.1.5.jar:." testSODA
 
 You should see the following output:
 
     * Retrieving the first document by its key *
 
-    { "name" : "Alex", "friends" : 50 }
+    { "name" : "Alex", "friends" : 50 , "_id":"66df52ce93038afff74f0692"}
 
     * Retrieving documents representing users with at least 300 friends *
 
-    { "name" : "Mia", "friends" : 300 }
-    { "name" : "Gloria", "friends" : 399 }
+    { "name" : "Mia", "friends" : 300, "_id":"66df52ce93038afff74f0692" }
+    { "name" : "Gloria", "friends" : 399, "_id":"66df52ce93038afff74f0696" }
+
+Note - The "_id" values are randomly generated on every insert, and will be different from the specific values shown above.
 
 This example illustrates two ways of retrieving documents from the collection: by using unique document keys, or by using QBEs. To find all users with at least 300 friends, the following QBE was used in the code above:
 
@@ -204,25 +214,13 @@ You should see:
 
      Name                                      Null?    Type
      ----------------------------------------- -------- ----------------------------
-     ID                                        NOT NULL VARCHAR2(255)
-     CREATED_ON                                NOT NULL TIMESTAMP(6)
-     LAST_MODIFIED                             NOT NULL TIMESTAMP(6)
-     VERSION                                   NOT NULL VARCHAR2(255)
-     JSON_DOCUMENT                                      BLOB
-
-As you can see a table has been created with the following columns:
-
-    ID                   Stores the auto-generated key
-    JSON_DOCUMENT        Stores the document content
-    CREATED_ON           Stores the auto-generated created-on timestamp
-    LAST_MODIFIED        Stores the auto-generated last-modified timestamp
-    VERSION              Stores the auto-generated document version
+     DATA                                               JSON
 
 This table schema corresponds to the default collection configuration, but SODA collections are highly configurable. For example, the timestamp and the version columns are optional, there are many possible ways of generating the IDs or versions, etc. Custom collection configuration is covered in the documentation (see  [Creating a Document Collection with SODA for Java](https://docs.oracle.com/en/database/oracle/simple-oracle-document-access/java-1/adsda/using-soda-java.html#GUID-CCD5E91C-7F28-4193-8564-C8201CCF08CE) and [SODA Collection Configuration Using Custom Metadata](https://docs.oracle.com/en/database/oracle/simple-oracle-document-access/java-1/adsda/soda-collection-configuration-using-custom-metadata.html#GUID-D17E8D3C-EE74-49CD-84AA-CE86B9664554)). Although most users should be fine with the defaults, custom collection configuration might be useful in some cases, such as mapping an existing table to a new collection.
 
 To drop the collection, removing the underlying table and cleaning up the metadata persisted in the database, run the example again, but this time with the "drop" argument at the end:
 
-    java -classpath "orajsoda-version.jar:ojdbc8.jar:javax.json-1.1.4.jar:." testSODA drop
+    java -classpath "orajsoda.jar:ojdbc8.jar:javax.json-1.1.4.jar:jakarta.json-api-2.1.3.jar:jakarta.json-1.1.5.jar:." testSODA drop
 
 The output will now be different from before, since the same three documents will be inserted again. But, at the end, the collection will be dropped, and the underlying table removed.