From 57e0e28edfdaf3b5943c2e16c2deb048aa620357 Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Mon, 4 Jun 2018 15:50:10 +0200 Subject: [PATCH] DATALDAP-75 - Full editing pass on reference documentation. Original pull request: #5. --- src/main/asciidoc/index.adoc | 3 +- src/main/asciidoc/new-features.adoc | 8 +-- src/main/asciidoc/preface.adoc | 38 +++++++------ src/main/asciidoc/reference/introduction.adoc | 9 --- .../asciidoc/reference/ldap-repositories.adoc | 57 ++++++++++--------- 5 files changed, 55 insertions(+), 60 deletions(-) delete mode 100644 src/main/asciidoc/reference/introduction.adoc diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index c1ddd28..3f15958 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -5,8 +5,7 @@ Mattias Hellborg Arthursson; Ulrik Sandberg; Eric Dalquist; Keith Barlow; Rob Wi :linkcss: :doctype: book :docinfo: shared -:toc: -:toc-placement!: +:toc: left :toclevels: 4 :source-highlighter: prettify :icons: font diff --git a/src/main/asciidoc/new-features.adoc b/src/main/asciidoc/new-features.adoc index 817f8e8..89f8e4a 100644 --- a/src/main/asciidoc/new-features.adoc +++ b/src/main/asciidoc/new-features.adoc @@ -1,14 +1,14 @@ [[new-features]] -= New & Noteworthy += New and Noteworthy [[new-features.2.1]] -== What's new in Spring Data LDAP 2.1 +== What's New in Spring Data LDAP 2.1 * CDI extension to create LDAP repositories within a CDI container. [[new-features.2.0]] -== What's new in Spring Data LDAP 2.0 +== What's New in Spring Data LDAP 2.0 * Enhanced tooling support by using Spring Framework's `@NonNullApi` and `@Nullable` annotations. [[new-features.1.0]] -== What's new in Spring Data LDAP 1.0 +== What's New in Spring Data LDAP 1.0 * Migration of Spring LDAP's repository support into Spring Data LDAP. diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index 4b0c6ab..c373ee7 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -1,43 +1,45 @@ [[preface]] = Preface -Spring Data LDAP makes it easier to build Spring-based applications that use the Lightweight Directory Access Protocol with Spring LDAP. +Spring Data LDAP makes it easier to build Spring-based applications that use the Lightweight Directory Access Protocol (LDAP). -This document is the reference guide for Spring Data - Document Support. It explains Document module concepts and semantics and the syntax for various store namespaces. +This document is the reference guide for Spring Data - Document Support. It explains Document module concepts and semantics and the syntax for various data store namespaces. [[get-started:first-steps:spring]] == Knowing Spring -Spring Data uses Spring framework's http://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/spring-core.html[core] functionality, such as the http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/beans.html[IoC] container, http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/validation.html#core-convert[type conversion system], http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/expressions.html[expression language], http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/jmx.html[JMX integration], and portable http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/dao.html#dao-exceptions[DAO exception hierarchy]. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use. +Spring Data uses Spring framework's http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html[core] functionality, including: -To learn more about Spring, you can refer to the comprehensive (and sometimes disarming) documentation that explains in detail the Spring Framework. There are a lot of articles, blog entries and books on the matter - take a look at the Spring framework http://spring.io/docs[home page ] for more information. +* http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#beans[IoC] container +* http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#core-convert[Type conversion system] +* http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#expressions[Spring Expression Language (SpEL)] +* http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/integration.html#jmx[JMX integration] +* http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/data-access.html#dao-exceptions[DAO exception hierarchy] + +While it is not important to know the Spring APIs, you do need to understand the concepts behind them. At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use. + +To learn more about Spring, you can refer to the comprehensive documentation that explains the Spring Framework in detail. You can find a lot of articles, blog entries, and books on Spring. See the Spring framework http://spring.io/docs[home page ] for more information. [[requirements]] == Requirements -Spring Data LDAP 1.x binaries requires JDK level 6.0 and above, http://spring.io/docs[Spring Framework] {springVersion} and above, and http://projects.spring.io/spring-ldap[Spring LDAP] {springLdapVersion} and above. - -== Additional Help Resources - -Learning a new framework is not always straight forward. In this section, we try to provide what we think is an easy to follow guide for starting with Spring Data LDAP module. However, if you encounter issues or you are just looking for an advice, feel free to use one of the links below: +Spring Data LDAP 1.x binaries requires JDK level 6.0 or later, http://spring.io/docs[Spring Framework] {springVersion} or later, and http://projects.spring.io/spring-ldap[Spring LDAP] {springLdapVersion} or later. [[get-started:help]] -=== Support +== Additional Help Resources -There are a few support options available: +Learning a new framework is not always straight forward. In this section, we try to provide what we think is an easy-to-follow guide for starting with the Spring Data LDAP module. However, if you encounter issues or are looking for advice, try one or more of the following resources: [[get-started:help:community]] -==== Community Forum - -Spring Data on Stackoverflow http://stackoverflow.com/questions/tagged/spring-data[Stackoverflow] 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. +Community Forum:: +Spring Data on Stackoverflow http://stackoverflow.com/questions/tagged/spring-data[Stack Overflow] is a tag for all of 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 http://pivotal.io/[Pivotal Sofware, Inc.], the company behind Spring Data and Spring. +Professional Support:: +Professional, from-the-source support, with guaranteed response time, is available from http://pivotal.io/[Pivotal Sofware, Inc.], the company behind Spring and Spring Data. [[get-started:up-to-date]] === Following Development -For information on the Spring Data LDAP source code repository, nightly builds and snapshot artifacts please see the http://projects.spring.io/spring-data-ldap/[Spring Data LDAP homepage]. You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Community on http://stackoverflow.com/questions/tagged/spring-data[Stackoverflow]. To follow developer activity look for the mailing list information on the Spring Data LDAP homepage. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue https://jira.spring.io/browse/DATALDAP[tracker]. To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community http://spring.io[Portal]. Lastly, you can follow the Spring http://spring.io/blog[blog ]or the project team on Twitter (http://twitter.com/SpringData[SpringData]). +For information on the Spring Data LDAP source code repository, nightly builds, and snapshot artifacts, see the http://projects.spring.io/spring-data-ldap/[Spring Data LDAP homepage]. You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the community on http://stackoverflow.com/questions/tagged/spring-data[Stackoverflow]. To follow developer activity, look for the mailing list information on the Spring Data LDAP homepage. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue https://jira.spring.io/browse/DATALDAP[tracker]. To stay up-to-date with the latest news and announcements in the Spring ecosystem, subscribe to the Spring Community http://spring.io[Portal]. Finally, you can follow the Spring http://spring.io/blog[blog] or the project team on Twitter (http://twitter.com/SpringData[SpringData]). diff --git a/src/main/asciidoc/reference/introduction.adoc b/src/main/asciidoc/reference/introduction.adoc deleted file mode 100644 index 2d1da13..0000000 --- a/src/main/asciidoc/reference/introduction.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[[introduction]] -= Introduction - -== Document Structure - -This part of the reference documentation explains the core functionality offered by Spring Data LDAP. - -<> introduces the repository support for LDAP. - diff --git a/src/main/asciidoc/reference/ldap-repositories.adoc b/src/main/asciidoc/reference/ldap-repositories.adoc index 8e63a6b..0654d01 100644 --- a/src/main/asciidoc/reference/ldap-repositories.adoc +++ b/src/main/asciidoc/reference/ldap-repositories.adoc @@ -1,24 +1,23 @@ [[ldap.repositories]] -= LDAP repositories += LDAP Repositories -[[ldap.repo-intro]] -== Introduction +This chapter points out the specialties for repository support for LDAP. It builds on the core repository support explained in <>. You should have a sound understanding of the basic concepts explained there. -This chapter will point out the specialties for repository support for LDAP. This builds on the core repository support explained in <>. So make sure you've got a sound understanding of the basic concepts explained there. +You should keep in mind the following points as you work with Spring LDAP repositories: -* Spring LDAP repositories can be enabled using an `` tag in your XML configuration or using an `@EnableLdapRepositories` annotation on a configuration class. +* Spring LDAP repositories can be enabled by using a `` tag in your XML configuration or by using an `@EnableLdapRepositories` annotation on a configuration class. * To include support for `LdapQuery` parameters in automatically generated repositories, have your interface extend `LdapRepository` rather than `CrudRepository`. * All Spring LDAP repositories must work with entities annotated with the ODM annotations, as described in http://docs.spring.io/spring-ldap/docs/{springLdapVersion}/reference/#odm[Object-Directory Mapping]. -* Since all ODM managed classes must have a Distinguished Name as ID, all Spring LDAP repositories must have the ID type parameter set to `javax.naming.Name`. - Indeed, the built-in `LdapRepository` only takes one type parameter; the managed entity class, defaulting ID to `javax.naming.Name`. -* Due to specifics of the LDAP protocol, paging and sorting is not supported for Spring LDAP repositories. +* Since all ODM managed classes must have a Distinguished Name as the ID, all Spring LDAP repositories must have the ID type parameter set to `javax.naming.Name`. + Indeed, the built-in `LdapRepository` only takes one type parameter: the managed entity class, which defaults the ID to `javax.naming.Name`. +* Due to specifics of the LDAP protocol, paging and sorting are not supported for Spring LDAP repositories. -NOTE: Make sure to use ODM annotations like `org.springframework.ldap.odm.annotations.Id`. Using Spring Data's annotation does not work as Spring LDAP uses its own mapping layer. +NOTE: You must use ODM annotations, such as `org.springframework.ldap.odm.annotations.Id`. Using Spring Data's annotation does not work, because Spring LDAP uses its own mapping layer. [[ldap.repo-usage]] == Usage -To access domain entities stored in a LDAP-compliant directory you can leverage our sophisticated repository support that eases implementing those quite significantly. To do so, simply create an interface for your repository: +To access domain entities stored in a LDAP-compliant directory, you can use our sophisticated repository support that significantly eases implementation. To do so, create an interface for your repository, as the following example shows: .Sample Person entity ==== @@ -37,7 +36,7 @@ public class Person { @Attribute(name="firstName") private String firstName; - // No @Attribute annotation means this will be bound to the LDAP attribute + // No @Attribute annotation means this is bound to the LDAP attribute // with the same value private String firstName; @@ -52,9 +51,9 @@ public class Person { ---- ==== -We have a quite simple domain object here. Note that it has a property named `dn` of type `Name`. +We have a simple domain object here. Note that it has a property named `dn` of type `Name`. With that domain object, we can create a repository to persist objects of that type by defining an interface for it, as follows: -.Basic repository interface to persist Person entities +.Basic repository interface to persist `Person` entities ==== [source] ---- @@ -65,7 +64,7 @@ public interface PersonRepository extends CrudRepository { ---- ==== -Right now this interface simply serves typing purposes but we will add additional methods to it later. In your Spring configuration simply add +Right now, this interface serves only typing purposes, but we can add additional methods to it later. In your Spring configuration, add the following: .General LDAP repository Spring configuration ==== @@ -95,11 +94,11 @@ Right now this interface simply serves typing purposes but we will add additiona ---- ==== -This namespace element will cause the base packages to be scanned for interfaces extending `LdapRepository` and create Spring beans for each of them found. By default the repositories will get a `LdapTemplate` Spring bean wired that is called `ldapTemplate`, so you only need to configure `ldap-template-ref` explicitly if you deviate from this convention. +This namespace element causes the base packages to be scanned for interfaces that extend `LdapRepository` and create Spring beans for each one found. By default the repositories get an autowired `LdapTemplate` Spring bean that is called `ldapTemplate`, so you only need to configure `ldap-template-ref` explicitly if you deviate from this convention. -If you'd rather like to go with JavaConfig use the `@EnableLdapRepositories` annotation. The annotation carries the very same attributes like the namespace element. If no base package is configured the infrastructure will scan the package of the annotated configuration class. +If you want to go with Java configuration, use the `@EnableLdapRepositories` annotation. The annotation carries the same attributes as the namespace element. If no base package is configured, the infrastructure scans the package of the annotated configuration class. The following example shows how to set up Java configuration: -.JavaConfig for repositories +.Java configuration for repositories ==== [source,java] ---- @@ -124,7 +123,9 @@ class ApplicationConfig { ---- ==== -As our domain repository extends `CrudRepository` it provides you with CRUD operations as well as methods for access to the entities. Working with the repository instance is just a matter of dependency injecting it into a client. +Because our domain repository extends `CrudRepository`, it provides you with CRUD operations as well as methods for access to the entities. Working with the repository instance is a matter of dependency injecting it into a client. + +We can add paging access to our repository, as follows: .Paging access to Person entities ==== @@ -146,12 +147,12 @@ public class PersonRepositoryTests { ---- ==== -The sample creates an application context with Spring's unit test support which will perform annotation based dependency injection into test cases. Inside the test method we simply use the repository to query the datastore. +The sample creates an application context with Spring's unit test support, which will perform annotation-based dependency injection into test cases. Inside the test method, we use the repository to query the datastore. [[ldap.repositories.queries]] -== Query methods +== Query Methods -Most of the data access operations you usually trigger on a repository result a query being executed against the LDAP directory. Defining such a query is just a matter of declaring a method on the repository interface +Most of the data access operations you usually trigger on a repository result in a query being executed against the LDAP directory. Defining such a query is a matter of declaring a method on the repository interface, as the following example shows: .PersonRepository with query methods ==== @@ -164,10 +165,12 @@ public interface PersonRepository extends PagingAndSortingRepository findByLastnameFirstname(String lastname, String firstname); <2> } ---- -<1> The method shows a query for all people with the given lastname. The query will be derived parsing the method name for constraints which can be concatenated with `And` and `Or`. Thus the method name will result in a query expression of `(&(objectclass=person)(lastname=lastname))`. -<2> The method shows a query for all people with the given lastname and firstname. The query will be derived parsing the method name.Thus the method name will result in a query expression of `(&(objectclass=person)(lastname=lastname)(firstname=firstname))`. +<1> The method shows a query for all people with the given `lastname`. The query is derived by parsing the method name for constraints that can be concatenated with `And` and `Or`. Thus, the method name results in a query expression of `(&(objectclass=person)(lastname=lastname))`. +<2> The method shows a query for all people with the given `lastname` and `firstname`. The query is derived by parsing the method name. Thus, the method name results in a query expression of `(&(objectclass=person)(lastname=lastname)(firstname=firstname))`. ==== +The following table provides samples of the keywords that you can use with query methods: + [cols="1,2,3", options="header"] .Supported keywords for query methods |=== @@ -222,12 +225,12 @@ public interface PersonRepository extends PagingAndSortingRepository