Updated version guidance on Java docs

_includes/v19.2/app/BasicExample.java

@@ -39,6 +39,7 @@ public static void main(String[] args) {
         ds.setPassword(null);
         ds.setSsl(true);
         ds.setSslMode("require");
+        ds.setSslRootCert("certs/client.root.crt");
         ds.setSslCert("certs/client.maxroach.crt");
         ds.setSslKey("certs/client.maxroach.key.pk8");
         ds.setReWriteBatchedInserts(true); // add `rewriteBatchedInserts=true` to pg connection string

_includes/v19.2/app/java-tls-note.md

@@ -0,0 +1,3 @@
+{{site.data.alerts.callout_danger}}
+CockroachDB versions v20.1 and lower require TLS 1.2. By default, Java 8 uses TLS 1.2, but applications running on Java 9+ must be configured to run TLS 1.2. For example, when starting your app, use: `$ java -Djdk.tls.client.protocols=TLSv1.2 appName`
+{{site.data.alerts.end}}

_includes/v19.2/app/java-version-note.md

@@ -0,0 +1,3 @@
+{{site.data.alerts.callout_info}}
+We recommend using Java versions 8+ with CockroachDB.
+{{site.data.alerts.end}}

_includes/v20.1/app/BasicExample.java

@@ -39,6 +39,7 @@ public static void main(String[] args) {
         ds.setPassword(null);
         ds.setSsl(true);
         ds.setSslMode("require");
+        ds.setSslRootCert("certs/client.root.crt");
         ds.setSslCert("certs/client.maxroach.crt");
         ds.setSslKey("certs/client.maxroach.key.pk8");
         ds.setReWriteBatchedInserts(true); // add `rewriteBatchedInserts=true` to pg connection string

_includes/v20.1/app/java-tls-note.md

@@ -0,0 +1,3 @@
+{{site.data.alerts.callout_danger}}
+CockroachDB versions v20.1 and lower require TLS 1.2. By default, Java 8 uses TLS 1.2, but applications running on Java 9+ must be configured to run TLS 1.2. For example, when starting your app, use: `$ java -Djdk.tls.client.protocols=TLSv1.2 appName`
+{{site.data.alerts.end}}

_includes/v20.1/app/java-version-note.md

@@ -0,0 +1,3 @@
+{{site.data.alerts.callout_info}}
+We recommend using Java versions 8+ with CockroachDB.
+{{site.data.alerts.end}}

_includes/v20.2/app/BasicExample.java

@@ -39,6 +39,7 @@ public static void main(String[] args) {
         ds.setPassword(null);
         ds.setSsl(true);
         ds.setSslMode("require");
+        ds.setSslRootCert("certs/client.root.crt");
         ds.setSslCert("certs/client.maxroach.crt");
         ds.setSslKey("certs/client.maxroach.key.pk8");
         ds.setReWriteBatchedInserts(true); // add `rewriteBatchedInserts=true` to pg connection string

_includes/v20.2/app/java-tls-note.md

@@ -0,0 +1,7 @@
+{{site.data.alerts.callout_danger}}
+CockroachDB versions v20.2 and higher support TLS 1.2 and 1.3, and use 1.3 by default.
+
+A bug in the TLS 1.3 implementation in Java 11 versions lower than 11.0.7 and Java 13 versions lower than 13.0.3 makes the versions incompatible with CockroachDB. For applications running Java 11 or 13, make sure that you have version 11.0.7 or higher, or 13.0.3 or higher.
+
+If you cannot upgrade to a version higher than 11.0.7 or 13.0.3, you must configure the application to use TLS 1.2. For example, when starting your app, use: `$ java -Djdk.tls.client.protocols=TLSv1.2 appName`
+{{site.data.alerts.end}}

_includes/v20.2/app/java-version-note.md

@@ -0,0 +1,3 @@
+{{site.data.alerts.callout_info}}
+We recommend using Java versions 8+ with CockroachDB.
+{{site.data.alerts.end}}

v19.2/build-a-java-app-with-cockroachdb-hibernate.md

@@ -13,6 +13,8 @@ twitter: false
 
 This tutorial shows you how build a simple Java application with CockroachDB and the Hibernate ORM.
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
 {{site.data.alerts.callout_success}}
 For another use of Hibernate with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
 {{site.data.alerts.end}}
@@ -21,10 +23,6 @@ For another use of Hibernate with CockroachDB, see our [`examples-orms`](https:/
 
 {% include {{page.version.version}}/app/before-you-begin.md %}
 
-{{site.data.alerts.callout_danger}}
-The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
-{{site.data.alerts.end}}
-
 ## Step 1. Install the Gradle build tool
 
 This tutorial uses the [Gradle build tool](https://gradle.org/) to get all dependencies for your application, including Hibernate.

v19.2/build-a-java-app-with-cockroachdb-jooq.md

@@ -15,6 +15,8 @@ This tutorial shows you how build a simple Java application with CockroachDB and
 
 CockroachDB is supported in jOOQ [Professional and Enterprise editions](https://www.jooq.org/download/#databases).
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
 {{site.data.alerts.callout_success}}
 For another use of jOOQ with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
 {{site.data.alerts.end}}
@@ -47,10 +49,6 @@ For other ways to install Maven, see [its official documentation](https://maven.
 
 Download the free trial of jOOQ Professional or Enterprise edition from [jOOQ's website](https://www.jooq.org/download), and unzip the file.
 
-{{site.data.alerts.callout_info}}
-If you have Java 6, Java 8, or Java 11, go to [Download your jOOQ version](https://www.jooq.org/download/versions#trial), and download the free trial of jOOQ for your version of Java.
-{{site.data.alerts.end}}
-
 To install jOOQ to your machine's local Maven repository, run the `maven-install.sh` script included in the jOOQ install folder:
 
 {% include copy-clipboard.html %}

v19.2/build-a-java-app-with-cockroachdb.md

@@ -13,17 +13,15 @@ twitter: false
 
 This tutorial shows you how to build a simple Java application with CockroachDB and the Java JDBC driver.
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
 ## Before you begin
 
 {% include {{page.version.version}}/app/before-you-begin.md %}
 
-{{site.data.alerts.callout_danger}}
-The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
-{{site.data.alerts.end}}
-
 ## Step 1. Install the Java JDBC driver
 
-Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
+Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver.
 
 <section class="filter-content" markdown="1" data-scope="secure">
 
@@ -35,7 +33,7 @@ Download and set up the Java JDBC driver as described in the [official documenta
 
 Create a certificate and key for the `maxroach` user by running the following command. The code samples will run as this user.
 
-<span class="version-tag">New in v19.1</span>: You can pass the [`--also-generate-pkcs8-key` flag](cockroach-cert.html#flag-pkcs8) to generate a key in [PKCS#8 format](https://tools.ietf.org/html/rfc5208), which is the standard key encoding format in Java. In this case, the generated PKCS8 key will be named `client.maxroach.key.pk8`.
+You can pass the [`--also-generate-pkcs8-key` flag](cockroach-cert.html#flag-pkcs8) to generate a key in [PKCS#8 format](https://tools.ietf.org/html/rfc5208), which is the standard key encoding format in Java. In this case, the generated PKCS8 key will be named `client.maxroach.key.pk8`.
 
 {% include copy-clipboard.html %}
 ~~~ shell
@@ -64,7 +62,7 @@ It does all of the above using the practices we recommend for using JDBC with Co
 
 To run it:
 
-1. Download [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/v19.1/app/BasicExample.java), or create the file yourself and copy the code below.
+1. Download [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/{{page.version.version}}/app/BasicExample.java), or create the file yourself and copy the code below.
 2. Compile and run the code (adding the PostgreSQL JDBC driver to your classpath):
 
     {% include copy-clipboard.html %}
@@ -83,7 +81,7 @@ To clone a version of the code below that connects to insecure clusters, run the
 `git clone https://github.com/cockroachlabs/hello-world-java-jdbc/`
 {{site.data.alerts.end}}
 
-The contents of [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/v19.1/app/BasicExample.java):
+The contents of [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/{{page.version.version}}/app/BasicExample.java):
 
 {% include copy-clipboard.html %}
 ~~~ java
@@ -138,7 +136,7 @@ To run it:
     $ java -classpath .:/path/to/postgresql.jar BasicExample
     ~~~
 
-The contents of [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/v19.1/app/insecure/BasicExample.java):
+The contents of [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/{{page.version.version}}/app/insecure/BasicExample.java):
 
 {% include copy-clipboard.html %}
 ~~~ java

v19.2/install-client-drivers.md

@@ -129,13 +129,17 @@ For instructions on using peewee with CockroachDB, see the [CockroachDatabase pe
 
 <section class="filter-content" markdown="1" data-scope="java">
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
+{% include {{page.version.version}}/app/java-tls-note.md %}
+
 ## Drivers
 
 ### JDBC
 
 **Support level:** Full
 
-Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
+Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver.
 
 For a simple but complete "Hello World" example app, see [Build a Java App with CockroachDB and JDBC](build-a-java-app-with-cockroachdb.html).
 

v20.1/build-a-java-app-with-cockroachdb-hibernate.md

@@ -14,24 +14,18 @@ twitter: false
 
 This tutorial shows you how build a simple Java application with CockroachDB and the Hibernate ORM.
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
 {{site.data.alerts.callout_success}}
 For a sample app and tutorial that uses Spring Data JPA (Hibernate) and CockroachDB, see [Build a Spring App with CockroachDB and JPA](build-a-spring-app-with-cockroachdb-jpa.html).
 
 For another use of Hibernate with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
 {{site.data.alerts.end}}
 
-{{site.data.alerts.callout_info}}
-For Java applications that use the Spring framework, see the applications listed under [Java/Spring](build-a-spring-app-with-cockroachdb-mybatis.html).
-{{site.data.alerts.end}}
-
 ## Before you begin
 
 {% include {{page.version.version}}/app/before-you-begin.md %}
 
-{{site.data.alerts.callout_danger}}
-The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
-{{site.data.alerts.end}}
-
 ## Step 1. Install the Gradle build tool
 
 This tutorial uses the [Gradle build tool](https://gradle.org/) to get all dependencies for your application, including Hibernate.

v20.1/build-a-java-app-with-cockroachdb-jooq.md

@@ -16,14 +16,12 @@ This tutorial shows you how build a simple Java application with CockroachDB and
 
 CockroachDB is supported in jOOQ [Professional and Enterprise editions](https://www.jooq.org/download/#databases).
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
 {{site.data.alerts.callout_success}}
 For another use of jOOQ with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
 {{site.data.alerts.end}}
 
-{{site.data.alerts.callout_info}}
-For Java applications that use the Spring framework, see the applications listed under [Java/Spring](build-a-spring-app-with-cockroachdb-mybatis.html).
-{{site.data.alerts.end}}
-
 ## Before you begin
 
 {% include {{page.version.version}}/app/before-you-begin.md %}
@@ -52,10 +50,6 @@ For other ways to install Maven, see [its official documentation](https://maven.
 
 Download the free trial of jOOQ Professional or Enterprise edition from [jOOQ's website](https://www.jooq.org/download), and unzip the file.
 
-{{site.data.alerts.callout_info}}
-If you have Java 6, Java 8, or Java 11, go to [Download your jOOQ version](https://www.jooq.org/download/versions#trial), and download the free trial of jOOQ for your version of Java.
-{{site.data.alerts.end}}
-
 To install jOOQ to your machine's local Maven repository, run the `maven-install.sh` script included in the jOOQ install folder:
 
 {% include copy-clipboard.html %}

v20.1/build-a-java-app-with-cockroachdb.md

@@ -14,6 +14,8 @@ twitter: false
 
 This tutorial shows you how to build a simple Java application with CockroachDB and the Java JDBC driver.
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
 {{site.data.alerts.callout_success}}
 For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [Build a Spring App with CockroachDB and JDBC](build-a-spring-app-with-cockroachdb-jdbc.html).
 {{site.data.alerts.end}}
@@ -22,13 +24,9 @@ For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [B
 
 {% include {{page.version.version}}/app/before-you-begin.md %}
 
-{{site.data.alerts.callout_danger}}
-The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
-{{site.data.alerts.end}}
-
 ## Step 1. Install the Java JDBC driver
 
-Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
+Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver.
 
 <section class="filter-content" markdown="1" data-scope="secure">
 

v20.1/install-client-drivers.md

@@ -130,11 +130,15 @@ For instructions on using peewee with CockroachDB, see the [CockroachDatabase pe
 
 ## Drivers
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
+{% include {{page.version.version}}/app/java-tls-note.md %}
+
 ### JDBC
 
 **Support level:** Full
 
-Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
+Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver.
 
 For a simple but complete "Hello World" example app, see [Build a Java App with CockroachDB and JDBC](build-a-java-app-with-cockroachdb.html).
 

v20.2/build-a-java-app-with-cockroachdb-hibernate.md

@@ -14,6 +14,8 @@ twitter: false
 
 This tutorial shows you how build a simple Java application with CockroachDB and the Hibernate ORM.
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
 {{site.data.alerts.callout_success}}
 For a sample app and tutorial that uses Spring Data JPA (Hibernate) and CockroachDB, see [Build a Spring App with CockroachDB and JPA](build-a-spring-app-with-cockroachdb-jpa.html).
 
@@ -24,10 +26,6 @@ For another use of Hibernate with CockroachDB, see our [`examples-orms`](https:/
 
 {% include {{page.version.version}}/app/before-you-begin.md %}
 
-{{site.data.alerts.callout_danger}}
-The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
-{{site.data.alerts.end}}
-
 ## Step 1. Install the Gradle build tool
 
 This tutorial uses the [Gradle build tool](https://gradle.org/) to get all dependencies for your application, including Hibernate.

v20.2/build-a-java-app-with-cockroachdb-jooq.md

@@ -16,6 +16,8 @@ This tutorial shows you how build a simple Java application with CockroachDB and
 
 CockroachDB is supported in jOOQ [Professional and Enterprise editions](https://www.jooq.org/download/#databases).
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
 {{site.data.alerts.callout_success}}
 For another use of jOOQ with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
 {{site.data.alerts.end}}
@@ -48,10 +50,6 @@ For other ways to install Maven, see [its official documentation](https://maven.
 
 Download the free trial of jOOQ Professional or Enterprise edition from [jOOQ's website](https://www.jooq.org/download), and unzip the file.
 
-{{site.data.alerts.callout_info}}
-If you have Java 6, Java 8, or Java 11, go to [Download your jOOQ version](https://www.jooq.org/download/versions#trial), and download the free trial of jOOQ for your version of Java.
-{{site.data.alerts.end}}
-
 To install jOOQ to your machine's local Maven repository, run the `maven-install.sh` script included in the jOOQ install folder:
 
 {% include copy-clipboard.html %}

v20.2/build-a-java-app-with-cockroachdb.md

@@ -14,6 +14,8 @@ twitter: false
 
 This tutorial shows you how to build a simple Java application with CockroachDB and the Java JDBC driver.
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
 {{site.data.alerts.callout_success}}
 For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [Build a Spring App with CockroachDB and JDBC](build-a-spring-app-with-cockroachdb-jdbc.html).
 {{site.data.alerts.end}}
@@ -22,13 +24,9 @@ For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [B
 
 {% include {{page.version.version}}/app/before-you-begin.md %}
 
-{{site.data.alerts.callout_danger}}
-The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
-{{site.data.alerts.end}}
-
 ## Step 1. Install the Java JDBC driver
 
-Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
+Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver.
 
 <section class="filter-content" markdown="1" data-scope="secure">
 

v20.2/install-client-drivers.md

@@ -128,13 +128,17 @@ For instructions on using peewee with CockroachDB, see the [CockroachDatabase pe
 
 <section class="filter-content" markdown="1" data-scope="java">
 
+{% include {{page.version.version}}/app/java-version-note.md %}
+
+{% include {{page.version.version}}/app/java-tls-note.md %}
+
 ## Drivers
 
 ### JDBC
 
 **Support level:** Full
 
-Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
+Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver.
 
 For a simple but complete "Hello World" example app, see [Build a Java App with CockroachDB and JDBC](build-a-java-app-with-cockroachdb.html).