LDAP-268: Reference documentation of the new @DnAttribute annotation. Some javadoc polishing.

core/src/main/java/org/springframework/ldap/core/LdapOperations.java

@@ -1692,31 +1692,46 @@ public interface LdapOperations {
     <T> T findByDn(Name dn, Class<T> clazz);
 
     /**
-     * Create the given entry in the LDAP directory.
+     * Create the given entry in the LDAP directory. If the field annotated with {@link org.springframework.ldap.odm.annotations.Id}
+     * is set in the object, this will be used as the distinguished name of the new entry. If no explicit DN is specified,
+     * an attempt will be made to calculate the name from fields annotated with {@link org.springframework.ldap.odm.annotations.DnAttribute}.
      *
      * @param entry The entry to be create, it must <em>not</em> already exist in the directory.
      *
      * @throws org.springframework.ldap.NamingException on error.
+     * @throws IllegalArgumentException if the entry is null or on failure to determine the distinguished name.
      * @since 2.0
      */
     void create(Object entry);
 
     /**
-     * Update the given entry in the LDAP directory.
+     * Update the given entry in the LDAP directory. If the distinguished name is not explicitly specified (i.e. if the
+     * field annotated with {@link org.springframework.ldap.odm.annotations.Id} is <code>null</code>),
+     * an attempt will be made to calculate the name from fields annotated with
+     * {@link org.springframework.ldap.odm.annotations.DnAttribute}. If the {@link org.springframework.ldap.odm.annotations.Id}
+     * field and the calculated DN is different, the entry will be <strong>moved</strong> (i.e., an {@link #unbind(javax.naming.Name)}
+     * followed by a {@link #bind(DirContextOperations)}. Otherwise
+     * the current data of the entry will be read from the directory and a {@link #modifyAttributes(DirContextOperations)}
+     * operation will be performed using the <code>ModificationItems</code> resulting from the changes of the
+     * entry compared to its current state in the directory.
      *
      * @param entry The entry to update, it must already exist in the directory.
      *
      * @throws org.springframework.ldap.NamingException on error.
+     * @throws IllegalArgumentException if the entry is null or on failure to determine the distinguished name.
      * @since 2.0
      */
     void update(Object entry);
 
     /**
-     * Delete an entry from the LDAP directory.
+     * Delete an entry from the LDAP directory. If the field annotated with {@link org.springframework.ldap.odm.annotations.Id}
+     * is set in the object, this will be used as the distinguished name of the new entry. If no explicit DN is specified,
+     * an attempt will be made to calculate the name from fields annotated with {@link org.springframework.ldap.odm.annotations.DnAttribute}.
      *
      * @param entry The entry to delete, it must already exist in the directory.
      *
      * @throws org.springframework.ldap.NamingException on error.
+     * @throws IllegalArgumentException if the entry is null or on failure to determine the distinguished name.
      * @since 2.0
      */
     void delete(Object entry);

core/src/main/java/org/springframework/ldap/core/LdapTemplate.java

@@ -1819,12 +1819,18 @@ public class LdapTemplate implements LdapOperations, InitializingBean {
 
     @Override
     public void delete(Object entry) {
+        Assert.notNull(entry, "Entry must not be null");
         if (log.isDebugEnabled()) {
             log.debug(String.format("Deleting %s$1", entry));
         }
 
-        // Just to check that this is a managed class
-        unbind(odm.getId(entry));
+        Name id = odm.getId(entry);
+        if(id == null) {
+            id = odm.getCalculatedId(entry);
+        }
+
+        Assert.notNull(id, String.format("Unable to determine id for entry %s", entry.toString()));
+        unbind(id);
     }
 
     @Override

core/src/main/java/org/springframework/ldap/odm/annotations/DnAttribute.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2005-2013 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.springframework.ldap.odm.annotations;
 
 import java.lang.annotation.ElementType;
@@ -6,11 +22,30 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * Indicates that a field is to be automatically populated to/from the distinguished name
+ * of an entry. Fields annotated with this annotation will be automatically populated with values from
+ * the distinguished names of found entries.
+ * <p>
+ * For automatic calculation of the DN of an entry to work, the {@link #index()} value
+ * must be specified on all DnAttribute annotations in that class, and these attribute values,
+ * prepended with the {@link org.springframework.ldap.odm.annotations.Entry#base()} value will be used
+ * to figure out the distinguished name of entries to create and update.
+ * </p>
  * @author Mattias Hellborg Arthursson
+ * @since 2.0
  */
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface DnAttribute {
+    /**
+     * The name of the distinguished name attribute.
+     * @return the attribute name.
+     */
     String value();
+
+    /**
+     * The index of this attribute in the calculated distinguished name of an entry.
+     * @return the 0-based index of this attribute.
+     */
     int index() default -1;
 }