Skip to content

Commit bd90eda

Browse files
andy-stark-redisandy-stark-redis
committed
DOC-4543 split redis-py and Jedis pages
1 parent e72ad00 commit bd90eda

File tree

6 files changed

+409
-267
lines changed

6 files changed

+409
-267
lines changed

‎content/develop/clients/jedis/_index.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
categories:
3+
- docs
4+
- develop
5+
- stack
6+
- oss
7+
- rs
8+
- rc
9+
- oss
10+
- kubernetes
11+
- clients
12+
description: Connect your Java application to a Redis database
13+
linkTitle: Jedis (Java)
14+
title: Jedis guide (Java)
15+
weight: 5
16+
---
17+
18+
[Jedis](https://github.com/redis/jedis) is a synchronous Java client for Redis.
19+
Use [Lettuce]({{< relref "/develop/connect/clients/java/lettuce" >}}) if you need
20+
a more advanced Java client that also supports asynchronous and reactive connections.
21+
The sections below explain how to install `Jedis` and connect your application
22+
to a Redis database.
23+
24+
`Jedis` requires a running Redis or [Redis Stack]({{< relref "/operate/oss_and_stack/install/install-stack/" >}}) server. See [Getting started]({{< relref "/operate/oss_and_stack/install/" >}}) for Redis installation instructions.
25+
26+
## Install
27+
28+
To include `Jedis` as a dependency in your application, edit the dependency file, as follows.
29+
30+
* If you use **Maven**:
31+
32+
```xml
33+
<dependency>
34+
<groupId>redis.clients</groupId>
35+
<artifactId>jedis</artifactId>
36+
<version>5.2.0</version>
37+
</dependency>
38+
```
39+
40+
* If you use **Gradle**:
41+
42+
```
43+
repositories {
44+
mavenCentral()
45+
}
46+
//...
47+
dependencies {
48+
implementation 'redis.clients:jedis:5.2.0'
49+
//...
50+
}
51+
```
52+
53+
* If you use the JAR files, download the latest Jedis and Apache Commons Pool2 JAR files from [Maven Central](https://central.sonatype.com/) or any other Maven repository.
54+
55+
* Build from [source](https://github.com/redis/jedis)
56+
57+
58+
## Connect and test
59+
60+
The following code opens a basic connection to a local Redis server:
61+
62+
```java
63+
package org.example;
64+
import redis.clients.jedis.UnifiedJedis;
65+
66+
public class Main {
67+
public static void main(String[] args) {
68+
UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379");
69+
70+
// Code that interacts with Redis...
71+
72+
jedis.close();
73+
}
74+
}
75+
```
76+
77+
After you have connected, you can check the connection by storing and
78+
retrieving a simple string value:
79+
80+
```java
81+
...
82+
83+
String res1 = jedis.set("bike:1", "Deimos");
84+
System.out.println(res1); // OK
85+
86+
String res2 = jedis.get("bike:1");
87+
System.out.println(res2); // Deimos
88+
89+
...
90+
```
91+
92+
## More information
93+
94+
`Jedis` has a complete [API reference](https://www.javadoc.io/doc/redis.clients/jedis/latest/index.html) available on [javadoc.io/](https://javadoc.io/).
95+
The `Jedis` [GitHub repository](https://github.com/redis/jedis) also has useful docs
96+
and examples including a page about handling
97+
[failover with Jedis](https://github.com/redis/jedis/blob/master/docs/failover.md)
98+
99+
See also the other pages in this section for more information and examples:

‎content/develop/clients/jedis.md‎ renamed to ‎content/develop/clients/jedis/connect.md‎

Lines changed: 4 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -10,51 +10,12 @@ categories:
1010
- kubernetes
1111
- clients
1212
description: Connect your Java application to a Redis database
13-
linkTitle: Jedis (Java)
14-
title: Jedis guide (Java)
15-
weight: 5
13+
linkTitle: Connect
14+
title: Connect to the server
15+
weight: 2
1616
---
1717

18-
[Jedis](https://github.com/redis/jedis) is a synchronous Java client for Redis.
19-
Use [Lettuce]({{< relref "/develop/connect/clients/java/lettuce" >}}) if you need
20-
a more advanced Java client that also supports asynchronous and reactive connections.
21-
The sections below explain how to install `Jedis` and connect your application
22-
to a Redis database.
23-
24-
`Jedis` requires a running Redis or [Redis Stack]({{< relref "/operate/oss_and_stack/install/install-stack/" >}}) server. See [Getting started]({{< relref "/operate/oss_and_stack/install/" >}}) for Redis installation instructions.
25-
26-
## Install
27-
28-
To include `Jedis` as a dependency in your application, edit the dependency file, as follows.
29-
30-
* If you use **Maven**:
31-
32-
```xml
33-
<dependency>
34-
<groupId>redis.clients</groupId>
35-
<artifactId>jedis</artifactId>
36-
<version>5.2.0</version>
37-
</dependency>
38-
```
39-
40-
* If you use **Gradle**:
41-
42-
```
43-
repositories {
44-
mavenCentral()
45-
}
46-
//...
47-
dependencies {
48-
implementation 'redis.clients:jedis:5.2.0'
49-
//...
50-
}
51-
```
52-
53-
* If you use the JAR files, download the latest Jedis and Apache Commons Pool2 JAR files from [Maven Central](https://central.sonatype.com/) or any other Maven repository.
54-
55-
* Build from [source](https://github.com/redis/jedis)
56-
57-
## Connect
18+
## Basic connection
5819

5920
The following code opens a basic connection to a local Redis server:
6021

@@ -402,86 +363,3 @@ poolConfig.setTimeBetweenEvictionRuns(Duration.ofSeconds(1));
402363
// to prevent connection starvation
403364
JedisPooled jedis = new JedisPooled(poolConfig, "localhost", 6379);
404365
```
405-
406-
## Production usage
407-
408-
The following sections explain how to handle situations that may occur
409-
in your production environment.
410-
411-
### Timeouts
412-
413-
To set a timeout for a connection, use the `JedisPooled` or `JedisPool` constructor with the `timeout` parameter, or use `JedisClientConfig` with the `socketTimeout` and `connectionTimeout` parameters:
414-
415-
```java
416-
HostAndPort hostAndPort = new HostAndPort("localhost", 6379);
417-
418-
JedisPooled jedisWithTimeout = new JedisPooled(hostAndPort,
419-
DefaultJedisClientConfig.builder()
420-
.socketTimeoutMillis(5000) // set timeout to 5 seconds
421-
.connectionTimeoutMillis(5000) // set connection timeout to 5 seconds
422-
.build(),
423-
poolConfig
424-
);
425-
```
426-
427-
### Exception handling
428-
429-
The Jedis Exception Hierarchy is rooted on `JedisException`, which implements `RuntimeException`, and are therefore all unchecked exceptions.
430-
431-
```
432-
JedisException
433-
├── JedisDataException
434-
│ ├── JedisRedirectionException
435-
│ │ ├── JedisMovedDataException
436-
│ │ └── JedisAskDataException
437-
│ ├── AbortedTransactionException
438-
│ ├── JedisAccessControlException
439-
│ └── JedisNoScriptException
440-
├── JedisClusterException
441-
│ ├── JedisClusterOperationException
442-
│ ├── JedisConnectionException
443-
│ └── JedisValidationException
444-
└── InvalidURIException
445-
```
446-
447-
#### General exceptions
448-
449-
In general, Jedis can throw the following exceptions while executing commands:
450-
451-
- `JedisConnectionException` - when the connection to Redis is lost or closed unexpectedly. Configure failover to handle this exception automatically with Resilience4J and the built-in Jedis failover mechanism.
452-
- `JedisAccessControlException` - when the user does not have the permission to execute the command or the user ID and/or password are incorrect.
453-
- `JedisDataException` - when there is a problem with the data being sent to or received from the Redis server. Usually, the error message will contain more information about the failed command.
454-
- `JedisException` - this exception is a catch-all exception that can be thrown for any other unexpected errors.
455-
456-
Conditions when `JedisException` can be thrown:
457-
- Bad return from a health check with the [`PING`]({{< relref "/commands/ping" >}}) command
458-
- Failure during SHUTDOWN
459-
- Pub/Sub failure when issuing commands (disconnect)
460-
- Any unknown server messages
461-
- Sentinel: can connect to sentinel but master is not monitored or all Sentinels are down.
462-
- MULTI or DISCARD command failed
463-
- Shard commands key hash check failed or no Reachable Shards
464-
- Retry deadline exceeded/number of attempts (Retry Command Executor)
465-
- POOL - pool exhausted, error adding idle objects, returning broken resources to the pool
466-
467-
All the Jedis exceptions are runtime exceptions and in most cases irrecoverable, so in general bubble up to the API capturing the error message.
468-
469-
### DNS cache and Redis
470-
471-
When you connect to a Redis server with multiple endpoints, such as [Redis Enterprise Active-Active](https://redis.com/redis-enterprise/technology/active-active-geo-distribution/), you *must*
472-
disable the JVM's DNS cache. If a server node or proxy fails, the IP address for any database
473-
affected by the failure will change. When this happens, your app will keep
474-
trying to use the stale IP address if DNS caching is enabled.
475-
476-
Use the following code to disable the DNS cache:
477-
478-
```java
479-
java.security.Security.setProperty("networkaddress.cache.ttl","0");
480-
java.security.Security.setProperty("networkaddress.cache.negative.ttl", "0");
481-
```
482-
483-
## Learn more
484-
485-
* [Jedis API reference](https://www.javadoc.io/doc/redis.clients/jedis/latest/index.html)
486-
* [Failover with Jedis](https://github.com/redis/jedis/blob/master/docs/failover.md)
487-
* [GitHub](https://github.com/redis/jedis)

‎content/develop/clients/jedis/produsage.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
categories:
3+
- docs
4+
- develop
5+
- stack
6+
- oss
7+
- rs
8+
- rc
9+
- oss
10+
- kubernetes
11+
- clients
12+
description: Get your Jedis app ready for production
13+
linkTitle: Production usage
14+
title: Production usage
15+
weight: 3
16+
---
17+
18+
The following sections explain how to handle situations that may occur
19+
in your production environment.
20+
21+
### Timeouts
22+
23+
To set a timeout for a connection, use the `JedisPooled` or `JedisPool` constructor with the `timeout` parameter, or use `JedisClientConfig` with the `socketTimeout` and `connectionTimeout` parameters:
24+
25+
```java
26+
HostAndPort hostAndPort = new HostAndPort("localhost", 6379);
27+
28+
JedisPooled jedisWithTimeout = new JedisPooled(hostAndPort,
29+
DefaultJedisClientConfig.builder()
30+
.socketTimeoutMillis(5000) // set timeout to 5 seconds
31+
.connectionTimeoutMillis(5000) // set connection timeout to 5 seconds
32+
.build(),
33+
poolConfig
34+
);
35+
```
36+
37+
### Exception handling
38+
39+
The Jedis Exception Hierarchy is rooted on `JedisException`, which implements `RuntimeException`, and are therefore all unchecked exceptions.
40+
41+
```
42+
JedisException
43+
├── JedisDataException
44+
│ ├── JedisRedirectionException
45+
│ │ ├── JedisMovedDataException
46+
│ │ └── JedisAskDataException
47+
│ ├── AbortedTransactionException
48+
│ ├── JedisAccessControlException
49+
│ └── JedisNoScriptException
50+
├── JedisClusterException
51+
│ ├── JedisClusterOperationException
52+
│ ├── JedisConnectionException
53+
│ └── JedisValidationException
54+
└── InvalidURIException
55+
```
56+
57+
#### General exceptions
58+
59+
In general, Jedis can throw the following exceptions while executing commands:
60+
61+
- `JedisConnectionException` - when the connection to Redis is lost or closed unexpectedly. Configure failover to handle this exception automatically with Resilience4J and the built-in Jedis failover mechanism.
62+
- `JedisAccessControlException` - when the user does not have the permission to execute the command or the user ID and/or password are incorrect.
63+
- `JedisDataException` - when there is a problem with the data being sent to or received from the Redis server. Usually, the error message will contain more information about the failed command.
64+
- `JedisException` - this exception is a catch-all exception that can be thrown for any other unexpected errors.
65+
66+
Conditions when `JedisException` can be thrown:
67+
- Bad return from a health check with the [`PING`]({{< relref "/commands/ping" >}}) command
68+
- Failure during SHUTDOWN
69+
- Pub/Sub failure when issuing commands (disconnect)
70+
- Any unknown server messages
71+
- Sentinel: can connect to sentinel but master is not monitored or all Sentinels are down.
72+
- MULTI or DISCARD command failed
73+
- Shard commands key hash check failed or no Reachable Shards
74+
- Retry deadline exceeded/number of attempts (Retry Command Executor)
75+
- POOL - pool exhausted, error adding idle objects, returning broken resources to the pool
76+
77+
All the Jedis exceptions are runtime exceptions and in most cases irrecoverable, so in general bubble up to the API capturing the error message.
78+
79+
### DNS cache and Redis
80+
81+
When you connect to a Redis server with multiple endpoints, such as [Redis Enterprise Active-Active](https://redis.com/redis-enterprise/technology/active-active-geo-distribution/), you *must*
82+
disable the JVM's DNS cache. If a server node or proxy fails, the IP address for any database
83+
affected by the failure will change. When this happens, your app will keep
84+
trying to use the stale IP address if DNS caching is enabled.
85+
86+
Use the following code to disable the DNS cache:
87+
88+
```java
89+
java.security.Security.setProperty("networkaddress.cache.ttl","0");
90+
java.security.Security.setProperty("networkaddress.cache.negative.ttl", "0");
91+
```

0 commit comments

Comments
 (0)