Docs migration to Antora

Author: VanRoy

README.md

@@ -1,4 +1,4 @@
-![alt tag](img/assertj-db_icon.png)
+![alt tag](src/main/docs/modules/ROOT/images/assertj-db_icon.png)
 AssertJ-DB - Assertions for database
 ==========
 

src/main/docs/antora.yml

@@ -0,0 +1,12 @@
+name: assertj-db
+title: AssertJ DB
+nav:
+- modules/ROOT/nav.adoc
+ext:
+  collector:
+    scan:
+      dir: src/test/java/org/example/db
+      into: modules/ROOT/examples
+asciidoc:
+  attributes:
+    project-description: 'Provide assertions for Guava types (Multimap, Optional, ...)'

img/assertj-db_icon.png renamed to src/main/docs/modules/ROOT/images/assertj-db_icon.png

@@ -0,0 +1,14 @@
+* xref:index.adoc[]
+* xref:quickstart.adoc[]
+* xref:concepts/index.adoc[]
+** xref:concepts/connection.adoc[Connection]
+** xref:concepts/elements.adoc[Elements]
+** xref:concepts/types.adoc[]
+** xref:concepts/navigation.adoc[]
+** xref:concepts/datetime.adoc[Date Time]
+** xref:concepts/description.adoc[Description]
+** xref:concepts/letter-case.adoc[Letter Case]
+** xref:concepts/output.adoc[]
+* xref:features/index.adoc[]
+** xref:features/navigation.adoc[]
+** xref:features/assertions.adoc[]

img/assertj-db_icon.xcf renamed to src/main/docs/modules/ROOT/images/assertj-db_icon.xcf

@@ -0,0 +1,69 @@
+= Connection to the database
+
+To make assertions on a database, it is necessary to connect. The concept of `AssertDbConnection` represent how
+AssertJ-DB can retrieve data and schema information from database.
+
+It's also with a `AssertDbConnection` that you can instantiate the following element : `Table`, `Request`, `Changes`.
+
+[[AssertDbConnection]]
+== AssertDbConnection
+
+A https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnection.html[AssertDbConnection]
+is created with the factory https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnectionFactory.html[AssertDbConnectionFactory].
+
+There are 2 way to begin the AssertDbConnectionFactory, with a http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html[DataSource] ( the classic Java way
+to get a http://docs.oracle.com/javase/6/docs/api/java/sql/Connection.html[Connection] to a database ) or with JDBC connection information.
+
+Below is an example of using a DataSource to connect to H2 in memory database :
+
+[source,java]
+----
+AssertDbConnection connection = AssertDbConnectionFactory.of("jdbc:h2:mem:test", "sa", "").create();
+----
+
+And using a DataSource to connect :
+
+[source,java]
+----
+AssertDbConnection connection = AssertDbConnectionFactory.of(dataSource).create();
+----
+
+== LetterCase setup
+
+https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnectionFactory.html[AssertDbConnectionFactory]
+provide the capacity to indicate the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase]
+to use for the tables, columns and primary keys.
+
+[source,java]
+----
+AssertDbConnection connection = AssertDbConnectionFactory
+    .of(dataSource)
+    .letterCase(tableLetterCase, columnLetterCase, pkLetterCase)
+    .create();
+----
+
+For more information, see the <<assertj-db-concepts-dblettercase,paragraph on LetterCase>>.
+
+== Schema retrieval mode
+
+For many assertions, AssertJ-DB require to discover database schema metadata ( list of tables, columns, ... ).
+When the schema contains many tables this operation can slow down the tests executions.
+
+To avoid that and when the database schema is not updated during the test session, you can use the option
+https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/SchemaMetaDataMode.html[SchemaMetaDataMode] of
+https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnectionFactory.html[AssertDbConnectionFactory]
+to keep in memory the schema.
+
+Available mode are :
+
+ - DYNAMIC ( default ): Retrieve schema metadata each time is required.
+ - STATIC : Retrieve schema metadata only once and keep in memory for all duration of connection.
+
+Below is an example of using the STATIC mode for a connection :
+
+[source,java]
+----
+AssertDbConnection connection = AssertDbConnectionFactory.of(dataSource)
+    .schemaMetaDataMode(SchemaMetaDataMode.STATIC)
+    .create();
+----

img/assertj-db_icon_small.png renamed to src/main/docs/modules/ROOT/images/assertj-db_icon_small.png

