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 and Description
static interface	Field.Builder<T> Builder for Fields.

Method Summary

Modifier and Type	Method and 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