#247: Fixed "set properties" request in API documentation (#248)

exasol · Jul 20, 2022 · db92c56 · db92c56
1 parent e548b59
commit db92c56
Show file tree

Hide file tree

Showing 6 changed files with 115 additions and 86 deletions.
diff --git a/dependencies.md b/dependencies.md
@@ -11,14 +11,14 @@
 
 ## Test Dependencies
 
-| Dependency                                | License                                        |
-| ----------------------------------------- | ---------------------------------------------- |
-| [Hamcrest][7]                             | [BSD License 3][8]                             |
-| [JSONassert][9]                           | [The Apache Software License, Version 2.0][10] |
-| [JUnit Jupiter (Aggregator)][11]          | [Eclipse Public License v2.0][12]              |
-| [mockito-junit-jupiter][13]               | [The MIT License][14]                          |
-| [JUnit5 System Extensions][15]            | [Eclipse Public License v2.0][16]              |
-| [EqualsVerifier | release normal jar][17] | [Apache License, Version 2.0][18]              |
+| Dependency                                | License                                       |
+| ----------------------------------------- | --------------------------------------------- |
+| [Hamcrest][6]                             | [BSD License 3][7]                            |
+| [JSONassert][8]                           | [The Apache Software License, Version 2.0][9] |
+| [JUnit Jupiter (Aggregator)][10]          | [Eclipse Public License v2.0][11]             |
+| [mockito-junit-jupiter][12]               | [The MIT License][13]                         |
+| [JUnit5 System Extensions][14]            | [Eclipse Public License v2.0][15]             |
+| [EqualsVerifier | release normal jar][16] | [Apache License, Version 2.0][17]             |
 
 ## Runtime Dependencies
 
@@ -28,70 +28,70 @@
 
 ## Plugin Dependencies
 
-| Dependency                                              | License                                        |
-| ------------------------------------------------------- | ---------------------------------------------- |
-| [SonarQube Scanner for Maven][22]                       | [GNU LGPL 3][23]                               |
-| [Apache Maven Compiler Plugin][24]                      | [Apache License, Version 2.0][18]              |
-| [Apache Maven Enforcer Plugin][26]                      | [Apache License, Version 2.0][18]              |
-| [Maven Flatten Plugin][28]                              | [Apache Software Licenese][10]                 |
-| [org.sonatype.ossindex.maven:ossindex-maven-plugin][30] | [ASL2][10]                                     |
-| [Reproducible Build Maven Plugin][32]                   | [Apache 2.0][10]                               |
-| [Maven Surefire Plugin][34]                             | [Apache License, Version 2.0][18]              |
-| [Versions Maven Plugin][36]                             | [Apache License, Version 2.0][18]              |
-| [Apache Maven Deploy Plugin][38]                        | [Apache License, Version 2.0][18]              |
-| [Apache Maven GPG Plugin][40]                           | [Apache License, Version 2.0][18]              |
-| [Apache Maven Source Plugin][42]                        | [Apache License, Version 2.0][18]              |
-| [Apache Maven Javadoc Plugin][44]                       | [Apache License, Version 2.0][18]              |
-| [Nexus Staging Maven Plugin][46]                        | [Eclipse Public License][47]                   |
-| [JaCoCo :: Maven Plugin][48]                            | [Eclipse Public License 2.0][49]               |
-| [error-code-crawler-maven-plugin][50]                   | [MIT][4]                                       |
-| [Project keeper maven plugin][52]                       | [The MIT License][53]                          |
-| [Maven Clean Plugin][54]                                | [The Apache Software License, Version 2.0][10] |
-| [Maven Resources Plugin][56]                            | [The Apache Software License, Version 2.0][10] |
-| [Maven JAR Plugin][58]                                  | [The Apache Software License, Version 2.0][10] |
-| [Maven Install Plugin][60]                              | [The Apache Software License, Version 2.0][10] |
-| [Maven Site Plugin 3][62]                               | [The Apache Software License, Version 2.0][10] |
+| Dependency                                              | License                                       |
+| ------------------------------------------------------- | --------------------------------------------- |
+| [SonarQube Scanner for Maven][18]                       | [GNU LGPL 3][19]                              |
+| [Apache Maven Compiler Plugin][20]                      | [Apache License, Version 2.0][17]             |
+| [Apache Maven Enforcer Plugin][21]                      | [Apache License, Version 2.0][17]             |
+| [Maven Flatten Plugin][22]                              | [Apache Software Licenese][9]                 |
+| [org.sonatype.ossindex.maven:ossindex-maven-plugin][23] | [ASL2][9]                                     |
+| [Reproducible Build Maven Plugin][24]                   | [Apache 2.0][9]                               |
+| [Maven Surefire Plugin][25]                             | [Apache License, Version 2.0][17]             |
+| [Versions Maven Plugin][26]                             | [Apache License, Version 2.0][17]             |
+| [Apache Maven Deploy Plugin][27]                        | [Apache License, Version 2.0][17]             |
+| [Apache Maven GPG Plugin][28]                           | [Apache License, Version 2.0][17]             |
+| [Apache Maven Source Plugin][29]                        | [Apache License, Version 2.0][17]             |
+| [Apache Maven Javadoc Plugin][30]                       | [Apache License, Version 2.0][17]             |
+| [Nexus Staging Maven Plugin][31]                        | [Eclipse Public License][32]                  |
+| [JaCoCo :: Maven Plugin][33]                            | [Eclipse Public License 2.0][34]              |
+| [error-code-crawler-maven-plugin][35]                   | [MIT][4]                                      |
+| [Project keeper maven plugin][36]                       | [The MIT License][37]                         |
+| [Maven Clean Plugin][38]                                | [The Apache Software License, Version 2.0][9] |
+| [Maven Resources Plugin][39]                            | [The Apache Software License, Version 2.0][9] |
+| [Maven JAR Plugin][40]                                  | [The Apache Software License, Version 2.0][9] |
+| [Maven Install Plugin][41]                              | [The Apache Software License, Version 2.0][9] |
+| [Maven Site Plugin 3][42]                               | [The Apache Software License, Version 2.0][9] |
 
