Document usage

Author: mrotteveel

README.md

@@ -38,6 +38,110 @@ testCompile "org.firebirdsql:firebird-testcontainers-java:1.0.0"
 </dependency>
 ```
 
+Usage
+-----
+
+For extensive documentation, consult https://www.testcontainers.org/modules/databases/
+
+### JUnit rule
+
+Using a JUnit `@Rule` or `@ClassRule` you can configure a container and start it
+per test (`@Rule`) or per class (`@ClassRule`).
+
+The container defines several `withXXX` methods for configuration.
+
+Important standard options are:
+
+- `withUsername(String)` - Sets the username to create (defaults to `test`); if
+other than `sysdba` (case insensitive), sets docker environment variable
+`FIREBIRD_USER`
+- `withPassword(String)` - Sets the password of the user (defaults to `test`);
+if `withUsername` is other than `sysdba` (case insensitive), sets the docker
+environment variable `FIREBIRD_PASSWORD`, otherwise `ISC_PASSWORD`
+- `withDatabaseName(String)` - Sets the database name (defaults to `test`);
+sets docker environment variable `FIREBIRD_DATABASE`
+
+Firebird specific options are:
+
+- `withEnableLegacyClientAuth()` - (_Firebird 3+_) Enables `LegacyAuth` and uses
+it as the default for creating users, also relaxes `WireCrypt` to `Enabled`;
+sets docker environment variable `EnableLegacyClientAuth` to `true`
+- `withEnableWireCrypt` - (_Firebird 3+_) Relaxes `WireCrypt` from `Required` to
+`Enabled`; sets docker environment variable `EnableWireCrypt` to `true
+- `withTimeZone(String)` - Sets the time zone (defaults to JVM default time
+zone); sets docker environment variable `TZ` to the specified value
+- `withSysdbaPassword(String)` - Sets the SYSDBA password, but if 
+`withUsername(String)` is set to `sysdba` (case insensitive), this property is
+ignored and the value of `withPassword` is used instead; sets docker
+environment variable `ISC_PASSWORD` to the specified value
+
+Example of use:
+
+```java
+/**
+ * Simple test demonstrating use of {@code @Rule}.
+ */
+public class ExampleRuleTest {
+
+    @Rule
+    public final FirebirdContainer container = new FirebirdContainer()
+            .withUsername("testuser")
+            .withPassword("testpassword");
+
+    @Test
+    public void canConnectToContainer() throws Exception {
+        try (Connection connection = DriverManager
+                .getConnection(container.getJdbcUrl(), container.getUsername(), container.getPassword());
+             Statement stmt = connection.createStatement();
+             ResultSet rs = stmt.executeQuery("select CURRENT_USER from RDB$DATABASE")) {
+            assertTrue("has row", rs.next());
+            assertEquals("user name", "TESTUSER", rs.getString(1));
+        }
+    }
+}
+```
+
+### Testcontainers URL
+
+The testcontainers URL defines the container and connects to it. As long as there
+are active connections, the container will stay up.
+
+For Firebird the URL format is:
+
+- `jdbc:tc:firebird[:<image-tag>]://hostname/<databasename>[?<property>=<value>[&<property>=<value>...]]`
+- `jdbc:tc:firebirdsql[:<image-tag>]://hostname/<databasename>[?<property>=<value>[&<property>=<value>...]]`
+
+Where:
+
+- `<image-tag>` (_optional_) is the tag of the docker image to use
+- `<databasename>` (_optional_) is the name of the database (defaults to `test`)
+- `<property>` is a connection property (Jaybird properties **and** testcontainers properties are possible) \
+  Of special note are the properties:
+  - `user` (_optional_) specifies the username to create and connect (defaults to `test`)
+  - `password` (_optional_) specifies the password for the user (defaults to `test`)
+- `<value>` is the value of the property
+
+Example of use:
+
+```java
+/**
+ * Simple test demonstrating use of url to instantiate container.
+ */
+public class ExampleUrlTest {
+
+    @Test
+    public void canConnectUsingUrl() throws Exception {
+        try (Connection connection = DriverManager
+                .getConnection("jdbc:tc:firebird://hostname/databasename?user=someuser&password=somepwd");
+             Statement stmt = connection.createStatement();
+             ResultSet rs = stmt.executeQuery("select CURRENT_USER from RDB$DATABASE")) {
+            assertTrue("has row", rs.next());
+            assertEquals("user name", "SOMEUSER", rs.getString(1));
+        }
+    }
+}
+```
+
 License
 -------
 

…ebirdsql/testcontainers/ExampleTest.java …containers/examples/ExampleRuleTest.javasrc/test/java/org/firebirdsql/testcontainers/ExampleTest.java renamed to src/test/java/org/firebirdsql/testcontainers/examples/ExampleRuleTest.java src/test/java/org/firebirdsql/testcontainers/ExampleTest.java renamed to src/test/java/org/firebirdsql/testcontainers/examples/ExampleRuleTest.java

@@ -1,5 +1,6 @@
-package org.firebirdsql.testcontainers;
+package org.firebirdsql.testcontainers.examples;
 
+import org.firebirdsql.testcontainers.FirebirdContainer;
 import org.junit.Rule;
 import org.junit.Test;
 
@@ -14,10 +15,12 @@
 /**
  * Simple test demonstrating use of {@code @Rule}.
  */
-public class ExampleTest {
+public class ExampleRuleTest {
 
     @Rule
-    public final FirebirdContainer container = new FirebirdContainer();
+    public final FirebirdContainer container = new FirebirdContainer()
+            .withUsername("testuser")
+            .withPassword("testpassword");
 
     @Test
     public void canConnectToContainer() throws Exception {
@@ -26,7 +29,7 @@ public void canConnectToContainer() throws Exception {
              Statement stmt = connection.createStatement();
              ResultSet rs = stmt.executeQuery("select CURRENT_USER from RDB$DATABASE")) {
             assertTrue("has row", rs.next());
-            assertEquals("user name", container.getUsername().toUpperCase(), rs.getString(1));
+            assertEquals("user name", "TESTUSER", rs.getString(1));
         }
     }
 }

src/test/java/org/firebirdsql/testcontainers/examples/ExampleUrlTest.java

@@ -0,0 +1,28 @@
+package org.firebirdsql.testcontainers.examples;
+
+import org.junit.Test;
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.ResultSet;
+import java.sql.Statement;
+
+import static org.rnorth.visibleassertions.VisibleAssertions.assertEquals;
+import static org.rnorth.visibleassertions.VisibleAssertions.assertTrue;
+
+/**
+ * Simple test demonstrating use of url to instantiate container.
+ */
+public class ExampleUrlTest {
+
+    @Test
+    public void canConnectUsingUrl() throws Exception {
+        try (Connection connection = DriverManager
+                .getConnection("jdbc:tc:firebird://hostname/databasename?user=someuser&password=somepwd");
+             Statement stmt = connection.createStatement();
+             ResultSet rs = stmt.executeQuery("select CURRENT_USER from RDB$DATABASE")) {
+            assertTrue("has row", rs.next());
+            assertEquals("user name", "SOMEUSER", rs.getString(1));
+        }
+    }
+}