Skip to content

Commit 3698ba1

Browse files
pessepesse
authored
Merge pull request #53 from utPLSQL/feature/documentation_update
Feature/documentation update
2 parents 3d48df7 + ffd7056 commit 3698ba1

File tree

6 files changed

+112
-57
lines changed

6 files changed

+112
-57
lines changed

Diff for: ‎CONTRIBUTING.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Contributing
2+
To develop it locally, you need to setup your maven environment.
3+
4+
### Maven Installation
5+
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.
6+
7+
https://maven.apache.org/install.html
8+
9+
*Don't forget to configure your JAVA_HOME environment variable.*
10+
11+
### Oracle Maven Repository
12+
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:
13+
14+
http://docs.oracle.com/middleware/1213/core/MAVEN/config_maven_repo.htm#MAVEN9010
15+
16+
*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.*
17+
18+
### Local database with utPLSQL and utPLSQL-demo-project
19+
20+
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).
21+
The demo-project will serve as your test user. See .travis.yml to see an example on how it can be installed.
22+
23+
### Maven settings for utPLSQL-local profile
24+
25+
utPLSQL-java-api comes with a preconfigured profile "utPLSQL-local". This profile uses properties to set the correct
26+
environment variables for DB_URL, DB_USER and DB_PASS which is needed to run the integration tests.
27+
You can set these properties by adding the following to your Maven settings.xml:
28+
29+
```xml
30+
<settings>
31+
<!-- ... -->
32+
<profiles>
33+
<profile>
34+
<id>utPLSQL-local</id>
35+
<properties>
36+
<dbUrl>localhost:1521/XE</dbUrl>
37+
<dbUser>app</dbUser>
38+
<dbPass>app</dbPass>
39+
</properties>
40+
</profile>
41+
</profiles>
42+
43+
<activeProfiles>
44+
<activeProfile>utPLSQL-local</activeProfile>
45+
</activeProfiles>
46+
</settings>
47+
```
48+
49+
After configuring your access to Oracle's Maven repository, you will be able to successfully build this API.
50+
51+
```bash
52+
cd utPLSQL-java-api
53+
mvn clean package install
54+
```
55+
56+
### Skip the local database part
57+
58+
If you want to skip the local database part, just run ``mvn clean package install -DskipTests``.
59+
You will still be able to run ``mvn test`` because integration tests are run in the ``verify``-phase.

Diff for: ‎README.md

