utPLSQL-java-api

This is a collection of classes, that makes easy to access the utPLSQL v3 database objects using Java.

• Uses ut_runner.run 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.

The project is hosted on packagecloud.io

You install this Maven repository by adding it to the section of your pom.xml. No special plugins or extensions are required.

<repositories>
  <repository>
    <id>utplsql-java-api</id>
    <url>
      https://packagecloud.io/utplsql/utplsql-java-api/maven2
    </url>
    <releases>
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

To use the java-api library, add this to the <dependencies> section of your pom.xml.

<dependency>
    <groupId>org.utplsql</groupId>
    <artifactId>java-api</artifactId>
    <version>3.0.4</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.

Usage

Executing tests using default parameters:

try (Connection conn = DriverManager.getConnection(url)) {
    new TestRunner().run(conn);
} catch (SQLException e) {
    e.printStackTrace();
}

Executing tests and printing results to screen:

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

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 and 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:

<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.

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.