Package org.eclipse.m2m.atl.emftvm.util

# Class LazyCollection<E>

java.lang.Object
org.eclipse.m2m.atl.emftvm.util.LazyCollection<E>

Type Parameters:
  `E` - the collection element type

All Implemented Interfaces:
  `Iterable<E>`, `Collection<E>`

Direct Known Subclasses:
  `LazyBag`, `LazyList`, `LazyOrderedSet`, `LazySet`

public abstract class LazyCollection<E> extends Object implements Collection<E>
Immutable `Collection` that supports lazy evaluation. Based on the OCL 2.2 specification (formal/2010-02-01).

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`class`
`LazyCollection.AppendIterator`
`Iterator` that appends an object to the underlying collection.
`class`
`LazyCollection.CachingIterator`
`LazyCollection.ReadOnlyIterator` that caches values of the underlying collection.
`class`
`LazyCollection.CachingSetIterator`
`LazyCollection.ReadOnlyIterator` that removes duplicate values from the underlying collection.
`static class`
`LazyCollection.CollectIterator<T>`
`LazyCollection.ReadOnlyIterator` that collects the results of evaluating a function on each of the elements from the underlying collection.
`class`
`LazyCollection.ExcludingIterator`
`LazyCollection.ReadOnlyIterator` that excludes a given object.
`class`
`LazyCollection.FilterIterator`
`LazyCollection.ReadOnlyIterator` that filters elements from the underlying collection by evaluating a condition function on them.
`static class`
`LazyCollection.FlattenIterator`
Recursively flattens any nested `Iterable`s by iterating over their elements as well.
`static class`
`LazyCollection.FlattenSetIterator`
Recursively flattens any nested `Iterable`s by iterating over their elements as well.
`static class`
`LazyCollection.IntegerRangeListIterator`
`LazyCollection.ReadOnlyIterator` for `Integer` ranges.
`class`
`LazyCollection.IntersectionIterator`
`LazyCollection.ReadOnlyIterator` that returns only elements contained in both underlying collections.
`class`
`LazyCollection.IteratorToListIterator`
Converts an `Iterator` to a `ListIterator`.
`static class`
`LazyCollection.LongRangeListIterator`
`LazyCollection.ReadOnlyIterator` for `Long` ranges.
`static class`
`LazyCollection.ReadOnlyIterator<E>`
`Iterator` without `LazyCollection.ReadOnlyIterator.remove()`.
`static class`
`LazyCollection.ReadOnlyListIterator<E>`
`ListIterator` without `LazyCollection.ReadOnlyIterator.remove()`, `LazyCollection.ReadOnlyListIterator.add(Object)`, and `LazyCollection.ReadOnlyListIterator.set(Object)`.
`class`
`LazyCollection.RejectIterator`
`LazyCollection<E>.FilterIterator` that rejects elements from the underlying collection by evaluation a condition function on them.
`class`
`LazyCollection.ReverseIterator`
`LazyCollection.ReadOnlyIterator` that returns the values of the underlying collection in reverse order.
`class`
`LazyCollection.ReverseListIterator`
`LazyCollection.ReadOnlyIterator` that returns the values of the underlying collection in reverse order.
`class`
`LazyCollection.SelectIterator`
`LazyCollection<E>.FilterIterator` that selects elements from the underlying collection by evaluation a condition function on them.
`class`
`LazyCollection.SubListIterator`
`Iterator` that iterates over a subrange of the underlying `LazyList`'s contents.
`class`
`LazyCollection.SubListListIterator`
`Iterator` that iterates over a subrange of the underlying `LazyList`'s contents.
`class`
`LazyCollection.SubtractionIterator`
`LazyCollection.ReadOnlyIterator` that returns elements contained in this underlying collection, but not in the other underlying collection.
`class`
`LazyCollection.UnionIterator`
`Iterator` that returns first the elements of the underlying collection, then the elements of the other collection.
`class`
`LazyCollection.UnionSetIterator`
`Iterator` that returns first the elements of the underlying collection, then the elements of the other collection, with all duplicates removed.
`class`
`LazyCollection.WrappedIterator`
Abstract `LazyCollection.ReadOnlyIterator` that wraps around the underlying collection.
`class`
`LazyCollection.WrappedListIterator`
Abstract `LazyCollection.ReadOnlyListIterator` that wraps around the underlying collection.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected Collection<E>`
`cache`
Element cache.
`protected Iterable<E>`
`dataSource`
The inner data source for this collection.
`protected Map<E,Integer>`
`occurrences`
Cached element occurrence map.

## Constructor Summary

Constructors
Constructor
Description
`LazyCollection()`
Creates an empty `LazyCollection`.
`LazyCollection(Iterable<E> dataSource)`
Creates a `LazyCollection` around `dataSource`.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`add(E o)`
Unsupported.
`boolean`
`addAll(Collection<? extends E> c)`
Unsupported.
`E`
`any(CodeBlock body)`
Returns any element in the source collection for which `body` evaluates to `true`.
`protected StringBuffer`
`appendElements(StringBuffer buf, ExecEnv env)`
Appends the elements of this collection to `buf`.
`LazyBag<E>`
`asBag()`
Returns the Bag containing all the elements from self, including duplicates.
`LazyOrderedSet<E>`
`asOrderedSet()`
Returns an OrderedSet that contains all the elements from self, in undefined order, with duplicates removed.
`LazyList<E>`
`asSequence()`
Returns a Sequence that contains all the elements from self, in undefined order.
`LazySet<E>`
`asSet()`
Returns the Set containing all the elements from self, with duplicated removed.
`abstract String`
`asString(ExecEnv env)`
Evaluates the collection as an OCL String.
`void`
`clear()`
Unsupported.
`boolean`
`contains(Object o)`
`boolean`
`containsAll(Collection<?> c)`
`boolean`
`containsAny(Collection<?> c)`
Checks if this collection contains any of the elements in the specified collection.
`int`
`count(Object object)`
Returns the number of times that `object` occurs in the collection self.
`protected void`
`createCache()`
Creates the cache collections.
`boolean`
`excludes(Object object)`
Returns `true` if `object` is not an element of self, `false` otherwise.
`boolean`
`excludesAll(Collection<?> c2)`
Does self contain none of the elements of `c2` ?
`abstract LazyCollection<E>`
`excluding(Object object)`
Returns the collection containing all elements of self apart from all occurrences of `object`.
`abstract LazyCollection<E>`
`excludingAll(Collection<?> coll)`
Returns the collection containing all elements of self minus `coll`.
`boolean`
`exists(CodeBlock condition)`
Checks if `condition` holds for at least one element in the underlying collection.
`boolean`
`exists2(CodeBlock condition)`
Checks if `condition` holds for at least one element pair in the cartesian product of the underlying collection.
`boolean`
`forAll(CodeBlock condition)`
Checks if `condition` holds for all elements in the underlying collection.
`boolean`
`forAll2(CodeBlock condition)`
Checks if `condition` holds for all element pairs in the cartesian product of the underlying collection.
`boolean`
`includes(Object object)`
Returns `true` if `object` is an element of self, `false` otherwise.
`boolean`
`includesAll(Collection<?> c2)`
Does self contain all the elements of `c2` ?
`abstract LazyCollection<E>`
`including(E object)`
Returns the collection containing all elements of self plus `object`.
`abstract LazyCollection<E>`
`including(E object, int index)`
Returns the collection containing all elements of self plus `object`.
`abstract LazyCollection<E>`
`includingAll(Collection<? extends E> coll)`
Returns the collection containing all elements of self plus `coll`.
`abstract LazyCollection<E>`
`includingAll(Collection<? extends E> coll, int index)`
Returns the collection containing all elements of self plus `coll`.
`abstract LazyCollection<E>`
`includingRange(E first, E last)`
Returns the collection containing all elements of self plus the collection of `first` running to `last`.
`boolean`
`isEmpty()`
`boolean`
`isUnique(CodeBlock body)`
Results in `true` if `body` evaluates to a different value for each element in the source collection; otherwise, result is `false`.
`<T> T`
`iterate(T initialValue, CodeBlock updater)`
Builds an accumulated value by calling the `updater` function for each element in the underlying collection and the previous accumulated value.
`Iterator<E>`
`iterator()`
`Map<Object,LazySet<E>>`
`mappedBy(CodeBlock body)`
Returns a Map indexed by the return value(s) `x` of the body expression, containing the Set of elements for which the body expression returns `x`.
`Map<Object,E>`
`mappedBySingle(CodeBlock body)`
Returns a Map indexed by the return value(s) `x` of the body expression, containing a single element for which the body expression returns `x`.
`E`
`max()`
The element with the maximum value of all elements in self.
`E`
`min()`
The element with the minimum value of all elements in self.
`boolean`
`notEmpty()`
Is self not the empty collection?
`boolean`
`one(CodeBlock body)`
Results in `true` if there is exactly one element in the source collection for which `body` is `true`.
`<T> LazySet<Tuple>`
`product(Iterable<T> c2)`
The cartesian product operation of `self` and `c2`.
`boolean`
`remove(Object o)`
Unsupported.
`boolean`
`removeAll(Collection<?> c)`
Unsupported.
`boolean`
`retainAll(Collection<?> c)`
Unsupported.
`int`
`size()`
`abstract LazyCollection<E>`
`sortedBy(CodeBlock body)`
Results in the Collection containing all elements of the source collection.
`E`
`sum()`
The addition of all elements in self.
`Object[]`
`toArray()`
`<T> T[]`
`toArray(T[] a)`
`String`
`toString()`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface java.util.Collection

`equals, hashCode, parallelStream, removeIf, spliterator, stream, toArray`

### Methods inherited from interface java.lang.Iterable

`forEach`

## Field Details

### dataSource

protected Iterable<E> dataSource
The inner data source for this collection. Is set to `null` when cache is complete.

### cache

protected Collection<E> cache
Element cache.

### occurrences

protected Map<E,Integer> occurrences
Cached element occurrence map.

## Constructor Details

### LazyCollection

public LazyCollection(Iterable<E> dataSource)
Creates a `LazyCollection` around `dataSource`.

Parameters:
  `dataSource` - the underlying collection

### LazyCollection

public LazyCollection()
Creates an empty `LazyCollection`.

## Method Details

### createCache

protected void createCache()
Creates the cache collections.

### add

public boolean add(E o)
Unsupported.

Specified by:
  `add` in interface `Collection<E>`
Parameters:
  `o` - the element to add
Returns:
  nothing
Throws:
  `UnsupportedOperationException`

### addAll

public boolean addAll(Collection<? extends E> c)
Unsupported.

Specified by:
  `addAll` in interface `Collection<E>`
Parameters:
  `c` - the collection to add
Returns:
  nothing
Throws:
  `UnsupportedOperationException`

### clear

public void clear()
Unsupported.

Specified by:
  `clear` in interface `Collection<E>`
Throws:
  `UnsupportedOperationException`

### contains

public boolean contains(Object o)

Specified by:
  `contains` in interface `Collection<E>`

### containsAll

public boolean containsAll(Collection<?> c)

Specified by:
  `containsAll` in interface `Collection<E>`

### containsAny

public boolean containsAny(Collection<?> c)
Checks if this collection contains any of the elements in the specified collection.

Parameters:
  `c` - collection to be checked for containment in this collection.
Returns:
  `true` if this collection contains any of the elements in the specified collection.

### isEmpty

public boolean isEmpty()

Specified by:
  `isEmpty` in interface `Collection<E>`

### iterator

public Iterator<E> iterator()

Specified by:
  `iterator` in interface `Collection<E>`
Specified by:
  `iterator` in interface `Iterable<E>`

### remove

public boolean remove(Object o)
Unsupported.

Specified by:
  `remove` in interface `Collection<E>`
Parameters:
  `o` - the element to remove
Returns:
  nothing
Throws:
  `UnsupportedOperationException`

### removeAll

public boolean removeAll(Collection<?> c)
Unsupported.

Specified by:
  `removeAll` in interface `Collection<E>`
Parameters:
  `c` - the collection to remove
Returns:
  nothing
Throws:
  `UnsupportedOperationException`

### retainAll

public boolean retainAll(Collection<?> c)
Unsupported.

Specified by:
  `retainAll` in interface `Collection<E>`
Parameters:
  `c` - the collection to retain
Returns:
  nothing
Throws:
  `UnsupportedOperationException`

### size

public int size()

Specified by:
  `size` in interface `Collection<E>`

### toArray

public Object[] toArray()

Specified by:
  `toArray` in interface `Collection<E>`

### toArray

public <T> T[] toArray(T[] a)

Specified by:
  `toArray` in interface `Collection<E>`

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### asString

public abstract String asString(ExecEnv env)
Evaluates the collection as an OCL String.

Parameters:
  `env` - the execution environment
Returns:
  the String representation of this `LazyCollection`.

### appendElements

protected StringBuffer appendElements(StringBuffer buf, ExecEnv env)
Appends the elements of this collection to `buf`.

Parameters:
  `buf` - the `StringBuffer` to add the elements' string representation to
  `env` - the execution environment
Returns:
  buf

### includes

public boolean includes(Object object)
Returns `true` if `object` is an element of self, `false` otherwise.

Parameters:
  `object` - the object to check for
Returns:
  `true` if `object` is an element of self, `false` otherwise.

### excludes

public boolean excludes(Object object)
Returns `true` if `object` is not an element of self, `false` otherwise.

Parameters:
  `object` - the object to check for
Returns:
  `true` if `object` is not an element of self, `false` otherwise.

### count

public int count(Object object)
Returns the number of times that `object` occurs in the collection self.

Parameters:
  `object` - the object to check for
Returns:
  The number of times that `object` occurs in the collection self.

### includesAll

public boolean includesAll(Collection<?> c2)
Does self contain all the elements of `c2` ?

Parameters:
  `c2` - the collection to check
Returns:
  `true` iff self contains all elements of `c2`.

### excludesAll

public boolean excludesAll(Collection<?> c2)
Does self contain none of the elements of `c2` ?

Parameters:
  `c2` - the collection to check
Returns:
  `true` iff self contains no elements of `c2`.

### notEmpty

public boolean notEmpty()
Is self not the empty collection?

Returns:
  `false` iff self contains no elements.

### max

public E max()
The element with the maximum value of all elements in self. Elements must be of a type supporting the max operation. The max operation - supported by the elements - must take one parameter of type `E` and be both associative and commutative. Integer and Real fulfill this condition.

Returns:
  The element with the maximum value of all elements in self.

### min

public E min()
The element with the minimum value of all elements in self. Elements must be of a type supporting the min operation. The min operation - supported by the elements - must take one parameter of type T and be both associative and commutative. Integer and Real fulfill this condition.

Returns:
  The element with the minimum value of all elements in self.

### sum

public E sum()
The addition of all elements in self. Elements must be of a type supporting the + operation. The + operation must take one parameter of type `E` and be both associative: (a+b)+c = a+(b+c), and commutative: a+b = b+a. Integer and Real fulfill this condition.

Returns:
  `self->iterate( elem; acc : E = 0 | acc + elem )`

### product

public <T> LazySet<Tuple> product(Iterable<T> c2)
The cartesian product operation of `self` and `c2`.

Lazy operation.

Type Parameters:
  `T` - the element type
Parameters:
  `c2` - the other factor in the cartesian product
Returns:
  `self->iterate (e1; acc: Set(Tuple(first: T, second: T2)) = Set{} |
  c2->iterate (e2; acc2: Set(Tuple(first: T, second: T2)) = acc |
  acc2->including (Tuple{first = e1, second = e2}) ) )`

### asBag

public LazyBag<E> asBag()
Returns the Bag containing all the elements from self, including duplicates.

Lazy operation.

Returns:
  The Bag containing all the elements from self, including duplicates.

### asSequence

public LazyList<E> asSequence()
Returns a Sequence that contains all the elements from self, in undefined order.

Lazy operation.

Returns:
  A Sequence that contains all the elements from self, in undefined order.

### asSet

public LazySet<E> asSet()
Returns the Set containing all the elements from self, with duplicated removed.

Lazy operation.

Returns:
  The Set containing all the elements from self, with duplicated removed.

### asOrderedSet

public LazyOrderedSet<E> asOrderedSet()
Returns an OrderedSet that contains all the elements from self, in undefined order, with duplicates removed.

Lazy operation.

Returns:
  An OrderedSet that contains all the elements from self, in undefined order, with duplicates removed.

### including

public abstract LazyCollection<E> including(E object)
Returns the collection containing all elements of self plus `object`.

Lazy operation.

Parameters:
  `object` - the object to include
Returns:
  The collection containing all elements of self plus `object`.

### including

public abstract LazyCollection<E> including(E object, int index)
Returns the collection containing all elements of self plus `object`.

Lazy operation.

Parameters:
  `object` - the object to include
  `index` - the index at which to insert `coll` (starting at 1)
Returns:
  The collection containing all elements of self plus `object`.

### includingAll

public abstract LazyCollection<E> includingAll(Collection<? extends E> coll)
Returns the collection containing all elements of self plus `coll`.

Lazy operation.

Parameters:
  `coll` - the collection to include
Returns:
  The collection containing all elements of self plus `coll`.

### includingAll

public abstract LazyCollection<E> includingAll(Collection<? extends E> coll, int index)
Returns the collection containing all elements of self plus `coll`.

Lazy operation.

Parameters:
  `coll` - the collection to include
  `index` - the index at which to insert `coll` (starting at 1)
Returns:
  The collection containing all elements of self plus `coll`.

### excluding

public abstract LazyCollection<E> excluding(Object object)
Returns the collection containing all elements of self apart from all occurrences of `object`.

Lazy operation.

Parameters:
  `object` - the object to exclude
Returns:
  The collection containing all elements of self apart from all occurrences of `object`.

### excludingAll

public abstract LazyCollection<E> excludingAll(Collection<?> coll)
Returns the collection containing all elements of self minus `coll`.

Lazy operation.

Parameters:
  `coll` - the collection to exclude
Returns:
  The collection containing all elements of self minus `coll`.

### includingRange

public abstract LazyCollection<E> includingRange(E first, E last)
Returns the collection containing all elements of self plus the collection of `first` running to `last`.

Lazy operation.

Parameters:
  `first` - the first object of the range to include
  `last` - the last object of the range to include
Returns:
  The collection containing all elements of self plus the collection of `first` running to `last`

### forAll

public boolean forAll(CodeBlock condition)
Checks if `condition` holds for all elements in the underlying collection.

Parameters:
  `condition` - the condition function
Returns:
  `true` iff `condition` holds for all elements in the underlying collection.

### forAll2

public boolean forAll2(CodeBlock condition)
Checks if `condition` holds for all element pairs in the cartesian product of the underlying collection.

Parameters:
  `condition` - the condition function
Returns:
  `true` iff `condition` holds for all element pairs in the cartesian product of the underlying collection.

### exists

public boolean exists(CodeBlock condition)
Checks if `condition` holds for at least one element in the underlying collection.

Parameters:
  `condition` - the condition function
Returns:
  `true` iff `condition` holds for at least one element in the underlying collection.

### exists2

public boolean exists2(CodeBlock condition)
Checks if `condition` holds for at least one element pair in the cartesian product of the underlying collection.

Parameters:
  `condition` - the condition function
Returns:
  `true` iff `condition` holds for at least one element pair in the cartesian product of the underlying collection.

### iterate

public <T> T iterate(T initialValue, CodeBlock updater)
Builds an accumulated value by calling the `updater` function for each element in the underlying collection and the previous accumulated value.

Type Parameters:
  `T` - the element type
Parameters:
  `initialValue` - the initial accumulated value
  `updater` - the updater function
Returns:
  The accumulated value

### isUnique

public boolean isUnique(CodeBlock body)
Results in `true` if `body` evaluates to a different value for each element in the source collection; otherwise, result is `false`.

Parameters:
  `body` - the code to execute on each element
Returns:
  `true` if `body` evaluates to a different value for each element in the source collection.

### any

public E any(CodeBlock body) throws NoSuchElementException
Returns any element in the source collection for which `body` evaluates to `true`. If there is more than one element for which `body` is `true`, one of them is returned. There must be at least one element fulfilling `body`.

Parameters:
  `body` - the function to evaluate on each element
Returns:
  any element in the source collection for which body evaluates to `true`.
Throws:
  `NoSuchElementException` - if there is no element in the source collection for which `body` is `true`.

### one

public boolean one(CodeBlock body)
Results in `true` if there is exactly one element in the source collection for which `body` is `true`.

Parameters:
  `body` - the function to evaluate on each element
Returns:
  `true` if there is exactly one element in the source collection for which `body` is `true`.

### sortedBy

public abstract LazyCollection<E> sortedBy(CodeBlock body)
Results in the Collection containing all elements of the source collection. The element for which body has the lowest value comes first, and so on. The type of the body expression must have the `<` operation defined. The `<` operation must return a Boolean value and must be transitive (i.e., if `a < b` and `b < c` then `a < c`).

Parameters:
  `body` - the function to evaluate on each element
Returns:
  the sorted collection

### mappedBy

public Map<Object,LazySet<E>> mappedBy(CodeBlock body)
Returns a Map indexed by the return value(s) `x` of the body expression, containing the Set of elements for which the body expression returns `x`.

Parameters:
  `body` - the function to evaluate on each element
Returns:
  the Map

### mappedBySingle

public Map<Object,E> mappedBySingle(CodeBlock body)
Returns a Map indexed by the return value(s) `x` of the body expression, containing a single element for which the body expression returns `x`.

Parameters:
  `body` - the function to evaluate on each element
Returns:
  the Map