Driver: Improve section about Java

docs/_include/links.md

@@ -35,6 +35,7 @@
 [Executable stack with Apache Kafka, Apache Flink, and CrateDB]: https://github.com/crate/cratedb-examples/tree/main/framework/flink/kafka-jdbcsink-java
 [Geospatial Data Model]: https://cratedb.com/data-model/geospatial
 [Geospatial Database]: https://cratedb.com/geospatial-spatial-database
+[Hibernate]: https://hibernate.org/
 [HNSW]: https://en.wikipedia.org/wiki/Hierarchical_navigable_small_world
 [HNSW paper]: https://arxiv.org/pdf/1603.09320
 [HoloViews]: https://www.holoviews.org/
@@ -45,6 +46,8 @@
 [inverted index]: https://en.wikipedia.org/wiki/Inverted_index
 [JDBC]: https://en.wikipedia.org/wiki/Java_Database_Connectivity
 [JOIN]: inv:crate-reference#sql_joins
+[jOOQ]: https://www.jooq.org/
+[JPA]: https://en.wikipedia.org/wiki/Jakarta_Persistence
 [JSON Database]: https://cratedb.com/solutions/json-database
 [kNN]: https://en.wikipedia.org/wiki/K-nearest_neighbor_algorithm
 [LangChain and CrateDB: Code Examples]: https://github.com/crate/cratedb-examples/tree/main/topic/machine-learning/langchain

docs/_include/logos.md

@@ -0,0 +1,13 @@
+<!-- markdownlint-disable MD034 -->
+<!-- markdownlint-disable MD053 -->
+
+[CrateDB home]: https://cratedb.com/
+[CrateDB logo]: https://avatars.githubusercontent.com/u/4048232?s=200&v=4
+[Hibernate logo]: https://logo.svgcdn.com/devicon/hibernate-original.svg
+[jOOQ logo]: https://www.jooq.org/img/jooq-logo-black.png
+[JUnit home]: https://junit.org/
+[JUnit logo]: https://avatars.githubusercontent.com/u/874086?s=200&v=4
+[PostgreSQL home]: https://www.postgresql.org/
+[PostgreSQL logo]: https://jdbc.postgresql.org/icons/postgreslogo.svg
+[Testcontainers for Java]: https://testcontainers.com/guides/getting-started-with-testcontainers-for-java/
+[Testcontainers logo]: https://avatars.githubusercontent.com/u/13393021?s=200&v=4

docs/connect/index.md

@@ -176,7 +176,7 @@ application
 :maxdepth: 1
 :hidden:
 
-java
+java/index
 javascript
 php
 python

docs/connect/java/_jdbc_example.md

@@ -0,0 +1,13 @@
+---
+orphan: true
+---
+:::{card}
+:link: https://github.com/crate/cratedb-examples/tree/main/by-language/java-jdbc
+:link-type: url
+:width: 50%
+{material-regular}`play_arrow;2em`
+Connect to CrateDB using JDBC.
++++
+Demonstrates a basic example using both the vanilla PostgreSQL JDBC Driver
+and the CrateDB JDBC Driver.
+:::

docs/connect/java/cratedb-jdbc.md

@@ -0,0 +1,152 @@
+:::{include} /_include/logos.md
+:::
+
+(crate-jdbc)=
+(cratedb-jdbc)=
+
+# CrateDB JDBC
+
+```{div} .float-right
+[![CrateDB logo][CrateDB logo]{height=40px loading=lazy}][CrateDB home]
+```
+```{div} .clearfix
+```
+
+:::{include} /_include/links.md
+:::
+
+:::{div} sd-text-muted
+Connect to CrateDB using CrateDB JDBC.
+:::
+
+:::{rubric} About
+:::
+
+:::{div}
+The [CrateDB JDBC Driver] is an open-source JDBC driver written in
+Pure Java (Type 4), which communicates using the PostgreSQL native
+network protocol. CrateDB JDBC needs Java >= 11.
+:::
+
+:::{rubric} Synopsis
+:::
+
+`example.java`
+```java
+import java.sql.*;
+
+void main() throws SQLException {
+
+    // Connect to database.
+    Properties properties = new Properties();
+    properties.put("user", "crate");
+    properties.put("password", "crate");
+    Connection conn = DriverManager.getConnection(
+        "jdbc:crate://localhost:5432/doc?sslmode=disable",
+        properties
+    );
+    conn.setAutoCommit(true);
+
+    // Invoke query.
+    Statement st = conn.createStatement();
+    st.execute("SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 5;");
+
+    // Display results.
+    ResultSet rs = st.getResultSet();
+    while (rs.next()) {
+        System.out.printf(Locale.ENGLISH, "%s: %d\n", rs.getString(1), rs.getInt(2));
+    }
+    conn.close();
+
+}
+```
+
+:::{rubric} CrateDB Cloud
+:::
+
+For connecting to CrateDB Cloud, use the `sslmode=require` parameter,
+and replace username, password, and hostname with values matching
+your environment.
+```java
+properties.put("user", "admin");
+properties.put("password", "password");
+Connection conn = DriverManager.getConnection(
+    "jdbc:crate://testcluster.cratedb.net:5432/doc?sslmode=require",
+    properties
+);
+```
+
+## Install
+
+:::{rubric} Download
+:::
+
+:::{card}
+:link: https://cratedb.com/docs/jdbc/en/latest/getting-started.html#installation
+:link-type: url
+{material-regular}`download;2em`
+Navigate to the CrateDB JDBC Driver installation page.
+:::
+
+:::{card}
+:link: https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar
+:link-type: url
+{material-regular}`download;2em`
+Directly download the recommended `crate-jdbc-standalone-2.7.0.jar`.
+:::
+
+:::{rubric} Maven `pom.xml`
+:::
+```xml
+<dependencies>
+    <dependency>
+        <groupId>io.crate</groupId>
+        <artifactId>crate-jdbc</artifactId>
+        <version>2.7.0</version>
+    </dependency>
+</dependencies>
+```
+
+:::{rubric} Gradle `build.gradle`
+:::
+```groovy
+repositories {
+    mavenCentral()
+}
+dependencies {
+    implementation 'io.crate:crate-jdbc:2.7.0'
+}
+```
+
+## Quickstart example
+
+Create a file `example.java` including the synopsis code shared above.
+
+:::{include} ../_cratedb.md
+:::
+Download JAR file.
+```shell
+wget https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar
+```
+:::{dropdown} Instructions for Windows users
+If you don't have the `wget` program installed, for example on Windows, just
+download the JAR file using your web browser of choice.
+If you want to use PowerShell, invoke the `Invoke-WebRequest` command instead
+of `wget`.
+```powershell
+Invoke-WebRequest https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar -OutFile crate-jdbc-standalone-2.7.0.jar
+```
+:::
+Invoke program. Needs Java >= 21 ([JEP 445]), alternatively see [](#full-example).
+```shell
+java -cp crate-jdbc-standalone-2.7.0.jar example.java
+```
+
+
+## Full example
+
+:::{include} _jdbc_example.md
+:::
+
+
+[JEP 445]: https://openjdk.org/jeps/445