Merge branch 'feature/version_check' of https://github.com/utPLSQL/utPLSQL-java-api into feature/version_check

Samuel Nitsche · Samuel Nitsche · commit c4c6e08631d8 · 2017-11-04T13:49:25.000+01:00
diff --git a/README.md b/README.md
@@ -1,9 +1,73 @@
 [![Build Status](https://img.shields.io/travis/utPLSQL/utPLSQL-java-api/develop.svg?label=develop-branch)](https://travis-ci.org/utPLSQL/utPLSQL-java-api)
 [![Build Status](https://img.shields.io/travis/utPLSQL/utPLSQL-java-api/master.svg?label=master-branch)](https://travis-ci.org/utPLSQL/utPLSQL-java-api)
 
-##### Configuring the Oracle Maven Repository #####
+# 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.
+
+* 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.
+
+## Downloading
+This is a Maven Library project, you can add on your Java project as a dependency. At the moment, it's not available in any public Maven repository, but you can clone it and install as a local dependency (follow the Contributing session).
+
+```xml
+<dependency>
+    <groupId>org.utplsql</groupId>
+    <artifactId>java-api</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <scope>compile</scope>
+</dependency>
+```
+
+## Usage
+
+Executing tests using default parameters:
+```java
+try (Connection conn = DriverManager.getConnection(url)) {
+    new TestRunner().run(conn);
+} catch (SQLException e) {
+    e.printStackTrace();
+}
+```
+
+Executing tests and printing results to screen:
+```java
+try (Connection conn = DriverManager.getConnection(url)) {
+    Reporter documentationReporter = new DocumentationReporter().init(conn);
+    
+    new TestRunner()
+        .addReporter(documentationReporter)
+        .run(conn);
+    
+    new OutputBuffer(documentationReporter)
+        .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.*
+
+### 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
-https://blogs.oracle.com/dev2dev/entry/how_to_get_oracle_jdbc#pom
 
-##### IntelliJ IDEA Maven Module #####
-https://www.jetbrains.com/help/idea/2017.1/maven.html
+*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.*
+
+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 -DskipTests
+```
+
+The cmd above is ignoring unit tests because it needs a database connection with the latest utPLSQL v3 installed. Please take a look on .travis.yml and .travis folder to see how testing was configured.
diff --git a/src/main/java/org/utplsql/api/DBHelper.java b/src/main/java/org/utplsql/api/DBHelper.java
@@ -12,7 +12,7 @@
  */
 public final class DBHelper {
 
-    public static final String UTPLSQL_VERSION = "3.0.3";
+    public static final String UTPLSQL_COMPATIBILITY_VERSION = "3.0.3";
 
     private DBHelper() {}
 
@@ -93,7 +93,31 @@ public static boolean versionCompatibilityCheck(Connection conn, String requeste
 
     public static boolean versionCompatibilityCheck(Connection conn)
             throws SQLException {
-        return versionCompatibilityCheck(conn, UTPLSQL_VERSION);
+        return versionCompatibilityCheck(conn, UTPLSQL_COMPATIBILITY_VERSION);
+    }
+
+    /**
+     * Enable the dbms_output buffer with unlimited size.
+     * @param conn the connection
+     */
+    public static void enableDBMSOutput(Connection conn) {
+        try (CallableStatement call = conn.prepareCall("BEGIN dbms_output.enable(NULL); END;")) {
+            call.execute();
+        } catch (SQLException e) {
+            System.out.println("Failed to enable dbms_output.");
+        }
+    }
+
+    /**
+     * Disable the dbms_output buffer.
+     * @param conn the connection
+     */
+    public static void disableDBMSOutput(Connection conn) {
+        try (CallableStatement call = conn.prepareCall("BEGIN dbms_output.disable(); END;")) {
+            call.execute();
+        } catch (SQLException e) {
+            System.out.println("Failed to disable dbms_output.");
+        }
     }
 
     /** Checks if actual API-version is compatible with utPLSQL database version and throws a RuntimeException if not
diff --git a/src/main/java/org/utplsql/api/TestRunner.java b/src/main/java/org/utplsql/api/TestRunner.java
@@ -107,6 +107,8 @@ public void run(Connection conn) throws SomeTestsFailedException, SQLException {
         OracleConnection oraConn = conn.unwrap(OracleConnection.class);
         CallableStatement callableStatement = null;
         try {
+            DBHelper.enableDBMSOutput(conn);
+
             callableStatement = conn.prepareCall(
                     "BEGIN " +
                         "ut_runner.run(" +
@@ -176,8 +178,11 @@ public void run(Connection conn) throws SomeTestsFailedException, SQLException {
                 throw e;
             }
         } finally {
-            if (callableStatement != null)
+            if (callableStatement != null) {
                 callableStatement.close();
+            }
+
+            DBHelper.disableDBMSOutput(conn);
         }
     }
 
