mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git

Matthew Swift
25.33.2012 263d085885df024dca9250cc03c807912b0a7662
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/Entry.java
@@ -6,17 +6,16 @@
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * trunk/opendj3/legal-notices/CDDLv1_0.txt
 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
 * or http://forgerock.org/license/CDDLv1.0.html.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * trunk/opendj3/legal-notices/CDDLv1_0.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 * file and include the License file at legal-notices/CDDLv1_0.txt.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
@@ -28,13 +27,9 @@
package org.forgerock.opendj.ldap;
import java.util.Collection;
import org.forgerock.i18n.*;
import org.forgerock.i18n.LocalizedIllegalArgumentException;
/**
 * An entry, comprising of a distinguished name and zero or more attributes.
@@ -63,473 +58,430 @@
 *
 * @see Entries
 */
public interface Entry
{
public interface Entry {
  /**
   * Ensures that this entry contains the provided attribute and values
   * (optional operation). This method has the following semantics:
   * <ul>
   * <li>If this entry does not already contain an attribute with the same
   * attribute description, then this entry will be modified such that it
   * contains {@code attribute}, even if it is empty.
   * <li>If this entry already contains an attribute with the same attribute
   * description, then the attribute values contained in {@code attribute} will
   * be merged with the existing attribute values.
   * </ul>
   * <p>
   * <b>NOTE:</b> When {@code attribute} is non-empty, this method implements
   * LDAP Modify add semantics.
   *
   * @param attribute
   *          The attribute values to be added to this entry, merging with any
   *          existing attribute values.
   * @return {@code true} if this entry changed as a result of this call.
   * @throws UnsupportedOperationException
   *           If this entry does not permit attributes or their values to be
   *           added.
   * @throws NullPointerException
   *           If {@code attribute} was {@code null}.
   */
  boolean addAttribute(Attribute attribute);
    /**
     * Ensures that this entry contains the provided attribute and values
     * (optional operation). This method has the following semantics:
     * <ul>
     * <li>If this entry does not already contain an attribute with the same
     * attribute description, then this entry will be modified such that it
     * contains {@code attribute}, even if it is empty.
     * <li>If this entry already contains an attribute with the same attribute
     * description, then the attribute values contained in {@code attribute}
     * will be merged with the existing attribute values.
     * </ul>
     * <p>
     * <b>NOTE:</b> When {@code attribute} is non-empty, this method implements
     * LDAP Modify add semantics.
     *
     * @param attribute
     *            The attribute values to be added to this entry, merging with
     *            any existing attribute values.
     * @return {@code true} if this entry changed as a result of this call.
     * @throws UnsupportedOperationException
     *             If this entry does not permit attributes or their values to
     *             be added.
     * @throws NullPointerException
     *             If {@code attribute} was {@code null}.
     */
    boolean addAttribute(Attribute attribute);
    /**
     * Ensures that this entry contains the provided attribute and values
     * (optional operation). This method has the following semantics:
     * <ul>
     * <li>If this entry does not already contain an attribute with the same
     * attribute description, then this entry will be modified such that it
     * contains {@code attribute}, even if it is empty.
     * <li>If this entry already contains an attribute with the same attribute
     * description, then the attribute values contained in {@code attribute}
     * will be merged with the existing attribute values.
     * </ul>
     * <p>
     * <b>NOTE:</b> When {@code attribute} is non-empty, this method implements
     * LDAP Modify add semantics.
     *
     * @param attribute
     *            The attribute values to be added to this entry, merging with
     *            any existing attribute values.
     * @param duplicateValues
     *            A collection into which duplicate values will be added, or
     *            {@code null} if duplicate values should not be saved.
     * @return {@code true} if this entry changed as a result of this call.
     * @throws UnsupportedOperationException
     *             If this entry does not permit attributes or their values to
     *             be added.
     * @throws NullPointerException
     *             If {@code attribute} was {@code null}.
     */
    boolean addAttribute(Attribute attribute, Collection<ByteString> duplicateValues);
    /**
     * Ensures that this entry contains the provided attribute and values
     * (optional operation). This method has the following semantics:
     * <ul>
     * <li>If this entry does not already contain an attribute with the same
     * attribute description, then this entry will be modified such that it
     * contains {@code attribute}, even if it is empty.
     * <li>If this entry already contains an attribute with the same attribute
     * description, then the attribute values contained in {@code attribute}
     * will be merged with the existing attribute values.
     * </ul>
     * <p>
     * The attribute description will be decoded using the schema associated
     * with this entry (usually the default schema).
     * <p>
     * Any attribute values which are not instances of {@code ByteString} will
     * be converted using the {@link ByteString#valueOf(Object)} method.
     * <p>
     * <b>NOTE:</b> When {@code attribute} is non-empty, this method implements
     * LDAP Modify add semantics.
     *
     * @param attributeDescription
     *            The name of the attribute whose values are to be added.
     * @param values
     *            The attribute values to be added to this entry, merging any
     *            existing attribute values.
     * @return This entry.
     * @throws LocalizedIllegalArgumentException
     *             If {@code attributeDescription} could not be decoded using
     *             the schema associated with this entry.
     * @throws UnsupportedOperationException
     *             If this entry does not permit attributes or their values to
     *             be added.
     * @throws NullPointerException
     *             If {@code attributeDescription} was {@code null}.
     */
    Entry addAttribute(String attributeDescription, Object... values);
  /**
   * Ensures that this entry contains the provided attribute and values
   * (optional operation). This method has the following semantics:
   * <ul>
   * <li>If this entry does not already contain an attribute with the same
   * attribute description, then this entry will be modified such that it
   * contains {@code attribute}, even if it is empty.
   * <li>If this entry already contains an attribute with the same attribute
   * description, then the attribute values contained in {@code attribute} will
   * be merged with the existing attribute values.
   * </ul>
   * <p>
   * <b>NOTE:</b> When {@code attribute} is non-empty, this method implements
   * LDAP Modify add semantics.
   *
   * @param attribute
   *          The attribute values to be added to this entry, merging with any
   *          existing attribute values.
   * @param duplicateValues
   *          A collection into which duplicate values will be added, or {@code
   *          null} if duplicate values should not be saved.
   * @return {@code true} if this entry changed as a result of this call.
   * @throws UnsupportedOperationException
   *           If this entry does not permit attributes or their values to be
   *           added.
   * @throws NullPointerException
   *           If {@code attribute} was {@code null}.
   */
  boolean addAttribute(Attribute attribute,
      Collection<ByteString> duplicateValues);
    /**
     * Removes all the attributes from this entry (optional operation).
     *
     * @return This entry.
     * @throws UnsupportedOperationException
     *             If this entry does not permit attributes to be removed.
     */
    Entry clearAttributes();
    /**
     * Returns {@code true} if this entry contains all of the attribute values
     * contained in {@code attribute}. If {@code attribute} is empty then this
     * method will return {@code true} if the attribute is present in this
     * entry, regardless of how many values it contains.
     *
     * @param attribute
     *            The attribute values whose presence in this entry is to be
     *            tested.
     * @param missingValues
     *            A collection into which missing values will be added, or
     *            {@code null} if missing values should not be saved.
     * @return {@code true} if this entry contains all of the attribute values
     *         contained in {@code attribute}.
     * @throws NullPointerException
     *             If {@code attribute} was {@code null}.
     */
    boolean containsAttribute(Attribute attribute, Collection<ByteString> missingValues);
    /**
     * Returns {@code true} if this entry contains all of the attribute values
     * contained in {@code values}. If {@code values} is {@code null} or empty
     * then this method will return {@code true} if the attribute is present in
     * this entry, regardless of how many values it contains.
     * <p>
     * The attribute description will be decoded using the schema associated
     * with this entry (usually the default schema).
     * <p>
     * Any attribute values which are not instances of {@code ByteString} will
     * be converted using the {@link ByteString#valueOf(Object)} method.
     *
     * @param attributeDescription
     *            The name of the attribute whose presence in this entry is to
     *            be tested.
     * @param values
     *            The attribute values whose presence in this entry is to be
     *            tested, which may be {@code null}.
     * @return {@code true} if this entry contains all of the attribute values
     *         contained in {@code values}.
     * @throws LocalizedIllegalArgumentException
     *             If {@code attributeDescription} could not be decoded using
     *             the schema associated with this entry.
     * @throws NullPointerException
     *             If {@code attributeDescription} was {@code null}.
     */
    boolean containsAttribute(String attributeDescription, Object... values);
  /**
   * Ensures that this entry contains the provided attribute and values
   * (optional operation). This method has the following semantics:
   * <ul>
   * <li>If this entry does not already contain an attribute with the same
   * attribute description, then this entry will be modified such that it
   * contains {@code attribute}, even if it is empty.
   * <li>If this entry already contains an attribute with the same attribute
   * description, then the attribute values contained in {@code attribute} will
   * be merged with the existing attribute values.
   * </ul>
   * <p>
   * The attribute description will be decoded using the schema associated with
   * this entry (usually the default schema).
   * <p>
   * Any attribute values which are not instances of {@code ByteString} will be
   * converted using the {@link ByteString#valueOf(Object)} method.
   * <p>
   * <b>NOTE:</b> When {@code attribute} is non-empty, this method implements
   * LDAP Modify add semantics.
   *
   * @param attributeDescription
   *          The name of the attribute whose values are to be added.
   * @param values
   *          The attribute values to be added to this entry, merging any
   *          existing attribute values.
   * @return This entry.
   * @throws LocalizedIllegalArgumentException
   *           If {@code attributeDescription} could not be decoded using the
   *           schema associated with this entry.
   * @throws UnsupportedOperationException
   *           If this entry does not permit attributes or their values to be
   *           added.
   * @throws NullPointerException
   *           If {@code attributeDescription} was {@code null}.
   */
  Entry addAttribute(String attributeDescription, Object... values);
    /**
     * Returns {@code true} if {@code object} is an entry which is equal to this
     * entry. Two entries are considered equal if their distinguished names are
     * equal, they both have the same number of attributes, and every attribute
     * contained in the first entry is also contained in the second entry.
     *
     * @param object
     *            The object to be tested for equality with this entry.
     * @return {@code true} if {@code object} is an entry which is equal to this
     *         entry, or {@code false} if not.
     */
    boolean equals(Object object);
    /**
     * Returns an {@code Iterable} containing all of the attributes in this
     * entry. The returned {@code Iterable} may be used to remove attributes if
     * permitted by this entry.
     *
     * @return An {@code Iterable} containing all of the attributes.
     */
    Iterable<Attribute> getAllAttributes();
    /**
     * Returns an {@code Iterable} containing all the attributes in this entry
     * having an attribute description which is a sub-type of the provided
     * attribute description. The returned {@code Iterable} may be used to
     * remove attributes if permitted by this entry.
     *
     * @param attributeDescription
     *            The name of the attributes to be returned.
     * @return An {@code Iterable} containing the matching attributes.
     * @throws NullPointerException
     *             If {@code attributeDescription} was {@code null}.
     */
    Iterable<Attribute> getAllAttributes(AttributeDescription attributeDescription);
  /**
   * Removes all the attributes from this entry (optional operation).
   *
   * @return This entry.
   * @throws UnsupportedOperationException
   *           If this entry does not permit attributes to be removed.
   */
  Entry clearAttributes();
    /**
     * Returns an {@code Iterable} containing all the attributes in this entry
     * having an attribute description which is a sub-type of the provided
     * attribute description. The returned {@code Iterable} may be used to
     * remove attributes if permitted by this entry.
     * <p>
     * The attribute description will be decoded using the schema associated
     * with this entry (usually the default schema).
     *
     * @param attributeDescription
     *            The name of the attributes to be returned.
     * @return An {@code Iterable} containing the matching attributes.
     * @throws LocalizedIllegalArgumentException
     *             If {@code attributeDescription} could not be decoded using
     *             the schema associated with this entry.
     * @throws NullPointerException
     *             If {@code attributeDescription} was {@code null}.
     */
    Iterable<Attribute> getAllAttributes(String attributeDescription);
    /**
     * Returns the named attribute contained in this entry, or {@code null} if
     * it is not included with this entry.
     *
     * @param attributeDescription
     *            The name of the attribute to be returned.
     * @return The named attribute, or {@code null} if it is not included with
     *         this entry.
     * @throws NullPointerException
     *             If {@code attributeDescription} was {@code null}.
     */
    Attribute getAttribute(AttributeDescription attributeDescription);
    /**
     * Returns the named attribute contained in this entry, or {@code null} if
     * it is not included with this entry.
     * <p>
     * The attribute description will be decoded using the schema associated
     * with this entry (usually the default schema).
     *
     * @param attributeDescription
     *            The name of the attribute to be returned.
     * @return The named attribute, or {@code null} if it is not included with
     *         this entry.
     * @throws LocalizedIllegalArgumentException
     *             If {@code attributeDescription} could not be decoded using
     *             the schema associated with this entry.
     * @throws NullPointerException
     *             If {@code attributeDescription} was {@code null}.
     */
    Attribute getAttribute(String attributeDescription);
  /**
   * Returns {@code true} if this entry contains all of the attribute values
   * contained in {@code attribute}. If {@code attribute} is empty then this
   * method will return {@code true} if the attribute is present in this entry,
   * regardless of how many values it contains.
   *
   * @param attribute
   *          The attribute values whose presence in this entry is to be tested.
   * @param missingValues
   *          A collection into which missing values will be added, or {@code
   *          null} if missing values should not be saved.
   * @return {@code true} if this entry contains all of the attribute values
   *         contained in {@code attribute}.
   * @throws NullPointerException
   *           If {@code attribute} was {@code null}.
   */
  boolean containsAttribute(Attribute attribute,
      Collection<ByteString> missingValues);
    /**
     * Returns the number of attributes in this entry.
     *
     * @return The number of attributes.
     */
    int getAttributeCount();
    /**
     * Returns the string representation of the distinguished name of this
     * entry.
     *
     * @return The string representation of the distinguished name.
     */
    DN getName();
    /**
     * Returns the hash code for this entry. It will be calculated as the sum of
     * the hash codes of the distinguished name and all of the attributes.
     *
     * @return The hash code for this entry.
     */
    int hashCode();
  /**
   * Returns {@code true} if this entry contains all of the attribute values
   * contained in {@code values}. If {@code values} is {@code null} or empty
   * then this method will return {@code true} if the attribute is present in
   * this entry, regardless of how many values it contains.
   * <p>
   * The attribute description will be decoded using the schema associated with
   * this entry (usually the default schema).
   * <p>
   * Any attribute values which are not instances of {@code ByteString} will be
   * converted using the {@link ByteString#valueOf(Object)} method.
   *
   * @param attributeDescription
   *          The name of the attribute whose presence in this entry is to be
   *          tested.
   * @param values
   *          The attribute values whose presence in this entry is to be tested,
   *          which may be {@code null}.
   * @return {@code true} if this entry contains all of the attribute values
   *         contained in {@code values}.
   * @throws LocalizedIllegalArgumentException
   *           If {@code attributeDescription} could not be decoded using the
   *           schema associated with this entry.
   * @throws NullPointerException
   *           If {@code attributeDescription} was {@code null}.
   */
  boolean containsAttribute(String attributeDescription, Object... values);
    /**
     * Removes all of the attribute values contained in {@code attribute} from
     * this entry if it is present (optional operation). If {@code attribute} is
     * empty then the entire attribute will be removed if it is present.
     * <p>
     * <b>NOTE:</b> This method implements LDAP Modify delete semantics.
     *
     * @param attribute
     *            The attribute values to be removed from this entry, which may
     *            be empty if the entire attribute is to be removed.
     * @param missingValues
     *            A collection into which missing values will be added, or
     *            {@code null} if missing values should not be saved.
     * @return {@code true} if this entry changed as a result of this call.
     * @throws UnsupportedOperationException
     *             If this entry does not permit attributes or their values to
     *             be removed.
     * @throws NullPointerException
     *             If {@code attribute} was {@code null}.
     */
    boolean removeAttribute(Attribute attribute, Collection<ByteString> missingValues);
  /**
   * Returns {@code true} if {@code object} is an entry which is equal to this
   * entry. Two entries are considered equal if their distinguished names are
   * equal, they both have the same number of attributes, and every attribute
   * contained in the first entry is also contained in the second entry.
   *
   * @param object
   *          The object to be tested for equality with this entry.
   * @return {@code true} if {@code object} is an entry which is equal to this
   *         entry, or {@code false} if not.
   */
  boolean equals(Object object);
  /**
   * Returns an {@code Iterable} containing all of the attributes in this entry.
   * The returned {@code Iterable} may be used to remove attributes if permitted
   * by this entry.
   *
   * @return An {@code Iterable} containing all of the attributes.
   */
  Iterable<Attribute> getAllAttributes();
  /**
   * Returns an {@code Iterable} containing all the attributes in this entry
   * having an attribute description which is a sub-type of the provided
   * attribute description. The returned {@code Iterable} may be used to remove
   * attributes if permitted by this entry.
   *
   * @param attributeDescription
   *          The name of the attributes to be returned.
   * @return An {@code Iterable} containing the matching attributes.
   * @throws NullPointerException
   *           If {@code attributeDescription} was {@code null}.
   */
  Iterable<Attribute> getAllAttributes(AttributeDescription attributeDescription);
  /**
   * Returns an {@code Iterable} containing all the attributes in this entry
   * having an attribute description which is a sub-type of the provided
   * attribute description. The returned {@code Iterable} may be used to remove
   * attributes if permitted by this entry.
   * <p>
   * The attribute description will be decoded using the schema associated with
   * this entry (usually the default schema).
   *
   * @param attributeDescription
   *          The name of the attributes to be returned.
   * @return An {@code Iterable} containing the matching attributes.
   * @throws LocalizedIllegalArgumentException
   *           If {@code attributeDescription} could not be decoded using the
   *           schema associated with this entry.
   * @throws NullPointerException
   *           If {@code attributeDescription} was {@code null}.
   */
  Iterable<Attribute> getAllAttributes(String attributeDescription);
  /**
   * Returns the named attribute contained in this entry, or {@code null} if it
   * is not included with this entry.
   *
   * @param attributeDescription
   *          The name of the attribute to be returned.
   * @return The named attribute, or {@code null} if it is not included with
   *         this entry.
   * @throws NullPointerException
   *           If {@code attributeDescription} was {@code null}.
   */
  Attribute getAttribute(AttributeDescription attributeDescription);
  /**
   * Returns the named attribute contained in this entry, or {@code null} if it
   * is not included with this entry.
   * <p>
   * The attribute description will be decoded using the schema associated with
   * this entry (usually the default schema).
   *
   * @param attributeDescription
   *          The name of the attribute to be returned.
   * @return The named attribute, or {@code null} if it is not included with
   *         this entry.
   * @throws LocalizedIllegalArgumentException
   *           If {@code attributeDescription} could not be decoded using the
   *           schema associated with this entry.
   * @throws NullPointerException
   *           If {@code attributeDescription} was {@code null}.
   */
  Attribute getAttribute(String attributeDescription);
  /**
   * Returns the number of attributes in this entry.
   *
   * @return The number of attributes.
   */
  int getAttributeCount();
  /**
   * Returns the string representation of the distinguished name of this entry.
   *
   * @return The string representation of the distinguished name.
   */
  DN getName();
  /**
   * Returns the hash code for this entry. It will be calculated as the sum of
   * the hash codes of the distinguished name and all of the attributes.
   *
   * @return The hash code for this entry.
   */
  int hashCode();
  /**
   * Removes all of the attribute values contained in {@code attribute} from
   * this entry if it is present (optional operation). If {@code attribute} is
   * empty then the entire attribute will be removed if it is present.
   * <p>
   * <b>NOTE:</b> This method implements LDAP Modify delete semantics.
   *
   * @param attribute
   *          The attribute values to be removed from this entry, which may be
   *          empty if the entire attribute is to be removed.
   * @param missingValues
   *          A collection into which missing values will be added, or {@code
   *          null} if missing values should not be saved.
   * @return {@code true} if this entry changed as a result of this call.
   * @throws UnsupportedOperationException
   *           If this entry does not permit attributes or their values to be
   *           removed.
   * @throws NullPointerException
   *           If {@code attribute} was {@code null}.
   */
  boolean removeAttribute(Attribute attribute,
      Collection<ByteString> missingValues);
  /**
   * Removes the named attribute from this entry if it is present (optional
   * operation). If this attribute does not contain the attribute, the call
   * leaves this entry unchanged and returns {@code false}.
   *
   * @param attributeDescription
   *          The name of the attribute to be removed.
   * @return {@code true} if this entry changed as a result of this call.
   * @throws UnsupportedOperationException
   *           If this entry does not permit attributes to be removed.
   * @throws NullPointerException
   *           If {@code attributeDescription} was {@code null}.
   */
  boolean removeAttribute(AttributeDescription attributeDescription);
  /**
   * Removes all of the attribute values contained in {@code values} from the
   * named attribute in this entry if it is present (optional operation). If
   * {@code values} is {@code null} or empty then the entire attribute will be
   * removed if it is present.
   * <p>
   * The attribute description will be decoded using the schema associated with
   * this entry (usually the default schema).
   * <p>
   * Any attribute values which are not instances of {@code ByteString} will be
   * converted using the {@link ByteString#valueOf(Object)} method.
   * <p>
   * <b>NOTE:</b> This method implements LDAP Modify delete semantics.
   *
   * @param attributeDescription
   *          The name of the attribute whose values are to be removed.
   * @param values
   *          The attribute values to be removed from this entry, which may be
   *          {@code null} or empty if the entire attribute is to be removed.
   * @return This entry.
   * @throws LocalizedIllegalArgumentException
   *           If {@code attributeDescription} could not be decoded using the
   *           schema associated with this entry.
   * @throws UnsupportedOperationException
   *           If this entry does not permit attributes or their values to be
   *           removed.
   * @throws NullPointerException
   *           If {@code attributeDescription} was {@code null}.
   */
  Entry removeAttribute(String attributeDescription, Object... values);
  /**
   * Adds all of the attribute values contained in {@code attribute} to this
   * entry, replacing any existing attribute values (optional operation). If
   * {@code attribute} is empty then the entire attribute will be removed if it
   * is present.
   * <p>
   * <b>NOTE:</b> This method implements LDAP Modify replace semantics.
   *
   * @param attribute
   *          The attribute values to be added to this entry, replacing any
   *          existing attribute values, and which may be empty if the entire
   *          attribute is to be removed.
   * @return {@code true} if this entry changed as a result of this call.
   * @throws UnsupportedOperationException
   *           If this entry does not permit attributes or their values to be
   *           replaced.
   * @throws NullPointerException
   *           If {@code attribute} was {@code null}.
   */
  boolean replaceAttribute(Attribute attribute);
  /**
   * Adds all of the attribute values contained in {@code values} to this entry,
   * replacing any existing attribute values (optional operation). If {@code
   * values} is {@code null} or empty then the entire attribute will be removed
   * if it is present.
   * <p>
   * The attribute description will be decoded using the schema associated with
   * this entry (usually the default schema).
   * <p>
   * Any attribute values which are not instances of {@code ByteString} will be
   * converted using the {@link ByteString#valueOf(Object)} method.
   * <p>
   * <b>NOTE:</b> This method implements LDAP Modify replace semantics.
   *
   * @param attributeDescription
   *          The name of the attribute whose values are to be replaced.
   * @param values
   *          The attribute values to be added to this entry, replacing any
   *          existing attribute values, and which may be {@code null} or empty
   *          if the entire attribute is to be removed.
   * @return This entry.
   * @throws LocalizedIllegalArgumentException
   *           If {@code attributeDescription} could not be decoded using the
   *           schema associated with this entry.
   * @throws UnsupportedOperationException
   *           If this entry does not permit attributes or their values to be
   *           replaced.
   * @throws NullPointerException
   *           If {@code attribute} was {@code null}.
   */
  Entry replaceAttribute(String attributeDescription, Object... values);
  /**
   * Sets the distinguished name of this entry (optional operation).
   *
   * @param dn
   *          The distinguished name.
   * @return This entry.
   * @throws UnsupportedOperationException
   *           If this entry does not permit the distinguished name to be set.
   * @throws NullPointerException
   *           If {@code dn} was {@code null}.
   */
  Entry setName(DN dn);
    /**
     * Removes the named attribute from this entry if it is present (optional
     * operation). If this attribute does not contain the attribute, the call
     * leaves this entry unchanged and returns {@code false}.
     *
     * @param attributeDescription
     *            The name of the attribute to be removed.
     * @return {@code true} if this entry changed as a result of this call.
     * @throws UnsupportedOperationException
     *             If this entry does not permit attributes to be removed.
     * @throws NullPointerException
     *             If {@code attributeDescription} was {@code null}.
     */
    boolean removeAttribute(AttributeDescription attributeDescription);
    /**
     * Removes all of the attribute values contained in {@code values} from the
     * named attribute in this entry if it is present (optional operation). If
     * {@code values} is {@code null} or empty then the entire attribute will be
     * removed if it is present.
     * <p>
     * The attribute description will be decoded using the schema associated
     * with this entry (usually the default schema).
     * <p>
     * Any attribute values which are not instances of {@code ByteString} will
     * be converted using the {@link ByteString#valueOf(Object)} method.
     * <p>
     * <b>NOTE:</b> This method implements LDAP Modify delete semantics.
     *
     * @param attributeDescription
     *            The name of the attribute whose values are to be removed.
     * @param values
     *            The attribute values to be removed from this entry, which may
     *            be {@code null} or empty if the entire attribute is to be
     *            removed.
     * @return This entry.
     * @throws LocalizedIllegalArgumentException
     *             If {@code attributeDescription} could not be decoded using
     *             the schema associated with this entry.
     * @throws UnsupportedOperationException
     *             If this entry does not permit attributes or their values to
     *             be removed.
     * @throws NullPointerException
     *             If {@code attributeDescription} was {@code null}.
     */
    Entry removeAttribute(String attributeDescription, Object... values);
    /**
     * Adds all of the attribute values contained in {@code attribute} to this
     * entry, replacing any existing attribute values (optional operation). If
     * {@code attribute} is empty then the entire attribute will be removed if
     * it is present.
     * <p>
     * <b>NOTE:</b> This method implements LDAP Modify replace semantics.
     *
     * @param attribute
     *            The attribute values to be added to this entry, replacing any
     *            existing attribute values, and which may be empty if the
     *            entire attribute is to be removed.
     * @return {@code true} if this entry changed as a result of this call.
     * @throws UnsupportedOperationException
     *             If this entry does not permit attributes or their values to
     *             be replaced.
     * @throws NullPointerException
     *             If {@code attribute} was {@code null}.
     */
    boolean replaceAttribute(Attribute attribute);
  /**
   * Sets the distinguished name of this entry (optional operation).
   * <p>
   * The distinguished name will be decoded using the schema associated with
   * this entry (usually the default schema).
   *
   * @param dn
   *          The string representation of the distinguished name.
   * @return This entry.
   * @throws LocalizedIllegalArgumentException
   *           If {@code dn} could not be decoded using the schema associated
   *           with this entry.
   * @throws UnsupportedOperationException
   *           If this entry does not permit the distinguished name to be set.
   * @throws NullPointerException
   *           If {@code dn} was {@code null}.
   */
  Entry setName(String dn);
    /**
     * Adds all of the attribute values contained in {@code values} to this
     * entry, replacing any existing attribute values (optional operation). If
     * {@code values} is {@code null} or empty then the entire attribute will be
     * removed if it is present.
     * <p>
     * The attribute description will be decoded using the schema associated
     * with this entry (usually the default schema).
     * <p>
     * Any attribute values which are not instances of {@code ByteString} will
     * be converted using the {@link ByteString#valueOf(Object)} method.
     * <p>
     * <b>NOTE:</b> This method implements LDAP Modify replace semantics.
     *
     * @param attributeDescription
     *            The name of the attribute whose values are to be replaced.
     * @param values
     *            The attribute values to be added to this entry, replacing any
     *            existing attribute values, and which may be {@code null} or
     *            empty if the entire attribute is to be removed.
     * @return This entry.
     * @throws LocalizedIllegalArgumentException
     *             If {@code attributeDescription} could not be decoded using
     *             the schema associated with this entry.
     * @throws UnsupportedOperationException
     *             If this entry does not permit attributes or their values to
     *             be replaced.
     * @throws NullPointerException
     *             If {@code attribute} was {@code null}.
     */
    Entry replaceAttribute(String attributeDescription, Object... values);
    /**
     * Sets the distinguished name of this entry (optional operation).
     *
     * @param dn
     *            The distinguished name.
     * @return This entry.
     * @throws UnsupportedOperationException
     *             If this entry does not permit the distinguished name to be
     *             set.
     * @throws NullPointerException
     *             If {@code dn} was {@code null}.
     */
    Entry setName(DN dn);
    /**
     * Sets the distinguished name of this entry (optional operation).
     * <p>
     * The distinguished name will be decoded using the schema associated with
     * this entry (usually the default schema).
     *
     * @param dn
     *            The string representation of the distinguished name.
     * @return This entry.
     * @throws LocalizedIllegalArgumentException
     *             If {@code dn} could not be decoded using the schema
     *             associated with this entry.
     * @throws UnsupportedOperationException
     *             If this entry does not permit the distinguished name to be
     *             set.
     * @throws NullPointerException
     *             If {@code dn} was {@code null}.
     */
    Entry setName(String dn);
  /**
   * Returns a string representation of this entry.
   *
   * @return The string representation of this entry.
   */
  String toString();
    /**
     * Returns a string representation of this entry.
     *
     * @return The string representation of this entry.
     */
    String toString();
}