mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git
sdk/src/org/opends/sdk/Entry.java
@@ -31,55 +31,75 @@ import java.util.Collection; import org.opends.sdk.schema.ObjectClass; /** * An entry, comprising of a distinguished name and zero or more * attributes. * An entry, comprising of a distinguished name and zero or more attributes. * <p> * 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. * 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 multiple schemas. * <p> * Full LDAP modify semantics are provided via the {@link #addAttribute}, {@link #removeAttribute}, and {@link #replaceAttribute} methods. * Full LDAP modify semantics are provided via the {@link #addAttribute}, * {@link #removeAttribute}, and {@link #replaceAttribute} methods. * <p> * 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. * <p> * TODO: can we return collections/lists instead of iterables? * <p> * TODO: containsAttributeValue(String, Object) * Specifically: * <ul> * <li>Which methods are supported. * <li>The order in which attributes are returned using the * {@link #getAllAttributes()} method. * <li>How existing attributes are modified during calls to * {@link #addAttribute}, {@link #removeAttribute}, and * {@link #replaceAttribute} and the conditions, if any, where a reference to * the passed in attribute is maintained. * </ul> */ 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. * 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. * <p> * <b>NOTE:</b> 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. * 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. * 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 attribute} to this * entry, merging with any existing attribute values (optional operation). If * {@code attribute} is empty then this entry is left unchanged. * <p> * <b>NOTE:</b> 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}. */ @@ -90,71 +110,36 @@ /** * 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. * 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. * <p> * If {@code attribute} is an instance of {@code Attribute} then it * will be added to this entry as if {@link #addAttribute} was called. * The attribute description will be decoded using the schema associated with * this entry (usually the default schema). * <p> * 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. * <p> * <b>NOTE:</b> 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. * <p> * The attribute description will be decoded using the schema * associated with this entry. * <p> * Any attribute values which are not instances of {@code ByteString} * will be converted using the {@link ByteString#valueOf(Object)} * method. * 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 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. * 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. * 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. * If this entry does not permit attributes or their values to be * added. * @throws NullPointerException * If {@code attribute} was {@code null}. * If {@code attributeDescription} was {@code null}. */ Entry addAttribute(String attributeDescription, Object... values) throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; @@ -170,94 +155,88 @@ /** * Indicates whether or not this entry contains the named attribute. * 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 attributeDescription * The name of the attribute. * @return {@code true} if this entry contains the named attribute, * otherwise {@code false}. * @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 attributeDescription} was {@code null}. * If {@code attribute} was {@code null}. */ boolean containsAttribute(AttributeDescription attributeDescription) throws NullPointerException; boolean containsAttribute(Attribute attribute, Collection<ByteString> missingValues) throws NullPointerException; /** * Indicates whether or not this entry contains the named attribute. * 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. * 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. * @return {@code true} if this entry contains the named attribute, * otherwise {@code false}. * 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. * 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) boolean containsAttribute(String attributeDescription, Object... values) 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. * 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. * @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. * 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. @@ -265,43 +244,42 @@ * @throws NullPointerException * If {@code attributeDescription} was {@code null}. */ Iterable<Attribute> findAttributes( AttributeDescription attributeDescription) Iterable<Attribute> getAllAttributes(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. * 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. * 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. * If {@code attributeDescription} could not be decoded using the * schema associated with this entry. * @throws NullPointerException * If {@code attributeDescription} was {@code null}. */ Iterable<Attribute> findAttributes(String attributeDescription) Iterable<Attribute> getAllAttributes(String attributeDescription) throws LocalizedIllegalArgumentException, NullPointerException; /** * Returns the named attribute contained in this entry, or {@code * null} if it is not included with this entry. * 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. * @return The named attribute, or {@code null} if it is not included with * this entry. * @throws NullPointerException * If {@code attributeDescription} was {@code null}. */ @@ -311,19 +289,19 @@ /** * Returns the named attribute contained in this entry, or {@code * null} if it is not included with this entry. * 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. * 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. * @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. * If {@code attributeDescription} could not be decoded using the * schema associated with this entry. * @throws NullPointerException * If {@code attributeDescription} was {@code null}. */ @@ -342,19 +320,7 @@ /** * 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<Attribute> getAttributes(); /** * Returns the string representation of the distinguished name of this * entry. * Returns the string representation of the distinguished name of this entry. * * @return The string representation of the distinguished name. */ @@ -363,20 +329,8 @@ /** * 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<String> 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. * 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. */ @@ -385,24 +339,22 @@ /** * 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. * 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. * 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. * 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. * If this entry does not permit attributes or their values to be * removed. * @throws NullPointerException * If {@code attribute} was {@code null}. */ @@ -413,15 +365,13 @@ /** * 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}. * 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. * @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 @@ -433,84 +383,56 @@ /** * 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. * 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. * * @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 (usually the default schema). * <p> * The attribute description will be decoded using the schema * associated with this entry. * <p> * Any attribute values which are not instances of {@code ByteString} * will be converted using the {@link ByteString#valueOf(Object)} * method. * 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. * 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. * 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. * 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; 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. * 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. * 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. * If this entry does not permit attributes or their values to be * replaced. * @throws NullPointerException * If {@code attribute} was {@code null}. */ @@ -520,59 +442,38 @@ /** * 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. * 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. * 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. * 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. * 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. * 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. * 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; throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; @@ -583,8 +484,7 @@ * The distinguished name. * @return This entry. * @throws UnsupportedOperationException * If this entry does not permit the distinguished name to * be set. * If this entry does not permit the distinguished name to be set. * @throws NullPointerException * If {@code dn} was {@code null}. */ @@ -594,6 +494,28 @@ /** * 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) throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; /** * Returns a string representation of this entry. * * @return The string representation of this entry.
