# Java Client Setup

## XTablesClient Documentation

### Overview

**XTablesClient** is a Java client for interacting with the XTABLES server. It provides client-side functionality for managing socket communications, including resolving the server's IP address, handling versioning information, and sending/receiving messages over different types of sockets.

This client is designed for efficient interaction with the XTABLES server using protocols such as `PUSH`, `REQ`, and `SUB` for sending data, making requests, and subscribing to server updates.

#### Key Features:

* Automatic IP resolution using mDNS (Multicast DNS).
* Version tracking and logging.
* Support for multiple socket types for communication with the server.
* Methods for sending different data types to the server (e.g., `String`, `Integer`, `Double`, `List`).

***

## Installation

To use **XTablesClient** in your project, follow these steps to download and import the necessary files.

#### Step 1: Download the XTablesClient Java Library

Download the latest version of the XTablesClient library from the GitHub repository:

[Download XTablesClient ZIP](https://github.com/Kobeeeef/XTABLES/raw/zip-files/zips/jclient.zip)

#### Step 2: Import the Library into Your Project

1. Unzip the downloaded ZIP file to a directory of your choice.
2. Add the Java files to your project. Depending on your development environment, follow the relevant steps:

   **For IntelliJ IDEA:**

   * Right-click on your project > **Open Module Settings** > **Modules** > **+** > **Import Module**.
   * Select the directory where the unzipped files are located and add them as a module in your project.

   **For Eclipse:**

   * Right-click on your project > **Build Path** > **Configure Build Path**.
   * Under the **Source** tab, click **Add Folder** and select the directory containing the unzipped Java files.

***

This method ensures you are correctly adding source files (instead of JAR files) into your project.

#### Step 3: Add Required Dependencies

Download the `pom.xml` to include all required dependencies for your project.

You can add these dependencies to your `pom.xml` (for Maven) or `build.gradle` (for Gradle) files.

#### Step 4: Use the XTablesClient in Your Project

Once the library is added to your project, you can start using **XTablesClient** to interact with the XTABLES server.

Example initialization:

```java
import XTABLES.XTablesClient;

public class Main {
    public static void main(String[] args) {
        // Create an XTablesClient instance with the server's IP
        XTablesClient client = new XTablesClient("192.168.1.100");
        
        // Use client methods to interact with the XTABLES server
        client.putString("key", "value");
    }
}
```

***

### Class Overview

The **XTablesClient** class includes several methods and functionalities for interacting with the XTABLES server. Below is a detailed explanation of the main components and features.

#### Constructors

1. **`XTablesClient()`**: Initializes the client with automatic IP resolution.
2. **`XTablesClient(String ip)`**: Initializes the client with the provided IP address.
3. **`XTablesClient(String ip, int pushSocketPort, int requestSocketPort, int subscribeSocketPort)`**: Initializes the client with the provided IP address and custom port numbers for different socket types.

### Core Methods

* `putBytes(String key, byte[] value)`: Sends a `PUT` request with a byte array to the server.
* `putString(String key, String value)`: Sends a `PUT` request with a string value to the server.
* `putInteger(String key, Integer value)`: Sends a `PUT` request with an integer value to the server.
* `putLong(String key, Long value)`: Sends a `PUT` request with a long value to the server.
* `putDouble(String key, Double value)`: Sends a `PUT` request with a double value to the server.
* `putBoolean(String key, boolean value)`: Sends a `PUT` request with a boolean value to the server.
* `putList(String key, List<T> value)`: Sends a `PUT` request with a list value to the server.
* `publish(String key, byte[] value)`: Publish a message to the server.

### Retrieval Methods

* `getBytes(String key)`: Retrieves a byte array from the server.
* `getString(String key)`: Retrieves a string value from the server.
* `getInteger(String key)`: Retrieves an integer value from the server.
* `getLong(String key)`: Retrieves a long value from the server.
* `getDouble(String key)`: Retrieves a double value from the server.
* `getBoolean(String key)`: Retrieves a boolean value from the server.
* `getList(String key, Class<T> clazz)`: Retrieves a list value from the server.

### Subscription Methods

* `subscribe(String key)`: Subscribes to a message channel for updates.
* `unsubscribe(String key)`: Unsubscribe from a message channel.

### Additional Methods

* `shutdown()`: Gracefully shuts down the `XTablesClient` by destroying the `ZMQ` context (if it exists) and stopping the subscription handler thread, logging the shutdown event.
* `getVersion()`: Returns the version information of the `XTables` client.
* `addVersionProperty(String prop)`: Adds a custom property to the version string.
* `reboot()`: Reboots the server and checks if the operation was successful, returning `true` if successful, `false` otherwise.
* `ping()`: Sends a ping request to the server and returns a `PingResponse` containing the success status and round-trip time.
* `subscribeToServerLogs(Consumer<XTableProto.XTableMessage.XTableLog> consumer)`: Subscribes a consumer to receive log updates from the server.
* `unsubscribeToServerLogs(Consumer<XTableProto.XTableMessage.XTableLog> consumer)`: Unsubscribes a consumer from receiving log updates.
* `delete(String key)`: Deletes a table or data identified by the provided key, returning `true` if successful, `false` otherwise.
* `delete()`: Deletes the default table or data.
* `getTables(String key)`: Retrieves a list of table names based on the provided key, or all root tables if the key is `null`.
* `getTables()`: Retrieves a list of all root table names.
* `setServerDebug(boolean value)`: Sets the `XTABLES` debug mode to the specified value. This method constructs and sends a message to toggle the server's debug mode and verifies the server's response to ensure the operation was successful. Returns `true` if the server acknowledged the operation successfully, `false` otherwise.

***

### Example Usage

Below is an example of how to use the `XTablesClient` class in your project.

#### Sending Data to the Server

```java
import XTABLES.XTablesClient;

public class Example {
    public static void main(String[] args) {
        // Initialize the client
        XTablesClient client = new XTablesClient("192.168.1.100");

        // Send different types of data
        client.putString("username", "KobeLei");
        client.putInteger("age", 17);
        client.putDouble("height", 5.9);
    }
}
```

#### Receiving and Handling Server Updates

```java
import XTABLES.XTablesClient;

public class UpdateHandler {
    public static void main(String[] args) {
        // Initialize the client
        XTablesClient client = new XTablesClient("192.168.1.100");

        // Subscribe to updates
        client.subscribeToUpdates(update -> {
            System.out.println("Received update: " + update.getKey());
        });
    }
}
```