@@ -0,0 +1,84 @@
+= DateValue, TimeValue and DateTimeValue
+
+The preferred way to compare values with date, time and date/time is to use java.time.LocalDate, java.time.LocalTime, java.time.LocalDateTime directly.
+
+But for the backward compatibility, it's always possible to use AssertJ-DB DateValue utilities.
+
+So The https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/DateValue.html[DateValue],
+https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/TimeValue.html[TimeValue] and
+https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/DateTimeValue.html[DateTimeValue] classes are simpler but contains this kind of information.
+
+There is 4 kinds of static methods to instantiate these values :
+
+* `of` which receives the information as `int` parameters
+
+[source,java]
+----
+DateValue dateValue = DateValue.of(2007, 12, 23);
+
+// With hours and minutes only
+TimeValue timeValue1 = TimeValue.of(9, 1);
+// With seconds additional
+TimeValue timeValue2 = TimeValue.of(9, 1, 6);
+// With nanoseconds additional
+TimeValue timeValue3 = TimeValue.of(9, 1, 6, 3);
+
+// With date only (so hour is midnight)
+DateTimeValue dateTimeValue1 = DateTimeValue.of(dateValue);
+// With date and time
+DateTimeValue dateTimeValue2 = DateTimeValue.of(dateValue, timeValue1);
+----
+
+* `from` which receives the equivalent from `java.sql` package (`java.sql.Date`, `java.sql.Time` and      `java.sql.Timestamp`)
+or a `java.util.Calendar`
+
+[source,java]
+----
+Date date = Date.valueOf("2007-12-23");
+DateValue dateValue = DateValue.from(date);
+
+Time time = Time.valueOf("09:01:06");
+TimeValue timeValue = TimeValue.from(time);
+
+Timestamp timestamp = Timestamp.valueOf("2007-12-23 09:01:06.000000003");
+DateTimeValue dateTimeValue = DateTimeValue.from(timestamp);
+
+Calendar calendar = Calendar.getInstance();
+DateValue dateValueFromCal = DateValue.from(calendar);
+TimeValue timeValueFromCal = TimeValue.from(calendar);
+DateTimeValue dateTimeValueFromCal = DateTimeValue.from(calendar);
+----
+
+* `parse` which receives a `String` to represent the value (this method can throw a `ParseException`)
+
+[source,java]
+----
+DateValue dateValue = DateValue.parse("2007-12-23");
+
+// With hours and minutes only
+TimeValue timeValue1 = TimeValue.parse("09:01");
+// With seconds additional
+TimeValue timeValue2 = TimeValue.parse("09:01:06");
+// With nanoseconds additional
+TimeValue timeValue3 = TimeValue.parse("09:01:06.000000003");
+
+// With date only (so hour is midnight)
+DateTimeValue dateTimeValue1 = DateTimeValue.parse("2007-12-23");
+// With date and time (hours and minutes only)
+DateTimeValue dateTimeValue2 = DateTimeValue.parse("2007-12-23T09:01");
+// With date and time (seconds additional)
+DateTimeValue dateTimeValue2 = DateTimeValue.parse("2007-12-23T09:01:06");
+// With date and time (nanoseconds additional)
+DateTimeValue dateTimeValue2 = DateTimeValue.parse("2007-12-23T09:01:06.000000003");
+----
+
+*   `now` which create an instance corresponding to the current moment.
+
+[source,java]
+----
+DateValue dateValue = DateValue.now();                   // The current date
+TimeValue timeValue = TimeValue.now();                   // The current time
+DateTimeValue dateTimeValue = DateTimeValue.now();       // The current date/time
+----
+
+All these static methods (except for `now` method) have equivalent constructors.

src/main/docs/modules/ROOT/images/db-changes-concept.png

@@ -0,0 +1,21 @@
+= Default description
+
+In assertj, it is possible to add a description with the methods of the https://www.javadoc.io/doc/org.assertj/assertj-core/latest/org/assertj/core/api/Descriptable.html[Descriptable] interface.
+This description is used in the error message if the assertion fails.
+
+Due to the navigation, it is more complicated in assertj-db to know on which element an error is thrown.
+So to help the tester, there are default descriptions.
+
+For example :
+
+*   `"members table"` for an assertion on a table
+*   `"'select * from actor' request"` for an assertion on a request
+*   `"'select id, name, firstname, bi...' request"` for an assertion on a request with more text
+*   `"Row at index 0 of members table"` for an assertion on a row of a table
+*   `"Column at index 0 (column name : ID) of 'select * from members' request"` for an assertion on a column of a request
+*   `"Value at index 0 of Column at index 0 (column name : ID) of 'select * from members' request"` for an assertion on a value of a column of a request
+*   `"Value at index 0 (column name : ID) of Row at index 0 of 'select * from members' request"` for an assertion on a value of a row of a request
+*   `"Value at index 0 (column name : ID) of Row at end point of Change at index 0 (on table : MEMBERS and with primary key : [4]) of Changes on tables of 'sa/jdbc:h2:mem:test' source"`
+for an assertion on a value of the row at end point of a change on a table
+
+This default description can be replaced by the choice of the tester by using the methods of https://www.javadoc.io/doc/org.assertj/assertj-core/latest/org/assertj/core/api/Descriptable.html[Descriptable].