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

Migrate documentation to Antora.

Browse Source 
Closes: #526
This commit is contained in:
Christoph Strobl
2023-09-08 13:25:48 +02:00
parent 3e22ff066b
commit 28b6260941
27 changed files with 246 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -8,3 +8,7 @@ target/
*.ipr
*.iws
/.idea/
node_modules
node
package.json
package-lock.json

4
README.adoc
View File

@@ -139,10 +139,10 @@ Building the documentation builds also the project without running tests.
[source,bash]
----
$ ./mvnw clean install -Pdistribute
$ ./mvnw clean install -Pantora
----
The generated documentation is available from `target/site/reference/html/index.html`.
The generated documentation is available from `target/antora/site/data-keyvalue/index.html`.
== Examples

29
pom.xml
View File

@@ -82,6 +82,35 @@
</plugins>
</build>
<profiles>
<profile>
<!-- placeholder for no profile -->
<id>none</id>
</profile>
<profile>
<id>antora-process-resources</id>
<build>
<resources>
<resource>
<directory>src/main/antora/resources/antora-resources</directory>
<filtering>true</filtering>
</resource>
</resources>
</build>
</profile>
<profile>
<id>antora</id>
<build>
<plugins>
<plugin>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</profile>
</profiles>
<repositories>
<repository>
<id>spring-snapshot</id>

42
src/main/antora/antora-playbook.yml Normal file
View File

@@ -0,0 +1,42 @@
# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2
#
# The purpose of this Antora playbook is to build the docs in the current branch.
antora:
extensions:
- '@antora/collector-extension'
- require: '@springio/antora-extensions/root-component-extension'
root_component_name: 'data-redis'
site:
title: Spring Data KeyValue
url: https://docs.spring.io/spring-data-keyvalue/reference/
content:
sources:
- url: ./../../..
branches: HEAD
start_path: src/main/antora
worktrees: true
- url: https://github.com/spring-projects/spring-data-commons
# Refname matching:
# https://docs.antora.org/antora/latest/playbook/content-refname-matching/
branches: [ main, 3.2.x ]
start_path: src/main/antora
asciidoc:
attributes:
page-pagination: ''
hide-uri-scheme: '@'
tabs-sync-option: '@'
chomp: 'all'
extensions:
- '@asciidoctor/tabs'
- '@springio/asciidoctor-extensions'
sourcemap: true
urls:
latest_version_segment: ''
runtime:
log:
failure_level: warn
format: pretty
ui:
bundle:
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip
snapshot: true

12
src/main/antora/antora.yml Normal file
View File

@@ -0,0 +1,12 @@
name: data-keyvalue
version: true
title: Spring Data KeyValue
nav:
- modules/ROOT/nav.adoc
ext:
collector:
- run:
command: ./mvnw validate process-resources -Pantora-process-resources
local: true
scan:
dir: target/classes/

13
src/main/antora/modules/ROOT/nav.adoc Normal file
View File

@@ -0,0 +1,13 @@
* xref:index.adoc[]
* xref:keyvalue.adoc[]
** xref:keyvalue/template.adoc[]
* xref:repositories.adoc[]
** xref:repositories/core-concepts.adoc[]
** xref:repositories/definition.adoc[]
** xref:repositories/create-instances.adoc[]
** xref:keyvalue/repository/map-repositories.adoc[]
** xref:repositories/query-keywords-reference.adoc[]
** xref:repositories/query-return-types-reference.adoc[]
* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

5
src/main/antora/modules/ROOT/pages/commons/upgrade.adoc Normal file
View File

@@ -0,0 +1,5 @@
include::{commons}@data-commons::page$upgrade.adoc[]
Once you’ve decided to upgrade your application, you can find detailed information regarding specific features in the rest of the document.
Spring Data's documentation is specific to that version, so any information that you find in here will contain the most up-to-date changes that are in that version.

19
src/main/antora/modules/ROOT/pages/index.adoc Normal file
View File

@@ -0,0 +1,19 @@
[[spring-data-key-value-reference-guide]]
= Spring Data Key-Value
:revnumber: {version}
:revdate: {localdate}
:feature-scroll: true
Spring Data KeyValue provides connectivity and repository support for the in memory map structures.
It eases development of applications with a consistent programming model that need to access key based storage and servers as foundation for custom adapters._
[horizontal]
xref:keyvalue.adoc[Key/Value Storage] :: Support for built in key-value structures
xref:repositories.adoc[Repositories] :: KeyValue Repositories
https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information.
Oliver Gierke; Thomas Darimont; Christoph Strobl; Jay Bryant; Mark Paluch
(C) 2008-{copyright-year} VMware, Inc.
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

46
src/main/antora/modules/ROOT/pages/keyvalue.adoc Normal file
View File

