Package org.forgerock.opendj.ldap

Interface Attribute

  • All Superinterfaces:
    Collection<ByteString>, Iterable<ByteString>
    All Known Implementing Classes:
    AbstractAttribute, EntryHistoricalAttribute, LinkedAttribute
    public interface Attribute
extends Collection<ByteString>
    An attribute, comprising of an attribute description and zero or more attribute values.

    Any methods which perform comparisons between attribute values use the equality matching rule associated with the attribute description.

    Any methods which accept Object based attribute values convert the attribute values to instances of ByteString using ByteString.valueOfObject(Object).

    This class is conceptually a mathematical Set<ByteString>.
    However, this is declared to implement Collection<ByteString> because java's Set.equals(Object) requires that all sets should be equal with any other set. This is impossible for an attribute because it is testing attribute description's equality.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default boolean add​(Object... values)
      Adds all of the provided attribute values to this attribute if they are not already present (optional operation).
      default boolean add​(ByteString value)
      Adds value to this attribute if it is not already present (optional operation).
      default boolean addAll​(Collection<? extends ByteString> values)
      Adds all of the attribute values contained in values to this attribute if they are not already present (optional operation).
      default <T> boolean addAll​(Collection<T> values, Collection<? super T> duplicateValues)
      Adds all of the attribute values contained in values to this attribute if they are not already present (optional operation).
      default void clear()
      Removes all of the attribute values from this attribute (optional operation).
      boolean contains​(Object value)
      Returns true if this attribute contains value.
      boolean containsAll​(Collection<?> values)
      Returns true if this attribute contains all of the attribute values contained in values.
      boolean equals​(Object object)
      Returns true if object is an attribute which is equal to this attribute.
      ByteString firstValue()
      Returns the first attribute value in this attribute.
      default String firstValueAsString()
      Returns the first attribute value in this attribute decoded as a UTF-8 string.
      AttributeDescription getAttributeDescription()
      Returns the attribute description of this attribute, which includes its attribute type and any options.
      default String getAttributeDescriptionAsString()
      Returns the string representation of the attribute description of this attribute, which includes its attribute type and any options.
      int hashCode()
      Returns the hash code for this attribute.
      boolean isEmpty()
      Returns true if this attribute contains no attribute values.
      default boolean isReal()
      Indicates whether this is a real attribute (persisted) rather than a virtual attribute (dynamically computed).
      boolean isVirtual()
      Indicates whether this is a virtual attribute (dynamically computed) rather than a real attribute (persisted).
      Iterator<ByteString> iterator()
      Returns an iterator over the attribute values in this attribute.
      ConditionResult matchesApproximateAssertion​(Assertion assertion, ByteSequence rawAssertion)
      Indicates whether this attribute matches the specified assertion using the attribute's default approximate matching rule.
      ConditionResult matchesEqualityAssertion​(Assertion assertion, ByteSequence rawAssertion)
      Indicates whether this attribute matches the specified assertion using the attribute's default equality matching rule.
      ConditionResult matchesGreaterOrEqualAssertion​(Assertion assertion, ByteSequence rawAssertion)
      Indicates whether this attribute matches the specified assertion using the attribute's default ordering matching rule.
      ConditionResult matchesLessOrEqualAssertion​(Assertion assertion, ByteSequence rawAssertion)
      Indicates whether this attribute matches the specified assertion using the attribute's default ordering matching rule.
      ConditionResult matchesSubstringAssertion​(Assertion assertion, ByteSequence rawInitialSubstring, List<? extends ByteSequence> rawAnySubstrings, ByteSequence rawFinalSubstring)
      Indicates whether this attribute matches the specified assertion using the attribute's default ordering matching rule.
      AttributeParser parse()
      Returns a parser for this attribute which can be used for decoding values as different types of object.
      default Attribute put​(Object... values)
      Adds all of the provided attribute values to this attribute if they are not already present (optional operation).
      default Attribute put​(ByteString value)
      Adds value to this attribute if it is not already present (optional operation).
      default boolean remove​(Object value)
      Removes value from this attribute if it is present (optional operation).
      default boolean removeAll​(Collection<?> values)
      Removes all of the attribute values contained in values from this attribute if they are present (optional operation).
      default <T> boolean removeAll​(Collection<T> values, Collection<? super T> missingValues)
      Removes all of the attribute values contained in values from this attribute if they are present (optional operation).
      default boolean retainAll​(Collection<?> values)
      Retains only the attribute values in this attribute which are contained in values (optional operation).
      default <T> boolean retainAll​(Collection<T> values, Collection<? super T> missingValues)
      Retains only the attribute values in this attribute which are contained in values (optional operation).
      int size()
      Returns the number of attribute values in this attribute.
      ByteString[] toArray()
      Returns an array containing all of the attribute values contained in this attribute.
      <T> T[] toArray​(T[] array)
      Returns an array containing all of the attribute values in this attribute; the runtime type of the returned array is that of the specified array.
      String toString()
      Returns a string representation of this attribute.

    • Method Detail

      • add

        default boolean add​(ByteString value)
        Adds value to this attribute if it is not already present (optional operation). If this attribute already contains value, the call leaves the attribute unchanged and returns false.
        Specified by:
        add in interface Collection<ByteString>
        Parameters:
        value - The attribute value to be added to this attribute.
        Returns:
        true if this attribute changed as a result of this call.
        Throws:
        UnsupportedOperationException - If this attribute does not support addition of attribute values.
        NullPointerException - If value was null.

      • put

        default Attribute put​(ByteString value)
        Adds value to this attribute if it is not already present (optional operation).

        If this attribute already contains value, the call leaves the attribute unchanged. This method is equivalent to add(ByteString) except that it is designed for chaining by returning a reference to the updated attribute.

        Parameters:
        value - The attribute value to be added to this attribute.
        Returns:
        This attribute.
        Throws:
        UnsupportedOperationException - If this attribute does not support addition of attribute values.
        NullPointerException - If value was null.

      • add

        default boolean add​(Object... values)
        Adds all of the provided attribute values to this attribute if they are not already present (optional operation).

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

        Parameters:
        values - The attribute values to be added to this attribute.
        Returns:
        true if this attribute changed as a result of this call.
        Throws:
        UnsupportedOperationException - If this attribute does not support addition of attribute values.
        NullPointerException - If values was null.

      • put

        default Attribute put​(Object... values)
        Adds all of the provided attribute values to this attribute if they are not already present (optional operation).

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

        This method is equivalent to add(Object...) except that it is designed for chaining by returning a reference to the updated attribute.

        Parameters:
        values - The attribute values to be added to this attribute.
        Returns:
        This attribute.
        Throws:
        UnsupportedOperationException - If this attribute does not support addition of attribute values.
        NullPointerException - If values was null.

      • addAll

        default boolean addAll​(Collection<? extends ByteString> values)
        Adds all of the attribute values contained in values to this attribute if they are not already present (optional operation).

        An invocation of this method is equivalent to: 

         attribute.addAll(values, null);
        Specified by:
        addAll in interface Collection<ByteString>
        Parameters:
        values - The attribute values to be added to this attribute.
        Returns:
        true if this attribute changed as a result of this call.
        Throws:
        UnsupportedOperationException - If this attribute does not support addition of attribute values.
        NullPointerException - If values was null.

      • addAll

        default <T> boolean addAll​(Collection<T> values,
                           Collection<? super T> duplicateValues)
        Adds all of the attribute values contained in values to this attribute if they are not already present (optional operation). Any attribute values which are already present will be added to duplicateValues if specified.

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

        Type Parameters:
        T - The type of the attribute value objects being added.
        Parameters:
        values - The attribute values to be added to this attribute.
        duplicateValues - A collection into which duplicate values will be added, or null if duplicate values should not be saved.
        Returns:
        true if this attribute changed as a result of this call.
        Throws:
        UnsupportedOperationException - If this attribute does not support addition of attribute values.
        NullPointerException - If values was null.

      • clear

        default void clear()
        Removes all of the attribute values from this attribute (optional operation). This attribute will be empty after this call returns.
        Specified by:
        clear in interface Collection<ByteString>
        Throws:
        UnsupportedOperationException - If this attribute does not support removal of attribute values.

      • contains

        boolean contains​(Object value)
        Returns true if this attribute contains value.

        If value is not an instance of ByteString then it will be converted using the ByteString.valueOfObject(Object) method.

        Specified by:
        contains in interface Collection<ByteString>
        Parameters:
        value - The attribute value whose presence in this attribute is to be tested.
        Returns:
        true if this attribute contains value, or false if not.
        Throws:
        NullPointerException - If value was null.

      • containsAll

        boolean containsAll​(Collection<?> values)
        Returns true if this attribute contains all of the attribute values contained in values.

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

        Specified by:
        containsAll in interface Collection<ByteString>
        Parameters:
        values - The attribute values whose presence in this attribute is to be tested.
        Returns:
        true if this attribute contains all of the attribute values contained in values, or false if not.
        Throws:
        NullPointerException - If values was null.

      • equals

        boolean equals​(Object object)
        Returns true if object is an attribute which is equal to this attribute. Two attributes are considered equal if their attribute descriptions are equal, they both have the same number of attribute values, and every attribute value contained in the first attribute is also contained in the second attribute.
        Specified by:
        equals in interface Collection<ByteString>
        Overrides:
        equals in class Object
        Parameters:
        object - The object to be tested for equality with this attribute.
        Returns:
        true if object is an attribute which is equal to this attribute, or false if not.

      • firstValue

        ByteString firstValue()
        Returns the first attribute value in this attribute.
        Returns:
        The first attribute value in this attribute.
        Throws:
        NoSuchElementException - If this attribute is empty.

      • firstValueAsString

        default String firstValueAsString()
        Returns the first attribute value in this attribute decoded as a UTF-8 string.
        Returns:
        The first attribute value in this attribute decoded as a UTF-8 string.
        Throws:
        NoSuchElementException - If this attribute is empty.

      • getAttributeDescription

        AttributeDescription getAttributeDescription()
        Returns the attribute description of this attribute, which includes its attribute type and any options.
        Returns:
        The attribute description.

      • getAttributeDescriptionAsString

        default String getAttributeDescriptionAsString()
        Returns the string representation of the attribute description of this attribute, which includes its attribute type and any options.
        Returns:
        The string representation of the attribute description.

      • hashCode

        int hashCode()
        Returns the hash code for this attribute. It will be calculated as the sum of the hash codes of the attribute description and all of the attribute values.
        Specified by:
        hashCode in interface Collection<ByteString>
        Overrides:
        hashCode in class Object
        Returns:
        The hash code for this attribute.

      • isEmpty

        boolean isEmpty()
        Returns true if this attribute contains no attribute values.
        Specified by:
        isEmpty in interface Collection<ByteString>
        Returns:
        true if this attribute contains no attribute values.

      • isReal

        default boolean isReal()
        Indicates whether this is a real attribute (persisted) rather than a virtual attribute (dynamically computed).
        Returns:
        true if this is a real attribute.

      • isVirtual

        boolean isVirtual()
        Indicates whether this is a virtual attribute (dynamically computed) rather than a real attribute (persisted).
        Returns:
        true if this is a virtual attribute.

      • iterator

        Iterator<ByteString> iterator()
        Returns an iterator over the attribute values in this attribute. The attribute values are returned in no particular order, unless the implementation of this attribute provides such a guarantee.
        Specified by:
        iterator in interface Collection<ByteString>
        Specified by:
        iterator in interface Iterable<ByteString>
        Returns:
        An iterator over the attribute values in this attribute.

      • matchesApproximateAssertion

        ConditionResult matchesApproximateAssertion​(Assertion assertion,
                                            ByteSequence rawAssertion)
        Indicates whether this attribute matches the specified assertion using the attribute's default approximate matching rule.
        Parameters:
        assertion - The attribute value assertion compiled using the attribute's default approximate matching rule.
        rawAssertion - The raw assertion value whose syntax is compatible with the attribute's default approximate matching rule.
        Returns:
        ConditionResult.FALSE if the assertion does not match any values in this attribute, ConditionResult.TRUE if the assertion matches at least one value in this attribute, or ConditionResult.UNDEFINED if the assertion does not match any values in this attribute, but one or more values could not be compared because they are incompatible with the matching rule.

      • matchesEqualityAssertion

        ConditionResult matchesEqualityAssertion​(Assertion assertion,
                                         ByteSequence rawAssertion)
        Indicates whether this attribute matches the specified assertion using the attribute's default equality matching rule.
        Parameters:
        assertion - The attribute value assertion compiled using the attribute's default equality matching rule.
        rawAssertion - The raw assertion value whose syntax is compatible with the attribute's default equality matching rule.
        Returns:
        ConditionResult.FALSE if the assertion does not match any values in this attribute, ConditionResult.TRUE if the assertion matches at least one value in this attribute, or ConditionResult.UNDEFINED if the assertion does not match any values in this attribute, but one or more values could not be compared because they are incompatible with the matching rule.

      • matchesGreaterOrEqualAssertion

        ConditionResult matchesGreaterOrEqualAssertion​(Assertion assertion,
                                               ByteSequence rawAssertion)
        Indicates whether this attribute matches the specified assertion using the attribute's default ordering matching rule.
        Parameters:
        assertion - The attribute value assertion compiled using the attribute's default ordering matching rule.
        rawAssertion - The raw assertion value whose syntax is compatible with the attribute's default ordering matching rule.
        Returns:
        ConditionResult.FALSE if the assertion does not match any values in this attribute, ConditionResult.TRUE if the assertion matches at least one value in this attribute, or ConditionResult.UNDEFINED if the assertion does not match any values in this attribute, but one or more values could not be compared because they are incompatible with the matching rule.

      • matchesLessOrEqualAssertion

        ConditionResult matchesLessOrEqualAssertion​(Assertion assertion,
                                            ByteSequence rawAssertion)
        Indicates whether this attribute matches the specified assertion using the attribute's default ordering matching rule.
        Parameters:
        assertion - The attribute value assertion compiled using the attribute's default ordering matching rule.
        rawAssertion - The raw assertion value whose syntax is compatible with the attribute's default ordering matching rule.
        Returns:
        ConditionResult.FALSE if the assertion does not match any values in this attribute, ConditionResult.TRUE if the assertion matches at least one value in this attribute, or ConditionResult.UNDEFINED if the assertion does not match any values in this attribute, but one or more values could not be compared because they are incompatible with the matching rule.

      • matchesSubstringAssertion

        ConditionResult matchesSubstringAssertion​(Assertion assertion,
                                          ByteSequence rawInitialSubstring,
                                          List<? extends ByteSequence> rawAnySubstrings,
                                          ByteSequence rawFinalSubstring)
        Indicates whether this attribute matches the specified assertion using the attribute's default ordering matching rule.
        Parameters:
        assertion - The attribute value assertion compiled using the attribute's default ordering matching rule.
        rawInitialSubstring - The assertion's initial sub-string, may be null if either rawFinalSubstring or rawAnySubstrings are specified.
        rawAnySubstrings - The assertion's intermediate sub-strings, may be empty if either rawFinalSubstring or rawAnySubstrings are specified.
        rawFinalSubstring - The final sub-string, may be null if either rawInitialSubstring or rawAnySubstrings are specified.
        Returns:
        ConditionResult.FALSE if the assertion does not match any values in this attribute, ConditionResult.TRUE if the assertion matches at least one value in this attribute, or ConditionResult.UNDEFINED if the assertion does not match any values in this attribute, but one or more values could not be compared because they are incompatible with the matching rule.

      • parse

        AttributeParser parse()
        Returns a parser for this attribute which can be used for decoding values as different types of object.
        Returns:
        A parser for this attribute.

      • remove

        default boolean remove​(Object value)
        Removes value from this attribute if it is present (optional operation). If this attribute does not contain value, the call leaves the attribute unchanged and returns false.

        If value is not an instance of ByteString then it will be converted using the ByteString.valueOfObject(Object) method.

        Specified by:
        remove in interface Collection<ByteString>
        Parameters:
        value - The attribute value to be removed from this attribute.
        Returns:
        true if this attribute changed as a result of this call.
        Throws:
        UnsupportedOperationException - If this attribute does not support removal of attribute values.
        NullPointerException - If value was null.

      • removeAll

        default boolean removeAll​(Collection<?> values)
        Removes all of the attribute values contained in values from this attribute if they are present (optional operation).

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

        An invocation of this method is equivalent to: 

         attribute.removeAll(values, null);
        Specified by:
        removeAll in interface Collection<ByteString>
        Parameters:
        values - The attribute values to be removed from this attribute.
        Returns:
        true if this attribute changed as a result of this call.
        Throws:
        UnsupportedOperationException - If this attribute does not support removal of attribute values.
        NullPointerException - If values was null.

      • removeAll

        default <T> boolean removeAll​(Collection<T> values,
                              Collection<? super T> missingValues)
        Removes all of the attribute values contained in values from this attribute if they are present (optional operation). Any attribute values which are not already present will be added to missingValues if specified.

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

        Type Parameters:
        T - The type of the attribute value objects being removed.
        Parameters:
        values - The attribute values to be removed from this attribute.
        missingValues - A collection into which missing values will be added, or null if missing values should not be saved.
        Returns:
        true if this attribute changed as a result of this call.
        Throws:
        UnsupportedOperationException - If this attribute does not support removal of attribute values.
        NullPointerException - If values was null.

      • retainAll

        default boolean retainAll​(Collection<?> values)
        Retains only the attribute values in this attribute which are contained in values (optional operation).

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

        An invocation of this method is equivalent to: 

         attribute.retainAll(values, null);
        Specified by:
        retainAll in interface Collection<ByteString>
        Parameters:
        values - The attribute values to be retained in this attribute.
        Returns:
        true if this attribute changed as a result of this call.
        Throws:
        UnsupportedOperationException - If this attribute does not support removal of attribute values.
        NullPointerException - If values was null.

      • retainAll

        default <T> boolean retainAll​(Collection<T> values,
                              Collection<? super T> missingValues)
        Retains only the attribute values in this attribute which are contained in values (optional operation). Any attribute values which are not already present will be added to missingValues if specified.

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

        Type Parameters:
        T - The type of the attribute value objects being retained.
        Parameters:
        values - The attribute values to be retained in this attribute.
        missingValues - A collection into which missing values will be added, or null if missing values should not be saved.
        Returns:
        true if this attribute changed as a result of this call.
        Throws:
        UnsupportedOperationException - If this attribute does not support removal of attribute values.
        NullPointerException - If values was null.

      • size

        int size()
        Returns the number of attribute values in this attribute.
        Specified by:
        size in interface Collection<ByteString>
        Returns:
        The number of attribute values in this attribute.

      • toArray

        ByteString[] toArray()
        Returns an array containing all of the attribute values contained in this attribute.

        If this attribute makes any guarantees as to what order its attribute values are returned by its iterator, this method must return the attribute values in the same order.

        The returned array will be "safe" in that no references to it are maintained by this attribute. The caller is thus free to modify the returned array.

        Specified by:
        toArray in interface Collection<ByteString>
        Returns:
        An array containing all of the attribute values contained in this attribute.

      • toArray

        <T> T[] toArray​(T[] array)
        Returns an array containing all of the attribute values in this attribute; the runtime type of the returned array is that of the specified array.

        If the set fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this attribute. If this attribute fits in the specified array with room to spare (i.e., the array has more elements than this attribute), the elements in the array immediately following the end of the set is set to null.

        If this attribute makes any guarantees as to what order its attribute values are returned by its iterator, this method must return the attribute values in the same order.

        Specified by:
        toArray in interface Collection<ByteString>
        Type Parameters:
        T - The type of elements contained in array.
        Parameters:
        array - An array into which the elements of this attribute should be put.
        Returns:
        An array containing all of the attribute values contained in this attribute.
        Throws:
        ArrayStoreException - If the runtime type of array is not a supertype of ByteString.
        NullPointerException - If array was null.

      • toString

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