JPA read side documentation

[TimMoore]

Fixes

Fixes #407

References

• JPA Support #168
• JpaSession interface and implementation #342
• Add support for JPA-based read sides #372

[TimMoore]

This line (adding persistenceJpaJavadsl) is the change, but I broke it down into one dependency per line to make it easier to read diffs in the future.

[TimMoore]

This page is mostly a copy of the previous ReadSideRDBMS.md with a few minor changes.

[TimMoore]

Here are all of the specific differences:

diff --git c/docs/manual/java/guide/cluster/ReadSideRDBMS.md w/docs/manual/java/guide/cluster/ReadSideJDBC.md
similarity index 66%
copy from docs/manual/java/guide/cluster/ReadSideRDBMS.md
copy to docs/manual/java/guide/cluster/ReadSideJDBC.md
index fac12888..f8306a0c 100644
--- c/docs/manual/java/guide/cluster/ReadSideRDBMS.md
+++ w/docs/manual/java/guide/cluster/ReadSideJDBC.md
@@ -1,30 +1,30 @@
-# Relational Database Read-Side support
+# JDBC Read-Side support
 
-This page is specifically about Lagom's support for relational database read-sides.  Before reading this, you should familiarize yourself with Lagom's general [[read-side support|ReadSide]].
+This page is specifically about Lagom's support for relational database read-sides using JDBC.  Before reading this, you should familiarize yourself with Lagom's general [[read-side support|ReadSide]] and [[relational database read-side support overview|ReadSideRDBMS]].
 
 ## Query the Read-Side Database
 
-Let us first look at how a service implementation can retrieve data from a relational database.
+Let us first look at how a service implementation can retrieve data from a relational database using JDBC.
 
-@[imports](code/docs/home/persistence/RDBMSReadSideQuery.java)
-@[service-impl](code/docs/home/persistence/RDBMSReadSideQuery.java)
+@[imports](code/docs/home/persistence/JdbcReadSideQuery.java)
+@[service-impl](code/docs/home/persistence/JdbcReadSideQuery.java)
 
-Note that the [`JdbcSession`](api/index.html?com/lightbend/lagom/javadsl/persistence/jdbc/JdbcSession.html) is injected in the constructor. `JdbcSession` allows access to a connection from the connection pool, using the `withConnection` method, and will manage transactions using the `withTransaction` method.  Importantly, `JdbcSession` also manages execution of the blocking JDBC calls in a threadpool designed to handle it, which is why the `withConnection` and `withTransaction` methods return `CompletionStage`.
+Note that the [`JdbcSession`](api/index.html?com/lightbend/lagom/javadsl/persistence/jdbc/JdbcSession.html) is injected in the constructor. `JdbcSession` allows access to a connection from the connection pool, using the `withConnection` method, and will manage transactions using the `withTransaction` method.  Importantly, `JdbcSession` also manages execution of the blocking JDBC calls in a thread pool designed to handle it, which is why the `withConnection` and `withTransaction` methods return `CompletionStage`.
 
 ## Update the Read-Side
 
-We need to transform the events generated by the [[Persistent Entities|PersistentEntity]] into database tables that can be queried as illustrated in the previous section. For that we will implement a [`ReadSideProcessor`](api/index.html?com/lightbend/lagom/javadsl/persistence/ReadSideProcessor.html) with assistance from the [`JdbcReadSide`](api/index.html?com/lightbend/lagom/javadsl/persistence/jdbc/JdbcReadSide.html) support component. It will consume events produced by persistent entities and update one or more JDBC tables that are optimized for queries.
+We need to transform the events generated by the [[Persistent Entities|PersistentEntity]] into database tables that can be queried as illustrated in the previous section. For that we will implement a [`ReadSideProcessor`](api/index.html?com/lightbend/lagom/javadsl/persistence/ReadSideProcessor.html) with assistance from the [`JdbcReadSide`](api/index.html?com/lightbend/lagom/javadsl/persistence/jdbc/JdbcReadSide.html) support component. It will consume events produced by persistent entities and update one or more database tables that are optimized for queries.
 
 This is how a `ReadSideProcessor` class looks like before filling in the implementation details:
 
-@[imports](code/docs/home/persistence/RDBMSBlogEventProcessor.java)
-@[initial](code/docs/home/persistence/RDBMSBlogEventProcessor.java)
+@[imports](code/docs/home/persistence/JdbcBlogEventProcessor.java)
+@[initial](code/docs/home/persistence/JdbcBlogEventProcessor.java)
 
 You can see that we have injected the JDBC read-side support, this will be needed later.
 
 You should already have implemented tagging for your events as described in the [[Read-Side documentation|ReadSide]], so first we'll implement the `aggregateTags` method in our read-side processor stub, like so:
 
