/*
|
* 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-2010 Sun Microsystems, Inc.
|
*/
|
|
package org.opends.sdk;
|
|
|
|
import java.util.Collection;
|
|
|
|
/**
|
* 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 multiple schemas.
|
* <p>
|
* 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.
|
* 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>
|
*
|
* @see Entries
|
*/
|
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)
|
throws UnsupportedOperationException, NullPointerException;
|
|
|
|
/**
|
* 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)
|
throws UnsupportedOperationException, NullPointerException;
|
|
|
|
/**
|
* 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)
|
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;
|
|
|
|
/**
|
* 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) throws NullPointerException;
|
|
|
|
/**
|
* 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)
|
throws LocalizedIllegalArgumentException, 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 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)
|
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.
|
* <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)
|
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.
|
* <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)
|
throws LocalizedIllegalArgumentException, NullPointerException;
|
|
|
|
/**
|
* 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)
|
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 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)
|
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.
|
* <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)
|
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.
|
* <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)
|
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;
|
|
|
|
/**
|
* 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.
|
*/
|
String toString();
|
}
|
