Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Java: new README.md #395

Merged
merged 14 commits into from
Jul 2, 2024
Next Next commit
implement readme
cyip10 committed Jun 28, 2024
commit c84c90a1b42ec4136095919ba9f565b16ee53d41
100 changes: 82 additions & 18 deletions java/README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,37 @@
# GLIDE for Redis

General Language Independent Driver for the Enterprise (GLIDE) for Redis, is an AWS-sponsored, open-source Redis client. GLIDE for Redis works with any Redis distribution that adheres to the Redis Serialization
Protocol (RESP) specification, including open-source Redis, Amazon ElastiCache for Redis, and Amazon MemoryDB for Redis.
Strategic, mission-critical Redis-based applications have requirements for security, optimized performance, minimal downtime, and observability. GLIDE for Redis is designed to provide a client experience that helps meet these objectives.
It is sponsored and supported by AWS, and comes pre-configured with best practices learned from over a decade of operating Redis-compatible services used by hundreds of thousands of customers.
To help ensure consistency in development and operations, GLIDE for Redis is implemented using a core driver framework, written in Rust, with extensions made available for each supported programming language. This design ensures that updates easily propagate to each language and reduces overall complexity.
In this release, GLIDE for Redis is available for Python, Javascript (Node.js), and Java.

## Supported Redis Versions

GLIDE for Redis is API-compatible with open source Redis version 6 and 7.

## Current Status

We've made GLIDE for Redis an open-source project, and are releasing it in Preview to the community to gather feedback, and actively collaborate on the project roadmap. We welcome questions and contributions from all Redis stakeholders.
This preview release is recommended for testing purposes only.

# Getting Started - Java Wrapper

## Notice: Java Wrapper - Work in Progress
## System Requirements

The beta release of GLIDE for Redis was tested on Intel x86_64 using Ubuntu 22.04.1, Amazon Linux 2023 (AL2023), and macOS 12.7.

We're excited to share that the Java client is currently in development! However, it's important to note that this client
is a work in progress and is not yet complete or fully tested. Your contributions and feedback are highly encouraged as
we work towards refining and improving this implementation. Thank you for your interest and understanding as we continue
to develop this Java wrapper.
## Java supported version
JDK 11+.
cyip10 marked this conversation as resolved.
Show resolved Hide resolved

The Java client contains the following parts:

1. `client`: A Java-wrapper around the rust-core client.
2. `examples`: An examples app to test the client against a Redis localhost
3. `benchmark`: A dedicated benchmarking tool designed to evaluate and compare the performance of GLIDE for Redis and other Java clients.
4. `integTest`: An integration test sub-project for API and E2E testing
1. `src`: Rust dynamic library FFI to integrate with [GLIDE core library](https://github.com/aws/glide-for-redis/blob/main/glide-core/README.md).
cyip10 marked this conversation as resolved.
Show resolved Hide resolved
cyip10 marked this conversation as resolved.
Show resolved Hide resolved
cyip10 marked this conversation as resolved.
Show resolved Hide resolved
2. `client`: A Java-wrapper around the [GLIDE core rust library](../glide-core/README.md) and unit tests for it.
3. `examples`: An examples app to test the client against a Redis localhost.
4. `benchmark`: A dedicated benchmarking tool designed to evaluate and compare the performance of GLIDE for Redis and other Java clients.
5. `integTest`: An integration test sub-project for API and E2E testing.

## Installation and Setup

@@ -29,27 +48,49 @@ Software Dependencies:
- protoc (protobuf compiler)
- Rust

cyip10 marked this conversation as resolved.
Show resolved Hide resolved
Please also consider installing the following packages to build [GLIDE core rust library](../glide-core/README.md):
cyip10 marked this conversation as resolved.
Show resolved Hide resolved

- GCC
- pkg-config
- openssl
- openssl-dev

#### Prerequisites
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should mention that an existing Valkey-compatible server is required to run the integration tests. Probably shouldn't say "install redis".

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe IT expects redis-server to be installed.
https://github.com/aws/glide-for-redis/blob/main/utils/cluster_manager.py#L287

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wait, should we leave redis references in the code?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

until there's an equivalent setup for valkey-server, we don't have a choice.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


**Protoc installation**

Download a binary matching your system from the [official release page](https://github.com/protocolbuffers/protobuf/releases) and make it accessible in your $PATH by moving it or creating a symlink.
tetrachromium marked this conversation as resolved.
Show resolved Hide resolved
For example, on Linux you can copy it to `/usr/bin`:

```bash
sudo cp protoc /usr/bin/
```

**Dependencies installation for Ubuntu**

```bash
sudo apt update -y
sudo apt install -y protobuf-compiler openjdk-11-jdk openssl gcc
sudo apt install -y openjdk-11-jdk openssl gcc
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
```

**Dependencies for MacOS**
**Dependencies installation for MacOS**

Ensure that you have a minimum Java version of JDK 11 installed on your system:
```bash
$ echo $JAVA_HOME
/Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home
brew update
brew install git gcc pkgconfig openssl openjdk@11
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
```

**Java version check**

$ java -version
openjdk version "11.0.1" 2018-10-16
OpenJDK Runtime Environment 18.9 (build 11.0.1+13)
OpenJDK 64-Bit Server VM 18.9 (build 11.0.1+13, mixed mode)
Ensure that you have a minimum Java version of JDK 11 installed on your system:

```bash
echo $JAVA_HOME
java -version
```

#### Building and installation steps
@@ -106,6 +147,29 @@ CompletableFuture<String> getResponse = client.get("key");
assert getResponse.get() == "foobar" : "Failed on client.get("key") request";
```

### Cluster Redis:
```java
import glide.api.RedisClusterClient;

String host = "localhost";
Integer port = 6379;
boolean useSsl = false;

RedisClientConfiguration config =
RedisClientConfiguration.builder()
.address(NodeAddress.builder().host(host).port(port).build())
.useTLS(useSsl)
.build();

RedisClusterClient client = RedisClusterClient.CreateClient(config).get();

CompletableFuture<String> setResponse = client.set("key", "foobar");
assert setResponse.get() == "OK" : "Failed on client.set("key", "foobar") request";

CompletableFuture<String> getResponse = client.get("key");
assert getResponse.get() == "foobar" : "Failed on client.get("key") request";
```

### Benchmarks

You can run benchmarks using `./gradlew run`. You can set arguments using the args flag like: