Java Client Setup

This page offers guidance on setting up the Java client, covering installation and configuration steps for seamless integration with the XTABLES server.

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

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:

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

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

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());
        });
    }
}