Clarify that @DnAttribute does not affect attribute mapping

[edysli]

Javadoc for @DnAttribute states:

Indicates that a field is to be automatically populated to/from the distinguished name of an entry.

However, spring-ldap will also try to create an actual LDAP attribute with any field annotated with @DnAttribute. So either the documentation is wrong or this annotation does too much.

In my case, using

@DnAttribute(value = "ou", index = 3) public String branch;

causes a schema violation:

Caused by: javax.naming.directory.SchemaViolationException:
[LDAP: error code 65 - Unable to modify entry '<removed>' because the entry resulting from applying the modifications would have violated the provided schema:
The entry contains attribute branch which is not defined in the schema.]

Please either document this behaviour or prevent @DnAttribute from affecting something else than the DN.

[edysli]

spring-ldap's reference manual has the answer:

The @Transient annotation is used to indicate the field should be ignored by the object directory mapping and not mapped to an underlying LDAP property. Note that if a @DnAttribute is not to be bound to an Attribute, i.e. it is only part of the Distinguished Name and not represented by an object attribute, it must also be annotated with @Transient.

This deserves to be mentioned in the Javadoc for @DnAttribute.

But still... having to add @Transient is quite counter-intuitive (also for fields that should not be mapped to an attribute). 😕

[jzheaux]

having to add @Transient is quite counter-intuitive ...

I think I understand where you are coming from, and I do think there is a needed documentation improvement.

The existing behavior seems to align with other serialization/mapping mechanisms like Java serialization or JPA. With Java serialization, all fields are mapped unless accompanied by the transient keyword. With JPA, all fields are mapped to the database table unless the @Transient annotation is used. With ODM, all fields are mapped to the entry unless the @Transient annotation is used.

So, @DnAttribute does nothing more than it states, AFAICT. It is unrelated to ODM's default stance of mapping all fields to the entry.

If I were to change something in the documentation, I would clarify that all fields are mapped by default to the entry. Any field that should not be mapped to the entry should be marked with @Transient.

I don't feel like @DnAttribute is pertinent to this point and so the paragraph you pointed to in the documentation, while correct, is misleading. @Transient is needed if you don't want something to be mapped, regardless of whether @DnAttribute is present.

If you agree, would you like to update your PR to adjust the documentation in this way? Or, if you feel we're not aligned yet, please help me see what I'm missing.

Also, I've logged #722 to adjust the ODM sample to demonstrate this a little more clearly.