-[5]: https://github.com/exasol/error-reporting-java
-[16]: http://www.eclipse.org/legal/epl-v20.html
-[10]: http://www.apache.org/licenses/LICENSE-2.0.txt
-[34]: https://maven.apache.org/surefire/maven-surefire-plugin/
-[46]: http://www.sonatype.com/public-parent/nexus-maven-plugins/nexus-staging/nexus-staging-maven-plugin/
-[54]: http://maven.apache.org/plugins/maven-clean-plugin/
-[4]: https://opensource.org/licenses/MIT
-[13]: https://github.com/mockito/mockito
-[28]: https://www.mojohaus.org/flatten-maven-plugin/
-[36]: http://www.mojohaus.org/versions-maven-plugin/
-[52]: https://github.com/exasol/project-keeper/
-[8]: http://opensource.org/licenses/BSD-3-Clause
-[24]: https://maven.apache.org/plugins/maven-compiler-plugin/
-[49]: https://www.eclipse.org/legal/epl-2.0/
-[38]: https://maven.apache.org/plugins/maven-deploy-plugin/
-[47]: http://www.eclipse.org/legal/epl-v10.html
-[23]: http://www.gnu.org/licenses/lgpl.txt
-[48]: https://www.jacoco.org/jacoco/trunk/doc/maven.html
-[14]: https://github.com/mockito/mockito/blob/main/LICENSE
-[32]: http://zlika.github.io/reproducible-build-maven-plugin
-[53]: https://github.com/exasol/project-keeper/blob/main/LICENSE
-[58]: http://maven.apache.org/plugins/maven-jar-plugin/
-[1]: https://projects.eclipse.org/license/epl-2.0
-[18]: https://www.apache.org/licenses/LICENSE-2.0.txt
-[22]: http://sonarsource.github.io/sonar-scanner-maven/
-[17]: https://www.jqno.nl/equalsverifier
-[26]: https://maven.apache.org/enforcer/maven-enforcer-plugin/
-[3]: http://www.exasol.com
-[12]: https://www.eclipse.org/legal/epl-v20.html
-[60]: http://maven.apache.org/plugins/maven-install-plugin/
-[11]: https://junit.org/junit5/
-[30]: https://sonatype.github.io/ossindex-maven/maven-plugin/
-[40]: https://maven.apache.org/plugins/maven-gpg-plugin/
 [0]: https://github.com/eclipse-ee4j/jsonp
