Merge pull request #53 from utPLSQL/feature/documentation_update

Feature/documentation update
utPLSQL · Mar 28, 2018 · 3698ba1 · 3698ba1
2 parents 3d48df7 + ffd7056
commit 3698ba1
Show file tree

Hide file tree

Showing 6 changed files with 112 additions and 57 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,59 @@
+# Contributing
+To develop it locally, you need to setup your maven environment.
+
+### Maven Installation
+That's the easy part, you just need to download the Maven binaries and extract it somewhere, then put the maven/bin folder on your PATH.
+
+https://maven.apache.org/install.html
+
+*Don't forget to configure your JAVA_HOME environment variable.*
+
+### Oracle Maven Repository
+The library uses OJDBC Driver to connect to the database, it's added as a maven dependency. To be able to download the Oracle dependencies, you need to configure your access to Oracle's Maven Repository:
+
+http://docs.oracle.com/middleware/1213/core/MAVEN/config_maven_repo.htm#MAVEN9010
+
+*Sections 6.1 and 6.5 are the more important ones, and the only ones you need if you're using the latest Maven version.*
+
+### Local database with utPLSQL and utPLSQL-demo-project
+
+To usefully contribute you'll have to setup a local database with installed [latest utPLSQL v3](https://github.com/utPLSQL/utPLSQL) and [utPLSQL-demo-project](https://github.com/utPLSQL/utPLSQL-demo-project). 
+The demo-project will serve as your test user. See .travis.yml to see an example on how it can be installed. 
+
+### Maven settings for utPLSQL-local profile
+
+utPLSQL-java-api comes with a preconfigured profile "utPLSQL-local". This profile uses properties to set the correct 
+environment variables for DB_URL, DB_USER and DB_PASS which is needed to run the integration tests.
+You can set these properties by adding the following to your Maven settings.xml:
+
+```xml
+<settings>
+    <!-- ... -->
+    <profiles>
+        <profile>
+            <id>utPLSQL-local</id>
+            <properties>
+                <dbUrl>localhost:1521/XE</dbUrl>
+                <dbUser>app</dbUser>
+                <dbPass>app</dbPass>
+            </properties>
+        </profile>
+    </profiles>
+
+    <activeProfiles>
+        <activeProfile>utPLSQL-local</activeProfile>
+    </activeProfiles>
+</settings>
+```
+
+After configuring your access to Oracle's Maven repository, you will be able to successfully build this API.
+
+```bash
+cd utPLSQL-java-api
+mvn clean package install
+```
+
+### Skip the local database part
+
+If you want to skip the local database part, just run ``mvn clean package install -DskipTests``. 
+You will still be able to run ``mvn test`` because integration tests are run in the ``verify``-phase.
diff --git a/README.md b/README.md
@@ -2,10 +2,11 @@
 [![Build Status](https://img.shields.io/travis/utPLSQL/utPLSQL-java-api/master.svg?label=master-branch)](https://travis-ci.org/utPLSQL/utPLSQL-java-api)
 
 # utPLSQL-java-api
-This is a collection of classes, that makes easy to access the [utPLSQL v3](https://github.com/utPLSQL/utPLSQL/) database objects using Java.
+This is a collection of classes, that makes it easy to access the [utPLSQL v3](https://github.com/utPLSQL/utPLSQL/) database objects using Java.
 
 * Uses [ut_runner.run](https://github.com/utPLSQL/utPLSQL/blob/develop/docs/userguide/running-unit-tests.md#ut_runnerrun-procedures) methods to execute tests.
 * Can gather results asynchronously from multiple reporters.
+* Handles compatibility for all 3.x versions of utPLSQL
 
 ## Downloading
 This is a Maven Library project, you can add on your Java project as a dependency. 
@@ -39,17 +40,21 @@ To use the java-api library, add this to the `<dependencies>` section of your `p
 <dependency>
     <groupId>org.utplsql</groupId>
     <artifactId>java-api</artifactId>
-    <version>3.0.4</version>
+    <version>3.1.0</version>
     <scope>compile</scope>
 </dependency>
 ```
 
 ## Compatibility
 The latest Java-API is always compatible with all database frameworks of the same major version.
-For example API-3.0.4 is compatible with database framework 3.0.0-3.0.4 but not with database framework 2.x.
+For example API-3.0.4 is compatible with database framework 3.0.0-3.1.0 but not with database framework 2.x.
 
 ## Usage
 
+You can find examples for many features of the java-api in the Unit- and Integration tests.
+
+### Test-Runner
+
 Executing tests using default parameters:
 ```java
 try (Connection conn = DriverManager.getConnection(url)) {
@@ -68,69 +73,57 @@ try (Connection conn = DriverManager.getConnection(url)) {
         .addReporter(documentationReporter)
         .run(conn);
 
-    new OutputBuffer(documentationReporter)
+    documentationReporter
+        .getOutputBuffer()
+        .setFetchSize(1)
         .printAvailable(conn, System.out);
 } catch (SQLException e) {
     e.printStackTrace();
 }
 ```
 
-## Contributing
-To develop it locally, you need to setup your maven environment.
-
-### Maven Installation
-That's the easy part, you just need to download the Maven binaries and extract it somewhere, then put the maven/bin folder on your PATH.
-
-https://maven.apache.org/install.html
-
-*Don't forget to configure your JAVA_HOME environment variable.*
+### Optional Features
 
-### Oracle Maven Repository
-The library uses OJDBC Driver to connect to the database, it's added as a maven dependency. To be able to download the Oracle dependencies, you need to configure your access to Oracle's Maven Repository:
+There might be some features which are not available in previous versions of utPLSQL. These "optional features" are listed in the enum org.utplsql.api.compatibility.OptionalFeatures and their availability can be checked against a connection or Version-object:
 
-http://docs.oracle.com/middleware/1213/core/MAVEN/config_maven_repo.htm#MAVEN9010
+```OptionalFeatures.CUSTOM_REPORTERS.isAvailableFor( databaseConnection );```
 
-*Sections 6.1 and 6.5 are the more important ones, and the only ones you need if you're using the latest Maven version.*
+### Compatibility-Proxy
+To handle downwards-compatibility, java-api provides an easy to use CompatiblityProxy, which is instantiated with a connection.
+It will check the database-version of utPLSQL and is used in several other features like `TestRunner` and `ReporterFactory`.
+You can also ask it for the database-version.
 
-### Local database with utPLSQL and utPLSQL-demo-project
+```java
+try (Connection conn = DriverManager.getConnection(url)) {
+   CompatiblityProxy proxy = new CompatibilityProxy( conn );
+   Version version = proxy.getDatabaseVersion();
+} catch (SQLException e) {
+    e.printStackTrace();
+}
+```
 
-To usefully contribute you'll have to setup a local database with installed [latest utPLSQL v3](https://github.com/utPLSQL/utPLSQL) and [utPLSQL-demo-project](https://github.com/utPLSQL/utPLSQL-demo-project). 
-The demo-project will serve as your test user. See .travis.yml to see an example on how it can be installed. 
+### Reporter-Factory
 
-### Maven settings for utPLSQL-local profile
+The java-api provides a ReporterFactory you can use to inject your own implementations of (java-side) reporters or reporter-handlers.
+It also provides a more generic approach to Reporter-handling.
 
-utPLSQL-java-api comes with a preconfigured profile "utPLSQL-local". This profile uses properties to set the correct 
-environment variables for DB_URL, DB_USER and DB_PASS which is needed to run the integration tests.
-You can set these properties by adding the following to your Maven settings.xml:
+If you request the Reporter-Factory for a Reporter it has no specific implementation for it will just
+return an instance of a `DefaultReporter` with the given name as SQL-Type, assuming
+that it exists in the database. Therefore you can address custom reporters without the need 
+of a specific java-side implementation.
 
-```xml
-<settings>
-    <!-- ... -->
-    <profiles>
-        <profile>
-            <id>utPLSQL-local</id>
-            <properties>
-                <dbUrl>localhost:1521/XE</dbUrl>
-                <dbUser>app</dbUser>
-                <dbPass>app</dbPass>
-            </properties>
-        </profile>
-    </profiles>
-
-    <activeProfiles>
-        <activeProfile>utPLSQL-local</activeProfile>
-    </activeProfiles>
-</settings>
+```java
+try (Connection conn = DriverManager.getConnection(url)) {
+    ReporterFactory reporterFactory = ReporterFactory.createDefault( new CompatibilityProxy( conn ));
+    reporterFactory.registerReporterFactoryMethod(CoreReporters.UT_DOCUMENTATION_REPORTER.name(), MyCustomReporterImplementation::new, "Custom handler for UT_DOCUMENTATION_REPORTER");
+
+    Reporter reporter = reporterFactory.createReporter(CreateReporters.UT_DOCUMENTATION_REPORTER.name());
+} catch (SQLException e) {
+    e.printStackTrace();
+}
 ```
 
-After configuring your access to Oracle's Maven repository, you will be able to successfully build this API.
 
-```bash
-cd utPLSQL-java-api
-mvn clean package install
-```
-
-### Skip the local database part
+## Contributing
 
-If you want to skip the local database part, just run ``mvn clean package install -DskipTests``. 
-You will still be able to run ``mvn test`` because integration tests are run in the ``verify``-phase.
+See [CONTRIBUTING.md](CONTRIBUTING.md)
diff --git a/src/main/java/org/utplsql/api/outputBuffer/AbstractOutputBuffer.java b/src/main/java/org/utplsql/api/outputBuffer/AbstractOutputBuffer.java
@@ -42,8 +42,9 @@ public Reporter getReporter() {
     }
 
     @Override
-    public void setFetchSize(int fetchSize) {
+    public OutputBuffer setFetchSize(int fetchSize) {
         this.fetchSize = fetchSize;
+        return this;
     }
 
     /**

diff --git a/src/main/java/org/utplsql/api/outputBuffer/NonOutputBuffer.java b/src/main/java/org/utplsql/api/outputBuffer/NonOutputBuffer.java
@@ -27,8 +27,8 @@ public Reporter getReporter() {
     }
 
     @Override
-    public void setFetchSize(int fetchSize) {
-
+    public OutputBuffer setFetchSize(int fetchSize) {
+        return this;
     }
 
     @Override

diff --git a/src/main/java/org/utplsql/api/outputBuffer/OutputBuffer.java b/src/main/java/org/utplsql/api/outputBuffer/OutputBuffer.java
@@ -15,8 +15,9 @@ public interface OutputBuffer {
     /** Override the fetchSize of the OutputBuffer
      *
      * @param fetchSize the ResultSet fetch-size.
+     * @return this Output-Buffer
      */
-    void setFetchSize( int fetchSize );
+    OutputBuffer setFetchSize( int fetchSize );
 
     /**
      * Print the lines as soon as they are produced and write to a PrintStream.

diff --git a/src/test/java/org/utplsql/api/OutputBufferIT.java b/src/test/java/org/utplsql/api/OutputBufferIT.java
@@ -59,8 +59,9 @@ public void printAvailableLines() throws SQLException {
                     printStreams.add(System.out);
                     printStreams.add(new PrintStream(fileOutStream));
 
-                    reporter.getOutputBuffer().setFetchSize(1);
-                    reporter.getOutputBuffer().printAvailable(newConnection(), printStreams);
+                    reporter.getOutputBuffer()
+                            .setFetchSize(1)
+                            .printAvailable(newConnection(), printStreams);
 
                     return Boolean.TRUE;
                 } catch (SQLException e) {