From 71169ca160fa2398961f74821603e01d874add03 Mon Sep 17 00:00:00 2001 From: Thomas Darimont Date: Thu, 20 Feb 2014 16:43:05 +0100 Subject: [PATCH] DATACMNS-445 - Documentation overhaul. Updated links and vendor-information in readme. Updated author information. Fixed some typos, added ids to sections updated examples and descriptions. Added and referenced description of repository populator namespace element. Original pull request: #65. --- readme.md | 10 +- src/docbkx/index.xml | 8 + src/docbkx/preface.xml | 5 +- src/docbkx/repositories.xml | 148 ++++++++++-------- src/docbkx/repository-namespace-reference.xml | 15 ++ ...pository-populator-namespace-reference.xml | 43 +++++ template.mf | 2 +- 7 files changed, 160 insertions(+), 71 deletions(-) create mode 100644 src/docbkx/repository-populator-namespace-reference.xml diff --git a/readme.md b/readme.md index 790aa2628..03c931373 100644 --- a/readme.md +++ b/readme.md @@ -1,6 +1,6 @@ # Spring Data Commons # -[Spring Data Commons](http://www.springsource.org/spring-data/commons) is part of the umbrella Spring Data project that provides shared infrastructure across the Spring Data projects. +[Spring Data Commons](http://projects.spring.io/spring-data/) is part of the umbrella Spring Data project that provides shared infrastructure across the Spring Data projects. Most importantly at the moment it contains technology neutral repository interfaces as well as a metadata model for persisting Java classes. ## Features ## @@ -15,20 +15,20 @@ Most importantly at the moment it contains technology neutral repository interfa ## Getting Help ## -This README as well as the [reference documentation](http://static.springsource.org/spring-data/data-commons/snapshot-site/reference/html/) are the best places to start learning about Spring Data Commons. +This README as well as the [reference documentation](http://docs.spring.io/spring-data/data-commons/docs/current/reference/html/) are the best places to start learning about Spring Data Commons. The main project [website](http://www.springsource.org/spring-data) contains links to basic project information such as source code, JavaDocs, Issue tracking, etc. -For more detailed questions, use the [forum](http://forum.springsource.org/forumdisplay.php?f=27). If you are new to Spring as well as to Spring Data, look for information about [Spring projects](http://www.springsource.org/projects). +For more detailed questions, use the [forum](http://forum.spring.io/forum/spring-projects/data). If you are new to Spring as well as to Spring Data, look for information about [Spring projects](https://spring.io/projects). ## Contributing to Spring Data Commons## Here are some ways for you to get involved in the community: -* Get involved with the Spring community on the Spring Community Forums. Please help out on the [forum](http://forum.springsource.org/forumdisplay.php?f=27) by responding to questions and joining the debate. +* Get involved with the Spring community on the Spring Community Forums. Please help out on the [forum](http://forum.spring.io/forum/spring-projects/data) by responding to questions and joining the debate. * Create [JIRA](https://jira.springsource.org/browse/DATACMNS) tickets for bugs and new features and comment and vote on the ones that you are interested in. * Github is for social coding: if you want to write code, we encourage contributions through pull requests from [forks of this repository](http://help.github.com/forking/). If you want to contribute code this way, please reference a JIRA ticket as well covering the specific issue you are addressing. -* Watch for upcoming articles on Spring by [subscribing](http://www.springsource.org/node/feed) to springframework.org +* Watch for upcoming articles on Spring by [subscribing](https://spring.io/blog.atom) to springframework.org Before we accept a non-trivial patch or pull request we will need you to sign the [contributor's agreement](https://support.springsource.com/spring_committer_signup). Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join the core team, and given the ability to merge pull requests. diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index 318d9312e..7128fd9f2 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -19,6 +19,14 @@ Oliver Gierke + + Thomas + Darimont + + + Christoph + Strobl + diff --git a/src/docbkx/preface.xml b/src/docbkx/preface.xml index bfe4eca6a..9314573e5 100644 --- a/src/docbkx/preface.xml +++ b/src/docbkx/preface.xml @@ -4,6 +4,7 @@ Preface - The Spring Data Commons project applies core Spring concepts to the development of solutions using many non-relational data stores. - + The Spring Data Commons project applies core Spring concepts to the + development of solutions using many relational and non-relational data + stores. diff --git a/src/docbkx/repositories.xml b/src/docbkx/repositories.xml index d5ca76e90..2048e3c99 100644 --- a/src/docbkx/repositories.xml +++ b/src/docbkx/repositories.xml @@ -2,7 +2,7 @@ - lWorking with Spring Data Repositories + Working with Spring Data Repositories The goal of Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access @@ -20,9 +20,9 @@ that you are using. covers XML configuration which is supported across all Spring Data modules supporting the repository API, covers the - query method method keywords supported by the repository abstraction in - general. For detailed information on the specific features of your module, - consult the chapter on that module of this document. + query method keywords supported by the repository abstraction in general. + For detailed information on the specific features of your module, consult + the chapter on that module of this document.
@@ -30,8 +30,8 @@ The central interface in Spring Data repository abstraction is Repository (probably not that much of a - surprise). It takes the the domain class to manage as well as the id type - of the domain class as type arguments. This interface acts primarily as a + surprise). It takes the domain class to manage as well as the id type of + the domain class as type arguments. This interface acts primarily as a marker interface to capture the types to work with and to help you to discover interfaces that extend this one. The CrudRepository provides sophisticated CRUD @@ -101,13 +101,15 @@ - Usually we will have persistence technology specific sub-interfaces - to include additional technology specific methods. We will now ship - implementations for a variety of Spring Data modules that implement - CrudRepository. - - + + We also provide persistence technology-specific abstractions like + e.g. JpaRepository or + MongoRepository. Those interfaces extend + CrudRepository and expose the + capabilities of the underlying persistence technology in addition to the + rather generic persistence technology-agnostic interfaces like e.g. + CrudRepository. + On top of the CrudRepository there is a PagingAndSortingRepository abstraction @@ -143,7 +145,8 @@ Page<User> users = repository.findAll(new PageRequest(1, 20)); Declare an interface extending Repository or one of its subinterfaces - and type it to the domain class that it will handle. + and type it to the domain class and ID type that it will + handle. public interface PersonRepository extends Repository<User, Long> { … } @@ -155,29 +158,36 @@ Page<User> users = repository.findAll(new PageRequest(1, 20)); - Set up Spring to create proxy instances for those - interfaces. + Set up Spring to create proxy instances for those interfaces. + Either via JavaConfig: + + import org.springframework.data.jpa.repository.config.EnableJpaRepositories; + +@EnableJpaRepositories +class Config {} + + or via XML + configuration: <?xml version="1.0" encoding="UTF-8"?> -<beans:beans xmlns:beans="http://www.springframework.org/schema/beans" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xmlns="http://www.springframework.org/schema/data/jpa" - xsi:schemaLocation="http://www.springframework.org/schema/beans - http://www.springframework.org/schema/beans/spring-beans.xsd - http://www.springframework.org/schema/data/jpa - http://www.springframework.org/schema/data/jpa/spring-jpa.xsd"> +<beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:jpa="http://www.springframework.org/schema/data/jpa" + xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/data/jpa http://www.springframework.org/schema/data/jpa/spring-jpa.xsd"> - <repositories base-package="com.acme.repositories" /> + <jpa:repositories base-package="com.acme.repositories"/> </beans> - - The JPA namespace is used in this example. If you are using - the repository abstraction for any other store, you need to change - this to the appropriate namespace declaration of your store module - which should be exchanging jpa in favor of, for - example, mongodb. - + The JPA namespace is used in this example. If you are using the + repository abstraction for any other store, you need to change this to + the appropriate namespace declaration of your store module which + should be exchanging jpa in favor of, for example, + mongodb. Also, note that the JavaConfig variant doesn't + configure a package explictly as the package of the annotated class is + used by default. To customize the package to scan @@ -223,6 +233,11 @@ Page<User> users = repository.findAll(new PageRequest(1, 20));CrudRepository into your domain repository. + + This allows you to define your own abstractions on top of the + provided Spring Data Repositories functionality. + + Selectively exposing CRUD methods @@ -245,7 +260,9 @@ interface UserRepository extends MyBaseRepository<User, Long> { findOne(…) as well as save(…).These methods will be routed into the base repository implementation of the store of your choice provided by - Spring Data because they are matching the method signatures in + Spring Data ,e.g. in the case if JPA + SimpleJpaRepository, because they are matching + the method signatures in CrudRepository. So the UserRepository will now be able to save users, and find single ones by id, as well as triggering a query to @@ -266,7 +283,7 @@ interface UserRepository extends MyBaseRepository<User, Long> { The repository proxy has two ways to derive a store-specific query from the method name. It can derive the query from the method name - directly, or by using an additionally created query. Available options + directly, or by using an manually defined query. Available options depend on the actual store. However, there's got to be an strategy that decides what actual query is created. Let's have a look at the available options. @@ -276,8 +293,11 @@ interface UserRepository extends MyBaseRepository<User, Long> { The following strategies are available for the repository infrastructure to resolve the query. You can configure the strategy at - the namespace through the query-lookup-strategy - attribute. Some strategies may not be supported for particular + the namespace through the query-lookup-strategy attribute + in case of XML configuration or via the + queryLookupStrategy attribute of the + Enable${store}Repositories annotation in case + of Java config. Some strategies may not be supported for particular datastores. @@ -321,14 +341,14 @@ interface UserRepository extends MyBaseRepository<User, Long> { The query builder mechanism built into Spring Data repository infrastructure is useful for building constraining queries over entities of the repository. The mechanism strips the prefixes - find…By, read…By, query…By, and get…By - from the method and starts parsing the rest of it. The introducing - clause can contain further expressions such as a Distinct - to set a distinct flag on the query to be created. However, the first - By acts as delimiter to indicate the start of the actual - criteria. At a very basic level you can define conditions on entity - properties and concatenate them with And and Or - . + find…By, read…By, query…By, + count…By, and get…By from the method and + starts parsing the rest of it. The introducing clause can contain + further expressions such as a Distinct to set a distinct + flag on the query to be created. However, the first By + acts as delimiter to indicate the start of the actual criteria. At a + very basic level you can define conditions on entity properties and + concatenate them with And and Or. Query creation from method names @@ -390,7 +410,7 @@ interface UserRepository extends MyBaseRepository<User, Long> {
-
+
Property expressions Property expressions can refer only to a direct property of the @@ -441,7 +461,7 @@ OG Does that make sense with my comment above?-->To resolve this ambiguity you
Special parameter handling - To handle parameters to your query you simply define method + To handle parameters in your query you simply define method parameters as already seen in the examples above. Besides that the infrastructure will recognize certain specific types like Pageable and @@ -485,9 +505,10 @@ List<User> findByLastname(String lastname, Pageable pageable);Creating repository instances In this section you create instances and bean definitions for the - repository interfaces defined. The easiest way to do so is by using the - Spring namespace that is shipped with each Spring Data module that - supports the repository mechanism. + repository interfaces defined. One way to do so is using the Spring + namespace that is shipped with each Spring Data module that supports the + repository mechanism although we generally recommend to use the + Java-Config style configuration.
XML configuration @@ -520,7 +541,7 @@ List<User> findByLastname(String lastname, Pageable pageable);UserRepository would be registered under userRepository. The base-package attribute allows wildcards, so that you can - have a pattern of scanned packages. + define a pattern of scanned packages. Using filters @@ -599,10 +620,10 @@ class ApplicationConfiguration { Standalone usage You can also use the repository infrastructure outside of a - Spring container. You still need some Spring libraries in your - classpath, but generally you can set up repositories programmatically - as well. The Spring Data modules that provide repository support ship - a persistence technology-specific + Spring container, e.g. in CDI environments. You still need some Spring + libraries in your classpath, but generally you can set up repositories + programmatically as well. The Spring Data modules that provide + repository support ship a persistence technology-specific RepositoryFactory that you can use as follows. @@ -651,8 +672,9 @@ UserRepository repository = factory.getRepository(UserRepository.class); The implementation itself does not depend on Spring Data and can be a regular Spring bean. So you can use standard dependency - injection behavior to inject references to other beans, take part - in aspects, and so on. + injection behavior to inject references to other beans like a + JdbTemplate, take part in aspects, and so + on. @@ -663,8 +685,8 @@ UserRepository repository = factory.getRepository(UserRepository.class);Let your standard repository interface extend the custom - one. Doing so makes CRUD and custom functionality available to - clients. + one. Doing so combines the CRUD and custom functionality and makes it + available to clients. @@ -688,8 +710,8 @@ UserRepository repository = factory.getRepository(UserRepository.class);The first configuration example will try to look up a class com.acme.repository.UserRepositoryImpl to act - as custom repository implementation, where the second example will try - to lookup + as custom repository implementation, whereas the second example will + try to lookup com.acme.repository.UserRepositoryFooBar. @@ -1074,7 +1096,7 @@ public class UserController {
-
+
Hypermedia support for Pageables Spring HATEOAS ships with a representation model class @@ -1163,7 +1185,7 @@ class PersonController {
-
+
Repository populators If you work with the Spring JDBC module, you probably are familiar @@ -1211,8 +1233,8 @@ class PersonController { </beans> - This declaration causes the data.json file - being read, deserialized by a Jackson + This declaration causes the data.json file to + be read and deserialized via a Jackson ObjectMapper.