-[15]: https://github.com/itsallcode/junit5-system-extensions
-[9]: https://github.com/skyscreamer/JSONassert
-[42]: https://maven.apache.org/plugins/maven-source-plugin/
+[1]: https://projects.eclipse.org/license/epl-2.0
 [2]: https://projects.eclipse.org/license/secondary-gpl-2.0-cp
-[7]: http://hamcrest.org/JavaHamcrest/
-[62]: http://maven.apache.org/plugins/maven-site-plugin/
-[56]: http://maven.apache.org/plugins/maven-resources-plugin/
-[44]: https://maven.apache.org/plugins/maven-javadoc-plugin/
-[50]: https://github.com/exasol/error-code-crawler-maven-plugin
+[3]: http://www.exasol.com
+[4]: https://opensource.org/licenses/MIT
+[5]: https://github.com/exasol/error-reporting-java
+[6]: http://hamcrest.org/JavaHamcrest/
+[7]: http://opensource.org/licenses/BSD-3-Clause
+[8]: https://github.com/skyscreamer/JSONassert
+[9]: http://www.apache.org/licenses/LICENSE-2.0.txt
+[10]: https://junit.org/junit5/
+[11]: https://www.eclipse.org/legal/epl-v20.html
+[12]: https://github.com/mockito/mockito
+[13]: https://github.com/mockito/mockito/blob/main/LICENSE
+[14]: https://github.com/itsallcode/junit5-system-extensions
+[15]: http://www.eclipse.org/legal/epl-v20.html
+[16]: https://www.jqno.nl/equalsverifier
+[17]: https://www.apache.org/licenses/LICENSE-2.0.txt
+[18]: http://sonarsource.github.io/sonar-scanner-maven/
+[19]: http://www.gnu.org/licenses/lgpl.txt
+[20]: https://maven.apache.org/plugins/maven-compiler-plugin/
+[21]: https://maven.apache.org/enforcer/maven-enforcer-plugin/
+[22]: https://www.mojohaus.org/flatten-maven-plugin/
+[23]: https://sonatype.github.io/ossindex-maven/maven-plugin/
+[24]: http://zlika.github.io/reproducible-build-maven-plugin
+[25]: https://maven.apache.org/surefire/maven-surefire-plugin/
+[26]: http://www.mojohaus.org/versions-maven-plugin/
+[27]: https://maven.apache.org/plugins/maven-deploy-plugin/
+[28]: https://maven.apache.org/plugins/maven-gpg-plugin/
+[29]: https://maven.apache.org/plugins/maven-source-plugin/
+[30]: https://maven.apache.org/plugins/maven-javadoc-plugin/
+[31]: http://www.sonatype.com/public-parent/nexus-maven-plugins/nexus-staging/nexus-staging-maven-plugin/
+[32]: http://www.eclipse.org/legal/epl-v10.html
+[33]: https://www.jacoco.org/jacoco/trunk/doc/maven.html
+[34]: https://www.eclipse.org/legal/epl-2.0/
+[35]: https://github.com/exasol/error-code-crawler-maven-plugin
+[36]: https://github.com/exasol/project-keeper/
+[37]: https://github.com/exasol/project-keeper/blob/main/LICENSE
+[38]: http://maven.apache.org/plugins/maven-clean-plugin/
+[39]: http://maven.apache.org/plugins/maven-resources-plugin/
+[40]: http://maven.apache.org/plugins/maven-jar-plugin/
+[41]: http://maven.apache.org/plugins/maven-install-plugin/
+[42]: http://maven.apache.org/plugins/maven-site-plugin/
diff --git a/doc/changes/changelog.md b/doc/changes/changelog.md
@@ -1,5 +1,6 @@
 # Changes
 
+* [15.3.3](changes_15.3.3.md)
 * [15.3.2](changes_15.3.2.md)
 * [15.3.1](changes_15.3.1.md)
 * [15.3.0](changes_15.3.0.md)