@@ -0,0 +1,46 @@
[[key-value]]
= KeyValue
Spring Data KeyValue provides easy configuration and access to `Map` like structures that associate values with unique keys.
It offers both low-level and high-level abstractions for interacting with the underlying data structure, freeing the user from infrastructural concerns.
The key-value abstraction within Spring Data Key Value requires an `Adapter` that shields the native store implementation, freeing up `KeyValueTemplate` to work on top of any key-value pair-like structure.
Keys are distributed across <<key-value.keyspaces,Keyspaces>>.
Unless otherwise specified, the class name is used as the default keyspace for an entity.
The following interface definition shows the `KeyValueOperations` interface, which is the heart of Spring Data Key-Value:
====
[source, java]
----
interface KeyValueOperations {
<T> T insert(T objectToInsert); <1>
void update(Object objectToUpdate); <2>
void delete(Class<?> type); <3>
<T> T findById(Object id, Class<T> type); <4>
<T> Iterable<T> findAllOf(Class<T> type); <5>
<T> Iterable<T> find(KeyValueQuery<?> query, Class<T> type); <6>
//... more functionality omitted.
}
----
<1> Inserts the given entity and assigns an ID (if required).
<2> Updates the given entity.
<3> Removes all entities of the matching type.
<4> Returns the entity of the given type with its matching ID.
<5> Returns all entities of the matching type.
<6> Returns a `List` of all entities of the given type that match the criteria of the query.
====
[[key-value.keyspaces]]
== Keyspaces
Keyspaces define the part of the data structure in which the entity should be kept.
This concept is similar to collections in MongoDB and Elasticsearch, cores in Solr, and tables in JPA.
By default, the keyspace of an entity is extracted from its type, but you can also store entities of different types within one keyspace.

18
src/main/antora/modules/ROOT/pages/keyvalue/repository/map-repositories.adoc Normal file
View File

@@ -0,0 +1,18 @@
[[key-value.repositories.map]]
= Map Repositories
Map repositories reside on top of the `KeyValueTemplate`.
Using the default `SpelQueryCreator` allows deriving query and sort expressions from the given method name, as the following example shows:
[source, java]
----
@Configuration
@EnableMapRepositories
class KeyValueConfig {
}
interface PersonRepository implements CrudRepository<Person, String> {
List<Person> findByLastname(String lastname);
}
----

74
src/main/asciidoc/key-value-repositories.adoc → src/main/antora/modules/ROOT/pages/keyvalue/template.adoc
View File

@@ -1,57 +1,16 @@
:spring-framework-docs: https://docs.spring.io/spring-framework/docs/{springVersion}/spring-framework-reference/
[[key-value]]
= Key-Value Repositories
This chapter explains concepts and usage patterns you need to know when working with the key-value abstraction and the `java.util.Map` based implementation provided by Spring Data Key Value.
[[key-value.core-concepts]]
== Core Concepts
The key-value abstraction within Spring Data Key Value requires an `Adapter` that shields the native store implementation, freeing up `KeyValueTemplate` to work on top of any key-value pair-like structure. Keys are distributed across <<key-value.keyspaces>>. Unless otherwise specified, the class name is used as the default keyspace for an entity. The following interface definition shows the `KeyValueOperations` interface, which is the heart of Spring Data Key-Value:
====
[source, java]
----
interface KeyValueOperations {
<T> T insert(T objectToInsert); <1>
void update(Object objectToUpdate); <2>
void delete(Class<?> type); <3>
<T> T findById(Object id, Class<T> type); <4>
<T> Iterable<T> findAllOf(Class<T> type); <5>
<T> Iterable<T> find(KeyValueQuery<?> query, Class<T> type); <6>
//... more functionality omitted.
}
----
<1> Inserts the given entity and assigns an ID (if required).
<2> Updates the given entity.
<3> Removes all entities of the matching type.
<4> Returns the entity of the given type with its matching ID.
<5> Returns all entities of the matching type.
<6> Returns a `List` of all entities of the given type that match the criteria of the query.
====
[[key-value.template-configuration]]
== Configuring The `KeyValueTemplate`
[[key-value.template]]
= KeyValueTemplate
In its very basic shape, the `KeyValueTemplate` uses a `MapAdapter` that wraps a `ConcurrentHashMap` and that uses link:{spring-framework-docs}core.html#expressions[Spring Expression Language] to run queries and sorting.
NOTE: The used `KeyValueAdapter` does the heavy lifting when it comes to storing and retrieving data. The data structure influences performance and multi-threading behavior.
NOTE: The used `KeyValueAdapter` does the heavy lifting when it comes to storing and retrieving data.
The data structure influences performance and multi-threading behavior.
You can use a different type or pre-initialize the adapter with some values, and you can do so by using various constructors on `MapKeyValueAdapter`, as the following example shows:
====
[source, java]
----
@EnableMapRepositories
@Configuration
class MyConfiguration {
@@ -66,15 +25,14 @@ class MyConfiguration {
}
}
----
<1> Defines a custom `KeyValueOperations` bean using the default bean name. See documentation and properties of {spring-data-keyvalue-docs}org/springframework/data/map/repository/config/EnableMapRepositories.html[`@EnableMapRepositories`] for further customization.
<1> Defines a custom `KeyValueOperations` bean using the default bean name. See documentation and properties of `@EnableMapRepositories` for further customization.
<2> Defines a custom `KeyValueAdapter` bean using a `ConcurrentHashMap` as storage that is used by `KeyValueTemplate`.
====
[[key-value.keyspaces]]
== Keyspaces
Keyspaces define the part of the data structure in which the entity should be kept.This concept is similar to collections in MongoDB and Elasticsearch, cores in Solr, and tables in JPA.
By default, the keyspace of an entity is extracted from its type, but you can also store entities of different types within one keyspace.In that case, any find operation type-checks the results.The following example shows a keyspace for a repository of `Person` objects:
The following example shows a keyspace for a repository of `Person` objects:
====
[source, java]
@@ -100,8 +58,6 @@ template.findAllOf(User.class); <2>
TIP: `@KeySpace` supports https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#expressions[SpEL] expressions allowing dynamic keyspace configuration.
5.2.0.M3
[[key-value.keyspaces-custom]]
=== Custom KeySpace Annotation
@@ -169,21 +125,3 @@ List<Person> targaryens = template.find(query, Person.class);
====
IMPORTANT: Please note that you need to have getters and setters present to sort using SpEL.
[[key-value.repositories.map]]
== Map Repositories
Map repositories reside on top of the `KeyValueTemplate`. Using the default `SpelQueryCreator` allows deriving query and sort expressions from the given method name, as the following example shows:
[source, java]
----
@Configuration
@EnableMapRepositories
class KeyValueConfig {
}
interface PersonRepository implements CrudRepository<Person, String> {
List<Person> findByLastname(String lastname);
}
----

