Spring/spring-data-redis
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DATAREDIS-1101 - Refine reference documentation.

Browse Source 
Align documentation with other Spring Data modules. Consolidate preface section. Add dependency information and Redis connector feature overview.

Original Pull Request: #513
This commit is contained in:
Mark Paluch
2020-02-25 11:05:37 +01:00
committed by Christoph Strobl
parent 9b0d405fdf
commit f183086ae8
11 changed files with 252 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
pom.xml
View File

@@ -284,6 +284,12 @@
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<configuration>
<attributes>
<lettuce>${lettuce}</lettuce>
<jedis>${jedis}</jedis>
</attributes>
</configuration>
</plugin>
</plugins>

2
src/main/asciidoc/appendix/introduction.adoc
View File

@@ -1,4 +1,4 @@
[float]
[[appendix]]
= Appendix Document Structure
The appendix contains various additional detail that complements the information in the rest of the reference documentation:

11
src/main/asciidoc/index.adoc
View File

@@ -16,20 +16,13 @@ include::preface.adoc[]
include::new-features.adoc[leveloffset=+1]
[[introduction]]
= Introduction
include::introduction/introduction.adoc[leveloffset=+1]
include::introduction/why-sdr.adoc[leveloffset=+1]
include::introduction/requirements.adoc[leveloffset=+1]
include::introduction/getting-started.adoc[leveloffset=+1]
include::{spring-data-commons-docs}/dependencies.adoc[leveloffset=+1]
[[reference]]
= Reference Documentation
include::reference/introduction.adoc[leveloffset=+1]
include::reference/why-sdr.adoc[leveloffset=+1]
include::reference/redis.adoc[leveloffset=+1]
include::reference/reactive-redis.adoc[leveloffset=+1]
include::reference/redis-cluster.adoc[leveloffset=+1]

53
src/main/asciidoc/introduction/getting-started.adoc
View File