diff --git a/doc/changes/changes_15.3.3.md b/doc/changes/changes_15.3.3.md
@@ -0,0 +1,21 @@
+# Common module of Exasol Virtual Schemas Adapters 15.3.3, released 2022-07-20
+
+Code name: Fixed "set properties" API documentation
+
+## Summary
+
+Version 15.3.3 fixes an error in the documentation of the Virtual Schema API that was located in the "set properties" request. The section with the updated property values was missing. Instead, the documentation claimed that `/schemaMetaData/properties` would contain the new values, which is not correct. You find the current values there.
+
+## Documentation
+
+* 247: Fixed API documentation of "set properties" request
+
+## Dependency Updates
+
+### Test Dependency Updates
+
+* Updated `org.skyscreamer:jsonassert:1.5.0` to `1.5.1`
+
+### Plugin Dependency Updates
+
+* Updated `com.exasol:project-keeper-maven-plugin:2.4.6` to `2.5.0`
diff --git a/doc/development/api/virtual_schema_api.md b/doc/development/api/virtual_schema_api.md
@@ -133,24 +133,33 @@ Notes
 
 ### Set Properties
 
-Request to set properties. The Adapter can decide whether it needs to send back new metadata. The Adapter is allowed to throw an Exception if the user provided invalid properties or in case of any other problems (e.g. connectivity).
+Request to set and unset properties. The Adapter can decide whether it needs to send back new metadata. The Adapter is allowed to throw an Exception if the user provided invalid properties or in case of any other problems (e.g. connectivity).
 
 **Request:**
 
 ```json
 {
+
     "type": "setProperties",
+    "properties": {
+        "JDBC_CONNECTION_STRING": "new-jdbc-connection-string",
+        "NEW_PROPERTY": "value of a not yet existing property",
+        "UNSET_PROPERTY": null
+    },
     "schemaMetadataInfo": {
         ...
         "properties": {
-            "JDBC_CONNECTION_STRING": "new-jdbc-connection-string",
-            "NEW_PROPERTY": "value of a not yet existing property",
-            "DELETED_PROPERTY": null
+            "JDBC_CONNECTION_STRING": "current-jdbc-connection-string",
+            "THIS_REMAINS_UNCHANGED": "not listed in the section above, so the value remains as it is"
         }
-    },
+    }
 }
 ```
 
+The new values appear in a separate object `/properties` directly in the root element. For reference the current property values are still reported under '/schemaMetadataInfo/properties'.
+
+Adapters must apply the properties incrementally, meaning that all parameters not explicitly listed in `/properties`, remain unchanged. 
+
 **Response:**
 
 ```json

diff --git a/pk_generated_parent.pom b/pk_generated_parent.pom
@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.exasol</groupId>
     <artifactId>virtual-schema-common-java-generated-parent</artifactId>
-    <version>15.3.2</version>
+    <version>15.3.3</version>
     <packaging>pom</packaging>
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

diff --git a/pom.xml b/pom.xml
@@ -1,14 +1,12 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.exasol</groupId>
     <artifactId>virtual-schema-common-java</artifactId>
-    <version>15.3.2</version>
+    <version>15.3.3</version>
     <name>Common module of Exasol Virtual Schemas Adapters</name>
     <description>This is one of the modules of Virtual Schemas Adapters. The libraries provided by this project are the
-        foundation of the adapter development, i.e. adapters must be implemented on top of them.
-    </description>
+        foundation of the adapter development, i.e. adapters must be implemented on top of them.</description>
     <url>https://github.com/exasol/virtual-schema-common-java/</url>
     <repositories>
         <repository>
@@ -53,7 +51,7 @@
         <dependency>
             <groupId>org.skyscreamer</groupId>
             <artifactId>jsonassert</artifactId>
-            <version>1.5.0</version>
+            <version>1.5.1</version>
             <scope>test</scope>
         </dependency>
         <dependency>
@@ -91,7 +89,7 @@
             <plugin>
                 <groupId>com.exasol</groupId>
                 <artifactId>project-keeper-maven-plugin</artifactId>
-                <version>2.4.6</version>
+                <version>2.5.0</version>
                 <executions>
                     <execution>
                         <goals>
@@ -105,7 +103,7 @@
     <parent>
         <artifactId>virtual-schema-common-java-generated-parent</artifactId>
         <groupId>com.exasol</groupId>
-        <version>15.3.2</version>
+        <version>15.3.3</version>
         <relativePath>pk_generated_parent.pom</relativePath>
     </parent>
 </project>