Update Java SDK documentation (#994)

biome.json

@@ -8,7 +8,11 @@
         "lineEnding": "lf",
         "lineWidth": 80,
         "attributePosition": "auto",
-        "ignore": ["aws/origin-request/index.js", "aws/viewer-request/index.js"]
+        "ignore": [
+            "aws/origin-request/index.js",
+            "aws/viewer-request/index.js",
+            "node_modules/**"
+        ]
     },
     "organizeImports": {
         "enabled": true
@@ -35,7 +39,8 @@
             "dist/**",
             ".astro/**",
             "src/util/surrealqlParser.js",
-            "star_cache.json"
+            "star_cache.json",
+            "node_modules/**"
         ]
     }
 }

src/content/doc-sdk-java/api-documentation.mdx

@@ -0,0 +1,12 @@
+---
+sidebar_position: 5
+sidebar_label: API Documentation
+title: Java | SDKs | API Documentation
+description: Where you can find the API documentation for the SurrealDB SDK for Java.
+---
+
+# API Documentation
+
+You can find the full API documentation for the SurrealDB SDK for Java on the [JavaDoc](https://surrealdb.github.io/surrealdb.java/javadoc/) website. The documentation provides detailed information about the classes, methods, and properties available in the SDK, as well as examples of how to use them in your applications.
+
+This documentation will also be available in your IDE when you import the SDK into your project, allowing you to access the documentation directly from your code editor.

src/content/doc-sdk-java/components/JavaVersion.astro

@@ -0,0 +1,9 @@
+---
+const result = await fetch(
+    'https://search.maven.org/solrsearch/select?q=g:%22com.surrealdb%22+AND+a:%22surrealdb%22&wt=json'
+);
+const data = await result.json();
+const version = data?.response?.docs[0]?.latestVersion ?? 'Unknown';
+---
+
+<code>{version}</code>

src/content/doc-sdk-java/core/_category_.json

@@ -0,0 +1,4 @@
+{
+    "sidebar_label": "Concepts",
+    "sidebar_position": 6
+}

src/content/doc-sdk-java/core/create-a-new-connection.mdx

@@ -0,0 +1,128 @@
+---
+sidebar_position: 1
+sidebar_label: Create a new connection
+title: Java | SDK | Create a new connection
+description: The SurrealDB SDK for Java enables simple and advanced querying of a remote or embedded database.
+---
+
+import Tabs from "@components/Tabs/Tabs.astro";
+import TabItem from "@components/Tabs/TabItem.astro";
+import Label from "@components/shared/Label.astro";
+
+# Create a new connection
+
+The first step towards interacting with SurrealDB is to create a new connection to a database instance. This involves initializing a new instance of the `Surreal` class and connecting it to a database endpoint. You can then switch to a specific namespace and database, and pass required authentication credentials.
+
+This guide will walk you through the process of creating a new connection to a SurrealDB instance using the Java SDK.
+
+## Related Methods
+
+<table>
+	<thead>
+		<tr>
+			<th scope="col">Method</th>
+			<th scope="col">Description</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td scope="row" data-label="Method">
+				<a href="https://surrealdb.github.io/surrealdb.java/javadoc/com/surrealdb/Surreal.html#connect(java.lang.String)">
+					<code> driver.connect(String url) </code>
+				</a>
+			</td>
+			<td scope="row" data-label="Description">Connects to a local, remote, or embedded database endpoint</td>
+		</tr>
+        <tr>
+            <td scope="row" data-label="Method">
+				<a href="https://surrealdb.github.io/surrealdb.java/javadoc/com/surrealdb/Surreal.html#close()">
+					<code> driver.close() </code>
+				</a>
+			</td>
+            <td scope="row" data-label="Description">Closes the persistent connection to the database</td>
+        </tr>
+		<tr>
+			<td scope="row" data-label="Method">
+				<a href="https://surrealdb.github.io/surrealdb.java/javadoc/com/surrealdb/Surreal.html#useNs(java.lang.String)">
+					<code> driver.useNs(String namespace) </code>
+				</a>
+			</td>
+			<td scope="row" data-label="Description">Switch to a specific namespace</td>
+		</tr>
+		<tr>
+			<td scope="row" data-label="Method">
+				<a href="https://surrealdb.github.io/surrealdb.java/javadoc/com/surrealdb/Surreal.html#useDb(java.lang.String)">
+					<code> driver.useDb(String database) </code>
+				</a>
+			</td>
+			<td scope="row" data-label="Description">Switch to a specific database</td>
+		</tr>
+	</tbody>
+</table>
+
+## Opening a connection
+
+The `.connect()` method accepts a `String` pointing to the desired local or remote instance. Since the Java SDK supports running embedded databases, you can also specify an embedded endpoint such as `memory://` and `surrealkv://`.
+
+### Supported protocols
+This is the complete list of supported connection protocols
+
+- `http://` - Plain HTTP
+- `https://` - Secure HTTP
+- `ws://` - Plain WebSocket
+- `wss://` - Secure WebSocket
+- `memory://` - In-memory database
+- `surrealkv://` - Disk-based database
+
+<br />
+
+## Selecting a namespace and database
+
+Depending on the complexity of your use case, you can switch to a specific namespace and database using the `.useNs()` and `.useDb()` methods. This is particularly useful if you want to switch to a different setup after connecting. You can also stay in the same namespace but switch to a different database. 
+
+### Example usage
+```java
+driver.useNs("surrealdb").useDb("docs");
+```
+
+<br />
+
+## Closing the connection
+
+The `.close()` method closes the persistent connection to the database. You should always call this method when you are done with the connection to free up resources. You can use a try-with-resources block to ensure that the connection is closed automatically when the block is exited.
+
+```java
+// Close the connection manually
+driver.close();
+
+// Using try-with-resources
+try (Surreal driver = new Surreal()) {
+	// ...
+}
+```
+
+<br />
+
+## Example
+
+Here is an example of the `.connect()`, `.useNs()`, `.useDb()`, and `.close()` methods in action.
+
+```java title="Example.java"
+package com.surrealdb.example;
+
+import com.surrealdb.Surreal;
+
+public class Example {
+
+    public static void main(String[] args) {
+        try (final Surreal driver = new Surreal()) {
+            // Connect to an in-memory database
+            driver.connect("memory");
+
+            // Select a namespace and database
+            driver.useNs("surrealdb").useDb("docs");
+		}
+	}
+
+}
+```

src/content/doc-sdk-java/core/handling-authentication.mdx

@@ -0,0 +1,81 @@
+---
+sidebar_position: 2
+sidebar_label: Handle authentication
+title: Java | SDK | Handle authentication
+description: SurrealDB supports a number of methods for authenticating users and securing the database.
+---
+
+import Label from "@components/shared/Label.astro";
+import Since from "@components/shared/Since.astro";
+import Version from '@components/Version.astro';
+import Tabs from "@components/Tabs/Tabs.astro";
+import TabItem from "@components/Tabs/TabItem.astro";
+
+# Handle authentication
+
+Since SurrealDB is a database that is designed to be used in a distributed environment, it is important to secure the database and the data that is stored in it. SurrealDB provides a number of methods for authenticating users and securing the database.
+
+In your SurrealDB database, you can configure authentication using the [`DEFINE USER`](/docs/surrealql/statements/define/user) or [`DEFINE ACCESS`](/docs/surrealql/statements/define/access) statements.
+
+## Related Methods
+
+<table>
+	<thead>
+		<tr>
+			<th scope="col">Method</th>
+			<th scope="col">Description</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td scope="row" data-label="Method">
+				<a href="https://surrealdb.github.io/surrealdb.java/javadoc/com/surrealdb/Surreal.html#signin(com.surrealdb.signin.Signin)">
+					<code> db.signin(Signin credentials) </code>
+				</a>
+			</td>
+			<td scope="row" data-label="Description">Authenticate with provided credentials</td>
+		</tr>
+	</tbody>
+</table>
+
+## Authenticating a connection
+
+You can call the `.signin()` method on a `Surreal` instance to authenticate with the database. The `signin` method takes any valid `Signin` implementation as an argument, which contains the credentials required to authenticate with the database.
+
+The following `Signin` implementations are available:
+- `new Root(String username, String password)`
+- `new Namespace(String username, String password, String namespace)`
+- `new Database(String username, String password, String namespace, String database)`
+
+## Example
+
+Here is an example of the `.signin()` methods in action.
+
+```java title="Example.java"
+package com.surrealdb.example;
+
+import com.surrealdb.Surreal;
+import com.surrealdb.signin.Database;
+import com.surrealdb.signin.Namespace;
+import com.surrealdb.signin.Root;
+
+public class Example {
+
+    public static void main(String[] args) {
+        try (final Surreal driver = new Surreal()) {
+          	driver.connect("wss://example.com");
+            driver.useNs("example").useDb("example");
+
+			// Authenticate as root user
+			driver.signin(new Root("root", "root"));
+
+			// Authenticate as a namespace user
+			driver.signin(new Namespace("root", "root", "ns"));
+
+			// Authenticate as a database user
+            driver.signin(new Database("root", "root", "ns", "db"));
+		}
+	}
+
+}
+```

src/content/doc-sdk-java/core/index.mdx

@@ -0,0 +1,14 @@
+---
+sidebar_position: 1
+sidebar_label: SDK Concepts
+title: Java | SDK | Concepts
+description: The SurrealDB SDK for Java enables simple and advanced querying of a remote or embedded database.
+---
+
+# Concepts 
+
+In this section, we will go over the core concepts of the SurrealDB SDK for Java. You will learn how to connect to a SurrealDB instance, manage authentication, and interact with the database.
+
+- [Create a new Connection](/docs/sdk/java/core/create-a-new-connection)
+- [Handle authentication](/docs/sdk/java/core/handling-authentication)
+