diff --git a/src/docbkx/repositories.xml b/src/docbkx/repositories.xml index 64fbcdb31..a6e6c4541 100644 --- a/src/docbkx/repositories.xml +++ b/src/docbkx/repositories.xml @@ -9,7 +9,7 @@ Implementing a data access layer of an application has been cumbersome for quite a while. Too much boilerplate code had to be written. - Domain classes were anemic and haven't been designed in a real object + Domain classes were anemic and not designed in a real object oriented or domain driven manner. Using both of these technologies makes developers life a lot easier @@ -30,10 +30,10 @@ Repository (probably not that much of a surprise). It is typeable to the domain class to manage as well as the id type of the domain class. This interface mainly acts as marker interface - to capture the types to deal with and helps us discovering interface that - extend this one. Beyond that there's + to capture the types to deal with and help us when discovering interfaces + that extend this one. Beyond that there's CrudRepository which provides some - sophisticated functionality around CRUD for the entity managed. + sophisticated functionality around CRUD for the entity being managed. Repository interface @@ -53,7 +53,7 @@ - public interface CrudRepository<T, ID extends Serializable> + public interface CrudRepository<T, ID extends Serializable> extends Repository<T, ID> { T save(T entity); @@ -101,7 +101,7 @@ 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 that + implementations for a variety of Spring Data modules that implement this interface. On top of the CrudRepository there is @@ -129,14 +129,14 @@ Page<User> users = repository.findAll(new PageRequest(1, 20); Query methods - Next to standard CRUD functionality repositories are usually query + Next to standard CRUD functionality repositories are usually queries on the underlying datastore. With Spring Data declaring those queries becomes - a four-step process. + a four-step process: Declare an interface extending - Repository or one of it's + Repository or one of its sub-interfaces and type it to the domain class it shall handle. public interface PersonRepository extends Repository<User, Long> { … } @@ -156,7 +156,7 @@ Page<User> users = repository.findAll(new PageRequest(1, 20);At this stage we barely scratched the surface of what's possible with the repositories but the general approach should be clear. Let's go - through each of these steps and and figure out details and various options + through each of these steps and figure out details and various options that you have at each stage.
Defining repository interfaces As a very first step you define a domain class specific repository - interface to start with. It's got to extend + interface. It's got to extend Repository and be typed to the domain class and an ID type. If you want to expose CRUD methods for that domain type, extend CrudRepository instead of @@ -206,8 +206,8 @@ Page<User> users = repository.findAll(new PageRequest(1, 20);@RepositoryDefinition. Extending CrudRepository will expose a complete - set of methods to manipulate your entities. If you rather want to be - selective about the methods being expose simply copy the ones you want + set of methods to manipulate your entities. If you would rather be + selective about the methods being exposed, simply copy the ones you want to expose from CrudRepository into your domain repository. @@ -244,19 +244,19 @@ interface UserRepository extends MyBaseRepository<User, Long> { Query lookup strategies The next thing we have to discuss is the definition of query - methods. There's roughly two main ways how the repository proxy is - generally able to come up with the store specific query from the - method name. The first option is to derive the quer from the method + methods. There are two main ways that the repository proxy is + able to come up with the store specific query from the + method name. The first option is to derive the query from the method name directly, the second is using some kind of additionally created query. What detailed options are available pretty much depends on the - actual store. However there's got to be some algorithm the decision - which actual query to is made. + actual store, however, there's got to be some algorithm that decides + what actual query is created. - There's three strategies for the repository infrastructure to + There are three strategies available for the repository infrastructure to resolve the query. The strategy to be used can be configured at the namespace through the query-lookup-strategy attribute. - However might be the case that some of the strategies are not - supported for the specific datastore. Here are your options: + However, It might be the case that some of the strategies are not + supported for specific datastores. Here are your options: CREATE @@ -273,7 +273,7 @@ interface UserRepository extends MyBaseRepository<User, Long> { This strategy tries to find a declared query which will be used for execution first. The query could be defined by an - annotation somwhere or declared by other means. Please consult the + annotation somewhere or declared by other means. Please consult the documentation of the specific store to find out what options are available for that store. If the repository infrastructure does not find a declared query for the method at bootstrap time it will @@ -283,13 +283,14 @@ interface UserRepository extends MyBaseRepository<User, Long> { CREATE_IF_NOT_FOUND (default) - This strategy is actually a combination of the both mentioned - above. It will try to lookup a declared query first but create a + This strategy is actually a combination of CREATE + and USE_DECLARED_QUERY. + It will try to lookup a declared query first but create a custom method name based query if no declared query was found. This - is default lookup strategy and thus will be used if you don't + is the default lookup strategy and thus will be used if you don't configure anything explicitly. It allows quick query definition by method names but also custom tuning of these queries by introducing - declared queries for those who need explicit tuning. + declared queries as needed.
@@ -297,7 +298,7 @@ interface UserRepository extends MyBaseRepository<User, Long> { Query creation The query builder mechanism built into Spring Data repository - infrastructue is useful to build constraining queries over entities of + infrastructure is useful to build constraining queries over entities of the repository. We will strip the prefixes findBy, find, readBy, read, getBy as well as get from the method and @@ -315,11 +316,11 @@ interface UserRepository extends MyBaseRepository<User, Long> { The actual result of parsing that method will of course depend - on the persistence store we create the query for. However there are - some general things to notice. The expression are usually property + on the persistence store we create the query for, however, there are + some general things to notice. The expressions are usually property traversals combined with operators that can be concatenated. As you can see in the example you can combine property expressions with And - and Or. Beyond that you will get support for various operators like + and Or. Beyond that you also get support for various operators like Between, LessThan, GreaterThan, Like for the property expressions. As the operators supported can vary from @@ -330,10 +331,10 @@ interface UserRepository extends MyBaseRepository<User, Long> { Property expressions Property expressions can just refer to a direct property of - the managed entity (as you just saw in the example above. On query + the managed entity (as you just saw in the example above). On query creation time we already make sure that the parsed property is at a - property of the managed domain class. However you can also traverse - nested properties to define constraints on. Assume + property of the managed domain class. However, you can also define + constraints by traversing nested properties. Assume Persons have Addresses with ZipCodes. In that case a method name of @@ -353,9 +354,9 @@ interface UserRepository extends MyBaseRepository<User, Long> { does not match we move the split point to the left (Address, ZipCode). - Now although this should work for most cases, there might be + Although this should work for most cases, there might be cases where the algorithm could select the wrong property. Suppose - our Person class has a + our Person class has an addressZip property as well. Then our algorithm would match in the first split round already and essentially choose the wrong property and finally fail (as the type of @@ -373,7 +374,7 @@ interface UserRepository extends MyBaseRepository<User, Long> { Special parameter handling To hand parameters to your query you simply define method - parameters as already seen in in examples above. Besides that we will + parameters as already seen in the examples above. Besides that we will recognizes certain specific types to apply pagination and sorting to your queries dynamically. @@ -390,7 +391,7 @@ List<User> findByLastname(String lastname, Pageable pageable);The first method allows you to pass a Pageable instance to the query method to dynamically add paging to your statically defined query. Sorting options are handed via - the Pageable instance, too. If you only + the Pageable instance too. If you only need sorting, simply add a Sort parameter to your method. As you also can see, simply returning a List is possible as well. We will then @@ -418,13 +419,13 @@ List<User> findByLastname(String lastname, Pageable pageable);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. Each of those includes a repositories element that allows - you to simply define a base packge Spring shall scan for you. + you to simply define a base package that Spring will scan for you. <?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 + 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"> @@ -434,18 +435,18 @@ List<User> findByLastname(String lastname, Pageable pageable); In this case we instruct Spring to scan - com.acme.repositories and all it's sub packages for + com.acme.repositories and all its sub packages for interfaces extending Repository or one of its sub-interfaces. For each interface found it will register the - presistence technology specific + persistence technology specific FactoryBean to create the according proxies that handle invocations of the query methods. Each of these beans will be registered under a bean name that is derived from the interface name, so an interface of UserRepository would be registered under userRepository. The base-package - attribute allows to use wildcards, so that you can have a pattern of - packages parsed. + attribute allows the use of wildcards, so that you can have a pattern of + scanned packages. Using filters @@ -454,7 +455,7 @@ List<User> findByLastname(String lastname, Pageable pageable);Repository sub-interface located underneath the configured base package and create a bean instance - for it. However, you might want to gain finer grained control over + for it. However, you might want finer grained control over which interfaces bean instances get created for. To do this we support the use of <include-filter /> and <exclude-filter /> elements inside @@ -476,7 +477,7 @@ List<User> findByLastname(String lastname, Pageable pageable); - This would exclude all interface ending on + This would exclude all interfaces ending in SomeRepository from being instantiated. @@ -502,7 +503,7 @@ List<User> findByLastname(String lastname, Pageable pageable);You can also use the repository infrastructure outside of a Spring container usage. You will still need to have some of the Spring libraries on your classpath but you can generally setup repositories - programatically as well. The Spring Data modules providing repository + programmatically as well. The Spring Data modules providing repository support ship a persistence technology specific RepositoryFactory that can be used as follows: @@ -524,7 +525,7 @@ UserRepository repository = factory.getRepository(UserRepository.class);Adding behaviour to single repositories Often it is necessary to provide a custom implementation for a few - repository methods. Spring Data repositories easily allow provide custom + repository methods. Spring Data repositories easily allow you to provide custom repository code and integrate it with generic CRUD abstraction and query method functionality. To enrich a repository with custom functionality you have to define an interface and an implementation for that @@ -549,7 +550,7 @@ UserRepository repository = factory.getRepository(UserRepository.class);Note that the implementation itself does not depend on - Spring Data and can be a regular Spring bean. So you can either use + Spring Data and can be a regular Spring bean. So you can use standard dependency injection behaviour to inject references to other beans, take part in aspects and so on. @@ -598,11 +599,11 @@ UserRepository repository = factory.getRepository(UserRepository.class);Manual wiring The approach above works perfectly well if your custom - implementation uses annotation based configuration and autowring - entirely as will be trated as any other Spring bean. If your customly - implemented bean needs some special wiring you simply declare the bean - and name it after the conventions just descibed. We will then pick up - the custom bean by name rather than creating an own instance. + implementation uses annotation based configuration and autowiring + entirely as it will be treated as any other Spring bean. If your custom + implementation bean needs some special wiring you simply declare the bean + and name it after the conventions just described. We will then pick up + the custom bean by name rather than creating an instance. Manual wiring of custom implementations (I) @@ -651,7 +652,7 @@ UserRepository repository = factory.getRepository(UserRepository.class); An interface declaring custom shared behaviour - public interface MyRepository<T, ID extends Serializable> + public interface MyRepository<T, ID extends Serializable> extends JpaRepository<T, ID> { void sharedCustomMethod(ID id); @@ -667,9 +668,9 @@ UserRepository repository = factory.getRepository(UserRepository.class); If you're using automatic repository interface detection using the Spring namespace using the interface just as is will cause Spring - trying to create an instance of + to create an instance of MyRepository. This is of course not - desired as it just acts as indermediate between + desired as it just acts as intermediary between Repository and the actual repository interfaces you want to define for each entity. To exclude an interface extending Repository from being @@ -680,17 +681,17 @@ UserRepository repository = factory.getRepository(UserRepository.class); Custom repository base class - public class MyRepositoryImpl<T, ID extends Serializable> + public class MyRepositoryImpl<T, ID extends Serializable> extends SimpleJpaRepository<T, ID> implements MyRepository<T, ID> { public void sharedCustomMethod(ID id) { // implementation goes here - } + } } The last step to get this implementation used as base class for - Spring Data repositores is replacing the standard + Spring Data repositories is replacing the standard RepositoryFactoryBean with a custom one using a custom RepositoryFactory that in turn creates instances of your MyRepositoryImpl class. @@ -698,7 +699,7 @@ UserRepository repository = factory.getRepository(UserRepository.class); Custom repository factory bean - public class MyRepositoryFactoryBean<T extends JpaRepository<?, ?> + public class MyRepositoryFactoryBean<T extends JpaRepository<?, ?> extends JpaRepositoryFactoryBean<T> { protected RepositoryFactorySupport getRepositoryFactory(…) { @@ -726,7 +727,7 @@ UserRepository repository = factory.getRepository(UserRepository.class); Using the custom factory with the namespace - <repositories base-package="com.acme.repository" + <repositories base-package="com.acme.repository" factory-class="com.acme.MyRepositoryFactoryBean" /> diff --git a/src/docbkx/repository-namespace-reference.xml b/src/docbkx/repository-namespace-reference.xml index 6190ea534..c6d3e5976 100644 --- a/src/docbkx/repository-namespace-reference.xml +++ b/src/docbkx/repository-namespace-reference.xml @@ -12,7 +12,7 @@ trigger auto detection see of repository instances. Attributes defined for - <repositories /> act are propagated to contained + <repositories /> are propagated to contained <repository /> elements but can be overridden of course.