Skip to content

Commit

Permalink
Java: update README.md (valkey-io#1765)
Browse files Browse the repository at this point in the history 
* rebase

* copy over origin dev readme

* update submodule

* Make documentation about adding the JAR dependency more clear

* Apply suggestions from code review

Co-authored-by: Guian Gumpac <guian.gumpac@improving.com>
Co-authored-by: Alexey Temnikov <alexey.temnikov@improving.com>

* updated readme

* address new comments

* address new comment

---------

Co-authored-by: Jonathan Louie <jonathanl@bitquilltech.com>
Co-authored-by: jonathanl-bq <72158117+jonathanl-bq@users.noreply.github.com>
Co-authored-by: Guian Gumpac <guian.gumpac@improving.com>
Co-authored-by: Alexey Temnikov <alexey.temnikov@improving.com>
  • Loading branch information
@cyip10 @jonathanl-bq
@GumpacG @alexey-temnikov
5 people authored Jul 5, 2024
1 parent c9e902a commit ed71606
Showing 1 changed file with 156 additions and 80 deletions.
236 changes: 156 additions & 80 deletions java/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,111 +1,187 @@
## Valkey GLIDE
# GLIDE for Valkey

Valkey General Language Independent Driver for the Enterprise (GLIDE), is an AWS-sponsored, open-source Valkey client that includes support for open-source Redis 6.2 to 7.2. Valkey GLIDE works with any distribution that adheres to the Redis Serialization Protocol (RESP) specification, including Amazon ElastiCache, and Amazon MemoryDB.
Strategic, mission-critical applications have requirements for security, optimized performance, minimal downtime, and observability. Valkey GLIDE 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 RESP-compatible services used by hundreds of thousands of customers. To help ensure consistency in development and operations, Valkey GLIDE 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 Preview release, Valkey GLIDE is available for Python and Java, with support for Javascript (Node.js) actively under development.
Valkey General Language Independent Driver for the Enterprise (GLIDE), is an AWS-sponsored, open-source Valkey client that includes support for open-source Redis 6.2 to 7.2.
Valkey GLIDE works with any distribution that adheres to the Redis Serialization Protocol (RESP) specification, including Amazon ElastiCache, and Amazon MemoryDB.
Strategic mission-critical applications have requirements for security, optimized performance, minimal downtime, and observability.
Valkey GLIDE 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 RESP-compatible services used by hundreds of thousands of customers.
To help ensure consistency in development and operations, Valkey GLIDE 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 Preview release, Valkey GLIDE is available for Python and Java, with support for Javascript (Node.js) actively under development.

# Getting Started - Java Wrapper

## System Requirements

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

## Layout of Java code
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](../glide-core/README.md).
2. `client`: A Java-wrapper around the GLIDE core rust library and unit tests for it.
3. `examples`: An examples app to test the client against a Valkey localhost.
4. `benchmark`: A dedicated benchmarking tool designed to evaluate and compare the performance of GLIDE for Valkey and other Java clients.
5. `integTest`: An integration test sub-project for API and E2E testing.

## Supported Engine Versions

Refer to the [Supported Engine Versions table](https://github.com/aws/glide-for-redis/blob/main/README.md#supported-engine-versions) for details.

## Installation and Setup

### Install from Gradle

At the moment, the Java client must be built from source.

### Build from source
#### Prerequisites

Software Dependencies:
For developers, please refer to Java's [DEVELOPER.md](./DEVELOPER.md) for further instruction on how to set up your development environment.

- JDK 11+
- git
- protoc (protobuf compiler)
- Rust
**Java version check**

#### Prerequisites
Ensure that you have a minimum Java version of JDK 11 installed on your system:

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

**Dependencies for MacOS**
### Adding the client to your project

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
Refer to https://central.sonatype.com/artifact/software.amazon.glide/glide-for-redis.
Once set up, you can run the basic examples.
Examples shown below are for `osx-aarch_64`.

$ 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)
Gradle:
- Copy the snippet and paste it in the `build.gradle` dependencies section.
- **IMPORTANT** must include a `classifier` to specify your platform.
```groovy
dependencies {
implementation group: 'software.amazon.glide', name: 'glide-for-redis', version: '0.4.3', classifier: 'osx-aarch_64'
}
```

#### Building and installation steps
The Java client is currently a work in progress and offers no guarantees. Users should build at their own risk.

