/* * CDDL HEADER START * * The contents of this file are subject to the terms of the * Common Development and Distribution License, Version 1.0 only * (the "License"). You may not use this file except in compliance * with the License. * * You can obtain a copy of the license at * trunk/opends/resource/legal-notices/OpenDS.LICENSE * or https://OpenDS.dev.java.net/OpenDS.LICENSE. * 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/opends/resource/legal-notices/OpenDS.LICENSE. 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 * * * Copyright 2009 Sun Microsystems, Inc. */ package org.opends.sdk; import java.util.Collection; import org.opends.sdk.schema.ObjectClass; /** * An entry, comprising of a distinguished name and zero or more * attributes. *

* Some methods require a schema in order to decode their parameters * (e.g. {@link #addAttribute(String, Object...)} and * {@link #setName(String)}). In these cases the default schema is used * unless an alternative schema is specified in the {@code Entry} * constructor. The default schema is not used for any other purpose. In * particular, an {@code Entry} will permit attributes to be added which * have been decoded using a different schema. *

* Full LDAP modify semantics are provided via the {@link #addAttribute}, {@link #removeAttribute}, and {@link #replaceAttribute} methods. *

* Implementations should specify any constraints or special behavior. * In particular, which methods are supported, and the order in which * attributes are returned using the {@link #getAttributes()} method. *

* TODO: can we return collections/lists instead of iterables? *

* TODO: containsAttributeValue(String, Object) */ public interface Entry { /** * Adds all of the attribute values contained in {@code attribute} to * this entry, merging with any existing attribute values (optional * operation). If {@code attribute} is empty then this entry is left * unchanged. *

* NOTE: 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 duplicateValues) throws UnsupportedOperationException, NullPointerException; /** * Adds all of the attribute values contained in {@code attribute} to * this entry, merging with any existing attribute values (optional * operation). If {@code attribute} is empty then this entry is left * unchanged. *

* If {@code attribute} is an instance of {@code Attribute} then it * will be added to this entry as if {@link #addAttribute} was called. *

* If {@code attribute} is not an instance of {@code Attribute} then * its attribute description will be decoded using the schema * associated with this entry, and any attribute values which are not * instances of {@code ByteString} will be converted using the * {@link ByteString#valueOf(Object)} method. *

* NOTE: 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) throws UnsupportedOperationException, NullPointerException; /** * Adds all of the attribute values contained in {@code values} to * this entry, merging with any existing attribute values (optional * operation). If {@code values} is {@code null} or empty then this * entry is left unchanged. *

* The attribute description will be decoded using the schema * associated with this entry. *

* Any attribute values which are not instances of {@code ByteString} * will be converted using the {@link ByteString#valueOf(Object)} * method. *

* NOTE: 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 attribute} was {@code null}. */ Entry addAttribute(String attributeDescription, Object... values) throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; /** * 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() throws UnsupportedOperationException; /** * Indicates whether or not this entry contains the named attribute. * * @param attributeDescription * The name of the attribute. * @return {@code true} if this entry contains the named attribute, * otherwise {@code false}. * @throws NullPointerException * If {@code attributeDescription} was {@code null}. */ boolean containsAttribute(AttributeDescription attributeDescription) throws NullPointerException; /** * Indicates whether or not this entry contains the named attribute. *

* The attribute description will be decoded using the schema * associated with this entry. * * @param attributeDescription * The name of the attribute. * @return {@code true} if this entry contains the named attribute, * otherwise {@code false}. * @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) throws LocalizedIllegalArgumentException, NullPointerException; /** * Indicates whether or not this entry contains the provided object * class. * * @param objectClass * The object class. * @return {@code true} if this entry contains the object class, * otherwise {@code false}. * @throws NullPointerException * If {@code objectClass} was {@code null}. */ boolean containsObjectClass(ObjectClass objectClass) throws NullPointerException; /** * Indicates whether or not this entry contains the named object * class. * * @param objectClass * The name of the object class. * @return {@code true} if this entry contains the object class, * otherwise {@code false}. * @throws NullPointerException * If {@code objectClass} was {@code null}. */ boolean containsObjectClass(String objectClass) throws NullPointerException; /** * 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 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 findAttributes( AttributeDescription attributeDescription) throws NullPointerException; /** * 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. *

* The attribute description will be decoded using the schema * associated with this entry. * * @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 findAttributes(String attributeDescription) throws LocalizedIllegalArgumentException, NullPointerException; /** * 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) throws NullPointerException; /** * Returns the named attribute contained in this entry, or {@code * null} if it is not included with this entry. *

* The attribute description will be decoded using the schema * associated 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 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) throws LocalizedIllegalArgumentException, NullPointerException; /** * Returns the number of attributes in this entry. * * @return The number of attributes. */ int getAttributeCount(); /** * Returns an {@code Iterable} containing 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 the attributes. */ Iterable getAttributes(); /** * Returns the string representation of the distinguished name of this * entry. * * @return The string representation of the distinguished name. */ DN getName(); /** * Returns an {@code Iterable} containing the names of the object * classes in this entry. The returned {@code Iterable} may be used to * remove object classes if permitted by this entry. * * @return An {@code Iterable} containing the object classes. */ Iterable getObjectClasses(); /** * 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. *

* NOTE: 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 missingValues) throws UnsupportedOperationException, NullPointerException; /** * 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) throws UnsupportedOperationException, NullPointerException; /** * 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. *

* The attribute description will be decoded using the schema * associated with this entry. * * @param attributeDescription * The name of the attribute 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 to be removed. * @throws NullPointerException * If {@code attributeDescription} was {@code null}. */ Entry removeAttribute(String attributeDescription) throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; /** * 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. *

* The attribute description will be decoded using the schema * associated with this entry. *

* Any attribute values which are not instances of {@code ByteString} * will be converted using the {@link ByteString#valueOf(Object)} * method. *

* NOTE: 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) throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; /** * 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. *

* NOTE: 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) throws UnsupportedOperationException, NullPointerException; /** * 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. *

* The attribute description will be decoded using the schema * associated with this entry. *

* Any attribute values which are not instances of {@code ByteString} * will be converted using the {@link ByteString#valueOf(Object)} * method. *

* NOTE: 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) throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; /** * Sets the distinguished name of this entry (optional operation). * * @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) throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; /** * 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) throws UnsupportedOperationException, NullPointerException; /** * Returns a string representation of this entry. * * @return The string representation of this entry. */ String toString(); }