8
src/main/antora/modules/ROOT/pages/repositories.adoc Normal file
View File

@@ -0,0 +1,8 @@
[[keyvalyue.repositories]]
= KeyValue Repositories
This chapter explains the basic foundations of Spring Data repositories and KeyValue specifics.
Before continuing to the specifics, make sure you have a sound understanding of the basic concepts.
The goal of the Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores.

4
src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc Normal file
View File

@@ -0,0 +1,4 @@
include::{commons}@data-commons::page$repositories/core-concepts.adoc[]
[[redis.entity-persistence.state-detection-strategies]]
include::{commons}@data-commons::page$is-new-state-detection.adoc[leveloffset=+1]

1
src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/core-domain-events.adoc[]

4
src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc Normal file
View File

@@ -0,0 +1,4 @@
[[core.extensions.querydsl]]
= Querydsl
Spring Data Redis does not support Querydsl.

1
src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/create-instances.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/custom-implementations.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/definition.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/definition.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/null-handling.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/object-mapping.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$object-mapping.adoc[]

4
src/main/antora/modules/ROOT/pages/repositories/projections.adoc Normal file
View File

@@ -0,0 +1,4 @@
[[cassandra.projections]]
= Projections
include::{commons}@data-commons::page$repositories/projections.adoc[leveloffset=+1]

1
src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-keywords-reference.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-methods-details.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-return-types-reference.adoc[]

21
src/main/antora/resources/antora-resources/antora.yml Normal file
View File

@@ -0,0 +1,21 @@
version: ${antora-component.version}
prerelease: ${antora-component.prerelease}
asciidoc:
attributes:
copyright-year: 2023
version: ${project.version}
springversionshort: ${spring.short}
springversion: ${spring}
attribute-missing: 'warn'
commons: ${springdata.commons.docs}
include-xml-namespaces: false
spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference
spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/${springdata.commons}/api/
springdocsurl: https://docs.spring.io/spring-framework/reference/{springversionshort}
springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api
spring-framework-docs: '{springdocsurl}'
spring-framework-javadoc: '{springjavadocurl}'
springhateoasversion: ${spring-hateoas}
releasetrainversion: ${releasetrain}
store: KeyValue

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

@@ -1,29 +0,0 @@
= Spring Data Key-Value Reference Guide
Oliver Gierke; Thomas Darimont; Christoph Strobl; Jay Bryant; Mark Paluch
:revnumber: {version}
:revdate: {localdate}
ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
:spring-data-commons-docs: https://raw.githubusercontent.com/spring-projects/spring-data-commons/master/src/main/asciidoc
:spring-data-keyvalue-docs: https://docs.spring.io/spring-data/keyvalue/docs/{version}/api/
:spring-framework-docs: https://docs.spring.io/spring-framework/docs/{springVersion}/spring-framework-reference/
(C) 2008-2022 The original authors.
NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
include::preface.adoc[]
include::{spring-data-commons-docs}/repositories.adoc[leveloffset=+1]
[[reference]]
= Reference Documentation
include::key-value-repositories.adoc[leveloffset=+1]
[[appendix]]
= Appendix
:numbered!:
include::{spring-data-commons-docs}/repository-namespace-reference.adoc[leveloffset=+1]
include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[leveloffset=+1]
include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[leveloffset=+1]

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

@@ -1,11 +0,0 @@
[[preface]]
= Preface
[[project]]
== Project Metadata
* Version control: https://github.com/spring-projects/spring-data-keyvalue
* Bugtracker: https://github.com/spring-projects/spring-data-keyvalue/issues
* Release repository: https://repo1.maven.org/maven2/
* Milestone repository: https://repo.spring.io/milestone
* Snapshot repository: https://repo.spring.io/snapshot