-@[tag](code/docs/home/persistence/RDBMSBlogEventProcessor.java)
+@[tag](code/docs/home/persistence/JdbcBlogEventProcessor.java)
 
 ### Building the read-side handler
 
@@ -32,7 +32,7 @@ The other method on the `ReadSideProcessor` is `buildHandler`.  This is responsi
 
 [`JdbcReadSide`](api/index.html?com/lightbend/lagom/javadsl/persistence/jdbc/JdbcReadSide.html) has a `builder` method for creating a builder for these handlers, this builder will create a handler that will automatically manage transactions and handle read-side offsets for you.  It can be created like so:
 
-@[create-builder](code/docs/home/persistence/RDBMSBlogEventProcessor.java)
+@[create-builder](code/docs/home/persistence/JdbcBlogEventProcessor.java)
 
 The argument passed to this method is an identifier for the read-side processor that Lagom should use when it persists the offset. Lagom will store the offsets in a table that it will automatically create itself if it doesn't exist. If you would prefer that Lagom didn't automatically create this table for you, you can turn off this feature by setting `lagom.persistence.jdbc.create-tables.auto=false` in `application.conf`. The DDL for the schema for this table is as follows:
    
@@ -54,24 +54,32 @@ Of course, setting a global prepare callback is completely optional, you may pre
 
 Below is an example method that we've implemented to create tables:
 
-@[create-table](code/docs/home/persistence/RDBMSBlogEventProcessor.java)
+@[create-table](code/docs/home/persistence/JdbcBlogEventProcessor.java)
 
 It can then be registered as the global prepare callback in the `buildHandler` method:
 
-@[register-global-prepare](code/docs/home/persistence/RDBMSBlogEventProcessor.java)
+@[register-global-prepare](code/docs/home/persistence/JdbcBlogEventProcessor.java)
+
+### Prepare
+
+In addition to the global prepare callback, there is also a prepare callback that can be specified by calling [`builder.setPrepare`](api/index.html?com/lightbend/lagom/javadsl/persistence/jdbc/JdbcReadSide.ReadSideHandlerBuilder.html#setPrepare-com.lightbend.lagom.javadsl.persistence.jdbc.JdbcReadSide.ConnectionBiConsumer-). This will be executed once per shard, when the read side processor starts up.
+
+If you read the [[Cassandra read-side support|ReadSideCassandra]] guide, you may have seen this used to prepare database statements for later use. JDBC `PreparedStatement` instances, however, are not guaranteed to be thread-safe, so the prepare callback should not be used for this purpose with relational databases.
+
+Again this callback is optional, and in our example we have no need for a prepare callback, so none is specified.
 
 ### Event handlers
 
-The event handlers take an event and a connection, and updates the read-side accordingly.
+The event handlers take an event and a connection, and update the read-side accordingly.
 
 Here's an example callback for handling the `PostAdded` event:
 
-@[post-added](code/docs/home/persistence/RDBMSBlogEventProcessor.java)
+@[post-added](code/docs/home/persistence/JdbcBlogEventProcessor.java)
 
 This can then be registered with the builder using `setEventHandler`:
 
-@[set-event-handler](code/docs/home/persistence/RDBMSBlogEventProcessor.java)
+@[set-event-handler](code/docs/home/persistence/JdbcBlogEventProcessor.java)
 
 Once you have finished registering all your event handlers, you can invoke the `build` method and return the built handler:
 
-@[build](code/docs/home/persistence/RDBMSBlogEventProcessor.java)
+@[build](code/docs/home/persistence/JdbcBlogEventProcessor.java)

[TimMoore]

In order to avoid breaking navigation from older versions, I kept this page as an overview of the two different RDBMS options.

I haven't yet made an equivalent change on the Scala side, because we only support JDBC there still, but should we preemptively rename the page to ReadSideJDBC.md?

[TimMoore]

After fighting a bit with GitHub Pages, I pushed this branch up to https://timmoore.github.io/lagom.github.io/

You might find it easier to review the new documentation there e.g., https://timmoore.github.io/lagom.github.io/documentation/1.3.x/java/ReadSideJPA.html

[rstento]

It looks good to me, Tim. In the future, I'd like to see pages this long and with this much content broken up into separate ones, or at least use a bulleted "mini-toc" list of links to anchors at the top. For example, you might have used a page for the configuration information and then a separate one for the usage example.

[rstento]

See my comment below for something to think about next time.