+44-51
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,11 @@
22
[![Build Status](https://img.shields.io/travis/utPLSQL/utPLSQL-java-api/master.svg?label=master-branch)](https://travis-ci.org/utPLSQL/utPLSQL-java-api)
33

44
# utPLSQL-java-api
5-
This is a collection of classes, that makes easy to access the [utPLSQL v3](https://github.com/utPLSQL/utPLSQL/) database objects using Java.
5+
This is a collection of classes, that makes it easy to access the [utPLSQL v3](https://github.com/utPLSQL/utPLSQL/) database objects using Java.
66

77
* Uses [ut_runner.run](https://github.com/utPLSQL/utPLSQL/blob/develop/docs/userguide/running-unit-tests.md#ut_runnerrun-procedures) methods to execute tests.
88
* Can gather results asynchronously from multiple reporters.
9+
* Handles compatibility for all 3.x versions of utPLSQL
910

1011
## Downloading
1112
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
3940
<dependency>
4041
<groupId>org.utplsql</groupId>
4142
<artifactId>java-api</artifactId>
42-
<version>3.0.4</version>
43+
<version>3.1.0</version>
4344
<scope>compile</scope>
4445
</dependency>
4546
```
4647

4748
## Compatibility
4849
The latest Java-API is always compatible with all database frameworks of the same major version.
49-
For example API-3.0.4 is compatible with database framework 3.0.0-3.0.4 but not with database framework 2.x.
50+
For example API-3.0.4 is compatible with database framework 3.0.0-3.1.0 but not with database framework 2.x.
5051

5152
## Usage
5253

54+
You can find examples for many features of the java-api in the Unit- and Integration tests.
55+
56+
### Test-Runner
57+
5358
Executing tests using default parameters:
5459
```java
5560
try (Connection conn = DriverManager.getConnection(url)) {
@@ -68,69 +73,57 @@ try (Connection conn = DriverManager.getConnection(url)) {
6873
.addReporter(documentationReporter)
6974
.run(conn);
7075

71-
new OutputBuffer(documentationReporter)
76+
documentationReporter
77+
.getOutputBuffer()
78+
.setFetchSize(1)
7279
.printAvailable(conn, System.out);
7380
} catch (SQLException e) {
7481
e.printStackTrace();
7582
}
7683
```
7784

78-
## Contributing
79-
To develop it locally, you need to setup your maven environment.
80-
81-
### Maven Installation
82-
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.
83-
84-
https://maven.apache.org/install.html
85-
86-
*Don't forget to configure your JAVA_HOME environment variable.*
85+
### Optional Features
8786

88-
### Oracle Maven Repository
89-
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:
87+
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:
9088

91-
http://docs.oracle.com/middleware/1213/core/MAVEN/config_maven_repo.htm#MAVEN9010
89+
```OptionalFeatures.CUSTOM_REPORTERS.isAvailableFor( databaseConnection );```
9290

93-
*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.*
91+
### Compatibility-Proxy
92+
To handle downwards-compatibility, java-api provides an easy to use CompatiblityProxy, which is instantiated with a connection.
93+
It will check the database-version of utPLSQL and is used in several other features like `TestRunner` and `ReporterFactory`.
94+
You can also ask it for the database-version.
9495

95-
### Local database with utPLSQL and utPLSQL-demo-project
96+
```java
97+
try (Connection conn = DriverManager.getConnection(url)) {
98+
CompatiblityProxy proxy = new CompatibilityProxy( conn );
99+
Version version = proxy.getDatabaseVersion();
100+
} catch (SQLException e) {
101+
e.printStackTrace();
102+
}
103+
```
96104

97-
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).
98-
The demo-project will serve as your test user. See .travis.yml to see an example on how it can be installed.
105+
### Reporter-Factory
99106

100-
### Maven settings for utPLSQL-local profile
107+
The java-api provides a ReporterFactory you can use to inject your own implementations of (java-side) reporters or reporter-handlers.
108+
It also provides a more generic approach to Reporter-handling.
101109

102-
utPLSQL-java-api comes with a preconfigured profile "utPLSQL-local". This profile uses properties to set the correct
103-
environment variables for DB_URL, DB_USER and DB_PASS which is needed to run the integration tests.
104-
You can set these properties by adding the following to your Maven settings.xml:
110+
If you request the Reporter-Factory for a Reporter it has no specific implementation for it will just
111+
return an instance of a `DefaultReporter` with the given name as SQL-Type, assuming
112+
that it exists in the database. Therefore you can address custom reporters without the need
113+
of a specific java-side implementation.
105114

106-
```xml
107-
<settings>
108-
<!-- ... -->
109-
<profiles>
110-
<profile>
111-
<id>utPLSQL-local</id>
112-
<properties>
113-
<dbUrl>localhost:1521/XE</dbUrl>
114-
<dbUser>app</dbUser>
115-
<dbPass>app</dbPass>
116-
</properties>
117-
</profile>
118-
</profiles>
119-
120-
<activeProfiles>
121-
<activeProfile>utPLSQL-local</activeProfile>
122-
</activeProfiles>
123-
</settings>
115+
```java
116+
try (Connection conn = DriverManager.getConnection(url)) {
117+
ReporterFactory reporterFactory = ReporterFactory.createDefault( new CompatibilityProxy( conn ));
118+
reporterFactory.registerReporterFactoryMethod(CoreReporters.UT_DOCUMENTATION_REPORTER.name(), MyCustomReporterImplementation::new, "Custom handler for UT_DOCUMENTATION_REPORTER");
119+
120+
Reporter reporter = reporterFactory.createReporter(CreateReporters.UT_DOCUMENTATION_REPORTER.name());
121+
} catch (SQLException e) {
122+
e.printStackTrace();
123+
}
124124
```
125125

126-
After configuring your access to Oracle's Maven repository, you will be able to successfully build this API.
127126

128-
```bash
129-
cd utPLSQL-java-api
130-
mvn clean package install
131-
```
132-
133-
### Skip the local database part
127+
## Contributing
134128

135-
If you want to skip the local database part, just run ``mvn clean package install -DskipTests``.
136-
You will still be able to run ``mvn test`` because integration tests are run in the ``verify``-phase.
129+
See [CONTRIBUTING.md](CONTRIBUTING.md)

Diff for: ‎src/main/java/org/utplsql/api/outputBuffer/AbstractOutputBuffer.java

+2-1
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,9 @@ public Reporter getReporter() {
4242
}
4343

4444
@Override
45-
public void setFetchSize(int fetchSize) {
45+
public OutputBuffer setFetchSize(int fetchSize) {
4646
this.fetchSize = fetchSize;
47+
return this;
4748
}
4849

4950
/**

Diff for: ‎src/main/java/org/utplsql/api/outputBuffer/NonOutputBuffer.java

+2-2
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@ public Reporter getReporter() {
2727
}
2828

2929
@Override
30-
public void setFetchSize(int fetchSize) {
31-
30+
public OutputBuffer setFetchSize(int fetchSize) {
31+
return this;
3232
}
3333

3434
@Override

Diff for: ‎src/main/java/org/utplsql/api/outputBuffer/OutputBuffer.java

+2-1
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,9 @@ public interface OutputBuffer {
1515
/** Override the fetchSize of the OutputBuffer
1616
*
1717
* @param fetchSize the ResultSet fetch-size.
18+
* @return this Output-Buffer
1819
*/
19-
void setFetchSize( int fetchSize );
20+
OutputBuffer setFetchSize( int fetchSize );
2021

2122
/**
2223
* Print the lines as soon as they are produced and write to a PrintStream.

Diff for: ‎src/test/java/org/utplsql/api/OutputBufferIT.java

+3-2
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,9 @@ public void printAvailableLines() throws SQLException {
5959
printStreams.add(System.out);
6060
printStreams.add(new PrintStream(fileOutStream));
6161

62-
reporter.getOutputBuffer().setFetchSize(1);
63-
reporter.getOutputBuffer().printAvailable(newConnection(), printStreams);
62+
reporter.getOutputBuffer()
63+
.setFetchSize(1)
64+
.printAvailable(newConnection(), printStreams);
6465

6566
return Boolean.TRUE;
6667
} catch (SQLException e) {

0 commit comments

Comments
 (0)