From 81411a06fdf08d5af59c813b5049d612e7286a1e Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 5 Jul 2023 13:42:19 -0500 Subject: [PATCH] Fix cross references --- modules/ROOT/pages/configuration.adoc | 14 +++++----- modules/ROOT/pages/dirobjectfactory.adoc | 6 ++-- modules/ROOT/pages/introduction.adoc | 28 +++++++++---------- modules/ROOT/pages/odm.adoc | 2 +- modules/ROOT/pages/pooling.adoc | 4 +-- modules/ROOT/pages/repositories.adoc | 4 +-- .../ROOT/pages/spring-ldap-basic-usage.adoc | 22 +++++++-------- modules/ROOT/pages/testing.adoc | 6 ++-- modules/ROOT/pages/transaction-support.adoc | 4 +-- modules/ROOT/pages/user-authentication.adoc | 10 +++---- 10 files changed, 50 insertions(+), 50 deletions(-) diff --git a/modules/ROOT/pages/configuration.adoc b/modules/ROOT/pages/configuration.adoc index 09562f4e..fb173a2e 100644 --- a/modules/ROOT/pages/configuration.adoc +++ b/modules/ROOT/pages/configuration.adoc @@ -66,7 +66,7 @@ The configurable attributes on context-source are as follows (required attribute | `LdapUtils.emptyLdapName()` | The base DN. When this attribute has been configured, all Distinguished Names supplied to and received from LDAP operations are relative to the specified LDAP path. This can significantly simplify working against the LDAP tree. However, there are several occasions when you need to have access to the base path. - For more information on this, see <> + For more information on this, see xref:configuration.adoc#base-context-configuration[Obtaining a Reference to the Base LDAP Path] | `anonymous-read-only` | `false` @@ -83,15 +83,15 @@ a| Defines the strategy with which to handle referrals, as described https://do | `native-pooling` | `false` -| Specify whether native Java LDAP connection pooling should be used. Consider using Spring LDAP connection pooling instead. See <> for more information. +| Specify whether native Java LDAP connection pooling should be used. Consider using Spring LDAP connection pooling instead. See xref:pooling.adoc[Pooling Support] for more information. | `authentication-source-ref` | A `SimpleAuthenticationSource` instance. -| ID of the `AuthenticationSource` instance to use (see <>). +| ID of the `AuthenticationSource` instance to use (see xref:configuration.adoc#spring-ldap-custom-principal-credentials-management[Custom Principal and Credentials Management]). | `authentication-strategy-ref` | A `SimpleDirContextAuthenticationStrategy` instance. -| ID of the `DirContextAuthenticationStrategy` instance to use (see <>). +| ID of the `DirContextAuthenticationStrategy` instance to use (see xref:configuration.adoc#spring-ldap-custom-dircontext-authentication-processing[Custom `DirContext` Authentication Processing]). | `base-env-props-ref` | @@ -104,7 +104,7 @@ a| Defines the strategy with which to handle referrals, as described https://do When `DirContext` instances are created to be used for performing operations on an LDAP server, these contexts often need to be authenticated. Spring LDAP offers various options for configuring this. -NOTE: This section refers to authenticating contexts in the core functionality of the `ContextSource`, to construct `DirContext` instances for use by `LdapClient` and `LdapTemplate`. LDAP is commonly used for the sole purpose of user authentication, and the `ContextSource` may be used for that as well. That process is discussed in <>. +NOTE: This section refers to authenticating contexts in the core functionality of the `ContextSource`, to construct `DirContext` instances for use by `LdapClient` and `LdapTemplate`. LDAP is commonly used for the sole purpose of user authentication, and the `ContextSource` may be used for that as well. That process is discussed in xref:user-authentication.adoc[User Authentication using Spring LDAP]. By default, authenticated contexts are created for both read-only and read-write operations. You should specify the `username` and `password` of the LDAP user to be used for authentication on the `context-source` element. @@ -130,7 +130,7 @@ Where `DefaultTlsDirContextAuthenticationStrategy` applies SIMPLE authentication Since different LDAP server implementations respond differently to explicit shutdown of the TLS channel (some servers require the connection be shut down gracefully, while others do not support it), the TLS `DirContextAuthenticationStrategy` implementations support specifying the shutdown behavior by using the `shutdownTlsGracefully` parameter. If this property is set to `false` (the default), no explicit TLS shutdown happens. If it is `true`, Spring LDAP tries to shut down the TLS channel gracefully before closing the target context. -NOTE: When working with TLS connections, you need to make sure that the native LDAP Pooling functionality (as specified by using the `native-pooling` attribute) is turned off. This is particularly important if `shutdownTlsGracefully` is set to `false`. However, since the TLS channel negotiation process is quite expensive, you can gain great performance benefits by using the Spring LDAP Pooling Support, described in <>. +NOTE: When working with TLS connections, you need to make sure that the native LDAP Pooling functionality (as specified by using the `native-pooling` attribute) is turned off. This is particularly important if `shutdownTlsGracefully` is set to `false`. However, since the TLS channel negotiation process is quite expensive, you can gain great performance benefits by using the Spring LDAP Pooling Support, described in xref:pooling.adoc[Pooling Support]. [[spring-ldap-custom-principal-credentials-management]] ==== Custom Principal and Credentials Management @@ -167,7 +167,7 @@ NOTE: When using the `SpringSecurityAuthenticationSource`, you need to use Sprin The internal Java LDAP provider provides some very basic pooling capabilities. You can turn this LDAP connection pooling on or off by using the `pooled` flag on `AbstractContextSource`. The default value is `false` (since release 1.3) -- that is, the native Java LDAP pooling is turned off. The configuration of LDAP connection pooling is managed by using `System` properties, so you need to handle this manually, outside of the Spring Context configuration. You can find details of the native pooling configuration https://java.sun.com/products/jndi/tutorial/ldap/connect/config.html[here]. -NOTE: There are several serious deficiencies in the built-in LDAP connection pooling, which is why Spring LDAP provides a more sophisticated approach to LDAP connection pooling, described in <>. If you need pooling functionality, this is the recommended approach. +NOTE: There are several serious deficiencies in the built-in LDAP connection pooling, which is why Spring LDAP provides a more sophisticated approach to LDAP connection pooling, described in xref:pooling.adoc[Pooling Support]. If you need pooling functionality, this is the recommended approach. NOTE: Regardless of the pooling configuration, the `ContextSource#getContext(String principal, String credentials)` method always explicitly does not use native Java LDAP Pooling, in order for reset passwords to take effect as soon as possible. diff --git a/modules/ROOT/pages/dirobjectfactory.adoc b/modules/ROOT/pages/dirobjectfactory.adoc index e249e778..215ebc0b 100644 --- a/modules/ROOT/pages/dirobjectfactory.adoc +++ b/modules/ROOT/pages/dirobjectfactory.adoc @@ -105,7 +105,7 @@ involved in adding and updating data. [[adding-data-by-using-dircontextadapter]] === Adding Data by Using `DirContextAdapter` -The following example uses `DirContextAdapter` to implement an improved implementation of the `create` repository method presented in <>: +The following example uses `DirContextAdapter` to implement an improved implementation of the `create` repository method presented in xref:spring-ldap-basic-usage.adoc#basic-binding-data[Adding Data]: .Binding using `DirContextAdapter` ==== @@ -286,7 +286,7 @@ public class GroupRepo implements BaseLdapNameAware { ---- ==== -In the preceding example, we implement `BaseLdapNameAware` to get the base LDAP path as described in <>. +In the preceding example, we implement `BaseLdapNameAware` to get the base LDAP path as described in xref:configuration.adoc#base-context-configuration[Obtaining a Reference to the Base LDAP Path]. This is necessary because distinguished names as member attribute values must always be absolute from the directory root. [[a-complete-personrepository-class]] @@ -397,5 +397,5 @@ public class PersonRepoImpl implements PersonRepo { NOTE: In several cases, the Distinguished Name (DN) of an object is constructed by using properties of the object. In the preceding example, the country, company and full name of the `Person` are used in the DN, which means that updating any of these properties actually requires moving the entry in the LDAP tree by using the `rename()` operation in addition to updating the `Attribute` values. Since this is highly implementation-specific, this is something you need to keep track of yourself, either by disallowing the user to change these properties or performing the `rename()` operation in your `update()` method if needed. -Note that, by using <>, the library can automatically handle this for you if you annotate your domain classes appropriately. +Note that, by using xref:odm.adoc[Object-Directory Mapping (ODM)], the library can automatically handle this for you if you annotate your domain classes appropriately. diff --git a/modules/ROOT/pages/introduction.adoc b/modules/ROOT/pages/introduction.adoc index 64621b64..1c483150 100644 --- a/modules/ROOT/pages/introduction.adoc +++ b/modules/ROOT/pages/introduction.adoc @@ -3,15 +3,15 @@ This section offers a relatively quick introduction to Spring LDAP. It includes the following content: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:introduction.adoc#spring-ldap-introduction-overview[Overview] +* xref:introduction.adoc#spring-ldap-traditional-ldap-vs-ldaptemplate[Traditional Java LDAP versus `LdapClient`] +* xref:introduction.adoc#spring-ldap-new-2.2[What's new in 2.2] +* xref:introduction.adoc#spring-ldap-new-2.1[What's new in 2.1] +* xref:introduction.adoc#spring-ldap-new-2.0[What's new in 2.0] +* xref:introduction.adoc#spring-ldap-packaging-overview[Packaging Overview] +* xref:introduction.adoc#spring-ldap-getting-started[Getting Started] +* xref:introduction.adoc#spring-ldap-support[Support] +* xref:introduction.adoc#spring-ldap-acknowledgements[Acknowledgements] [[spring-ldap-introduction-overview]] == Overview @@ -201,15 +201,15 @@ The following list briefly describes the most important changes in Spring LDAP 2 * The central API has been updated with Java 5+ features such as generics and varargs. As a consequence, the entire `spring-ldap-tiger` module has been deprecated, and we encourage you to migrate to using the core Spring LDAP classes. The parameterization of the core interfaces causes lots of compilation warnings on existing code, and we encourage you to take appropriate action to get rid of these warnings. -* The ODM (Object-Directory Mapping) functionality has been moved to core, and there are new methods in `LdapOperations` and `LdapTemplate` that use this automatic translation to and from ODM-annotated classes. See <> for more information. +* The ODM (Object-Directory Mapping) functionality has been moved to core, and there are new methods in `LdapOperations` and `LdapTemplate` that use this automatic translation to and from ODM-annotated classes. See xref:odm.adoc[Object-Directory Mapping (ODM)] for more information. * A custom XML namespace is now (finally) provided to simplify configuration of Spring LDAP. See <> for more information. -* Spring LDAP now provides support for Spring Data Repository and QueryDSL. See <> for more information. +* Spring LDAP now provides support for Spring Data Repository and QueryDSL. See xref:repositories.adoc[Spring LDAP Repositories] for more information. * `Name` instances as attribute values are now handled properly with regards to distinguished name equality in `DirContextAdapter` and ODM. - See <> and <> for more information. + See xref:dirobjectfactory.adoc#dns-as-attribute-values[`DirContextAdapter` and Distinguished Names as Attribute Values] and xref:odm.adoc#odm-dn-attributes[ODM and Distinguished Names as Attribute Values] for more information. * `DistinguishedName` and associated classes have been deprecated in favor of the standard Java `LdapName`. - See <> for information on how the library helps when working with `LdapName` objects. + See xref:spring-ldap-basic-usage.adoc#ldap-names[Dynamically Building Distinguished Names] for information on how the library helps when working with `LdapName` objects. * Fluent LDAP query building support has been added. This makes for a more pleasant programming experience when working with LDAP searches in Spring LDAP. - See <> and <> for more information about the LDAP query builder support. + See xref:spring-ldap-basic-usage.adoc#basic-queries[Building LDAP Queries] and xref:query-builder-advanced.adoc[Advanced LDAP Queries] for more information about the LDAP query builder support. * The old `authenticate` methods in `LdapTemplate` have been deprecated in favor of a couple of new `authenticate` methods that work with `LdapQuery` objects and _throw exceptions_ on authentication failure, making it easier for the user to find out what caused an authentication attempt to fail. * The https://github.com/spring-projects/spring-ldap/tree/main/samples[samples] have been polished and updated to make use of the features in 2.0. Quite a bit of effort has been put into providing a useful example of an https://github.com/spring-projects/spring-ldap/tree/main/samples/user-admin[LDAP user management application]. diff --git a/modules/ROOT/pages/odm.adoc b/modules/ROOT/pages/odm.adoc index 1e208ca8..9a6e86df 100644 --- a/modules/ROOT/pages/odm.adoc +++ b/modules/ROOT/pages/odm.adoc @@ -132,7 +132,7 @@ public class OdmPersonRepo { == ODM and Distinguished Names as Attribute Values Security groups in LDAP commonly contain a multi-value attribute, where each of the values is the distinguished name -of a user in the system. The difficulties involved when handling these kinds of attributes are discussed in <>. +of a user in the system. The difficulties involved when handling these kinds of attributes are discussed in xref:dirobjectfactory.adoc#dns-as-attribute-values[`DirContextAdapter` and Distinguished Names as Attribute Values]. ODM also has support for `javax.naming.Name` attribute values, making group modifications easy, as the following example shows: diff --git a/modules/ROOT/pages/pooling.adoc b/modules/ROOT/pages/pooling.adoc index 24d51682..ecc36a31 100644 --- a/modules/ROOT/pages/pooling.adoc +++ b/modules/ROOT/pages/pooling.adoc @@ -13,7 +13,7 @@ Validation of pooled connections is the primary motivation for using a custom po If connection validation is configured, pooled connections are validated by using `DefaultDirContextValidator`. `DefaultDirContextValidator` does a `DirContext.search(String, String, SearchControls)`, with an empty name, a filter of `"objectclass=*"`, and `SearchControls` set to limit a single result with the only the `objectclass` attribute and a 500ms timeout. If the returned `NamingEnumeration` has results, the `DirContext` passes validation. If no results are returned or an exception is thrown, the `DirContext` fails validation. The default settings should work with no configuration changes on most LDAP servers and provide the fastest way to validate the `DirContext`. -If you need customization, you can do so by using the validation configuration attributes, described in <>. +If you need customization, you can do so by using the validation configuration attributes, described in xref:pooling.adoc#pool-configuration[Pool Configuration]. NOTE: Connections are automatically invalidated if they throw an exception that is considered non-transient. For example, if a `DirContext` instance throws a `javax.naming.CommunicationException`, it is interpreted as a non-transient error and the instance is automatically invalidated, without the overhead of an additional `testOnReturn` operation. The exceptions that are interpreted as non-transient are configured by using the `nonTransientExceptions` property of the `PoolingContextSource`. @@ -252,7 +252,7 @@ The following example tests each `DirContext` before it is passed to the client This section describes issues that sometimes arise when people use Spring LDAP. At present, it covers the following issues: -* <> +* xref:pooling.adoc#spring-ldap-known-issues-custom-authentication[Custom Authentication] [[spring-ldap-known-issues-custom-authentication]] === Custom Authentication diff --git a/modules/ROOT/pages/repositories.adoc b/modules/ROOT/pages/repositories.adoc index dadea478..c999a6f7 100644 --- a/modules/ROOT/pages/repositories.adoc +++ b/modules/ROOT/pages/repositories.adoc @@ -7,7 +7,7 @@ Spring LDAP has built-in support for Spring Data repositories. The basic functio * 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 that are annotated with the ODM annotations, as described in <>. +* All Spring LDAP repositories must work with entities that are annotated with the ODM annotations, as described in xref:odm.adoc[Object-Directory Mapping (ODM)]. * 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`. The built-in `LdapRepository` takes only one type parameter: the managed entity class, defaulting the ID to `javax.naming.Name`. @@ -18,7 +18,7 @@ Spring LDAP has built-in support for Spring Data repositories. The basic functio == QueryDSL support Basic QueryDSL support is included in Spring LDAP. This support includes the following: -* An annotation processor, called `LdapAnnotationProcessor`, for generating QueryDSL classes based on Spring LDAP ODM annotations. See <> for more information on the ODM annotations. +* An annotation processor, called `LdapAnnotationProcessor`, for generating QueryDSL classes based on Spring LDAP ODM annotations. See xref:odm.adoc[Object-Directory Mapping (ODM)] for more information on the ODM annotations. * A Query implementation, called `QueryDslLdapQuery`, for building and running QueryDSL queries in code. diff --git a/modules/ROOT/pages/spring-ldap-basic-usage.adoc b/modules/ROOT/pages/spring-ldap-basic-usage.adoc index 5643bb12..3d5d62c8 100644 --- a/modules/ROOT/pages/spring-ldap-basic-usage.adoc +++ b/modules/ROOT/pages/spring-ldap-basic-usage.adoc @@ -3,12 +3,12 @@ This section describes the basics of using Spring LDAP. It contains the following content: -* <> -* <> -* <> -* <> -* <> -* <> +* xref:spring-ldap-basic-usage.adoc#spring-ldap-basic-usage-search-lookup-attributesmapper[Search and Lookup Using `AttributesMapper`] +* xref:spring-ldap-basic-usage.adoc#basic-queries[Building LDAP Queries] +* xref:spring-ldap-basic-usage.adoc#ldap-names[Dynamically Building Distinguished Names] +* xref:spring-ldap-basic-usage.adoc#spring-ldap-basic-usage-examples[Examples] +* xref:spring-ldap-basic-usage.adoc#spring-ldap-basic-usage-binding-unbinding[Binding and Unbinding] +* xref:spring-ldap-basic-usage.adoc#spring-ldap-basic-usage-updating[Updating] [[spring-ldap-basic-usage-search-lookup-attributesmapper]] == Search and Lookup Using `AttributesMapper` @@ -141,9 +141,9 @@ NOTE: In addition to simplifying building of complex search parameters, the `Lda NOTE: `LdapClient` includes many overloaded methods for performing LDAP searches. This is in order to accommodate as many different use cases and programming style preferences as possible. For the vast majority of use cases, the methods that take an `LdapQuery` as input are the recommended methods to use. -NOTE: The `AttributesMapper` is only one of the available callback interfaces you can use when handling search and lookup data. See <> for alternatives. +NOTE: The `AttributesMapper` is only one of the available callback interfaces you can use when handling search and lookup data. See xref:dirobjectfactory.adoc[Simplifying Attribute Access and Manipulation with `DirContextAdapter`] for alternatives. -For more information on the `LdapQueryBuilder`, see <>. +For more information on the `LdapQueryBuilder`, see xref:query-builder-advanced.adoc[Advanced LDAP Queries]. [[ldap-names]] == Dynamically Building Distinguished Names @@ -243,7 +243,7 @@ This implementation suffered from a couple of shortcomings of its own and has be [[spring-ldap-basic-usage-binding-unbinding]] == Binding and Unbinding -This section describes how to add and remove data. Updating is covered in the <>. +This section describes how to add and remove data. Updating is covered in the xref:spring-ldap-basic-usage.adoc#spring-ldap-basic-usage-updating[next section]. [[basic-binding-data]] === Adding Data @@ -281,7 +281,7 @@ public class PersonRepoImpl implements PersonRepo { ---- ==== -Manual attributes building is -- while dull and verbose -- sufficient for many purposes. You can, however, simplify the binding operation further, as described in <>. +Manual attributes building is -- while dull and verbose -- sufficient for many purposes. You can, however, simplify the binding operation further, as described in xref:dirobjectfactory.adoc[Simplifying Attribute Access and Manipulation with `DirContextAdapter`]. [[removing-data]] @@ -365,6 +365,6 @@ public class PersonRepoImpl implements PersonRepo { ---- ==== -Building `Attributes` and `ModificationItem` arrays is a lot of work. However, as we describe in <>, +Building `Attributes` and `ModificationItem` arrays is a lot of work. However, as we describe in xref:dirobjectfactory.adoc[Simplifying Attribute Access and Manipulation with `DirContextAdapter`], Spring LDAP provides more help for simplifying these operations. diff --git a/modules/ROOT/pages/testing.adoc b/modules/ROOT/pages/testing.adoc index 936a897b..76224492 100644 --- a/modules/ROOT/pages/testing.adoc +++ b/modules/ROOT/pages/testing.adoc @@ -3,9 +3,9 @@ This section covers testing with Spring LDAP. It contains the following topics: -* <> -* <> -* <> +* xref:testing.adoc#spring-ldap-testing-embedded-server[Using an Embedded Server] +* xref:testing.adoc#spring-ldap-testing-apacheds[ApacheDS] +* xref:testing.adoc#spring-ldap-testing-unboundid[UnboundID] [[spring-ldap-testing-embedded-server]] == Using an Embedded Server diff --git a/modules/ROOT/pages/transaction-support.adoc b/modules/ROOT/pages/transaction-support.adoc index 77b37914..cfe27a0b 100644 --- a/modules/ROOT/pages/transaction-support.adoc +++ b/modules/ROOT/pages/transaction-support.adoc @@ -16,7 +16,7 @@ While this should be carefully considered, it should also be noted that the alte NOTE: The client-side transaction support adds some overhead in addition to the work required by the original operations. While this overhead should not be something to worry about in most cases, if your application does not perform several LDAP operations within the same transaction (for example, `modifyAttributes` followed by `rebind`), -or if transaction synchronization with a JDBC data source is not required (see <>), you gain little by using the LDAP transaction support. +or if transaction synchronization with a JDBC data source is not required (see xref:transaction-support.adoc#spring-ldap-jdbc-transaction-integration[JDBC Transaction Integration]), you gain little by using the LDAP transaction support. [[configuration]] == Configuration @@ -55,7 +55,7 @@ Configuring Spring LDAP transactions should look very familiar if you are used t ==== NOTE: While this setup works fine for most simple use cases, some more complex scenarios require additional configuration. -Specifically, if you need to create or delete subtrees within transactions, you need to use an alternative `TempEntryRenamingStrategy`, as described in <>. +Specifically, if you need to create or delete subtrees within transactions, you need to use an alternative `TempEntryRenamingStrategy`, as described in xref:transaction-support.adoc#renaming-strategies[Renaming Strategies]. In a real-world situation, you would probably apply the transactions on the service-object level rather than the repository level. The preceding example demonstrates the general idea. diff --git a/modules/ROOT/pages/user-authentication.adoc b/modules/ROOT/pages/user-authentication.adoc index 3bf1a1f8..32dcdecd 100644 --- a/modules/ROOT/pages/user-authentication.adoc +++ b/modules/ROOT/pages/user-authentication.adoc @@ -3,10 +3,10 @@ This section covers user authentication with Spring LDAP. It contains the following topics: -* <> -* <> -* <> -* <> +* xref:user-authentication.adoc#spring-ldap-user-authentication-basic[Basic Authentication] +* xref:user-authentication.adoc#operationsOnAuthenticatedContext[Performing Operations on the Authenticated Context] +* xref:user-authentication.adoc#spring-ldap-authentication-obsolete[Obsolete Authentication Methods] +* xref:user-authentication.adoc#spring-ldap-using-spring-security[Using Spring Security] [[spring-ldap-user-authentication-basic]] == Basic Authentication @@ -67,7 +67,7 @@ ldapClient.authenticate().query(query().where("uid").is("john.doe")).password("s ---- ==== -NOTE: As described in the <>, some setups may require you to perform additional operations to get actual authentication to occur. See <> for details. +NOTE: As described in the xref:user-authentication.adoc#operationsOnAuthenticatedContext[Performing Operations on the Authenticated Context], some setups may require you to perform additional operations to get actual authentication to occur. See xref:user-authentication.adoc#operationsOnAuthenticatedContext[Performing Operations on the Authenticated Context] for details. TIP: Do not write your own custom authenticate methods. Use the ones provided in Spring LDAP.