From ed3569de13796afcf11b12ec47cf2b129763375c Mon Sep 17 00:00:00 2001
From: Josh Cummings <josh.cummings@gmail.com>
Date: Fri, 11 Oct 2024 17:40:47 -0600
Subject: [PATCH] Clarify that index has precedence

Closes gh-940
---
 modules/ROOT/pages/odm.adoc | 55 +++++++++++++++++++++++++++++++++++--
 1 file changed, 53 insertions(+), 2 deletions(-)

diff --git a/modules/ROOT/pages/odm.adoc b/modules/ROOT/pages/odm.adoc
index 9a6e86df5..d11771cde 100644
--- a/modules/ROOT/pages/odm.adoc
+++ b/modules/ROOT/pages/odm.adoc
@@ -48,12 +48,63 @@ Finally, `@Attribute` also provides the type declaration, which lets you indicat
 Third, the `@Transient` annotation indicates that the given entity field does not map to an LDAP attribute.
 
 Finally, the `@DnAttribute` annotation additionally maps entity fields to components of an entry's distinguished name.
+
+Consider a class with the following annotation:
+
+====
+[source,java,role="primary"]
+----
+@DnAttribute(name="uid")
+String uid;
+----
+====
+
+and a DN like the following:
+
+====
+[source,bash]
+----
+uid=carla,dc=springframework,dc=org
+----
+====
+
+Then Spring LDAP will populate `uid` using `uid=carla` instead of looking for a `uid` attribute.
+
+[NOTE]
+----
 Only fields of type `String` can be annotated with `@DnAttribute`. Other types are not supported.
+----
 
-[TIP]
-When the `index` attribute of all `@DnAttribute` annotations in a class is specified, the DN can also be automatically calculated when creating and updating entries.
+You can alternatively supply an index like so:
+
+====
+[source,java,role="primary"]
+----
+@DnAttribute(index=1)
+String uid;
+
+@DnAttribute(index=0)
+String department;
+----
+====
+
+which is handy for DNs that have multiple components:
+
+====
+[source,bash]
+----
+uid=carla,department=engineering,dc=springframework,dc=org
+----
+====
+
+Using an `index` also allows Spring LDAP to compute the DN for you when creating or locating an entity for update or deletion.
 For update scenarios, this also automatically takes care of moving entries in the tree if attributes that are part of the distinguished name have changed.
 
+[NOTE]
+----
+Note that while both attributes are present on `@DnAttribute`, if `index` is specified, then `name` is ignored.
+----
+
 [NOTE]
 Remember that all fields are mapped to LDAP attributes by default.
 `@DnAttribute` does not change this; in other words, fields annotated with `@DnAttribute` will also map to an LDAP attribute, unless you also annotate the field with `@Transient`.