Implement complete Java client for VectorX with JNA bindings and MessagePack support

[Copilot]

This PR implements a comprehensive Java client for VectorX that replicates the functionality of the Python client in LaunchX-Labs/vecx-py. The implementation provides a complete Java interface to the VectorX C++ library with all the same capabilities.

🚀 Features Implemented

Core Components

• LibVectorX: Main client class providing high-level API for all vector operations
• VectorXNative: JNA interface with complete bindings to all native C++ methods
• LibraryLoader: Cross-platform native library loading with automatic OS/architecture detection
• BufferUtils: Efficient direct buffer management utilities for optimal native performance
• MessagePackUtils: Complete MessagePack serialization/deserialization support
• VectorXException: Comprehensive error handling with native error codes

Native Method Bindings

All native methods from the Python client's libvx.py are bound:

• vecx_create / vecx_destroy - Instance management
• vecx_encrypt_vector / vecx_decrypt_vector - Single vector operations
• vecx_encrypt_vectors / vecx_decrypt_vectors - Batch operations
• vecx_encrypt_meta / vecx_decrypt_meta - Metadata operations
• vecx_decrypt_and_calculate_similarities - Optimized similarity search
• vecx_calculate_distances - Distance matrix computation
• vecx_get_error / vecx_get_version - Utility functions

Cross-Platform Support

Automatic detection and loading of native libraries for:

• Windows: vectorx-x64.dll, vectorx-x86.dll
• macOS: libvectorx-x64.dylib, libvectorx-arm64.dylib
• Linux: libvectorx-x64.so, libvectorx-arm64.so

📋 API Examples

Basic Vector Operations

try (LibVectorX vectorX = new LibVectorX()) {
    float[] vector = {1.0f, 2.0f, 3.0f, 4.0f};
    byte[] encrypted = vectorX.encryptVector(vector);
    float[] decrypted = vectorX.decryptVector(encrypted, vector.length);
}

Metadata Encryption with MessagePack

Map<String, Object> metadata = Map.of(
    "id", "vector_001",
    "category", "text_embedding",
    "timestamp", System.currentTimeMillis()
);

byte[] encryptedMeta = vectorX.encryptMeta(metadata);
Map<String, Object> decryptedMeta = vectorX.decryptMeta(encryptedMeta, Map.class);

Batch Operations

float[][] vectors = {{1.0f, 2.0f}, {3.0f, 4.0f}, {5.0f, 6.0f}};
byte[] encrypted = vectorX.encryptVectors(vectors);
float[][] decrypted = vectorX.decryptVectors(encrypted, vectors.length, vectors[0].length);

Similarity Search

float[] similarities = vectorX.decryptAndCalculateSimilarities(
    encryptedVectors, numVectors, vectorSize, queryVector);

🔧 Technical Implementation

Memory Management

• Uses Java direct buffers (FloatBuffer, ByteBuffer) for efficient native interop
• Implements AutoCloseable for automatic resource cleanup
• Provides manual cleanup methods for explicit resource management

Error Handling

• Custom VectorXException with native error codes
• Comprehensive error messages from native library
• Graceful fallback for library loading failures

Performance Optimizations

• Direct buffer operations minimize memory copying
• Batch operations for multiple vectors
• Combined decrypt + similarity calculation operations

📦 Maven Configuration

<dependency>
    <groupId>com.launchx.labs</groupId>
    <artifactId>vecx-java</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Dependencies:

• JNA 5.13.0 for native library access
• MessagePack Core 0.9.8 for serialization
• JUnit Jupiter 5.10.0 for testing

✅ Testing & Documentation

• Unit Tests: Comprehensive test suite covering all utility classes and core functionality
• Usage Examples: Complete examples demonstrating all major operations
• Javadoc: Full API documentation with detailed method descriptions
• README: Comprehensive documentation with installation and usage instructions

🎯 Compatibility

This Java client provides identical functionality to the Python client:

• Same encryption/decryption operations
• Same MessagePack serialization format
• Same native library interface
• Same error handling patterns

The implementation ensures seamless interoperability between Java and Python applications using VectorX.

📁 Project Structure

src/
├── main/java/com/launchx/labs/vecx/
│   ├── LibVectorX.java              # Main client class
│   ├── VectorXNative.java           # JNA native interface
│   ├── LibraryLoader.java           # Cross-platform library loading
│   ├── BufferUtils.java             # Direct buffer utilities
│   ├── MessagePackUtils.java        # MessagePack serialization
│   ├── VectorXException.java        # Exception handling
│   ├── package-info.java            # Package documentation
│   └── examples/
│       └── BasicUsageExample.java   # Usage examples
├── main/resources/native/           # Native library directory
└── test/java/com/launchx/labs/vecx/
    └── VectorXTest.java             # Unit tests

This implementation provides Java developers with a complete, production-ready client for VectorX operations with the same capabilities as the Python client.

This pull request was created as a result of the following prompt from Copilot chat.

Implement a Java client in LaunchX-Labs/vecx-java that is a direct replica of the Python client in LaunchX-Labs/vecx-py. The implementation should include:

1. FFI connection: Use JNA (Java Native Access) to connect to the C++ shared library, replicating the Python client's use of cffi. Bind all native methods found in vecx-py/vecx/libvx.py, including vecx_create, vecx_destroy, vecx_encrypt_vector, vecx_decrypt_vector, vecx_encrypt_vectors, vecx_decrypt_vectors, vecx_decrypt_and_calculate_similarities, vecx_encrypt_meta, vecx_decrypt_meta, vecx_calculate_distances, etc.

2. Class structure: Create a Java class (e.g., LibVectorX) that manages the native instance pointer and exposes methods equivalent to those in the Python LibVectorX class (encryptVector, decryptVector, encryptMeta, decryptMeta, calculateDistances, encryptVectors, decryptVectors, decryptAndCalculateSimilarities, etc.).

3. Dynamic library loading: Load the correct C++ shared library (.so, .dll, .dylib) at runtime depending on OS and architecture, as done in the Python client.

4. Buffer management: Use Java direct buffers (FloatBuffer, ByteBuffer) for passing arrays and binary data to native code, mirroring the numpy/ctypes usage in Python.

5. MessagePack support: Integrate the msgpack-java library to handle messagepack serialization and deserialization, replicating the Python client's usage of msgpack.

6. Utility methods: Replicate any utility methods and error handling found in the Python client.

7. Documentation: Add Javadoc comments and usage examples, similar to the Python docstrings and comments.

This should result in a Java client that can perform all the same vector and metadata operations as the Python client, and serialize/deserialize objects using MessagePack, providing a seamless experience for Java users.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.