Skip to content

Latest commit

 

History

History
122 lines (87 loc) · 8.63 KB

preface.adoc

File metadata and controls

122 lines (87 loc) · 8.63 KB

Preface

The Spring Data R2DBC project applies core Spring concepts to the development of solutions that use the R2DBC drivers for relational databases. We provide a DatabaseClient as a high-level abstraction for storing and querying rows.

This document is the reference guide for Spring Data - R2DBC Support. It explains R2DBC module concepts and semantics.

This section provides some basic introduction to Spring and databases.

Learning Spring

Spring Data uses Spring framework’s {spring-framework-ref}/core.html[core] functionality, including:

  • {spring-framework-ref}/core.html#beans[IoC] container

  • {spring-framework-ref}/core.html#validation[type conversion system]

  • {spring-framework-ref}/core.html#expressions[expression language]

  • {spring-framework-ref}/integration.html#jmx[JMX integration]

  • {spring-framework-ref}/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.

You can use the core functionality of the R2DBC support 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 use all the features of Spring Data R2DBC, such as the repository support, you need to configure some parts of the library to use Spring.

To learn more about Spring, 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 home page for more information.

What is R2DBC?

R2DBC is the acronym for Reactive Relational Database Connectivity. R2DBC is an API specification initiative that declares a reactive API to be implemented by driver vendors to access their relational databases.

Part of the answer as to why R2DBC was created is the need for a non-blocking application stack to handle concurrency with a small number of threads and scale with fewer hardware resources. This need cannot be satisfied by reusing standardized relational database access APIs — namely JDBC –- as JDBC is a fully blocking API. Attempts to compensate for blocking behavior with a ThreadPool are of limited use.

The other part of the answer is that most applications use a relational database to store their data. While several NoSQL database vendors provide reactive database clients for their databases, migration to NoSQL is not an option for most projects. This was the motivation for a new common API to serve as a foundation for any non-blocking database driver. While the open source ecosystem hosts various non-blocking relational database driver implementations, each client comes with a vendor-specific API, so a generic layer on top of these libraries is not possible.

What is Reactive?

The term, “reactive”, refers to programming models that are built around reacting to change, availability, and processability-network components reacting to I/O events, UI controllers reacting to mouse events, resources being made available, and others. In that sense, non-blocking is reactive, because, instead of being blocked, we are now in the mode of reacting to notifications as operations complete or data becomes available.

There is also another important mechanism that we on the Spring team associate with reactive, and that is non-blocking back pressure. In synchronous, imperative code, blocking calls serve as a natural form of back pressure that forces the caller to wait. In non-blocking code, it becomes essential to control the rate of events so that a fast producer does not overwhelm its destination.

Reactive Streams is a small spec (also adopted in Java 9) that defines the interaction between asynchronous components with back pressure. For example, a data repository (acting as a {reactiveStreamsJavadoc}/org/reactivestreams/Publisher.html[Publisher]) can produce data that an HTTP server (acting as a {reactiveStreamsJavadoc}/org/reactivestreams/Subscriber.html`[Subscriber]) can then write to the response. The main purpose of Reactive Streams is to let the subscriber control how quickly or how slowly the publisher produces data.

Reactive API

Reactive Streams plays an important role for interoperability.It is of interest to libraries and infrastructure components but less useful as an application API, because it is too low-level. Applications need a higher-level and richer, functional API to compose async logic —- similar to the Java 8 Stream API but not only for tables. This is the role that reactive libraries play.

Project Reactor is the reactive library of choice for Spring Data R2DBC. It provides the Mono and Flux API types to work on data sequences of 0..1 (Mono) and 0..N (Flux) through a rich set of operators aligned with the ReactiveX vocabulary of operators. Reactor is a Reactive Streams library, and, therefore, all of its operators support non-blocking back pressure. Reactor has a strong focus on server-side Java. It is developed in close collaboration with Spring.

Spring Data R2DBC requires Project Reactor as a core dependency, but it is interoperable with other reactive libraries through the Reactive Streams specification. As a general rule, a Spring Data R2DBC repository accepts a plain Publisher as input, adapts it to a Reactor type internally, uses that, and returns either a Mono or a Flux as output. So, you can pass any Publisher as input and apply operations on the output, but you need to adapt the output for use with another reactive library. Whenever feasible, Spring Data adapts transparently to the use of RxJava or another reactive library.

Requirements

The Spring Data R2DBC 3.x binaries require:

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 R2DBC module. However, if you encounter issues or you need advice, use one of the following links:

Community Forum

Spring Data on Stack Overflow is a tag for all Spring Data (not just R2DBC) users to share information and help each other. Note that registration is needed only for posting.

Professional Support

Professional, from-the-source support, with guaranteed response time, is available from Pivotal Software, Inc., the company behind Spring Data and Spring.

Following Development

  • For information on the Spring Data R2DBC source code repository, nightly builds, and snapshot artifacts, see the Spring Data R2DBC home page.

  • You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the community on Stack Overflow.

  • If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data R2DBC issue tracker.

  • To stay up to date with the latest news and announcements in the Spring ecosystem, subscribe to the Spring Community Portal.

  • You can also follow the Spring blog or the Spring Data project team on Twitter (SpringData).