Interface Attributes

  • All Known Implementing Classes:
    MapAttributes

    public interface Attributes

    A collection of string attributes.

    By default, this interface provides a default implementation for all methods that perform writes to the collection. The default implementation will always throw a UnsupportedOperationException, which means the collection is read-only by default.

    If an implementation needs to also support writes it must override and implement all these default methods.

    Author:
    David M. Lloyd
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  Attributes.Entry
      The entry collection for a mapping.
      static interface  Attributes.SetEntry
      The entry collection for a mapping whose values are a distinct set.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Attributes EMPTY
      Empty, read-only attribute collection.
    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default void add​(String key, int idx, String value)
      Add a mapping for the given key at the given position.
      default boolean addAll​(String key, Collection<String> values)
      Add all the values from the given collection to the value collection for the given key.
      default boolean addAll​(Map<String,​? extends Collection<String>> map)
      Add all the values from the given map to this attributes collection.
      default void addFirst​(String key, String value)
      Add a value before the first mapping for the given key.
      default void addLast​(String key, String value)
      Add a value after the last mapping for the given key.
      default Attributes asReadOnly()
      Returns a read-only instance of this instance.
      default void clear()
      Clear this collection, resetting its size to zero.
      default boolean containsKey​(String key)
      Determine if the given key has values in this collection.
      default boolean containsValue​(String key, String value)
      Determine if the given key has a mapping for the given value in this collection.
      default List<String> copyAndRemove​(String key)
      Remove all values for the given key from this collection, copying the values into a list which is returned.
      default List<String> copyAndReplace​(String key, Collection<String> values)
      Replace the mapping for the given key with the values copied from the given collection.
      Collection<Attributes.Entry> entries()
      Get the entry collection.
      Attributes.Entry get​(String key)
      Get the collection of values for the given key.
      String get​(String key, int idx)
      Get the mapping for the given key at the given position.
      default String getFirst​(String key)
      Get the first value mapped to the given key.
      default String getLast​(String key)
      Get the last value mapped to the given key.
      default int indexOf​(String key, String value)
      Get the index of the first occurrence of the given value at the given key, if any.
      default boolean isEmpty()
      Determine if this collection is empty.
      default Set<String> keySet()
      Get a set comprised of all the keys in this collection.
      default int lastIndexOf​(String key, String value)
      Get the index of the last occurrence of the given value at the given key, if any.
      default boolean remove​(String key)
      Remove all values for the given key from this collection.
      default String remove​(String key, int idx)
      Remove and return the mapping for the given key at the given position.
      default boolean remove​(String key, int idx, String value)
      Remove the mapping for the given key at the given position if it matches the given existing value.
      default boolean removeAll​(String key, String value)
      Remove the all occurrences of the given value under the given key, if any.
      default String removeFirst​(String key)
      Remove the first value mapped to the given key.
      default boolean removeFirst​(String key, String value)
      Remove the first occurrence of the given value under the given key, if any.
      default String removeLast​(String key)
      Remove the last value mapped to the given key.
      default boolean removeLast​(String key, String value)
      Remove the last occurrence of the given value under the given key, if any.
      default void removeRange​(String key, int from, int to)
      Remove all the values for the given key between the from index (inclusive) and the to index (exclusive).
      default String set​(String key, int idx, String value)
      Modify the mapping for the given key at the given position.
      default boolean set​(String key, int idx, String expect, String update)
      Conditionally set a specific value of a given key to a new value, if the existing value matches the expect parameter.
      int size()
      Get the number of keys in this attribute collection.
      int size​(String key)
      Get the number of values mapped to the given key.
      default Collection<String> values()
      Get all the values of all the keys in this collection.
    • Field Detail

      • EMPTY

        static final Attributes EMPTY
        Empty, read-only attribute collection.
    • Method Detail

      • entries

        Collection<Attributes.Entry> entries()
        Get the entry collection. Changes to the entry collection will modify this attribute collection, if it is writable. The returned entries will remain up to date with the state of this collection.
        Returns:
        the entry collection
      • size

        int size​(String key)
        Get the number of values mapped to the given key.
        Parameters:
        key - the key
        Returns:
        the number of mapped values
      • get

        Attributes.Entry get​(String key)
        Get the collection of values for the given key. The result may implement Attributes.SetEntry if the values are distinct (for example, a role or group set).
        Parameters:
        key - the attribute name
        Returns:
        the (possibly empty) attribute value collection
      • get

        String get​(String key,
                   int idx)
        Get the mapping for the given key at the given position.
        Parameters:
        key - the key
        idx - the index
        Returns:
        the mapping value
        Throws:
        IndexOutOfBoundsException - if idx is less than 0 or greater than or equal to size(key)
      • size

        int size()
        Get the number of keys in this attribute collection.
        Returns:
        the number of keys
      • remove

        default boolean remove​(String key)
        Remove all values for the given key from this collection.
        Parameters:
        key - the key
        Returns:
        true if the key was found, false otherwise
        Throws:
        UnsupportedOperationException - if this method is not implemented and the operation is not supported
      • add

        default void add​(String key,
                         int idx,
                         String value)
        Add a mapping for the given key at the given position.
        Parameters:
        key - the key
        idx - the index
        value - the mapping value
        Throws:
        IndexOutOfBoundsException - if idx is less than 0 or greater than or equal to size(key)
        UnsupportedOperationException - if this method is not implemented and the operation is not supported
      • set

        default String set​(String key,
                           int idx,
                           String value)
        Modify the mapping for the given key at the given position.
        Parameters:
        key - the key
        idx - the index
        value - the mapping value
        Returns:
        the previous mapping value
        Throws:
        IndexOutOfBoundsException - if idx is less than 0 or greater than or equal to size(key)
        UnsupportedOperationException - if this method is not implemented and the operation is not supported
      • remove

        default String remove​(String key,
                              int idx)
        Remove and return the mapping for the given key at the given position. All later entries for that key are shifted up to fill in the gap left by the removed element.
        Parameters:
        key - the key
        idx - the index
        Returns:
        the previous mapping value
        Throws:
        IndexOutOfBoundsException - if idx is less than 0 or greater than or equal to size(key)
        UnsupportedOperationException - if this method is not implemented and the operation is not supported
      • clear

        default void clear()
        Clear this collection, resetting its size to zero.
        Throws:
        UnsupportedOperationException - if this method is not implemented and the operation is not supported
      • copyAndRemove

        default List<String> copyAndRemove​(String key)
        Remove all values for the given key from this collection, copying the values into a list which is returned.
        Parameters:
        key - the key
        Returns:
        the values as a list (not null)
      • values

        default Collection<String> values()
        Get all the values of all the keys in this collection. The returned collection can be used to modify this attributes collection.
        Returns:
        the collection of all values (not null)
      • keySet

        default Set<String> keySet()
        Get a set comprised of all the keys in this collection. The returned set can be used to modify this attributes collection.
        Returns:
        the set of all keys (not null)
      • set

        default boolean set​(String key,
                            int idx,
                            String expect,
                            String update)
        Conditionally set a specific value of a given key to a new value, if the existing value matches the expect parameter.
        Parameters:
        key - the key
        idx - the index
        expect - the expected value
        update - the value to set
        Returns:
        true if the actual value matched the expected value and was updated, false otherwise
        Throws:
        IndexOutOfBoundsException - if idx is less than 0 or greater than or equal to size(key)
      • indexOf

        default int indexOf​(String key,
                            String value)
        Get the index of the first occurrence of the given value at the given key, if any.
        Parameters:
        key - the key
        value - the value
        Returns:
        the index, or -1 if the value was not found at the given key
      • lastIndexOf

        default int lastIndexOf​(String key,
                                String value)
        Get the index of the last occurrence of the given value at the given key, if any.
        Parameters:
        key - the key
        value - the value
        Returns:
        the index, or -1 if the value was not found at the given key
      • removeRange

        default void removeRange​(String key,
                                 int from,
                                 int to)
        Remove all the values for the given key between the from index (inclusive) and the to index (exclusive).
        Parameters:
        key - the key
        from - the start index (inclusive)
        to - the end index (exclusive)
        Throws:
        IndexOutOfBoundsException - if idx is less than 0 or greater than or equal to size(key)
      • getFirst

        default String getFirst​(String key)
        Get the first value mapped to the given key.
        Parameters:
        key - the key
        Returns:
        the value
        Throws:
        IndexOutOfBoundsException - if there are no values for the given key
      • getLast

        default String getLast​(String key)
        Get the last value mapped to the given key.
        Parameters:
        key - the key
        Returns:
        the value
        Throws:
        IndexOutOfBoundsException - if there are no values for the given key
      • addFirst

        default void addFirst​(String key,
                              String value)
        Add a value before the first mapping for the given key.
        Parameters:
        key - the key
        value - the value
      • addLast

        default void addLast​(String key,
                             String value)
        Add a value after the last mapping for the given key.
        Parameters:
        key - the key
        value - the value
      • removeFirst

        default String removeFirst​(String key)
        Remove the first value mapped to the given key.
        Parameters:
        key - the key
        Returns:
        the value
        Throws:
        IndexOutOfBoundsException - if there are no values for the given key
      • removeLast

        default String removeLast​(String key)
        Remove the last value mapped to the given key.
        Parameters:
        key - the key
        Returns:
        the value
        Throws:
        IndexOutOfBoundsException - if there are no values for the given key
      • remove

        default boolean remove​(String key,
                               int idx,
                               String value)
        Remove the mapping for the given key at the given position if it matches the given existing value. All later entries for that key are shifted up to fill in the gap left by the removed element.
        Parameters:
        key - the key
        idx - the index
        value - the expected previous mapping value
        Returns:
        true if the value matched and was removed, false otherwise
        Throws:
        IndexOutOfBoundsException - if idx is less than 0 or greater than or equal to size(key)
      • removeFirst

        default boolean removeFirst​(String key,
                                    String value)
        Remove the first occurrence of the given value under the given key, if any.
        Parameters:
        key - the key
        value - the value to remove
        Returns:
        true if the value was found and removed, false otherwise
      • removeLast

        default boolean removeLast​(String key,
                                   String value)
        Remove the last occurrence of the given value under the given key, if any.
        Parameters:
        key - the key
        value - the value to remove
        Returns:
        true if the value was found and removed, false otherwise
      • removeAll

        default boolean removeAll​(String key,
                                  String value)
        Remove the all occurrences of the given value under the given key, if any.
        Parameters:
        key - the key
        value - the value to remove
        Returns:
        true if the value was found and removed, false otherwise
      • addAll

        default boolean addAll​(Map<String,​? extends Collection<String>> map)
        Add all the values from the given map to this attributes collection.
        Parameters:
        map - the map to copy from
        Returns:
        true if elements were added, false otherwise
      • addAll

        default boolean addAll​(String key,
                               Collection<String> values)
        Add all the values from the given collection to the value collection for the given key.
        Parameters:
        key - the key
        values - the values to add
        Returns:
        true if elements were added, false otherwise
      • containsKey

        default boolean containsKey​(String key)
        Determine if the given key has values in this collection.
        Parameters:
        key - the key
        Returns:
        true if the key has values, false otherwise
      • containsValue

        default boolean containsValue​(String key,
                                      String value)
        Determine if the given key has a mapping for the given value in this collection.
        Parameters:
        key - the key
        value - the value
        Returns:
        true if the key has a mapping to the given value, false otherwise
      • copyAndReplace

        default List<String> copyAndReplace​(String key,
                                            Collection<String> values)
        Replace the mapping for the given key with the values copied from the given collection.
        Parameters:
        key - the key
        values - the new values
        Returns:
        a list containing the previously mapped values
      • isEmpty

        default boolean isEmpty()
        Determine if this collection is empty.
        Returns:
        true if the collection is empty, false otherwise
      • asReadOnly

        default Attributes asReadOnly()
        Returns a read-only instance of this instance.
        Returns:
        a read-only instance of this instance.