Skip to content

Commit 8e6a709

Browse files
uglidedmaier-redislabssazzad16chayim
authored
Redis.io code examples (#3418)
* Added a simple SET and GET example * Added a meta data file. Needs to be removed as soon as we added this into the files themselves. * Update SetGetTest.java Added output comments * Update SetGetTest.java Changed the output to be more use case specific. * Wrapped the code by a test suite to keep it self-explaining * Update SetGetExample.java * Update SimpleCommandsTestSuite.java Added some comments * Update SimpleCommandsTestSuite.java Added some additional comments about how to combine code samples with JUnit tests. * Update SetGetExample.java * Update example.json Testing with wildcard search for examples. * Update SetGetExample.java Hiding the end of the file by default * Update SetGetExample.java * Update SetGetExample.java * Test annotations are now ignored by the doc parser * Changed the package name * Remove indentation * New 'Example' file name rule * Revert indentation in SetGetExample.java * skeleton of documentation tests * Make doctests runnable in CI - Move doctests to test folder to make them discoverable by JUnit - Add doctests profile - Fix doctests workflow * Add Search QuickStart to doctests * Fix workflow file * Bump Java version to 11 * Exclude doctests from testCompile * Give up on 2 Java versions support * surefire plugin 3.0.0 * fix updated doc package --------- Co-authored-by: David Maier <[email protected]> Co-authored-by: M Sazzadul Hoque <[email protected]> Co-authored-by: Chayim I. Kirshen <[email protected]>
1 parent 1b7c5cc commit 8e6a709

File tree

6 files changed

+309
-1
lines changed

6 files changed

+309
-1
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ Set up test environments with ```make start```, tear down those environments wit
3333
* You can import code style file (located to hbase-formatter.xml) to Eclipse, IntelliJ
3434
* line break by column count seems not working with IntelliJ
3535
* <strike>You can run ```make format``` anytime to reformat without IDEs</strike>
36+
* DO NOT format the source codes within `io.redis.examples` test package.
37+
* A test class name MUST NOT end with `Example`.
3638

3739
## Adding commands
3840

‎.github/workflows/doctests.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: Documentation Tests
2+
3+
on:
4+
push:
5+
pull_request:
6+
workflow_dispatch:
7+
8+
jobs:
9+
doctests:
10+
runs-on: ubuntu-latest
11+
services:
12+
redis-stack:
13+
image: redis/redis-stack-server:latest
14+
options: >-
15+
--health-cmd "redis-cli ping" --health-interval 10s --health-timeout 5s --health-retries 5
16+
ports:
17+
- 6379:6379
18+
19+
steps:
20+
- uses: actions/checkout@v3
21+
- name: Cache dependencies
22+
uses: actions/cache@v2
23+
with:
24+
path: |
25+
~/.m2/repository
26+
/var/cache/apt
27+
key: jedis-${{hashFiles('**/pom.xml')}}
28+
- name: Set up Java
29+
uses: actions/setup-java@v2
30+
with:
31+
java-version: '11'
32+
distribution: 'temurin'
33+
- name: Run doctests
34+
run: |
35+
mvn -Pdoctests test

‎pom.xml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,9 @@
170170
<systemPropertyVariables>
171171
<redis-hosts>${redis-hosts}</redis-hosts>
172172
</systemPropertyVariables>
173+
<excludes>
174+
<exclude>**/examples/*Example.java</exclude>
175+
</excludes>
173176
<!--<trimStackTrace>false</trimStackTrace>-->
174177
</configuration>
175178
</plugin>
@@ -285,5 +288,19 @@
285288
</plugins>
286289
</build>
287290
</profile>
291+
<profile>
292+
<id>doctests</id>
293+
<build>
294+
<plugins>
295+
<plugin>
296+
<artifactId>maven-surefire-plugin</artifactId>
297+
<version>3.0.0</version>
298+
<configuration>
299+
<test>**/examples/*Example.java</test>
300+
</configuration>
301+
</plugin>
302+
</plugins>
303+
</build>
304+
</profile>
288305
</profiles>
289306
</project>

‎src/test/java/io/redis/examples/SearchQuickstartExample.java‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
//EXAMPLE: set_and_get
2+
//HIDE_START
3+
package io.redis.examples;
4+
5+
import java.math.BigDecimal;
6+
import java.util.*;
7+
8+
import redis.clients.jedis.*;
9+
import redis.clients.jedis.exceptions.*;
10+
import redis.clients.jedis.search.*;
11+
import redis.clients.jedis.search.aggr.*;
12+
import redis.clients.jedis.search.schemafields.*;
13+
//REMOVE_START
14+
import org.junit.Test;
15+
16+
import static org.junit.Assert.assertEquals;
17+
//REMOVE_END
18+
19+
class Bicycle {
20+
public String brand;
21+
public String model;
22+
public BigDecimal price;
23+
public String description;
24+
public String condition;
25+
26+
public Bicycle(String brand, String model, BigDecimal price, String description, String condition) {
27+
this.brand = brand;
28+
this.model = model;
29+
this.price = price;
30+
this.description = description;
31+
this.condition = condition;
32+
}
33+
}
34+
35+
public class SearchQuickstartExample {
36+
37+
@Test
38+
public void run() {
39+
//HIDE_END
40+
41+
// STEP_START connect
42+
UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379");
43+
// STEP_END
44+
// REMOVE_START
45+
try {
46+
jedis.ftDropIndex("idx:bicycle");
47+
} catch (JedisDataException e) {
48+
// ignore
49+
}
50+
// REMOVE_END
51+
52+
// STEP_START data_sample
53+
Bicycle bike1 = new Bicycle(
54+
"Diaz Ltd",
55+
"Dealer Sl",
56+
new BigDecimal(7315.58),
57+
"The Diaz Ltd Dealer Sl is a reliable choice" +
58+
" for urban cycling. The Diaz Ltd Dealer Sl " +
59+
"is a comfortable choice for urban cycling.",
60+
"used"
61+
);
62+
// STEP_END
63+
64+
Bicycle[] bicycles = {
65+
bike1,
66+
new Bicycle(
67+
"Bridges Group",
68+
"Project Pro",
69+
new BigDecimal(3610.82),
70+
"This mountain bike is perfect for mountain biking. The Bridges" +
71+
" Group Project Pro is a responsive choice for mountain biking.",
72+
"used"
73+
),
74+
new Bicycle(
75+
"Vega, Cole and Miller",
76+
"Group Advanced",
77+
new BigDecimal(8961.42),
78+
"The Vega, Cole and Miller Group Advanced provides a excellent" +
79+
" ride. With its fast carbon frame and 24 gears, this bicycle is" +
80+
" perfect for any terrain.",
81+
"used"
82+
),
83+
new Bicycle(
84+
"Powell-Montgomery",
85+
"Angle Race",
86+
new BigDecimal(4050.27),
87+
"The Powell-Montgomery Angle Race is a smooth choice for road" +
88+
" cycling. The Powell-Montgomery Angle Race provides a durable" +
89+
" ride.",
90+
"used"
91+
),
92+
new Bicycle(
93+
"Gill-Lewis",
94+
"Action Evo",
95+
new BigDecimal(283.68),
96+
"The Gill-Lewis Action Evo provides a smooth ride. The Gill-Lewis" +
97+
" Action Evo provides a excellent ride.",
98+
"used"
99+
),
100+
new Bicycle(
101+
"Rodriguez-Guerrero",
102+
"Drama Comp",
103+
new BigDecimal(4462.55),
104+
"This kids bike is perfect for young riders. With its excellent" +
105+
" aluminum frame and 12 gears, this bicycle is perfect for any" +
106+
" terrain.",
107+
"new"
108+
),
109+
new Bicycle(
110+
"Moore PLC",
111+
"Award Race",
112+
new BigDecimal(3790.76),
113+
114+
"This olive folding bike features a carbon frame and 27.5 inch" +
115+
" wheels. This folding bike is perfect for compact storage and" +
116+
" transportation.",
117+
"new"
118+
),
119+
new Bicycle(
120+
"Hall, Haley and Hayes",
121+
"Weekend Plus",
122+
new BigDecimal(2008.4),
123+
"The Hall, Haley and Hayes Weekend Plus provides a comfortable" +
124+
" ride. This blue kids bike features a steel frame and 29.0 inch" +
125+
" wheels.",
126+
"new"
127+
),
128+
new Bicycle(
129+
"Peck-Carson",
130+
"Sun Hybrid",
131+
new BigDecimal(9874.95),
132+
"With its comfortable aluminum frame and 25 gears, this bicycle is" +
133+
" perfect for any terrain. The Peck-Carson Sun Hybrid provides a" +
134+
" comfortable ride.",
135+
"new"
136+
),
137+
new Bicycle(
138+
"Fowler Ltd",
139+
"Weekend Trail",
140+
new BigDecimal(3833.71),
141+
"The Fowler Ltd Letter Trail is a comfortable choice for" +
142+
" transporting cargo. This cargo bike is perfect for transporting" +
143+
" cargo.",
144+
"refurbished"
145+
)
146+
};
147+
148+
// STEP_START define_index
149+
SchemaField[] schema = {
150+
TextField.of("$.brand").as("brand"),
151+
TextField.of("$.model").as("model"),
152+
TextField.of("$.description").as("description"),
153+
NumericField.of("$.price").as("price"),
154+
TagField.of("$.condition").as("condition")
155+
};
156+
// STEP_END
157+
158+
// STEP_START create_index
159+
jedis.ftCreate("idx:bicycle",
160+
FTCreateParams.createParams()
161+
.on(IndexDataType.JSON)
162+
.addPrefix("bicycle:"),
163+
schema
164+
);
165+
// STEP_END
166+
// STEP_START add_documents
167+
for (int i = 0; i < bicycles.length; i++) {
168+
jedis.jsonSetWithEscape(String.format("bicycle:%d", i), bicycles[i]);
169+
}
170+
// STEP_END
171+
172+
// STEP_START query_single_term_and_num_range
173+
Query query = new Query("folding @price:[1000 4000]");
174+
List<Document> result = jedis.ftSearch("idx:bicycle", query).getDocuments();
175+
System.out.println(result);
176+
// Prints: [id:bicycle:6, score: 1.0, payload:null, properties:[
177+
// $={"brand":"Moore PLC","model":"Award Race","price":3790.76,
178+
// "description":"This olive folding bike features a carbon frame and 27.5 inch wheels.
179+
// This folding bike is perfect for compact storage and transportation.","condition":"new"}]
180+
// ]
181+
// STEP_END
182+
// REMOVE_START
183+
assertEquals("Validate folding bike id", "bicycle:6", result.get(0).getId());
184+
// REMOVE_END
185+
186+
// STEP_START query_single_term_limit_fields
187+
Query cargo_query = new Query("cargo").returnFields("price");
188+
List<Document> cargo_result = jedis.ftSearch(
189+
"idx:bicycle", cargo_query).getDocuments();
190+
System.out.println(cargo_result);
191+
// Prints: [id:bicycle:9, score: 1.0, payload:null, properties:[price=3833.71]]
192+
// STEP_END
193+
// REMOVE_START
194+
assertEquals("Validate cargo bike id", "bicycle:9", cargo_result.get(0).getId());
195+
// REMOVE_END
196+
197+
// STEP_START simple_aggregation
198+
AggregationBuilder ab = new AggregationBuilder("*")
199+
.groupBy("@condition", Reducers.count().as("count"));
200+
AggregationResult ar = jedis.ftAggregate("idx:bicycle", ab);
201+
202+
for (int i = 0; i < ar.getTotalResults(); i++) {
203+
System.out.println(
204+
ar.getRow(i).getString("condition")
205+
+ " - "
206+
+ ar.getRow(i).getString("count"));
207+
}
208+
// Prints:
209+
// refurbished - 1
210+
// used - 5
211+
// new - 4
212+
// STEP_END
213+
// REMOVE_START
214+
assertEquals("Validate aggregation results", 3, ar.getTotalResults());
215+
// REMOVE_END
216+
}
217+
}
218+
//HIDE_END

‎src/test/java/io/redis/examples/SetGetExample.java‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
//EXAMPLE: set_and_get
2+
//HIDE_START
3+
package io.redis.examples;
4+
5+
import redis.clients.jedis.UnifiedJedis;
6+
//REMOVE_START
7+
import org.junit.Test;
8+
import static org.junit.Assert.assertEquals;
9+
//REMOVE_END
10+
11+
public class SetGetExample {
12+
13+
@Test
14+
public void run() {
15+
16+
UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379");
17+
18+
//HIDE_END
19+
String status = jedis.set("bike:1", "Process 134");
20+
21+
if ("OK".equals(status))
22+
System.out.println("Successfully added a bike.");
23+
24+
String value = jedis.get("bike:1");
25+
26+
if ( value != null)
27+
System.out.println("The name of the bike is: " + value + ".");
28+
//HIDE_START
29+
30+
//REMOVE_START
31+
assertEquals("OK", status);
32+
assertEquals("Process 134", value);
33+
//REMOVE_END
34+
}
35+
}
36+
//HIDE_END

‎src/test/java/redis/clients/jedis/examples/RedisCredentialsProviderExample.java‎ renamed to ‎src/test/java/redis/clients/jedis/examples/RedisCredentialsProviderUsage.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
import redis.clients.jedis.HostAndPort;
77
import redis.clients.jedis.JedisPooled;
88

9-
public class RedisCredentialsProviderExample {
9+
public class RedisCredentialsProviderUsage {
1010

1111
public static void main(String[] args) {
1212

0 commit comments

Comments
 (0)