Skip to content

Feature/documentation update #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 28, 2018
Merged

Feature/documentation update #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
994e5f4
Fluid interface for OutputBuffer
pesse Mar 28, 2018
ffd7056
Update documentation - more to come
pesse Mar 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
95 changes: 44 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)) {
Expand All @@ -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)
3 changes: 2 additions & 1 deletion src/main/java/org/utplsql/api/outputBuffer/AbstractOutputBuffer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,9 @@ public Reporter getReporter() {
}

@Override
public void setFetchSize(int fetchSize) {
public OutputBuffer setFetchSize(int fetchSize) {
this.fetchSize = fetchSize;
return this;
}

/**
Expand Down
4 changes: 2 additions & 2 deletions src/main/java/org/utplsql/api/outputBuffer/NonOutputBuffer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ public Reporter getReporter() {
}

@Override
public void setFetchSize(int fetchSize) {

public OutputBuffer setFetchSize(int fetchSize) {
return this;
}

@Override
Expand Down
3 changes: 2 additions & 1 deletion src/main/java/org/utplsql/api/outputBuffer/OutputBuffer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 3 additions & 2 deletions src/test/java/org/utplsql/api/OutputBufferIT.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down