Package org.forgerock.opendj.ldap

Interface Entry

All Known Subinterfaces:
SearchResultEntry
All Known Implementing Classes:
AbstractEntry, AbstractMapEntry, AddRequest, Entries.NullEntry, LinkedHashMapEntry, TreeMapEntry
public interface Entry
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. addAttribute(String, Object...) and setName(String)). In these cases the default schema is used unless an alternative schema is specified in the Entry constructor. The default schema is not used for any other purpose. In particular, an Entry may contain attributes which have been decoded using different schemas.

When determining whether an entry already contains a particular attribute, attribute descriptions will be compared using AttributeDescription.matches(org.forgerock.opendj.ldap.AttributeDescription).

Full LDAP modify semantics are provided via the addAttribute(org.forgerock.opendj.ldap.Attribute), removeAttribute(org.forgerock.opendj.ldap.Attribute, java.util.Collection<? super org.forgerock.opendj.ldap.ByteString>), and replaceAttribute(org.forgerock.opendj.ldap.Attribute) methods.

Implementations should specify any constraints or special behavior. Specifically:

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default Entry
    addAttribute(String attributeDescription, Object... values)
    Ensures that this entry contains the provided attribute and values (optional operation).
    default boolean
    addAttribute(Attribute attribute)
    Ensures that this entry contains the provided attribute and values (optional operation).
    default boolean
    addAttribute(Attribute attribute, Collection<? super ByteString> duplicateValues)
    Ensures that this entry contains the provided attribute and values (optional operation).
    default Attribute
    addAttributeIfAbsent(Attribute attribute)
    Adds the provided attribute if it is not already present in this Entry and returns null.
    default Entry
    clearAttributes()
    Removes all the attributes from this entry (optional operation).
    default boolean
    containsAnyAttributes(String attributeDescription)
    Returns true if this entry contains any non-empty attributes having an attribute description which is a sub-type of the provided attribute description.
    default boolean
    containsAnyAttributes(AttributeDescription attributeDescription)
    Returns true if this entry contains any non-empty attributes having an attribute description which is a sub-type of the provided attribute description.
    default boolean
    containsAttribute(String attributeDescription, Object... values)
    Returns true if this entry contains all of the attribute values contained in values.
    default boolean
    containsAttribute(AttributeDescription attributeDescription, Object... values)
    Returns true if this entry contains all of the attribute values contained in values.
    default boolean
    containsAttribute(Attribute attribute, Collection<? super ByteString> missingValues)
    Returns true if this entry contains all of the attribute values contained in attribute.
    boolean
    equals(Object object)
    Returns true if object is an entry which is equal to this entry.
    Iterable<Attribute>
    getAllAttributes()
    Returns an Iterable containing all of the attributes in this entry.
    default Iterable<Attribute>
    getAllAttributes(String attributeDescription)
    Returns an Iterable containing all the attributes in this entry having an attribute description which is a sub-type of the provided attribute description.
    default Iterable<Attribute>
    getAllAttributes(AttributeDescription attributeDescription)
    Returns an Iterable containing all the attributes in this entry having an attribute description which is a sub-type of the provided attribute description.
    default Attribute
    getAttribute(String attributeDescription)
    Returns the named attribute contained in this entry, or null if it is not included with this entry.
    default Attribute
    getAttribute(AttributeDescription attributeDescription)
    Returns the named attribute contained in this entry, or null if it is not included with this entry.
    int
    getAttributeCount()
    Returns the number of attributes in this entry.
    Dn
    getName()
    Returns the distinguished name of this entry.
    int
    hashCode()
    Returns the hash code for this entry.
    default Attribute
    mergeAttribute(Attribute attribute, BiFunction<? super Attribute,? super Attribute,? extends Attribute> mergeFunction)
    Adds the provided attribute if it is not already present in this Entry.
    default AttributeParser
    parseAttribute(String attributeDescription)
    Returns a parser for the named attribute contained in this entry.
    default AttributeParser
    parseAttribute(AttributeDescription attributeDescription)
    Returns a parser for the named attribute contained in this entry.
    default Entry
    removeAttribute(String attributeDescription, Object... values)
    Removes all of the attribute values contained in values from the named attribute in this entry if it is present (optional operation).
    default boolean
    removeAttribute(AttributeDescription attributeDescription)
    Removes the named attribute from this entry if it is present (optional operation).
    default boolean
    removeAttribute(Attribute attribute, Collection<? super ByteString> missingValues)
    Removes all of the attribute values contained in attribute from this entry if it is present (optional operation).
    default Entry
    replaceAttribute(String attributeDescription, Object... values)
    Adds all of the attribute values contained in values to this entry, replacing any existing attribute values (optional operation).
    default boolean
    replaceAttribute(Attribute attribute)
    Adds all of the attribute values contained in attribute to this entry, replacing any existing attribute values (optional operation).
    default Entry
    setName(String dn)
    Sets the distinguished name of this entry (optional operation).
    default Entry
    setName(Dn dn)
    Sets the distinguished name of this entry (optional operation).
    String
    toString()
    Returns a string representation of this entry.

  • Method Details

    • addAttribute

      default boolean addAttribute(Attribute attribute)
      Ensures that this entry contains the provided attribute and values (optional operation). This method has the following semantics:
      • If this entry does not already contain an attribute with a matching attribute description, then this entry will be modified such that it contains attribute, even if it is empty.
      • If this entry already contains an attribute with a matching attribute description, then the attribute values contained in attribute will be merged with the existing attribute values.

      NOTE: When attribute is non-empty, this method implements LDAP Modify add semantics.

      Parameters:
      attribute - The attribute values to be added to this entry, merging with any existing attribute values.
      Returns:
      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.
      NullPointerException - If attribute was null.

    • addAttribute

      default boolean addAttribute(Attribute attribute, Collection<? super ByteString> duplicateValues)
      Ensures that this entry contains the provided attribute and values (optional operation). This method has the following semantics:
      • If this entry does not already contain an attribute with a matching attribute description, then this entry will be modified such that it contains attribute, even if it is empty.
      • If this entry already contains an attribute with a matching attribute description, then the attribute values contained in attribute will be merged with the existing attribute values.

      NOTE: When attribute is non-empty, this method implements LDAP Modify add semantics.

      Parameters:
      attribute - The attribute values to be added to this entry, merging with any existing attribute values.
      duplicateValues - A collection into which duplicate values will be added, or null if duplicate values should not be saved.
      Returns:
      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.
      NullPointerException - If attribute was null.

    • addAttribute

      default Entry addAttribute(String attributeDescription, Object... values)
      Ensures that this entry contains the provided attribute and values (optional operation). This method has the following semantics:
      • If this entry does not already contain an attribute with a matching attribute description, then this entry will be modified such that it contains attribute, even if it is empty.
      • If this entry already contains an attribute with a matching attribute description, then the attribute values contained in attribute will be merged with the existing attribute values.

      The attribute description will be decoded using the schema associated with this entry (usually the default schema).

      Any attribute values which are not instances of ByteString will be converted using the ByteString.valueOfObject(Object) method.

      NOTE: When attribute is non-empty, this method implements LDAP Modify add semantics.

      Parameters:
      attributeDescription - The name of the attribute whose values are to be added.
      values - The attribute values to be added to this entry, merging any existing attribute values.
      Returns:
      This entry.
      Throws:
      LocalizedIllegalArgumentException - If attributeDescription could not be decoded using the schema associated with this entry.
      UnsupportedOperationException - If this entry does not permit attributes or their values to be added.
      NullPointerException - If attributeDescription was null.

    • addAttributeIfAbsent

      default Attribute addAttributeIfAbsent(Attribute attribute)
      Adds the provided attribute if it is not already present in this Entry and returns null. Otherwise returns the existing attribute.

      NOTE: this method is equivalent to Map.putIfAbsent(Object, Object).

      Parameters:
      attribute - The non-null attribute to be added if it is not already present.
      Returns:
      null if the attribute was added, or the existing attribute (in which case the entry is unchanged).
      Throws:
      UnsupportedOperationException - If this entry does not permit attributes or their values to be added.
      NullPointerException - If attribute was null.

    • clearAttributes

      default Entry clearAttributes()
      Removes all the attributes from this entry (optional operation).
      Returns:
      This entry.
      Throws:
      UnsupportedOperationException - If this entry does not permit attributes to be removed.

    • containsAttribute

      default boolean containsAttribute(Attribute attribute, Collection<? super ByteString> missingValues)
      Returns true if this entry contains all of the attribute values contained in attribute. If attribute is empty then this method will return true if the attribute is present in this entry, regardless of how many values it contains.
      Parameters:
      attribute - The attribute values whose presence in this entry is to be tested.
      missingValues - A collection into which missing values will be added, or null if missing values should not be saved.
      Returns:
      true if this entry contains all of the attribute values contained in attribute.
      Throws:
      NullPointerException - If attribute was null.

    • containsAttribute

      default boolean containsAttribute(String attributeDescription, Object... values)
      Returns true if this entry contains all of the attribute values contained in values. If values is null or empty then this method will return true if the attribute is present in this entry, regardless of how many values it contains.

      The attribute description will be decoded using the schema associated with this entry (usually the default schema).

      Any attribute values which are not instances of ByteString will be converted using the ByteString.valueOfObject(Object) method.

      Parameters:
      attributeDescription - The name of the attribute whose presence in this entry is to be tested.
      values - The attribute values whose presence in this entry is to be tested, which may be null.
      Returns:
      true if this entry contains all of the attribute values contained in values.
      Throws:
      LocalizedIllegalArgumentException - If attributeDescription could not be decoded using the schema associated with this entry.
      NullPointerException - If attributeDescription was null.

    • containsAttribute

      default boolean containsAttribute(AttributeDescription attributeDescription, Object... values)
      Returns true if this entry contains all of the attribute values contained in values. If values is null or empty then this method will return true if the attribute is present in this entry, regardless of how many values it contains.

      The attribute description will be decoded using the schema associated with this entry (usually the default schema).

      Any attribute values which are not instances of ByteString will be converted using the ByteString.valueOfObject(Object) method.

      Parameters:
      attributeDescription - The name of the attribute whose presence in this entry is to be tested.
      values - The attribute values whose presence in this entry is to be tested, which may be null.
      Returns:
      true if this entry contains all of the attribute values contained in values.
      Throws:
      LocalizedIllegalArgumentException - If attributeDescription could not be decoded using the schema associated with this entry.
      NullPointerException - If attributeDescription was null.

    • containsAnyAttributes

      default boolean containsAnyAttributes(AttributeDescription attributeDescription)
      Returns true if this entry contains any non-empty attributes having an attribute description which is a sub-type of the provided attribute description.

      NOTE: this method performs the matching defined for an LDAP search presence filter. For example, given the attribute description "name" then this method will return true if the entry contains "name", "name;option", "cn", or "cn;option". This method is NOT suitable for schema checking, which uses different matching semantics. Specifically, an entry which MUST contain "name" is not valid if it contains "cn", but not "name". See RFC 4512 - Attribute Description Hierarchies.

      Parameters:
      attributeDescription - The name of the attribute whose presence in this entry is to be tested.
      Returns:
      true if this entry contains any non-empty attributes having an attribute description which is a sub-type of the provided attribute description.
      Throws:
      NullPointerException - If attributeDescription was null.

    • containsAnyAttributes

      default boolean containsAnyAttributes(String attributeDescription)
      Returns true if this entry contains any non-empty attributes having an attribute description which is a sub-type of the provided attribute description.

      NOTE: this method performs the matching defined for an LDAP search presence filter. For example, given the attribute description "name" then this method will return true if the entry contains "name", "name;option", "cn", or "cn;option". This method is NOT suitable for schema checking, which uses different matching semantics. Specifically, an entry which MUST contain "name" is not valid if it contains "cn", but not "name". See RFC 4512 - Attribute Description Hierarchies.

      Parameters:
      attributeDescription - The name of the attribute whose presence in this entry is to be tested.
      Returns:
      true if this entry contains any non-empty attributes having an attribute description which is a sub-type of the provided attribute description.
      Throws:
      NullPointerException - If attributeDescription was null.

    • equals

      boolean equals(Object object)
      Returns true if 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.
      Overrides:
      equals in class Object
      Parameters:
      object - The object to be tested for equality with this entry.
      Returns:
      true if object is an entry which is equal to this entry, or false if not.

    • getAllAttributes

      Iterable<Attribute> getAllAttributes()
      Returns an Iterable containing all of the attributes in this entry. The returned Iterable may be used to remove attributes if permitted by this entry.
      Returns:
      An Iterable containing all of the attributes.

    • getAllAttributes

      default Iterable<Attribute> getAllAttributes(AttributeDescription attributeDescription)
      Returns an Iterable containing all the attributes in this entry having an attribute description which is a sub-type of the provided attribute description. The returned Iterable may be used to remove attributes if permitted by this entry.
      Parameters:
      attributeDescription - The name of the attributes to be returned.
      Returns:
      An Iterable containing the matching attributes.
      Throws:
      NullPointerException - If attributeDescription was null.

    • getAllAttributes

      default Iterable<Attribute> getAllAttributes(String attributeDescription)
      Returns an Iterable containing all the attributes in this entry having an attribute description which is a sub-type of the provided attribute description. The returned 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 (usually the default schema).

      Parameters:
      attributeDescription - The name of the attributes to be returned.
      Returns:
      An Iterable containing the matching attributes.
      Throws:
      LocalizedIllegalArgumentException - If attributeDescription could not be decoded using the schema associated with this entry.
      NullPointerException - If attributeDescription was null.

    • getAttribute

      default Attribute getAttribute(AttributeDescription attributeDescription)
      Returns the named attribute contained in this entry, or null if it is not included with this entry.
      Parameters:
      attributeDescription - The name of the attribute to be returned.
      Returns:
      The named attribute, or null if it is not included with this entry.
      Throws:
      NullPointerException - If attributeDescription was null.

    • getAttribute

      default Attribute getAttribute(String attributeDescription)
      Returns the named attribute contained in this entry, or null if it is not included with this entry.

      The attribute description will be decoded using the schema associated with this entry (usually the default schema).

      Parameters:
      attributeDescription - The name of the attribute to be returned.
      Returns:
      The named attribute, or null if it is not included with this entry.
      Throws:
      LocalizedIllegalArgumentException - If attributeDescription could not be decoded using the schema associated with this entry.
      NullPointerException - If attributeDescription was null.

    • getAttributeCount

      int getAttributeCount()
      Returns the number of attributes in this entry.
      Returns:
      The number of attributes.

    • getName

      Dn getName()
      Returns the distinguished name of this entry.
      Returns:
      The distinguished name of this entry.

    • hashCode

      int hashCode()
      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.
      Overrides:
      hashCode in class Object
      Returns:
      The hash code for this entry.

    • mergeAttribute

      default Attribute mergeAttribute(Attribute attribute, BiFunction<? super Attribute,? super Attribute,? extends Attribute> mergeFunction)
      Adds the provided attribute if it is not already present in this Entry. Otherwise, replaces the existing attribute with the results of the remapping function, or removes it if the result is null.

      NOTE: this method is equivalent to Map.merge(Object, Object, BiFunction).

      Parameters:
      attribute - The non-null attribute to be added or merged with the existing attribute.
      mergeFunction - The function to recompute the attribute if it is already present in this Entry.
      Returns:
      The attribute that was added or merged, or null if the attribute was removed.
      Throws:
      UnsupportedOperationException - If this entry does not permit attributes or their values to be removed.
      NullPointerException - If attribute or remappingFunction was null.

    • parseAttribute

      default AttributeParser parseAttribute(AttributeDescription attributeDescription)
      Returns a parser for the named attribute contained in this entry.
      Parameters:
      attributeDescription - The name of the attribute to be parsed.
      Returns:
      A parser for the named attribute.
      Throws:
      NullPointerException - If attributeDescription was null.

    • parseAttribute

      default AttributeParser parseAttribute(String attributeDescription)
      Returns a parser for the named attribute contained in this entry.

      The attribute description will be decoded using the schema associated with this entry (usually the default schema).

      Parameters:
      attributeDescription - The name of the attribute to be parsed.
      Returns:
      A parser for the named attribute.
      Throws:
      LocalizedIllegalArgumentException - If attributeDescription could not be decoded using the schema associated with this entry.
      NullPointerException - If attributeDescription was null.

    • removeAttribute

      default boolean removeAttribute(Attribute attribute, Collection<? super ByteString> missingValues)
      Removes all of the attribute values contained in attribute from this entry if it is present (optional operation). If attribute is empty then the entire attribute will be removed if it is present.

      NOTE: This method implements LDAP Modify delete semantics.

      Parameters:
      attribute - The attribute values to be removed from this entry, which may be empty if the entire attribute is to be removed.
      missingValues - A collection into which missing values will be added, or null if missing values should not be saved.
      Returns:
      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.
      NullPointerException - If attribute was null.

    • removeAttribute

      default boolean removeAttribute(AttributeDescription attributeDescription)
      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 false.
      Parameters:
      attributeDescription - The name of the attribute to be removed.
      Returns:
      true if this entry changed as a result of this call.
      Throws:
      UnsupportedOperationException - If this entry does not permit attributes to be removed.
      NullPointerException - If attributeDescription was null.

    • removeAttribute

      default Entry removeAttribute(String attributeDescription, Object... values)
      Removes all of the attribute values contained in values from the named attribute in this entry if it is present (optional operation). If values is 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).

      Any attribute values which are not instances of ByteString will be converted using the ByteString.valueOfObject(Object) method.

      NOTE: This method implements LDAP Modify delete semantics.

      Parameters:
      attributeDescription - The name of the attribute whose values are to be removed.
      values - The attribute values to be removed from this entry, which may be null or empty if the entire attribute is to be removed.
      Returns:
      This entry.
      Throws:
      LocalizedIllegalArgumentException - If attributeDescription could not be decoded using the schema associated with this entry.
      UnsupportedOperationException - If this entry does not permit attributes or their values to be removed.
      NullPointerException - If attributeDescription was null.

    • replaceAttribute

      default boolean replaceAttribute(Attribute attribute)
      Adds all of the attribute values contained in attribute to this entry, replacing any existing attribute values (optional operation). If attribute is empty then the entire attribute will be removed if it is present.

      NOTE: This method implements LDAP Modify replace semantics as described in RFC 4511 - Section 4.6. Modify Operation.

      Parameters:
      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.
      Returns:
      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.
      NullPointerException - If attribute was null.

    • replaceAttribute

      default Entry replaceAttribute(String attributeDescription, Object... values)
      Adds all of the attribute values contained in values to this entry, replacing any existing attribute values (optional operation). If values is 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).

      Any attribute values which are not instances of ByteString will be converted using the ByteString.valueOfObject(Object) method.

      NOTE: This method implements LDAP Modify replace semantics as described in RFC 4511 - Section 4.6. Modify Operation.

      Parameters:
      attributeDescription - The name of the attribute whose values are to be replaced.
      values - The attribute values to be added to this entry, replacing any existing attribute values, and which may be null or empty if the entire attribute is to be removed.
      Returns:
      This entry.
      Throws:
      LocalizedIllegalArgumentException - If attributeDescription could not be decoded using the schema associated with this entry.
      UnsupportedOperationException - If this entry does not permit attributes or their values to be replaced.
      NullPointerException - If attribute was null.

    • setName

      default Entry setName(Dn dn)
      Sets the distinguished name of this entry (optional operation).
      Parameters:
      dn - The distinguished name.
      Returns:
      This entry.
      Throws:
      UnsupportedOperationException - If this entry does not permit the distinguished name to be set.
      NullPointerException - If dn was null.

    • setName

      default Entry setName(String dn)
      Sets the distinguished name of this entry (optional operation).

      The distinguished name will be decoded using the schema associated with this entry (usually the default schema).

      Parameters:
      dn - The string representation of the distinguished name.
      Returns:
      This entry.
      Throws:
      LocalizedIllegalArgumentException - If dn could not be decoded using the schema associated with this entry.
      UnsupportedOperationException - If this entry does not permit the distinguished name to be set.
      NullPointerException - If dn was null.

    • toString

      String toString()
      Returns a string representation of this entry.
      Overrides:
      toString in class Object
      Returns:
      The string representation of this entry.