@@ -1,53 +0,0 @@
[[get-started]]
= Getting Started
This section provides an easy-to-follow guide for getting started with the Spring Data Redis module.
[[get-started:first-steps]]
== First Steps
As explained in <<why-spring-redis>>, Spring Data Redis (SDR) provides integration between the Spring framework and the Redis key-value store. Consequently, you should become acquainted with both of these frameworks. Throughout the SDR documentation, each section provides links to relevant resources. However, you should become familiar with these topics before reading this guide.
[[get-started:first-steps:spring]]
=== Learning Spring
Spring Data uses Spring framework's https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html[core] functionality, such as the https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html[IoC] container, https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#resources[resource] abstract, and the https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#aop[AOP] infrastructure. While it is not important to know the Spring APIs, understanding the concepts behind them is important. At a minimum, the idea behind IoC should be familiar. That being said, the more knowledge you have about the Spring, the faster you can pick up Spring Data Redis. In addition to the Spring Framework's comprehensive documentation, there are a lot of articles, blog entries, and books on the matter. The Spring Guides https://spring.io/guides[home page] offer a good place to start. In general, this should be the starting point for developers wanting to try Spring Data Redis.
[[get-started:first-steps:nosql]]
=== Learning NoSQL and Key Value Stores
NoSQL stores have taken the storage world by storm. It is a vast domain with a plethora of solutions, terms, and patterns (to make things worse, even the term itself has multiple https://www.google.com/search?q=nosoql+acronym[meanings]). While some of the principles are common, it is crucial that you be familiar to some degree with the stores supported by SDR. The best way to get acquainted with these solutions is to read their documentation and follow their examples. It usually does not take more then five to ten minutes to go through them and, if you come from an RDMBS-only background, many times these exercises can be eye-openers.
[[get-started:first-steps:samples]]
=== Trying out the Samples
One can find various samples for key-value stores in the dedicated Spring Data example repo, at https://github.com/spring-projects/spring-data-keyvalue-examples[https://github.com/spring-projects/spring-data-keyvalue-examples]. For Spring Data Redis, you should pay particular attention to the `retwisj` sample, a Twitter-clone built on top of Redis that can be run locally or be deployed into the cloud. See its https://docs.spring.io/spring-data/data-keyvalue/examples/retwisj/current/[documentation], the following blog https://spring.io/blog/2011/04/27/getting-started-redis-spring-cloud-foundry/[entry] for more information.
[[get-started:help]]
== Need Help?
If you encounter issues or you are just looking for advice, use one of the links below:
[[get-started:help:community]]
=== Community Support
The Spring Data tag on https://stackoverflow.com/questions/tagged/spring-data[Stack Overflow] is a message board for all Spring Data (not just Redis) users to share information and help each other. Note that registration is needed *only* for posting.
[[get-started:help:professional]]
=== Professional Support
Professional, from-the-source support, with guaranteed response time, is available from https://www.pivotal.io/[Pivotal Software, Inc.], the company behind Spring Data and Spring.
[[get-started:up-to-date]]
== Following Development
For information on the Spring Data source code repository, nightly builds, and snapshot artifacts, see the Spring Data home https://spring.io/spring-data[page].
You can help make Spring Data best serve the needs of the Spring community by interacting with developers on Stack Overflow at either
https://stackoverflow.com/questions/tagged/spring-data[spring-data] or https://stackoverflow.com/questions/tagged/spring-data-redis[spring-data-redis].
If you encounter a bug or want to suggest an improvement (including to this documentation), please create a ticket on the Spring Data issue https://jira.spring.io/browse/DATAREDIS[tracker].
To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community https://spring.io/[Portal].
Lastly, you can follow the Spring https://spring.io/blog/[blog] or the project team (https://twitter.com/SpringData[@SpringData]) on Twitter.

3
src/main/asciidoc/introduction/introduction.adoc
View File

@@ -1,3 +0,0 @@
This document is the reference guide for Spring Data Redis (SDR) Support. It explains Key-Value module concepts and semantics and the syntax for various stores namespaces.
For an introduction to key-value stores, Spring, or Spring Data examples, see <<get-started>>. This documentation refers only to Spring Data Redis Support and assumes the user is familiar with key-value storage and Spring concepts.

6
src/main/asciidoc/introduction/requirements.adoc
View File

@@ -1,6 +0,0 @@
[[requirements]]
= Requirements
Spring Data Redis 2.x binaries require JDK level 8.0 and above and https://projects.spring.io/spring-framework/[Spring Framework] {springVersion} and above.
In terms of key-value stores, https://redis.io[Redis] 2.6.x or higher is required. Spring Data Redis is currently tested against the latest 4.0 release.

2
src/main/asciidoc/new-features.adoc
View File

@@ -1,5 +1,5 @@
[[new-features]]
= New Features
= New & Noteworthy
This section briefly covers items that are new and noteworthy in the latest releases.

82
src/main/asciidoc/preface.adoc
View File

@@ -1,3 +1,83 @@
[[preface]]
= Preface
The Spring Data Redis project applies core Spring concepts to the development of solutions by using a key-value style data store. We provide a "`template`" as a high-level abstraction for sending and receiving messages. You may notice similarities to the JDBC support in the Spring Framework.
The Spring Data Redis project applies core Spring concepts to the development of solutions by using a key-value style data store.
We provide a "`template`" as a high-level abstraction for sending and receiving messages.
You may notice similarities to the JDBC support in the Spring Framework.
This section provides an easy-to-follow guide for getting started with the Spring Data Redis module.
[[get-started:first-steps:spring]]
== Learning Spring
Spring Data uses Spring framework's https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html[core] functionality, including:
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#beans[IoC] container
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#validation[type conversion system]
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#expressions[expression language]
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/integration.html#jmx[JMX integration]
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/data-access.html#dao-exceptions[DAO exception hierarchy].
While you need not know the Spring APIs, understanding the concepts behind them is important.
At a minimum, the idea behind Inversion of Control (IoC) should be familiar, and you should be familiar with whatever IoC container you choose to use.
The core functionality of the Redis support can be used directly, with no need to invoke the IoC services of the Spring Container.
This is much like `JdbcTemplate`, which can be used "'standalone'" without any other services of the Spring container.
To leverage all the features of Spring Data Redis, such as the repository support, you need to configure some parts of the library to use Spring.
To learn more about Spring, you can refer to the comprehensive documentation that explains the Spring Framework in detail.
There are a lot of articles, blog entries, and books on the subject.
See the Spring framework https://spring.io/docs[home page] for more information.
In general, this should be the starting point for developers wanting to try Spring Data Redis.
[[get-started:first-steps:nosql]]
== Learning NoSQL and Key Value Stores
NoSQL stores have taken the storage world by storm.
It is a vast domain with a plethora of solutions, terms, and patterns (to make things worse, even the term itself has multiple https://www.google.com/search?q=nosoql+acronym[meanings]).
While some of the principles are common, it is crucial that you be familiar to some degree with the stores supported by SDR. The best way to get acquainted with these solutions is to read their documentation and follow their examples.
It usually does not take more then five to ten minutes to go through them and, if you come from an RDMBS-only background, many times these exercises can be eye-openers.
[[get-started:first-steps:samples]]
=== Trying out the Samples
One can find various samples for key-value stores in the dedicated Spring Data example repo, at https://github.com/spring-projects/spring-data-keyvalue-examples[https://github.com/spring-projects/spring-data-keyvalue-examples].
For Spring Data Redis, you should pay particular attention to the `retwisj` sample, a Twitter-clone built on top of Redis that can be run locally or be deployed into the cloud.
See its https://docs.spring.io/spring-data/data-keyvalue/examples/retwisj/current/[documentation], the following blog https://spring.io/blog/2011/04/27/getting-started-redis-spring-cloud-foundry/[entry] for more information.
[[requirements]]
== Requirements
Spring Data Redis 2.x binaries require JDK level 8.0 and above and https://projects.spring.io/spring-framework/[Spring Framework] {springVersion} and above.
In terms of key-value stores, https://redis.io[Redis] 2.6.x or higher is required.
Spring Data Redis is currently tested against the latest 4.0 release.
[[get-started:help]]
== Additional Help Resources
Learning a new framework is not always straightforward.
In this section, we try to provide what we think is an easy-to-follow guide for starting with the Spring Data Redis module.
However, if you encounter issues or you need advice, feel free to use one of the following links:
[get-started:help:community]]
Community Forum :: Spring Data on https://stackoverflow.com/questions/tagged/spring-data[Stack Overflow] is a tag for all Spring Data (not just Document) users to share information and help each other.
Note that registration is needed only for posting.
[[get-started:help:professional]]
Professional Support :: Professional, from-the-source support, with guaranteed response time, is available from https://pivotal.io/[Pivotal Sofware, Inc.], the company behind Spring Data and Spring.
[[get-started:up-to-date]]
== Following Development
For information on the Spring Data source code repository, nightly builds, and snapshot artifacts, see the Spring Data home https://spring.io/spring-data[page].
You can help make Spring Data best serve the needs of the Spring community by interacting with developers on Stack Overflow at either
https://stackoverflow.com/questions/tagged/spring-data[spring-data] or https://stackoverflow.com/questions/tagged/spring-data-redis[spring-data-redis].
If you encounter a bug or want to suggest an improvement (including to this documentation), please create a ticket on the Spring Data issue https://jira.spring.io/browse/DATAREDIS[tracker].
To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community https://spring.io/[Portal].
Lastly, you can follow the Spring https://spring.io/blog/[blog] or the project team (https://twitter.com/SpringData[@SpringData]) on Twitter.

15
src/main/asciidoc/reference/introduction.adoc
View File

@@ -1,6 +1,15 @@
[float]
= Document structure
[[introduction]]
= Introduction
== Document Structure
This part of the reference documentation explains the core functionality offered by Spring Data Redis.
It explains Key-Value module concepts and semantics and the syntax for various stores namespaces.
For an introduction to key-value stores, Spring, or Spring Data examples, see <<get-started:first-steps:nosql>>.
This documentation refers only to Spring Data Redis Support and assumes the user is familiar with key-value storage and Spring concepts.
<<redis>> introduces the Redis module feature set.
"`<<redis>>`" introduces the Redis module feature set.
"`<<redis.repositories>>`" introduces the repository support for Redis.
This document is the reference guide for Spring Data Redis (SDR) Support.

153
src/main/asciidoc/reference/redis.adoc
View File

@@ -9,6 +9,53 @@ Redis is an advanced key-value store. It is similar to memcached but the dataset
Spring Data Redis provides easy configuration and access to Redis from Spring applications. It offers both low-level and high-level abstractions for interacting with the store, freeing the user from infrastructural concerns.
[[redis:setup]]
== Getting Started
An easy way to setting up a working environment is to create a Spring-based project in https://spring.io/tools/sts[STS].
First, you need to set up a running Redis server.
To create a Spring project in STS:
. Go to File -> New -> Spring Template Project -> Simple Spring Utility Project, and press Yes when prompted. Then enter a project and a package name, such as `org.spring.redis.example`.
.Add the following to the pom.xml files `dependencies` element:
+
[source,xml,subs="+attributes"]
----
<dependencies>
<!-- other dependency elements omitted -->
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-redis</artifactId>
<version>{version}</version>
</dependency>
</dependencies>
----
. Change the version of Spring in the pom.xml to be
+
[source,xml,subs="+attributes"]
----
<spring.framework.version>{springVersion}</spring.framework.version>
----
. Add the following location of the Spring Milestone repository for Maven to your `pom.xml` such that it is at the same level of your `<dependencies/>` element:
+
[source,xml]
----
<repositories>
<repository>
<id>spring-milestone</id>
<name>Spring Maven MILESTONE Repository</name>
<url>https://repo.spring.io/libs-milestone</url>
</repository>
</repositories>
----
The repository is also https://repo.spring.io/milestone/org/springframework/data/[browseable here].
[[redis:requirements]]
== Redis Requirements
@@ -37,12 +84,90 @@ NOTE: Depending on the underlying configuration, the factory can return a new co
The easiest way to work with a `RedisConnectionFactory` is to configure the appropriate connector through the IoC container and inject it into the using class.
IMPORTANT: Unfortunately, currently, not all connectors support all Redis features. When invoking a method on the Connection API that is unsupported by the underlying library, an `UnsupportedOperationException` is thrown.
Unfortunately, currently, not all connectors support all Redis features. When invoking a method on the Connection API that is unsupported by the underlying library, an `UnsupportedOperationException` is thrown. The following overview explains features that are supported by the individual Redis connectors:
[[redis:connectors:overview]]
.Feature Availability across Redis Connectors
|===
| Supported Feature | Lettuce | Jedis
| Standalone Connections
| X
| X
| <<redis:write-to-master-read-from-replica,Master/Replica Connections>>
| X
|
| <<redis:sentinel,Redis Sentinel>>
| Master Lookup, Sentinel Authentication, Replica Reads
| Master Lookup
| <<cluster,Redis Cluster>>
| Cluster Connections, Cluster Node Connections, Replica Reads
| Cluster Connections, Cluster Node Connections
| Transport Channels
| TCP, OS-native TCP (epoll, kqueue), Unix Domain Sockets
| TCP
| Connection Pooling
| X (using `commons-pool2`)
| X (using `commons-pool2`)
| Other Connection Features
| Singleton-connection sharing for non-blocking commands
| `JedisShardInfo` support
| SSL Support
| X
| X
| <<pubsub,Pub/Sub>>
| X
| X
| <<pipeline,Pipelining>>
| X
| X
| <<tx,Transactions>>
| X
| X
| Datatype support
| Key, String, List, Set, Sorted Set, Hash, Server, Stream, Scripting, Geo, HyperLogLog
| Key, String, List, Set, Sorted Set, Hash, Server, Scripting, Geo, HyperLogLog
| <<redis:reactive,Reactive (non-blocking) API>>
| X
|
|===
[[redis:connectors:lettuce]]
=== Configuring the Lettuce Connector
https://github.com/lettuce-io/lettuce-core[Lettuce] is a https://netty.io/[Netty]-based open-source connector supported by Spring Data Redis through the `org.springframework.data.redis.connection.lettuce` package. The following example shows how to create a new Lettuce connection factory:
https://github.com/lettuce-io/lettuce-core[Lettuce] is a https://netty.io/[Netty]-based open-source connector supported by Spring Data Redis through the `org.springframework.data.redis.connection.lettuce` package.
.Add the following to the pom.xml files `dependencies` element:
[source,xml,subs="+attributes"]
----
<dependencies>
<!-- other dependency elements omitted -->
<dependency>
<groupId>io.lettuce</groupId>
<artifactId>lettuce-core</artifactId>
<version>{lettuce}</version>
</dependency>
</dependencies>
----
The following example shows how to create a new Lettuce connection factory:
[source,java]
----
@@ -79,7 +204,27 @@ NOTE: Netty currently supports the epoll (Linux) and kqueue (BSD/macOS) interfac
[[redis:connectors:jedis]]
=== Configuring the Jedis Connector
https://github.com/xetorthio/jedis[Jedis] is a community-driven connector supported by the Spring Data Redis module through the `org.springframework.data.redis.connection.jedis` package. In its simplest form, the Jedis configuration looks as follow:
https://github.com/xetorthio/jedis[Jedis] is a community-driven connector supported by the Spring Data Redis module through the `org.springframework.data.redis.connection.jedis` package.
.Add the following to the pom.xml files `dependencies` element:
[source,xml,subs="+attributes"]
----
<dependencies>
<!-- other dependency elements omitted -->
<dependency>
<groupId>redis.clients</groupId>
<artifactId>jedis</artifactId>
<version>{jedis}</version>
</dependency>
</dependencies>
----
In its simplest form, the Jedis configuration looks as follow:
[source,java]
----
@@ -634,7 +779,7 @@ The following table lists the default settings for `RedisCacheManager`:
|Initial Caches
|None
|Trasaction Aware
|Transaction Aware
|No
|====

0
src/main/asciidoc/introduction/why-sdr.adoc → src/main/asciidoc/reference/why-sdr.adoc
View File