Iterating using the JadeIterableIF Interfaces

With the release of Jade version 2020.0.01 and higher, the collection-expression of the foreach instruction has been extended and replaced by the iterable-expression so that in addition to accepting a collection, it now accepts JadeIterableIF and JadeReverseIterableIF interfaces.

For this to work as intended, the implemented createIterator and createReversibleIterator methods must return a valid implementor of these JadeIteratorIF and JadeReversibleIteratorIF interfaces, respectively.

foreach Instruction Options

The foreach instruction reversed option is valid only if the iterable‑expression represents a Collection or a JadeReverseIterableIF implementation. It is not valid for a JadeIterableIF implementation to use the reversed option, because its corresponding JadeIteratorIF implementation does not provide a back method.

Locking Behavior

When using a JadeIterableIF‑ or JadeReverseIterableIF‑based iterable‑expression, the locking behavior can be subtly different from using a collection‑expression in earlier releases.

The discreteLock option can still be used with a JadeIterableIF‑ or JadeReverseIterableIF‑based iterable‑expression, but at run time its effect takes place only if the underlying iterable object is a Collection instance. If the runtime iterable object is a non‑Collection instance, no implicit locking will take place.

Execution of a JadeIterableIF‑ or JadeReverseIterableIF‑based foreach iteration with no discreteLock option acquires an implicit shared lock for the duration of the foreach loop only if the underlying iterable object is a Collection instance. If the object is a non‑Collection instance, no implicit lock is acquired before retrieving the JadeIteratorIF implementor and iterating through the values.

Locking of non‑Collection iterable objects can be coded into the implementation of the interface methods, if required.

where Clause Optimization

Compilation of a JadeIterableIF‑ or JadeReverseIterableIF‑based iterable‑expression never attempts to optimize the where clause expression as it cannot guarantee that the runtime object will be a dictionary.

Iterating with the foreach Instruction as Clause

Due to the non‑generic nature of the JadeIterableIF and JadeReverseIterableIF interfaces, by default, using either interface in a non‑Collection iterable object in a foreach instruction allows the target variable to be of type Any, because the compiler cannot guarantee anything more specific.

To make this more useful, an iterable‑expression can be used in combination with an as clause, to allow the target variable to be a specific type. It is then up to you to ensure that any iterable object passed to this expression does retrieve a value from its iterator that is valid with respect to the as clause type. This allows you to write generic methods that can be provided any Collection or non‑Collection iterable object that all retrieve values of the same type.

For examples of iterating using the JadeIterableIF interface, see "Examples of JadeIterableIF Iteration", in the following subsection.

2020.0.01 and higher