valkey-io · Aryex · Jul 26, 2026
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -226,6 +226,15 @@ export default defineConfig({
                         "migration/java/jedis/jedis-compatibility-layer/configurations-mapping",
                       ],
                     },
+                    {
+                      label: "Jedis 4.x Compatibility Layer",
+                      items: [
+                        "migration/java/jedis/jedis-4-compatibility-layer",
+                        "migration/java/jedis/jedis-4-compatibility-layer/instructions",
+                        "migration/java/jedis/jedis-4-compatibility-layer/supported-features",
+                        "migration/java/jedis/jedis-4-compatibility-layer/configurations-mapping",
+                      ],
+                    },
                     {
                       label: "Manual Migrations",
                       items: [

diff --git a/src/content/docs/migration/java/jedis/index.mdx b/src/content/docs/migration/java/jedis/index.mdx
@@ -10,6 +10,8 @@ import { Aside, LinkCard } from '@astrojs/starlight/components';
 
 #### Looking to migrate from Jedis?
 
-<LinkCard title="Quick Migration" href={`/migration/java/jedis/jedis-compatibility-layer/`} description="A simple drop-in replacement using the Jedis Compatibility Layer." />
+<LinkCard title="Quick Migration (Jedis 5.x)" href={`/migration/java/jedis/jedis-compatibility-layer/`} description="A simple drop-in replacement using the Jedis Compatibility Layer for Jedis 5.x applications." />
+
+<LinkCard title="Quick Migration (Jedis 4.x)" href={`/migration/java/jedis/jedis-4-compatibility-layer/`} description="A drop-in replacement for Jedis 4.0.x–4.4.x applications using the Jedis 4.x Compatibility Layer." />
 
 <LinkCard title="Full Migration" href={`/migration/java/jedis/manual-migrations/`} description="Take full avantage of Valkey GLIDE by moving to native APIs." />
diff --git a/...ocs/migration/java/jedis/jedis-4-compatibility-layer/configurations-mapping.mdx b/...ocs/migration/java/jedis/jedis-4-compatibility-layer/configurations-mapping.mdx
@@ -0,0 +1,104 @@
+---
+title: Configuration Mapping
+description: Configuration mapping between Jedis 4.x and the GLIDE Jedis 4.x Compatibility Layer.
+sidebar:
+  order: 4
+
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+This page describes how Jedis 4.x configuration parameters map to Valkey GLIDE configuration when using the Jedis 4.x Compatibility Layer.
+
+## Configuration Overview
+
+The following Jedis 4.x configuration parameters are:
+
+* **Successfully Mapped**: user, password, clientName, ssl, connectionTimeoutMillis, socketTimeoutMillis, database.
+* **Accepted but Ignored**: redisProtocol (always RESP2), pool configuration values.
+* **Not Supported**: Custom SSLSocketFactory, HostnameVerifier, keystore/truststore, cipher suites, TLS protocol versions, client-auth, AuthXManager, custom RedisCredentialsProvider.
+
+## Parameter Mappings
+
+### `DefaultJedisClientConfig` Parameters
+
+| Jedis 4.x Parameter | GLIDE Mapping | Notes |
+|---|---|---|
+| `user` | `ServerCredentials.username` | Fully supported |
+| `password` | `ServerCredentials.password` | Fully supported |
+| `clientName` | `BaseClientConfiguration.clientName` | Fully supported |
+| `ssl` | `BaseClientConfiguration.useTLS` | System trust store only |
+| `connectionTimeoutMillis` | `AdvancedBaseClientConfiguration.connectionTimeout` | Fully supported |
+| `socketTimeoutMillis` | `BaseClientConfiguration.requestTimeout` | Fully supported |
+| `database` | Handled via SELECT command after connection | Fully supported |
+| `redisProtocol` / `getRedisProtocol()` | Ignored | Always RESP2; exists for source compatibility |
+
+### Pool Configuration Parameters
+
+<Aside type="note" title="Pool config is accepted but ignored">
+  GLIDE manages connection pooling internally. Apache Commons Pool settings are accepted at the API level for compatibility but have no effect on GLIDE's behavior.
+</Aside>
+
+| Jedis 4.x Pool Parameter | GLIDE Behavior |
+|---|---|
+| `maxTotal` | Ignored — GLIDE manages pool size internally |
+| `maxIdle` | Ignored |
+| `minIdle` | Ignored |
+| `maxWaitMillis` | Ignored |
+| `testOnBorrow` | Ignored |
+| `testOnReturn` | Ignored |
+| `testWhileIdle` | Ignored |
+| `timeBetweenEvictionRunsMillis` | Ignored |
+| `numTestsPerEvictionRun` | Ignored |
+| `minEvictableIdleTimeMillis` | Ignored |
+| `blockWhenExhausted` | Ignored |
+
+### Pool Type Differences
+
+| Client | Jedis 4.x Pool Type | Jedis 5.x Pool Type |
+|---|---|---|
+| `JedisPool` | `GenericObjectPoolConfig<Jedis>` | `GenericObjectPoolConfig<Jedis>` |
+| `JedisPooled` | `GenericObjectPoolConfig<Connection>` | `GenericObjectPoolConfig<Object>` |
+
+Both types are accepted by this compatibility layer and both are ignored internally.
+
+## SSL/TLS Configuration
+
+### Supported
+
+| Configuration | Example |
+|---|---|
+| Enable TLS (system trust store) | `DefaultJedisClientConfig.builder().ssl(true).build()` |
+| `rediss://` URI scheme | `new JedisPooled("rediss://localhost:6380")` |
+| Insecure mode (testing only) | `SslOptions.builder().sslVerifyMode(SslVerifyMode.INSECURE).build()` |
+
+### Not Supported (throws `JedisConfigurationException`)
+
+| Configuration | Alternative |
+|---|---|
+| Custom `SSLSocketFactory` | Use system trust store or native GLIDE config |
+| Custom `HostnameVerifier` | Use system trust store or `SslVerifyMode.INSECURE` for testing |
+| Keystore / truststore on `SslOptions` | Install certificates in the system trust store |
+| Custom cipher suites | GLIDE auto-selects secure ciphers |
+| TLS protocol version selection | GLIDE auto-selects TLS 1.2+ |
+| Client-auth flags on `SSLParameters` | Use username/password authentication |
+
+## Cluster Configuration
+
+### `JedisCluster` Constructor Parameters
+
+| Parameter | GLIDE Mapping | Notes |
+|---|---|---|
+| `Set<HostAndPort> nodes` | Cluster node addresses | Fully supported |
+| `connectionTimeout` | Connection timeout | Fully supported |
+| `soTimeout` | Socket/request timeout | Fully supported |
+| `maxAttempts` | Retry configuration | Mapped to GLIDE retry strategy |
+| `password` | Authentication credentials | Fully supported |
+| `clientName` | Client name | Fully supported |
+
+## Key Migration Insights
+
+1. **Pool configuration doesn't matter**: GLIDE's internal connection management is optimized and ignores pool settings. This is usually an improvement over manually tuned pools.
+2. **Protocol is always RESP2**: The `.protocol()` method exists for source compatibility with shared config types, but GLIDE always negotiates RESP2 in this layer. For RESP3, use the Jedis 5.x layer.
+3. **SSL simplified**: GLIDE uses system certificate stores with secure defaults (TLS 1.2+, modern cipher suites). Custom SSL configuration must be migrated to system-level trust or to native GLIDE APIs.
+4. **Timeouts map directly**: Connection and socket timeouts are mapped to GLIDE's equivalent timeout settings with the same semantics.
diff --git a/src/content/docs/migration/java/jedis/jedis-4-compatibility-layer/index.mdx b/src/content/docs/migration/java/jedis/jedis-4-compatibility-layer/index.mdx
@@ -0,0 +1,80 @@
+---
+title: Overview
+description: Learn how the Valkey GLIDE Jedis 4.x Compatibility Layer enables seamless migration from Jedis 4.x to Valkey GLIDE with minimal or no code changes.
+sidebar:
+  order: 1
+
+---
+
+import { Aside, LinkCard } from '@astrojs/starlight/components';
+
+The Valkey GLIDE Jedis 4.x Compatibility Layer is a **drop-in replacement** that enables seamless migration from Jedis 4.x applications to Valkey GLIDE with minimal or no code changes.
+
+It implements the Jedis 4.x API while using the high-performance Valkey GLIDE client underneath. This allows existing Jedis 4.x applications to benefit from GLIDE's modern architecture without a complete rewrite.
+
+<Aside type="note" title="Which compatibility layer do I need?">
+  This layer targets **Jedis 4.0.x through 4.4.x** applications. If your application already uses **Jedis 5.x** APIs (e.g., `GenericObjectPoolConfig<Object>` for `JedisPooled`, RESP3 support), use the [Jedis Compatibility Layer](/migration/java/jedis/jedis-compatibility-layer/) instead.
+</Aside>
+
+## Why a Separate Jedis 4.x Layer?
+
+Jedis 5.x introduced breaking changes to several public types — notably `JedisPooled` pool generics changed from `GenericObjectPoolConfig<Connection>` to `GenericObjectPoolConfig<Object>`, and optional RESP3 / `RedisProtocol` APIs were added.
+
+Applications compiled against Jedis 4.x signatures need this module. You pick **one** GLIDE compatibility artifact that matches your existing API:
+
+| Your Jedis Version | GLIDE Compatibility Artifact |
+|---|---|
+| 4.0.x – 4.4.x | `valkey-glide-jedis-4-compatibility` |
+| 5.0.x – 5.2.x | `valkey-glide-jedis-compatibility` |
+
+## Zero-Code Migration
+
+For applications using standard Redis commands, migration can be as simple as changing a single dependency in your build configuration. Your existing Jedis 4.x code continues to work without modification:
+
+```java
+import redis.clients.jedis.Jedis;
+import redis.clients.jedis.JedisPool;
+import org.apache.commons.pool2.impl.GenericObjectPoolConfig;
+
+// Jedis 4.x style - GenericObjectPoolConfig<Jedis>
+GenericObjectPoolConfig<Jedis> poolConfig = new GenericObjectPoolConfig<>();
+poolConfig.setMaxTotal(8);
+
+try (JedisPool pool = new JedisPool(poolConfig, "localhost", 6379)) {
+    try (Jedis jedis = pool.getResource()) {
+        jedis.set("key", "value");
+        String result = jedis.get("key");
+    }
+}
+```
+
+## Key Benefits
+
+* **Reduced Effort:** Eliminates the need to rewrite most application code, saving development time, reducing testing, and lowering migration risk.
+* **Gradual Migration:** Start by swapping the dependency. Later, you can incrementally migrate complex features to native GLIDE APIs at your own pace.
+* **Business Continuity:** Avoid "big-bang" rewrites. Deploy changes incrementally with minimal downtime and the ability to roll back easily.
+* **Faster Time-to-Value:** Immediately benefit from GLIDE's modern async I/O model and optimized performance.
+* **RESP2 Protocol:** Always uses RESP2 protocol, matching Jedis 4.x default behavior.
+
+## Limitations
+
+The compatibility layer is essentially **a wrapper** around Valkey GLIDE that implements the Jedis 4.x interface.
+As such, not all Jedis and Valkey GLIDE features are supported.
+
+Key limitations include:
+- **Connection pooling**: GLIDE manages pooling internally — pool configuration values are accepted but ignored.
+- **Protocol**: Always RESP2. For RESP3, upgrade to Jedis 5.x and use the Jedis 5.x compatibility layer.
+- **SSL/TLS**: Basic TLS via `ssl(true)` and `rediss://` URIs is supported (system trust store). Custom `SSLSocketFactory`, `HostnameVerifier`, keystore/truststore, cipher suites, and client-auth are **not** supported.
+- **AuthXManager**: Not supported. Use standard username/password authentication.
+
+For simple applications, the wrapper may be enough. For applications that need advanced features or want to take full advantage of Valkey GLIDE, a full migration to the native GLIDE API is recommended.
+
+## Next Steps
+
+Ready to get started?
+
+<LinkCard title="Migration Instructions" href={`/migration/java/jedis/jedis-4-compatibility-layer/instructions/`} description="Step-by-step instructions for migrating from Jedis 4.x using the compatibility layer." />
+
+<LinkCard title="Supported Features" href={`/migration/java/jedis/jedis-4-compatibility-layer/supported-features/`} description="See what Jedis 4.x features and commands are supported." />
+
+<LinkCard title="Configuration Mapping" href={`/migration/java/jedis/jedis-4-compatibility-layer/configurations-mapping/`} description="How Jedis 4.x configurations map to Valkey GLIDE configurations." />