diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..64ed197 --- /dev/null +++ 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 + + + + + utPLSQL-local + + localhost:1521/XE + app + app + + + + + + utPLSQL-local + + +``` + +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 index c5b2b05..13339b5 100644 --- 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 `` section of your `p org.utplsql java-api - 3.0.4 + 3.1.0 compile ``` ## 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 - - - - - utPLSQL-local - - localhost:1521/XE - app - app - - - - - - utPLSQL-local - - +```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) \ No newline at end of file diff --git a/src/main/java/org/utplsql/api/outputBuffer/AbstractOutputBuffer.java b/src/main/java/org/utplsql/api/outputBuffer/AbstractOutputBuffer.java index 1fa2f43..4dac3a4 100644 --- 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 index 7b981d1..4279e9c 100644 --- 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 index 09d82ef..78ef639 100644 --- 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 index f9b5b1f..a0c0032 100644 --- 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) {