Package org.protelis.lang.datatype

Interface Field<T>

  • Type Parameters:
    T - the data type carried by field values
    All Superinterfaces:
    java.io.Serializable
    All Known Implementing Classes:
    AbstractField, FieldMapImpl, LazyField
    public interface Field<T>
extends java.io.Serializable
    A field associates a collection of devices to values. One such device is the local one.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  Field.Builder<T>
      Builder for Fields.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default boolean containsKey​(DeviceUID id)
      Verifies if some device has an entry in this field.
      default java.util.Map.Entry<DeviceUID,​T> foldExcludingLocal​(java.util.Map.Entry<DeviceUID,​T> base, java.util.function.BinaryOperator<java.util.Map.Entry<DeviceUID,​T>> combiner)
      Reduction operation with base value (fold), which does not consider the local value, and whose computation has base as initial element.
      default <R> R foldExcludingLocal​(R base, java.util.function.Function<java.util.Map.Entry<DeviceUID,​T>,​R> mapper, java.util.function.BinaryOperator<R> combiner)
      Reduction operation with base value (fold), which does not consider the local value, and whose computation has base as initial element.
      default java.util.Map.Entry<DeviceUID,​T> foldIncludingLocal​(java.util.function.BinaryOperator<java.util.Map.Entry<DeviceUID,​T>> combiner)
      Reduction operation with base value (fold), which uses the local value as initial element.
      default <R> R foldIncludingLocal​(java.util.function.Function<java.util.Map.Entry<DeviceUID,​T>,​R> mapper, java.util.function.BinaryOperator<R> combiner)
      Reduction operation with base value (fold), which uses the local value as initial element.
      default DeviceUID foldKeysExcludingLocal​(DeviceUID base, java.util.function.BinaryOperator<DeviceUID> combiner)
      Reduction operation over keys with base value (fold), which does not consider the local key, and whose computation has base as initial element.
      default DeviceUID foldKeysIncludingLocal​(java.util.function.BinaryOperator<DeviceUID> combiner)
      Reduction operation over keys with base value (fold), which uses the local value as initial element.
      default T foldValuesExcludingLocal​(T base, java.util.function.BinaryOperator<T> combiner)
      Reduction operation over values with base value (fold), which does not consider the local key, and whose computation has base as initial element.
      default T foldValuesIncludingLocal​(java.util.function.BinaryOperator<T> combiner)
      Reduction operation over values with base value (fold), which uses the local value as initial element.
      default T get​(DeviceUID id)  
      default java.lang.Class<? extends T> getExpectedType()  
      default java.util.Optional<T> getIfPresent​(DeviceUID id)  
      default java.util.Map.Entry<DeviceUID,​T> getLocal()  
      DeviceUID getLocalDevice()  
      default T getLocalValue()  
      default boolean isEmpty()  
      java.lang.Iterable<? extends java.util.Map.Entry<DeviceUID,​T>> iterable()  
      default java.lang.Iterable<DeviceUID> keys()  
      default java.util.stream.Stream<DeviceUID> keyStream()  
      default <R> Field<R> map​(java.util.function.Function<DeviceUID,​R> mapper)
      Map operation over this field, returning a new field whose values are provided by the mapper function.
      default Field<T> projectOn​(Field<?> restricted)
      Project this field over a restricted domain.
      default Option<java.util.Map.Entry<DeviceUID,​T>> reduce​(java.util.function.BinaryOperator<java.util.Map.Entry<DeviceUID,​T>> combiner)
      Reduction operation over the field.
      default <R> Option<R> reduce​(java.util.function.Function<java.util.Map.Entry<DeviceUID,​T>,​R> mapper, java.util.function.BinaryOperator<R> combiner)
      Reduction operation over the field.
      default Option<DeviceUID> reduceKeys​(java.util.function.BinaryOperator<DeviceUID> combiner)
      Reduction operation over the field's keys.
      default Option<T> reduceValues​(java.util.function.BinaryOperator<T> combiner)
      Reduction operation over the field's values.
      default int size()
      The number of neighbors in this field.
      default java.util.stream.Stream<? extends java.util.Map.Entry<DeviceUID,​T>> stream()  
      default java.util.Map<DeviceUID,​T> toMap()  
      default java.lang.Iterable<T> values()  
      default java.util.stream.Stream<T> valueStream()  

    • Method Detail

      • containsKey

        default boolean containsKey​(DeviceUID id)
        Verifies if some device has an entry in this field. Note to interface implementors: the default version of this method is not optimized for performance and should be overridden.
        Parameters:
        id - a device UID
        Returns:
        true if there is an entry in this field for the device

      • foldExcludingLocal

        default java.util.Map.Entry<DeviceUID,​T> foldExcludingLocal​(java.util.Map.Entry<DeviceUID,​T> base,
                                                                  java.util.function.BinaryOperator<java.util.Map.Entry<DeviceUID,​T>> combiner)
        Reduction operation with base value (fold), which does not consider the local value, and whose computation has base as initial element.
        Parameters:
        base - base value for the computation
        combiner - reduction function, takes two R and returns a single R
        Returns:
        the result of the reduction

      • foldExcludingLocal

        default <R> R foldExcludingLocal​(R base,
                                 java.util.function.Function<java.util.Map.Entry<DeviceUID,​T>,​R> mapper,
                                 java.util.function.BinaryOperator<R> combiner)
        Reduction operation with base value (fold), which does not consider the local value, and whose computation has base as initial element. This is the most generic version, actually performing a map + reduce operation.
        Type Parameters:
        R - Return type
        Parameters:
        base - base value for the computation
        mapper - mapping function for pre-processing field entries
        combiner - reduction function, takes two R and returns a single R
        Returns:
        the result of the reduction

      • foldIncludingLocal

        default java.util.Map.Entry<DeviceUID,​T> foldIncludingLocal​(java.util.function.BinaryOperator<java.util.Map.Entry<DeviceUID,​T>> combiner)
        Reduction operation with base value (fold), which uses the local value as initial element.
        Parameters:
        combiner - reduction function, takes two R and returns a single R
        Returns:
        the result of the reduction

      • foldIncludingLocal

        default <R> R foldIncludingLocal​(java.util.function.Function<java.util.Map.Entry<DeviceUID,​T>,​R> mapper,
                                 java.util.function.BinaryOperator<R> combiner)
        Reduction operation with base value (fold), which uses the local value as initial element. This is the most generic version, actually performing a map + reduce operation.
        Type Parameters:
        R - Return type
        Parameters:
        mapper - mapping function for pre-processing field entries
        combiner - reduction function, takes two R and returns a single R
        Returns:
        the result of the reduction

      • foldKeysExcludingLocal

        default DeviceUID foldKeysExcludingLocal​(DeviceUID base,
                                         java.util.function.BinaryOperator<DeviceUID> combiner)
        Reduction operation over keys with base value (fold), which does not consider the local key, and whose computation has base as initial element.
        Parameters:
        base - base value for the computation
        combiner - reduction function, takes two DeviceUID and returns a single one
        Returns:
        the result of the reduction

      • foldKeysIncludingLocal

        default DeviceUID foldKeysIncludingLocal​(java.util.function.BinaryOperator<DeviceUID> combiner)
        Reduction operation over keys with base value (fold), which uses the local value as initial element.
        Parameters:
        combiner - reduction function, takes two DeviceUID and returns a single one
        Returns:
        the result of the reduction

      • foldValuesExcludingLocal

        default T foldValuesExcludingLocal​(T base,
                                   java.util.function.BinaryOperator<T> combiner)
        Reduction operation over values with base value (fold), which does not consider the local key, and whose computation has base as initial element.
        Parameters:
        base - base value for the computation
        combiner - reduction function, takes two Ts and returns a single one
        Returns:
        the result of the reduction

      • foldValuesIncludingLocal

        default T foldValuesIncludingLocal​(java.util.function.BinaryOperator<T> combiner)
        Reduction operation over values with base value (fold), which uses the local value as initial element.
        Parameters:
        combiner - reduction function, takes two Ts and returns a single one
        Returns:
        the result of the reduction

      • get

        default T get​(@Nonnull
              DeviceUID id)
        Parameters:
        id - the DeviceUID
        Returns:
        the associated value
        Throws:
        java.util.NoSuchElementException - if the field does not have the provided id among its keys

      • getExpectedType

        default java.lang.Class<? extends T> getExpectedType()
        Returns:
        The type of the values of this field

      • getIfPresent

        default java.util.Optional<T> getIfPresent​(@Nonnull
                                           DeviceUID id)
        Parameters:
        id - the DeviceUID
        Returns:
        the associated value wrapped in an Optional, or an Optional.empty() if the device is not aligned.

      • getLocal

        default java.util.Map.Entry<DeviceUID,​T> getLocal()
        Returns:
        the local DeviceUID, T entry

      • getLocalDevice

        DeviceUID getLocalDevice()
        Returns:
        the local Device

      • getLocalValue

        default T getLocalValue()
        Returns:
        the value associated with the local device

      • isEmpty

        default boolean isEmpty()
        Returns:
        True if there are no neighbors

      • iterable

        java.lang.Iterable<? extends java.util.Map.Entry<DeviceUID,​T>> iterable()
        Returns:
        An iterator over the set of neighbor/value pairs

      • keys

        default java.lang.Iterable<DeviceUID> keys()
        Returns:
        An Iterable for the field keys

      • keyStream

        default java.util.stream.Stream<DeviceUID> keyStream()
        Returns:
        A Stream for the field keys

      • map

        default <R> Field<R> map​(@Nonnull
                         java.util.function.Function<DeviceUID,​R> mapper)
        Map operation over this field, returning a new field whose values are provided by the mapper function.
        Type Parameters:
        R - data type yield by the resulting field
        Parameters:
        mapper - mapping function
        Returns:
        a new field whose values are provided by the mapper function

      • projectOn

        default Field<T> projectOn​(@Nonnull
                           Field<?> restricted)
        Project this field over a restricted domain. If the domain is larger than this field, an exception is thrown.
        Parameters:
        restricted - the restricted domain
        Returns:
        a new field with the same values, but with possibly less entries. If the restriction is operated over the same domain of the current field, the field itself can be returned.

      • reduce

        default Option<java.util.Map.Entry<DeviceUID,​T>> reduce​(@Nonnull
                                                              java.util.function.BinaryOperator<java.util.Map.Entry<DeviceUID,​T>> combiner)
        Reduction operation over the field. Ignores the local value and returns an Option.
        Parameters:
        combiner - the reduction function, taking two entries and returning a single one.
        Returns:
        An Option with the computed value, or an empty option if the field was containing only the local value

      • reduce

        default <R> Option<R> reduce​(@Nonnull
                             java.util.function.Function<java.util.Map.Entry<DeviceUID,​T>,​R> mapper,
                             @Nonnull
                             java.util.function.BinaryOperator<R> combiner)
        Reduction operation over the field. Ignores the local value and returns an Option. This is the most general version, operating a map + reduce operation.
        Type Parameters:
        R - resulting option type
        Parameters:
        mapper - the mapping function
        combiner - the reduction function, taking two Rs and returning a single one.
        Returns:
        An Option with the computed value, or an empty option if the field was containing only the local value

      • reduceKeys

        default Option<DeviceUID> reduceKeys​(@Nonnull
                                     java.util.function.BinaryOperator<DeviceUID> combiner)
        Reduction operation over the field's keys. Ignores the local value and returns an Option.
        Parameters:
        combiner - the reduction function, taking two entries and returning a single one.
        Returns:
        An Option with the computed value, or an empty option if the field was containing only the local value

      • reduceValues

        default Option<T> reduceValues​(@Nonnull
                               java.util.function.BinaryOperator<T> combiner)
        Reduction operation over the field's values. Ignores the local value and returns an Option.
        Parameters:
        combiner - the reduction function, taking two entries and returning a single one.
        Returns:
        An Option with the computed value, or an empty option if the field was containing only the local value

      • size

        default int size()
        The number of neighbors in this field. Hence, a field that only contains the local value has size 0. Note to Field implementors: the default implementation is inefficient and should be overridden.
        Returns:
        Number of neighbors with values in the field

      • stream

        default java.util.stream.Stream<? extends java.util.Map.Entry<DeviceUID,​T>> stream()
        Returns:
        A Stream over the set of neighbor/value pairs

      • toMap

        default java.util.Map<DeviceUID,​T> toMap()
        Returns:
        a map version of the field. The map must not return a mutable view, namely, changes to this map must not affect the field.

      • values

        default java.lang.Iterable<T> values()
        Returns:
        An Iterable set of values

      • valueStream

        default java.util.stream.Stream<T> valueStream()
        Returns:
        A Stream over the set of values