From 1c4c734ad0a241aab0eb4985ff4d3a27be45bdc6 Mon Sep 17 00:00:00 2001 From: Eduardo Marques Date: Mon, 3 Jul 2017 12:02:19 +0100 Subject: [PATCH] Site: anchor link fine-tuning - closes #26 --- src/site/markdown/Compatibility.md | 6 +++--- src/site/markdown/DB.md | 8 ++++---- src/site/markdown/DBAssertions.md | 14 +++++++------- src/site/markdown/DBSetup.md | 14 +++++++------- src/site/markdown/DataSets.md | 20 ++++++++++++++------ src/site/markdown/DataSources.md | 14 +++++++------- src/site/markdown/Facade.md | 4 ++-- src/site/markdown/Logs.md | 8 ++++---- src/site/markdown/Tutorial.md | 16 ++++++++-------- 9 files changed, 56 insertions(+), 48 deletions(-) diff --git a/src/site/markdown/Compatibility.md b/src/site/markdown/Compatibility.md index e165c007..d29a07d4 100644 --- a/src/site/markdown/Compatibility.md +++ b/src/site/markdown/Compatibility.md @@ -1,7 +1,7 @@ # Compatibility -  + ## JDBC drivers JDBDT is expected to work with any (sane) JDBC driver. @@ -14,10 +14,10 @@ The JDBDT build currently tests integration with: * [PostgreSQL](http://postgresql.org) * [SQLite](https://www.sqlite.org) through [xerial's JDBC driver](https://github.com/xerial/sqlite-jdbc) -  + ## Known issues -  + ### PostgreSQL diff --git a/src/site/markdown/DB.md b/src/site/markdown/DB.md index d8173cfd..d5a15d71 100644 --- a/src/site/markdown/DB.md +++ b/src/site/markdown/DB.md @@ -43,7 +43,7 @@ The available options relate to logging and a few other features discussed below DB db = database(...); db.enable(Option.LOG_SETUP); -  + ### Logging @@ -80,7 +80,7 @@ Note that if you use a `.gz` extension for log files, they will be GZIP-compress db.setLog(new File("MyLog.jdbdt.xml.gz")); -  + ### Statement reuse A database handle internally reuses `java.sql.PreparedStatement` objects @@ -104,13 +104,13 @@ the `REUSE_STATEMENTS` option should be disabled as follows: No problems were detected for [all other JDBC drivers tested in the JDBDT build](Compatibility.html#Drivers). -  + ### Batch updates The `BATCH_UPDATES` option indicates that database insertions should use the JDBC batch update mechanism, unless the JDBC driver in does not support this feature (in this case the option will have no effect). The option is enabled by default. -  + ## Summary of API methods ### `JDBDT` diff --git a/src/site/markdown/DBAssertions.md b/src/site/markdown/DBAssertions.md index 560d70ec..da55eddc 100644 --- a/src/site/markdown/DBAssertions.md +++ b/src/site/markdown/DBAssertions.md @@ -12,7 +12,7 @@ to check for the existence of database tables.   ## Delta assertions -  + ### δ assertions ? What do you mean ? δ-assertions state the expected incremental changes made to the database, @@ -30,7 +30,7 @@ The programming pattern in line with this scheme is as follows: theSUT.changesTheDB(); Call delta assertion method(s) -  + ### Snapshots A data source **snapshot** is a data set that is used as reference for subsequent delta @@ -58,7 +58,7 @@ will issue a fresh database query, and record the obtained data set as the snaps DataSource s = ... ; // 's' can be a Table or Query takeSnapshot(s); // --> internally takes and records a snapshot -  + ### Assertion methods The elementary δ-assertion method is `assertDelta`. @@ -135,7 +135,7 @@ A number of other assertion methods are defined for convenience, all of which in letTheSUT_updatePassword(999, "dontDoeIt") assertDelta(before, after); -  + ## State assertions A state assertion checks that the database contents in full, and @@ -174,10 +174,10 @@ it verifies that the given data source has no defined rows. letTheSUT_insertOneUser( ... ); assertState(expected); -  + ## Other assertions -  + ### Data set comparison Two given data sets can be verified as equivalent using the `assertEquals` method. @@ -204,7 +204,7 @@ Note that an assertion of this kind will be insensitive to the order of rows in -  + ## Table existence assertions The `assertTableExists` assertion methods verifies if a given table exists in the database. Symmetrically, `assertTableDoesNotExist` verifies that a table does not diff --git a/src/site/markdown/DBSetup.md b/src/site/markdown/DBSetup.md index dfb0a625..528cc96c 100644 --- a/src/site/markdown/DBSetup.md +++ b/src/site/markdown/DBSetup.md @@ -12,7 +12,7 @@ but also for table row [insertions / updates / deletions](DBSetup.html#IUD); These functionalities are described below, along with a discussion of a few [database setup patterns](DBSetup.html#Patterns) that can be implemented using these operations. -  + ## Populating a table @@ -84,12 +84,12 @@ More generally, you may query the changed status of data sources using the `chan } -  + ## Data set insertions, updates and deletes -Beyond `populate`, data sets may be used for insertions, updates and deletes. +Beyond `populate`, data sets may be used for table insertions, updates and deletes. -The `insert` method inserts a given data set, without clearing any previous contents (unlike `populate` that clears it first). +The `insert` method inserts a given data set onto a table, without deleting any previous contents (unlike `populate` that clears the table first). Table t = ... DataSet additionalData = data(t) ... @@ -114,7 +114,7 @@ The `update` and `delete` method respectively update and delete a data set in th delete(ds); -  + ## Cleaning a table @@ -154,7 +154,7 @@ for different database engines (e.g., + ## Saving and restoring database state @@ -198,7 +198,7 @@ and discards the JDBDT save-point (or any other save-point set for the database restore(db); -  + ## Database setup patterns A number of database test patterns can be implemented using JDBDT, as exemplified in the [JDBDT tutorial](Tutorial.html). The code skeleton below (assuming [JUnit](http://junit.org)-based tests) diff --git a/src/site/markdown/DataSets.md b/src/site/markdown/DataSets.md index 09e0358a..1b5bc957 100644 --- a/src/site/markdown/DataSets.md +++ b/src/site/markdown/DataSets.md @@ -4,7 +4,8 @@ A `DataSet` object represents a collection of rows for a [data source](DataSources.html) that may be used for database [setup](DBSetup.html) or [assertions](DBAssertions.html). -  + + ## Creation @@ -12,7 +13,8 @@ The examples below define data sets for a [table](DataSources.html#Table) (`Tabl but the definition of data sets works similarly for [queries](DataSources.html#Query) (`Query`). -  + + ### Plain definition In the simplest manner, @@ -39,7 +41,8 @@ typically followed by a chained sequence of calls. .row(103, "guest", "Guest User", "welcome", Date.valueOf("2016-01-02")); -  + + ### Typed data sets `TypedDataSet` is a typed extension of `DataSet`. It allows for a simple @@ -75,7 +78,9 @@ of column values. .rows(john, harry, guest) .rows(listOfOtherUsers); -  + + + ### Data set builders A `DataSetBuilder` instance can be used to define or augment a data set @@ -124,13 +129,16 @@ set. .nullValue("CREATED") // set to NULL .generate(500); -  + + + ## Read-only data sets A data set is marked read-only when defined as a [database snapshot](DBAssertions.html#Snapshots). Any attempt to modify it subsequently will cause an `InvalidOperationException`. -  + + ## Summary of API methods ### `JDBDT` diff --git a/src/site/markdown/DataSources.md b/src/site/markdown/DataSources.md index 52d0bf4e..87913502 100644 --- a/src/site/markdown/DataSources.md +++ b/src/site/markdown/DataSources.md @@ -4,10 +4,10 @@ `DataSource` objects represent tables and queries that are used for database [setup](DBSetup.html) or [assertions](DBAssertions.html). -  + ## Tables -  + ### Using table builders Tables are represented by `Table`, a subclass of `DataSource`. A table is created @@ -26,7 +26,7 @@ and the `build` method to build the actual `Table` object in association to a [d .columns("LOGIN", "NAME", "PASSWORD", "CREATED") .build(db); -  + ### Key columns for a table In addition, if you wish to perform updates and deletes using data sets, `key` can be used to define the columns that form the table's primary key (or that in some other form identify each database row uniquely) @@ -38,13 +38,13 @@ the table's primary key (or that in some other form identify each database row u .key("LOGIN") .build(db); -  + ## Queries Queries are represented by `Query`, a subclass of `DataSource`. A `Query` object can be created from a raw SQL statements or using a `QueryBuilder`. -  + ### Definition from raw SQL The `query` facade method may be used to define a query using raw SQL. @@ -60,7 +60,7 @@ The `query` facade method may be used to define a query using raw SQL. int idArgument = ...; Query q = query(db, "SELECT LOGIN, NAME FROM USER WHERE ID = ?", idArgument); -  + ### Definition using `QueryBuilder` `QueryBuilder` objects can be used to define queries programmatically. @@ -117,7 +117,7 @@ to the order of query results, but the use of `orderBy` may make it easier to in .where("u1.LOGIN <> u2.LOGIN AND u1.PASSWORD = u2.PASSWORD") .build(db); -  + ## Summary of API methods ### `JDBDT` diff --git a/src/site/markdown/Facade.md b/src/site/markdown/Facade.md index 7c0bc076..d18dc4ce 100644 --- a/src/site/markdown/Facade.md +++ b/src/site/markdown/Facade.md @@ -6,7 +6,7 @@ The `org.jdbdt.JDBDT` class is the facade for the JDBDT API, providing the core interface methods for database setup, verification, and API object creation. -  + ## Static import @@ -15,7 +15,7 @@ may be convenient to refer to the API methods concisely. import static org.jdbdt.JDBDT.*; -  + ## Overview of functionality [(browse Javadoc instead)](apidocs/index.html?org/jdbdt/JDBDT.html) diff --git a/src/site/markdown/Logs.md b/src/site/markdown/Logs.md index ea9cc564..2c13b201 100644 --- a/src/site/markdown/Logs.md +++ b/src/site/markdown/Logs.md @@ -3,7 +3,7 @@ An XML format is used for [JDBDT log files](DB.html#Logging) and for the output of calls to `JDBDT.dump`. -  + ## Generic format Every JDBDT log message is defined by a `jdbdt-log-message` XML node. @@ -49,7 +49,7 @@ and SQL type (`sql-type`). -  + ## Data sets A `data-set` node displays the contents of a [data set](DataSets.html) that associates @@ -89,7 +89,7 @@ column label (`label` attribute) and Java type (`java-type`). -  + ## State and data set assertions An `assertion` node refers to a [database state assertion](DBAssertions.html#StateAssertions) or a [data set assertion](DBAssertions.html#DataSetAssertions). It comprises: @@ -150,7 +150,7 @@ The `steve` and `bill` "users" were matched. -  + ## Delta assertions A `delta-assertion` node refers to a [database delta assertion](DBAssertions.html#DeltaAssertions). For an assertion diff --git a/src/site/markdown/Tutorial.md b/src/site/markdown/Tutorial.md index 6b86e6ad..29534db1 100644 --- a/src/site/markdown/Tutorial.md +++ b/src/site/markdown/Tutorial.md @@ -2,7 +2,7 @@ This tutorial will help you understand the essential features of JDBDT. -  + ## Tutorial code @@ -12,7 +12,7 @@ Get the tutorial code from [GitHub](http://github.com/edrdo/jdbdt-tutorial): git clone git@github.com:edrdo/jdbdt-tutorial.git -  + ### Maven project overview The code is organized as a [Maven](http://maven.apache.org) project, and comprises the following artifacts: @@ -27,7 +27,7 @@ This class will be our main point of interest. There are three such classes `DerbyTest`, `H2Test`, `HSQLDBTest` (in `src/test/java/org/jdbdt/tutorial`). As their name indicates, they make use of JDBC drivers for [Apache Derby](http://db.apache.org/derby), [H2](http://h2database.com), and [HSQLDB](http://hsqldb.org). - A JUnit test suite, `AllTests`, allowing tests in all classes mentioned above to be executed at once (`src/test/java/org/jdbdt/tutorial/AllTests.java`). -  + ### Running the tests In the command line go to the root folder of the project and type `mvn test` to execute the `AllTests` suite. @@ -35,7 +35,7 @@ In the command line go to the root folder of the project and type `mvn test` to Otherwise, import the project using a Maven-compatible IDE and run the tests from the IDE environment. [Eclipse](http://eclipse.org) users will find that a `.project` file is already in the root folder. -  + ### The test subject The SUT of the tutorial is the `UserDAO` class. Objects of this kind @@ -77,10 +77,10 @@ for user insertion, update, removal and retrieval. * `getAllUsers()`: get a list of all users. * `getUsers(r)`: get a list of all users with a given role. -  + ## Test code / use of JDBDT -  + ### JDBDT import statements The test code of `UserDAOTest` makes use of JDBDT to setup and validate the @@ -94,7 +94,7 @@ contents of the database. You should notice the following JDBDT imports: The static import (the very first one) relates to methods in the [JDBDT facade](Facade.html) that exposes the core JDBDT API. -  + ### Database setup and tear-down @@ -379,7 +379,7 @@ as [described before](Tutorial.html#TheTestCode.DBSetup), and also that `UserDAO` does not issue a database commit (that would make any changes permanent and terminate the transaction started with `save(theDB)`). -  + ### Tests and assertions The tests in `UserDAOTest`, marked with the JUnit `@Test` annotation, validate the different methods