Before starting this step, make sure you've installed all software requirements.
1. Clone the repository:
```bash
VERSION=0.1.0 # You can modify this to other released version or set it to "main" to get the unstable branch
git clone --branch ${VERSION} https://github.com/aws/glide-for-redis.git
cd glide-for-redis
```
2. Initialize git submodule:
```bash
git submodule update --init --recursive
```
3. Generate protobuf files:
```bash
cd java/
./gradlew :client:protobuf
```
4. Build the client library:
```bash
cd java/
./gradlew :client:build
```
5. Run tests:
```bash
cd java/
$ ./gradlew :client:test
Maven:
- **IMPORTANT** must include a `classifier`. Please use this dependency block and add it to the pom.xml file.
```xml
<dependency>
<groupId>software.amazon.glide</groupId>
<artifactId>glide-for-redis</artifactId>
<classifier>osx-aarch_64</classifier>
<version>0.4.3</version>
</dependency>
```

Other useful gradle developer commands:
* `./gradlew :client:test` to run client unit tests
* `./gradlew :integTest:test` to run client examples
* `./gradlew spotlessCheck` to check for codestyle issues
* `./gradlew spotlessApply` to apply codestyle recommendations
* `./gradlew :examples:run` to run client examples (make sure you have a running redis on port `6379`)
* `./gradlew :benchmarks:run` to run performance benchmarks
## Setting up the Java module

## Basic Examples
To use Glide for Valkey in a Java project with modules, include a module-info.java in your project.

For example, if your program is called `App`, you can follow this path
```java
app/src/main/java/module-info.java
```

### Standalone Redis:
and inside the module it will specifically require the line
`requires glide.api;`

For example, if your project has a module called playground, it would look like this
```java
import glide.api.RedisClient;
module playground {
requires glide.api;
}
```

RedisClient client = RedisClient.CreateClient().get();
## Basic Examples

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

CompletableFuture<String> getResponse = client.get("key");
assert getResponse.get() == "foobar" : "Failed on client.get("key") request";
```java
// You can run this example code in Main.java.
import glide.api.GlideClient;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.GlideClientConfiguration;
import java.util.concurrent.ExecutionException;

import static glide.api.models.GlideString.gs;

public class Main {

public static void main(String[] args) {
runGlideExamples();
}

private static void runGlideExamples() {
String host = "localhost";
Integer port = 6379;
boolean useSsl = false;

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

try {
Glide client = GlideClient.CreateClient(config).get();

System.out.println("PING: " + client.ping(gs("PING")).get());
System.out.println("PING(found you): " + client.ping( gs("found you")).get());

System.out.println("SET(apples, oranges): " + client.set(gs("apples"), gs("oranges")).get());
System.out.println("GET(apples): " + client.get(gs("apples")).get());

} catch (ExecutionException | InterruptedException e) {
System.out.println("Glide example failed with an exception: ");
e.printStackTrace();
}
}
}
```

### Cluster Valkey:
```java
// You can run this example code in Main.java.
import glide.api.GlideClusterClient;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.RequestRoutingConfiguration;

import java.util.concurrent.ExecutionException;

import static glide.api.models.GlideString.gs;

public class Main {

public static void main(String[] args) {
runGlideExamples();
}

private static void runGlideExamples() {
String host = "localhost";
Integer port1 = 7001;
Integer port2 = 7002;
Integer port3 = 7003;
Integer port4 = 7004;
Integer port5 = 7005;
Integer port6 = 7006;
boolean useSsl = false;

RedisClusterClientConfiguration config =
RedisClusterClientConfiguration.builder()
.address(NodeAddress.builder().host(host).port(port1).port(port2).port(port3).port(port4).port(port5).port(port6).build())
.useTLS(useSsl)
.build();

try {
GlideClusterClient client = GlideClusterClient.CreateClient(config).get();

System.out.println("PING: " + client.ping(gs("PING")).get());
System.out.println("PING(found you): " + client.ping( gs("found you")).get());

System.out.println("SET(apples, oranges): " + client.set(gs("apples"), gs("oranges")).get());
System.out.println("GET(apples): " + client.get(gs("apples")).get());

} catch (ExecutionException | InterruptedException e) {
System.out.println("Glide example failed with an exception: ");
e.printStackTrace();
}
}
}
```

### Benchmarks
Expand All @@ -119,9 +195,9 @@ You can run benchmarks using `./gradlew run`. You can set arguments using the ar

The following arguments are accepted:
* `resultsFile`: the results output file
* `concurrentTasks`: Number of concurrent tasks
* `concurrentTasks`: number of concurrent tasks
* `clients`: one of: all|jedis|lettuce|glide
* `clientCount`: Client count
* `host`: redis server host url
* `port`: redis server port number
* `tls`: redis TLS configured
* `clientCount`: client count
* `host`: Valkey server host url
* `port`: Valkey server port number
* `tls`: Valkey TLS configured

0 comments on commit ed71606

Please sign in to comment.