Skip to content

Commit 27c63f1

Browse files
author
Eric Harmeling
committed
Updated version guidance on Java docs
1 parent 17870b9 commit 27c63f1

21 files changed

+65
-54
lines changed

‎_includes/v19.2/app/BasicExample.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ public static void main(String[] args) {
3939
ds.setPassword(null);
4040
ds.setSsl(true);
4141
ds.setSslMode("require");
42+
ds.setSslRootCert("certs/client.root.crt");
4243
ds.setSslCert("certs/client.maxroach.crt");
4344
ds.setSslKey("certs/client.maxroach.key.pk8");
4445
ds.setReWriteBatchedInserts(true); // add `rewriteBatchedInserts=true` to pg connection string

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{{site.data.alerts.callout_danger}}
2+
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`
3+
{{site.data.alerts.end}}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{{site.data.alerts.callout_info}}
2+
We recommend using Java versions 8+ with CockroachDB.
3+
{{site.data.alerts.end}}

‎_includes/v20.1/app/BasicExample.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ public static void main(String[] args) {
3939
ds.setPassword(null);
4040
ds.setSsl(true);
4141
ds.setSslMode("require");
42+
ds.setSslRootCert("certs/client.root.crt");
4243
ds.setSslCert("certs/client.maxroach.crt");
4344
ds.setSslKey("certs/client.maxroach.key.pk8");
4445
ds.setReWriteBatchedInserts(true); // add `rewriteBatchedInserts=true` to pg connection string

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{{site.data.alerts.callout_danger}}
2+
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`
3+
{{site.data.alerts.end}}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{{site.data.alerts.callout_info}}
2+
We recommend using Java versions 8+ with CockroachDB.
3+
{{site.data.alerts.end}}

‎_includes/v20.2/app/BasicExample.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ public static void main(String[] args) {
3939
ds.setPassword(null);
4040
ds.setSsl(true);
4141
ds.setSslMode("require");
42+
ds.setSslRootCert("certs/client.root.crt");
4243
ds.setSslCert("certs/client.maxroach.crt");
4344
ds.setSslKey("certs/client.maxroach.key.pk8");
4445
ds.setReWriteBatchedInserts(true); // add `rewriteBatchedInserts=true` to pg connection string

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{{site.data.alerts.callout_danger}}
2+
CockroachDB versions v20.2 and higher support TLS 1.2 and 1.3, and use 1.3 by default.
3+
4+
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.
5+
6+
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`
7+
{{site.data.alerts.end}}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{{site.data.alerts.callout_info}}
2+
We recommend using Java versions 8+ with CockroachDB.
3+
{{site.data.alerts.end}}

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

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ twitter: false
1313

1414
This tutorial shows you how build a simple Java application with CockroachDB and the Hibernate ORM.
1515

16+
{% include {{page.version.version}}/app/java-version-note.md %}
17+
1618
{{site.data.alerts.callout_success}}
1719
For another use of Hibernate with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
1820
{{site.data.alerts.end}}
@@ -21,10 +23,6 @@ For another use of Hibernate with CockroachDB, see our [`examples-orms`](https:/
2123

2224
{% include {{page.version.version}}/app/before-you-begin.md %}
2325

24-
{{site.data.alerts.callout_danger}}
25-
The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
26-
{{site.data.alerts.end}}
27-
2826
## Step 1. Install the Gradle build tool
2927

3028
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

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ This tutorial shows you how build a simple Java application with CockroachDB and
1515

1616
CockroachDB is supported in jOOQ [Professional and Enterprise editions](https://www.jooq.org/download/#databases).
1717

18+
{% include {{page.version.version}}/app/java-version-note.md %}
19+
1820
{{site.data.alerts.callout_success}}
1921
For another use of jOOQ with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
2022
{{site.data.alerts.end}}
@@ -47,10 +49,6 @@ For other ways to install Maven, see [its official documentation](https://maven.
4749

4850
Download the free trial of jOOQ Professional or Enterprise edition from [jOOQ's website](https://www.jooq.org/download), and unzip the file.
4951

50-
{{site.data.alerts.callout_info}}
51-
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.
52-
{{site.data.alerts.end}}
53-
5452
To install jOOQ to your machine's local Maven repository, run the `maven-install.sh` script included in the jOOQ install folder:
5553

5654
{% include copy-clipboard.html %}

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

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,17 +13,15 @@ twitter: false
1313

1414
This tutorial shows you how to build a simple Java application with CockroachDB and the Java JDBC driver.
1515

16+
{% include {{page.version.version}}/app/java-version-note.md %}
17+
1618
## Before you begin
1719

1820
{% include {{page.version.version}}/app/before-you-begin.md %}
1921

20-
{{site.data.alerts.callout_danger}}
21-
The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
22-
{{site.data.alerts.end}}
23-
2422
## Step 1. Install the Java JDBC driver
2523

26-
Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
24+
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.
2725

2826
<section class="filter-content" markdown="1" data-scope="secure">
2927

@@ -35,7 +33,7 @@ Download and set up the Java JDBC driver as described in the [official documenta
3533

3634
Create a certificate and key for the `maxroach` user by running the following command. The code samples will run as this user.
3735

38-
<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`.
36+
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`.
3937

4038
{% include copy-clipboard.html %}
4139
~~~ shell
@@ -64,7 +62,7 @@ It does all of the above using the practices we recommend for using JDBC with Co
6462

6563
To run it:
6664

67-
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.
65+
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.
6866
2. Compile and run the code (adding the PostgreSQL JDBC driver to your classpath):
6967

7068
{% include copy-clipboard.html %}
@@ -83,7 +81,7 @@ To clone a version of the code below that connects to insecure clusters, run the
8381
`git clone https://github.com/cockroachlabs/hello-world-java-jdbc/`
8482
{{site.data.alerts.end}}
8583

86-
The contents of [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/v19.1/app/BasicExample.java):
84+
The contents of [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/{{page.version.version}}/app/BasicExample.java):
8785

8886
{% include copy-clipboard.html %}
8987
~~~ java
@@ -138,7 +136,7 @@ To run it:
138136
$ java -classpath .:/path/to/postgresql.jar BasicExample
139137
~~~
140138

141-
The contents of [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/v19.1/app/insecure/BasicExample.java):
139+
The contents of [`BasicExample.java`](https://github.com/raw/cockroachdb/docs/master/_includes/{{page.version.version}}/app/insecure/BasicExample.java):
142140

143141
{% include copy-clipboard.html %}
144142
~~~ java

‎v19.2/install-client-drivers.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,13 +129,17 @@ For instructions on using peewee with CockroachDB, see the [CockroachDatabase pe
129129

130130
<section class="filter-content" markdown="1" data-scope="java">
131131

132+
{% include {{page.version.version}}/app/java-version-note.md %}
133+
134+
{% include {{page.version.version}}/app/java-tls-note.md %}
135+
132136
## Drivers
133137

134138
### JDBC
135139

136140
**Support level:** Full
137141

138-
Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
142+
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.
139143

140144
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).
141145

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

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,24 +14,18 @@ twitter: false
1414

1515
This tutorial shows you how build a simple Java application with CockroachDB and the Hibernate ORM.
1616

17+
{% include {{page.version.version}}/app/java-version-note.md %}
18+
1719
{{site.data.alerts.callout_success}}
1820
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).
1921

2022
For another use of Hibernate with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
2123
{{site.data.alerts.end}}
2224

23-
{{site.data.alerts.callout_info}}
24-
For Java applications that use the Spring framework, see the applications listed under [Java/Spring](build-a-spring-app-with-cockroachdb-mybatis.html).
25-
{{site.data.alerts.end}}
26-
2725
## Before you begin
2826

2927
{% include {{page.version.version}}/app/before-you-begin.md %}
3028

31-
{{site.data.alerts.callout_danger}}
32-
The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
33-
{{site.data.alerts.end}}
34-
3529
## Step 1. Install the Gradle build tool
3630

3731
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

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,12 @@ This tutorial shows you how build a simple Java application with CockroachDB and
1616

1717
CockroachDB is supported in jOOQ [Professional and Enterprise editions](https://www.jooq.org/download/#databases).
1818

19+
{% include {{page.version.version}}/app/java-version-note.md %}
20+
1921
{{site.data.alerts.callout_success}}
2022
For another use of jOOQ with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
2123
{{site.data.alerts.end}}
2224

23-
{{site.data.alerts.callout_info}}
24-
For Java applications that use the Spring framework, see the applications listed under [Java/Spring](build-a-spring-app-with-cockroachdb-mybatis.html).
25-
{{site.data.alerts.end}}
26-
2725
## Before you begin
2826

2927
{% 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.
5250

5351
Download the free trial of jOOQ Professional or Enterprise edition from [jOOQ's website](https://www.jooq.org/download), and unzip the file.
5452

55-
{{site.data.alerts.callout_info}}
56-
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.
57-
{{site.data.alerts.end}}
58-
5953
To install jOOQ to your machine's local Maven repository, run the `maven-install.sh` script included in the jOOQ install folder:
6054

6155
{% include copy-clipboard.html %}

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

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ twitter: false
1414

1515
This tutorial shows you how to build a simple Java application with CockroachDB and the Java JDBC driver.
1616

17+
{% include {{page.version.version}}/app/java-version-note.md %}
18+
1719
{{site.data.alerts.callout_success}}
1820
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).
1921
{{site.data.alerts.end}}
@@ -22,13 +24,9 @@ For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [B
2224

2325
{% include {{page.version.version}}/app/before-you-begin.md %}
2426

25-
{{site.data.alerts.callout_danger}}
26-
The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
27-
{{site.data.alerts.end}}
28-
2927
## Step 1. Install the Java JDBC driver
3028

31-
Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
29+
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.
3230

3331
<section class="filter-content" markdown="1" data-scope="secure">
3432

‎v20.1/install-client-drivers.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,11 +130,15 @@ For instructions on using peewee with CockroachDB, see the [CockroachDatabase pe
130130

131131
## Drivers
132132

133+
{% include {{page.version.version}}/app/java-version-note.md %}
134+
135+
{% include {{page.version.version}}/app/java-tls-note.md %}
136+
133137
### JDBC
134138

135139
**Support level:** Full
136140

137-
Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
141+
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.
138142

139143
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).
140144

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

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ twitter: false
1414

1515
This tutorial shows you how build a simple Java application with CockroachDB and the Hibernate ORM.
1616

17+
{% include {{page.version.version}}/app/java-version-note.md %}
18+
1719
{{site.data.alerts.callout_success}}
1820
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).
1921

@@ -24,10 +26,6 @@ For another use of Hibernate with CockroachDB, see our [`examples-orms`](https:/
2426

2527
{% include {{page.version.version}}/app/before-you-begin.md %}
2628

27-
{{site.data.alerts.callout_danger}}
28-
The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
29-
{{site.data.alerts.end}}
30-
3129
## Step 1. Install the Gradle build tool
3230

3331
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

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ This tutorial shows you how build a simple Java application with CockroachDB and
1616

1717
CockroachDB is supported in jOOQ [Professional and Enterprise editions](https://www.jooq.org/download/#databases).
1818

19+
{% include {{page.version.version}}/app/java-version-note.md %}
20+
1921
{{site.data.alerts.callout_success}}
2022
For another use of jOOQ with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository.
2123
{{site.data.alerts.end}}
@@ -48,10 +50,6 @@ For other ways to install Maven, see [its official documentation](https://maven.
4850

4951
Download the free trial of jOOQ Professional or Enterprise edition from [jOOQ's website](https://www.jooq.org/download), and unzip the file.
5052

51-
{{site.data.alerts.callout_info}}
52-
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.
53-
{{site.data.alerts.end}}
54-
5553
To install jOOQ to your machine's local Maven repository, run the `maven-install.sh` script included in the jOOQ install folder:
5654

5755
{% include copy-clipboard.html %}

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

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ twitter: false
1414

1515
This tutorial shows you how to build a simple Java application with CockroachDB and the Java JDBC driver.
1616

17+
{% include {{page.version.version}}/app/java-version-note.md %}
18+
1719
{{site.data.alerts.callout_success}}
1820
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).
1921
{{site.data.alerts.end}}
@@ -22,13 +24,9 @@ For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [B
2224

2325
{% include {{page.version.version}}/app/before-you-begin.md %}
2426

25-
{{site.data.alerts.callout_danger}}
26-
The examples on this page assume you are using a Java version <= 9. They do not work with Java 10.
27-
{{site.data.alerts.end}}
28-
2927
## Step 1. Install the Java JDBC driver
3028

31-
Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
29+
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.
3230

3331
<section class="filter-content" markdown="1" data-scope="secure">
3432

‎v20.2/install-client-drivers.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,13 +128,17 @@ For instructions on using peewee with CockroachDB, see the [CockroachDatabase pe
128128

129129
<section class="filter-content" markdown="1" data-scope="java">
130130

131+
{% include {{page.version.version}}/app/java-version-note.md %}
132+
133+
{% include {{page.version.version}}/app/java-tls-note.md %}
134+
131135
## Drivers
132136

133137
### JDBC
134138

135139
**Support level:** Full
136140

137-
Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html).
141+
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.
138142

139143
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).
140144

0 commit comments

Comments
 (0)