Java SDK

Installation

Add to pom.xml:

<dependency>
  <groupId>com.tollmesh</groupId>
  <artifactId>tollmeshcache</artifactId>
  <version>1.0.0</version>
</dependency>

Quick Start

import com.tollmesh.store.*;
import java.time.Duration;

ClientConfig config = new ClientConfig()
  .setHost("localhost")
  .setPort(8080);

Client client = new Client(config);

// Rate limiting
ConsumeResult result = client.consume("user-123", 100, Duration.ofMinutes(1));
if (result.ok) {
  System.out.println("Request allowed");
}

client.close();

Features

• ✅ Sync & async clients
• ✅ CompletableFuture async support
• ✅ OkHttp3 connection pooling
• ✅ Strong type safety
• ✅ Builder pattern configuration

Async Usage

AsyncClient asyncClient = new AsyncClient(config);

asyncClient.consume("user-123", 100, Duration.ofMinutes(1))
  .thenAccept(result -> {
    if (result.ok) {
      System.out.println("Request allowed");
    }
  })
  .exceptionally(error -> {
    System.err.println("Error: " + error.getMessage());
    return null;
  });

API Reference

This section covers rate limiting, replay protection, and caching. This SDK also has full, identical-API support for Job Queues, Sorted Sets, Streams, Pub/Sub, Transactions, Persistence, Pipelines, WASM Scripting, Search, Ranking, and Metrics — see the full API Reference for all of them, with live-verified examples.

Rate Limiting

ConsumeResult result = client.consume(key, limit, window);
// Fields: ok, remaining, reset_at

Replay Protection

SeenResult result = client.seen(key, ttl);
// Field: seen

Caching

client.cacheSet(namespace, key, value, ttl);
CacheValue cached = client.cacheGet(namespace, key);
// Fields: value, exists

Health

HealthResponse health = client.health();
// Methods: isHealthy(), isDegraded(), getUptimeSeconds()

Error Handling

import com.tollmesh.store.TollMeshException;

try {
  result = client.consume("key", 100, Duration.ofMinutes(1));
} catch (TollMeshException e) {
  System.err.println("Error " + e.getErrorCode() + ": " + e.getMessage());
  if (e.isRateLimited()) {
    // Handle rate limit
  }
}

Configuration

ClientConfig config = new ClientConfig()
  .setHost("localhost")
  .setPort(8080)
  .setTimeout(5000)
  .setVerifySsl(true)
  .setApiKey("optional-key")
  .setHttpScheme("http")
  .setMaxRetries(3)
  .setRetryBackoff(1.0)
  .setConnectionPoolSize(10);

Testing

mvn test

Examples

See examples/ for:

• RateLimitingExample.java - Rate limiting patterns